Synchronize code with specs.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8366 6f19259b-4bc3-4df7-8a09-765794883524

IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h

@@ -1,17 +1,20 @@
 /** @file
   This protocol is used to prepare all information that is needed for the S3 resume boot path. This
   protocol is not required for all platforms.
-  This protocol is defined in framework S3Resume v0.9, page 21.
   
-Copyright (c) 2006, Intel Corporation
+  Copyright (c) 2006 - 2009, Intel Corporation
-All rights reserved. This program and the accompanying materials
+  All rights reserved. This program and the accompanying materials
-are licensed and made available under the terms and conditions of the BSD License
+  are licensed and made available under the terms and conditions of the BSD License
-which accompanies this distribution.  The full text of the license may be found at
+  which accompanies this distribution.  The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php
+  http://opensource.org/licenses/bsd-license.php
 
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
+  @par Revision Reference:
+  This Protocol is defined in Framework of S3 Resume Boot Path Spec.
+  Version 0.9.
+  
 **/
 
 #ifndef _ACPI_S3_SAVE_PROTOCOL_H_
@@ -35,6 +38,23 @@ typedef struct _EFI_ACPI_S3_SAVE_PROTOCOL EFI_ACPI_S3_SAVE_PROTOCOL;
 //
 // Protocol Data Structures
 //
+
+/**
+  This function returns the size of the legacy memory below 1 MB that is required during an S3
+  resume. Before the Framework-based firmware transfers control to the OS, it has to transition from
+  flat mode into real mode in case the OS supplies only a real-mode waking vector. This transition
+  requires a certain amount of legacy memory below 1 MB. After getting the size of legacy memory
+  below 1 MB, the caller is responsible for allocating the legacy memory below 1 MB according to
+  the size that is returned. The specific implementation of allocating the legacy memory is out of the
+  scope of this specification.
+
+  @param  This                  A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
+  @param  LegacyMemoryAddress   The returned size of legacy memory below 1MB.
+
+  @retval EFI_SUCCESS           Size is successfully returned.
+  @retval EFI_INVALID_PARAMETER The pointer Size is NULL.
+
+**/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_ACPI_S3_SAVE)(
@@ -42,6 +62,31 @@ EFI_STATUS
   IN VOID                           * LegacyMemoryAddress
   );
 
+/**
+  This function is used to do the following:
+  
+  - Prepare all information that is needed in the S3 resume boot path. This information can include
+  the following:
+     -- Framework boot script table
+     -- RSDT pointer
+     -- Reserved memory for the S3 resume
+     
+  - Get the minimum memory length below 1 MB that is required for the S3 resume boot path.
+  If LegacyMemoryAddress is NULL, the firmware will be unable to jump into a real-mode
+  waking vector. However, it might still be able to jump into a flat-mode waking vector as long as the
+  OS provides a flat-mode waking vector. It is the caller<65>s responsibility to ensure the
+  LegacyMemoryAddress is valid. If the LegacyMemoryAddress is higher than 1 MB,
+  EFI_INVALID_PARAMETER will be returned.
+
+  @param  This                  A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
+  @param  LegacyMemoryAddress   The base of legacy memory.
+
+  @retval EFI_SUCCESS           All information was saved successfully.
+  @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.
+  @retval EFI_OUT_OF_RESOURCES  Resources were insufficient to save all the information.
+  @retval EFI_NOT_FOUND         Some necessary information cannot be found.
+  
+**/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_ACPI_GET_LEGACY_MEMORY_SIZE)(
@@ -49,6 +94,34 @@ EFI_STATUS
   OUT UINTN                         * Size
 );
 
+/**
+  @par Protocol Description:
+  The EFI_ACPI_S3_SAVE_PROTOCOL is responsible for preparing all the information that the
+  Framework needs to restore the platform<72>s preboot state during an S3 resume boot. This
+  information can include the following:
+    - The Framework boot script table, containing all necessary operations to initialize the platform
+    - ACPI table information, such as RSDT, through which the OS waking vector can be located
+    - Range of reserved memory that can be used on the S3 resume boot path
+  This protocol can be used after the Framework makes sure that the boot process is complete and
+  that no hardware has been left unconfigured. It is implementation specific where to call this
+  protocol to save all the information.
+  In the case of an EFI-aware OS, ExitBootServices()can be a choice to provide this hook.
+  The currently executing EFI OS loader image calls ExitBootServices()to terminate all boot
+  services. After ExitBootServices() successfully completes, the loader becomes responsible
+  for the continued operation of the system.
+  On a normal boot, ExitBootServices() checks if the platform supports S3 by looking for
+  EFI_ACPI_S3_SAVE_PROTOCOL. If the protocol exists, ExitBootServices()will assume
+  that the target platform supports an S3 resume and then call EFI_ACPI_S3_SAVE_PROTOCOL
+  to save the S3 resume information. The entire Framework boot script table will then be generated,
+  assuming the platform currently is in the preboot state.
+
+  @param GetLegacyMemorySize
+  Gets the size of legacy memory below 1 MB that is required for S3 resume.
+
+  @param S3Save
+  Prepare all information for an S3 resume.
+  
+**/
 struct _EFI_ACPI_S3_SAVE_PROTOCOL {
   EFI_ACPI_GET_LEGACY_MEMORY_SIZE   GetLegacyMemorySize;
   EFI_ACPI_S3_SAVE                  S3Save;

IntelFrameworkPkg/Include/Protocol/AcpiSupport.h

@@ -7,9 +7,7 @@
 	- Ensure that tables are properly aligned and use correct types of memory.
 	- Update checksum values and IDs.
 	- Complete the final installation of the tables.
-
+ 
-  This is defined in the ACPI Specification 0.9.
-  
   Copyright (c) 2007, Intel Corporation
   All rights reserved. This program and the accompanying materials
   are licensed and made available under the terms and conditions of the BSD License
@@ -19,6 +17,10 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
+  @par Revision Reference:
+  This Protocol is defined in Framework of ACPI Specification.
+  Version 0.9.
+
 **/
 
 #ifndef _ACPI_SUPPORT_PROTOCOL_H_
@@ -119,6 +121,11 @@ EFI_STATUS
   Causes one or more versions of the ACPI tables to be published in
   the EFI system configuration tables.
 
+  The PublishTables() function installs the ACPI tables for the versions that are specified in 
+  Version. No tables are published for Version equal to EFI_ACPI_VERSION_NONE. Once 
+  published, tables will continue to be updated as tables are modified with 
+  EFI_ACPI_SUPPORT_PROTOCOL.SetAcpiTable(). 
+
   @param  This                  A pointer to the EFI_ACPI_SUPPORT_PROTOCOL instance.
   @param  Version               Indicates to which version(s) of ACPI that the table should be published.
 
@@ -137,7 +144,6 @@ EFI_STATUS
 // ACPI Support Protocol
 //
 /**
-  @par Protocol Description:
   This protocol provides some basic services to support publishing ACPI system
   tables. The services handle many of the more mundane tasks that are required
   to publish a set of tables.

IntelFrameworkPkg/Include/Protocol/CpuIo.h

@@ -101,7 +101,6 @@ typedef struct {
 // *******************************************************
 //
 /**
-  @par Protocol Description:
   Provides the basic memory and I/O interfaces that are used to abstract
   accesses to devices in a system.
 

IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h

@@ -101,10 +101,10 @@ EFI_STATUS
   IN  BOOLEAN                         UseDatabase,
   IN  FRAMEWORK_EFI_HII_HANDLE        *Handle,
   IN  UINTN                           HandleCount,
-  IN  FRAMEWORK_EFI_IFR_PACKET                  *Packet, OPTIONAL
+  IN  FRAMEWORK_EFI_IFR_PACKET        *Packet, OPTIONAL
   IN  EFI_HANDLE                      CallbackHandle, OPTIONAL
   IN  UINT8                           *NvMapOverride, OPTIONAL
-  IN  FRAMEWORK_EFI_SCREEN_DESCRIPTOR            *ScreenDimensions, OPTIONAL
+  IN  FRAMEWORK_EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL
   OUT BOOLEAN                         *ResetRequired OPTIONAL
   );
 

IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h

@@ -178,7 +178,7 @@ EFI_STATUS
 (EFIAPI *EFI_FORM_CALLBACK)(
   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,
   IN     UINT16                        KeyValue,
-  IN     FRAMEWORK_EFI_IFR_DATA_ARRAY            *Data,
+  IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,
   OUT    EFI_HII_CALLBACK_PACKET       **Packet
   );
 

IntelFrameworkPkg/Include/Protocol/FrameworkHii.h

@@ -311,7 +311,7 @@ typedef struct _EFI_HII_VARIABLE_PACK_LIST {
 
   @param  This                  A pointer to the EFI_HII_PROTOCOL instance.
   @param  Packages              A pointer to an EFI_HII_PACKAGES package instance.
-  @param  Handle                A pointer to the FRAMEWORK_EFI_HII_HANDLE  instance.
+  @param  Handle                A pointer to the FRAMEWORK_EFI_HII_HANDLE instance.
 
   @retval EFI_SUCCESS           Data was extracted from Packages, the database
                                 was updated with the data, and Handle returned successfully.

IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h

@@ -355,7 +355,8 @@ EFI_STATUS
 
   @retval EFI_SUCCESS           The modes were accepted without any errors.
   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
-                                Or Device is invalid.
+                                Or Device is invalid, 
+                                Or IdentifyData is NULL.
 
 **/
 typedef

IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h

@@ -144,6 +144,7 @@ typedef enum {
 
   @retval EFI_SUCCESS           Success
   @retval EFI_OUT_OF_RESOURCES  If SubmitResources ( ) could not allocate resources
+  @retval EFI_INVALID_PARAMETER The Phase is invalid
   @retval EFI_NOT_READY         This phase cannot be entered at this time
   @retval EFI_DEVICE_ERROR      SetResources failed due to HW error.
 
@@ -168,6 +169,7 @@ EFI_STATUS
 
   @retval EFI_SUCCESS           Success
   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
+  @retval EFI_NOT_FOUND        There are no more PCI root bridge device handles.
 
 **/
 typedef
@@ -265,7 +267,7 @@ EFI_STATUS
   @retval EFI_INVALID_PARAMETER Configuration is NULL
   @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
   @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type
-
+  
 **/
 typedef
 EFI_STATUS

IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h

@@ -41,7 +41,18 @@ typedef enum {
 } EFI_USB_SMI_TYPE;
 
 typedef struct {
+  ///
+  /// Describes whether this child handler will be invoked in response to a USB legacy
+  /// emulation event, such as port-trap on the PS/2* keyboard control registers, or to a
+  /// USB wake event, such as resumption from a sleep state. 
+  ///
   EFI_USB_SMI_TYPE          Type;
+  ///
+  /// The device path is part of the context structure and describes the location of the
+  /// particular USB host controller in the system for which this register event will occur.
+  /// This location is important because of the possible integration of several USB host
+  /// controllers in a system. 
+  ///
   EFI_DEVICE_PATH_PROTOCOL  *Device;
 } EFI_SMM_USB_DISPATCH_CONTEXT;