Synchronize code with specs.

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

9 files changed, 111 insertions, 19 deletions

diff --git a/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h b/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
index 182e388e90..2fb269e60c 100644
--- a/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
+++ b/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

-All rights reserved. This program and the accompanying materials

-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

-http://opensource.org/licenses/bsd-license.php

+  Copyright (c) 2006 - 2009, 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

+  which accompanies this distribution.  The full text of the license may be found at

+  http://opensource.org/licenses/bsd-license.php

 

-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+  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 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’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’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;

diff --git a/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h b/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h
index 468dac2aaa..bca149ebd5 100644
--- a/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h
+++ b/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.

diff --git a/IntelFrameworkPkg/Include/Protocol/CpuIo.h b/IntelFrameworkPkg/Include/Protocol/CpuIo.h
index d79f9b49cf..696ea693b8 100644
--- a/IntelFrameworkPkg/Include/Protocol/CpuIo.h
+++ b/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.

 

diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h
index 9f77431562..d49d73f18b 100644
--- a/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h
+++ b/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

   );

 

diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
index db625f1df8..f44c90643f 100644
--- a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
+++ b/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

   );

 

diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h b/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h
index 17fc81a37b..c6e131e922 100644
--- a/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h
+++ b/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.

diff --git a/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h b/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
index bb586c1363..ac2760ddc9 100644
--- a/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
+++ b/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

diff --git a/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h b/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
index f56e4480e4..4b51bdb81e 100644
--- a/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
+++ b/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

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h
index 5887951e98..c2f70aceeb 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h
+++ b/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;