Synchronize code with specs.
authorgikidy <gikidy@6f19259b-4bc3-4df7-8a09-765794883524>
Thu, 21 May 2009 06:08:25 +0000 (06:08 +0000)
committergikidy <gikidy@6f19259b-4bc3-4df7-8a09-765794883524>
Thu, 21 May 2009 06:08:25 +0000 (06:08 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8366 6f19259b-4bc3-4df7-8a09-765794883524

IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
IntelFrameworkPkg/Include/Protocol/AcpiSupport.h
IntelFrameworkPkg/Include/Protocol/CpuIo.h
IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h
IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
IntelFrameworkPkg/Include/Protocol/FrameworkHii.h
IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h

index 182e388e90bba8c1b04bd881fe1958f6c43dab32..2fb269e60cf8342b8a8d79acba002ded5c866ad3 100644 (file)
@@ -1,17 +1,20 @@
 /** @file\r
   This protocol is used to prepare all information that is needed for the S3 resume boot path. This\r
   protocol is not required for all platforms.\r
-  This protocol is defined in framework S3Resume v0.9, page 21.\r
   \r
-Copyright (c) 2006, Intel Corporation\r
-All rights reserved. This program and the accompanying materials\r
-are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution.  The full text of the license may be found at\r
-http://opensource.org/licenses/bsd-license.php\r
+  Copyright (c) 2006 - 2009, Intel Corporation\r
+  All rights reserved. This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
 \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
+  @par Revision Reference:\r
+  This Protocol is defined in Framework of S3 Resume Boot Path Spec.\r
+  Version 0.9.\r
+  \r
 **/\r
 \r
 #ifndef _ACPI_S3_SAVE_PROTOCOL_H_\r
@@ -35,6 +38,23 @@ typedef struct _EFI_ACPI_S3_SAVE_PROTOCOL EFI_ACPI_S3_SAVE_PROTOCOL;
 //\r
 // Protocol Data Structures\r
 //\r
+\r
+/**\r
+  This function returns the size of the legacy memory below 1 MB that is required during an S3\r
+  resume. Before the Framework-based firmware transfers control to the OS, it has to transition from\r
+  flat mode into real mode in case the OS supplies only a real-mode waking vector. This transition\r
+  requires a certain amount of legacy memory below 1 MB. After getting the size of legacy memory\r
+  below 1 MB, the caller is responsible for allocating the legacy memory below 1 MB according to\r
+  the size that is returned. The specific implementation of allocating the legacy memory is out of the\r
+  scope of this specification.\r
+\r
+  @param  This                  A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.\r
+  @param  LegacyMemoryAddress   The returned size of legacy memory below 1MB.\r
+\r
+  @retval EFI_SUCCESS           Size is successfully returned.\r
+  @retval EFI_INVALID_PARAMETER The pointer Size is NULL.\r
+\r
+**/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_ACPI_S3_SAVE)(\r
@@ -42,6 +62,31 @@ EFI_STATUS
   IN VOID                           * LegacyMemoryAddress\r
   );\r
 \r
+/**\r
+  This function is used to do the following:\r
+  \r
+  - Prepare all information that is needed in the S3 resume boot path. This information can include\r
+  the following:\r
+     -- Framework boot script table\r
+     -- RSDT pointer\r
+     -- Reserved memory for the S3 resume\r
+     \r
+  - Get the minimum memory length below 1 MB that is required for the S3 resume boot path.\r
+  If LegacyMemoryAddress is NULL, the firmware will be unable to jump into a real-mode\r
+  waking vector. However, it might still be able to jump into a flat-mode waking vector as long as the\r
+  OS provides a flat-mode waking vector. It is the caller\92s responsibility to ensure the\r
+  LegacyMemoryAddress is valid. If the LegacyMemoryAddress is higher than 1 MB,\r
+  EFI_INVALID_PARAMETER will be returned.\r
+\r
+  @param  This                  A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.\r
+  @param  LegacyMemoryAddress   The base of legacy memory.\r
+\r
+  @retval EFI_SUCCESS           All information was saved successfully.\r
+  @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.\r
+  @retval EFI_OUT_OF_RESOURCES  Resources were insufficient to save all the information.\r
+  @retval EFI_NOT_FOUND         Some necessary information cannot be found.\r
+  \r
+**/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_ACPI_GET_LEGACY_MEMORY_SIZE)(\r
@@ -49,6 +94,34 @@ EFI_STATUS
   OUT UINTN                         * Size\r
 );\r
 \r
+/**\r
+  @par Protocol Description:\r
+  The EFI_ACPI_S3_SAVE_PROTOCOL is responsible for preparing all the information that the\r
+  Framework needs to restore the platform\92s preboot state during an S3 resume boot. This\r
+  information can include the following:\r
+    - The Framework boot script table, containing all necessary operations to initialize the platform\r
+    - ACPI table information, such as RSDT, through which the OS waking vector can be located\r
+    - Range of reserved memory that can be used on the S3 resume boot path\r
+  This protocol can be used after the Framework makes sure that the boot process is complete and\r
+  that no hardware has been left unconfigured. It is implementation specific where to call this\r
+  protocol to save all the information.\r
+  In the case of an EFI-aware OS, ExitBootServices()can be a choice to provide this hook.\r
+  The currently executing EFI OS loader image calls ExitBootServices()to terminate all boot\r
+  services. After ExitBootServices() successfully completes, the loader becomes responsible\r
+  for the continued operation of the system.\r
+  On a normal boot, ExitBootServices() checks if the platform supports S3 by looking for\r
+  EFI_ACPI_S3_SAVE_PROTOCOL. If the protocol exists, ExitBootServices()will assume\r
+  that the target platform supports an S3 resume and then call EFI_ACPI_S3_SAVE_PROTOCOL\r
+  to save the S3 resume information. The entire Framework boot script table will then be generated,\r
+  assuming the platform currently is in the preboot state.\r
+\r
+  @param GetLegacyMemorySize\r
+  Gets the size of legacy memory below 1 MB that is required for S3 resume.\r
+\r
+  @param S3Save\r
+  Prepare all information for an S3 resume.\r
+  \r
+**/\r
 struct _EFI_ACPI_S3_SAVE_PROTOCOL {\r
   EFI_ACPI_GET_LEGACY_MEMORY_SIZE   GetLegacyMemorySize;\r
   EFI_ACPI_S3_SAVE                  S3Save;\r
index 468dac2aaaf2e920ebbc477bf69f3d841db0d105..bca149ebd5c0c18c239cf76525a4c672e985555c 100644 (file)
@@ -7,9 +7,7 @@
        - Ensure that tables are properly aligned and use correct types of memory.\r
        - Update checksum values and IDs.\r
        - Complete the final installation of the tables.\r
-\r
-  This is defined in the ACPI Specification 0.9.\r
-  \r
\r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
+  @par Revision Reference:\r
+  This Protocol is defined in Framework of ACPI Specification.\r
+  Version 0.9.\r
+\r
 **/\r
 \r
 #ifndef _ACPI_SUPPORT_PROTOCOL_H_\r
@@ -119,6 +121,11 @@ EFI_STATUS
   Causes one or more versions of the ACPI tables to be published in\r
   the EFI system configuration tables.\r
 \r
+  The PublishTables() function installs the ACPI tables for the versions that are specified in \r
+  Version. No tables are published for Version equal to EFI_ACPI_VERSION_NONE. Once \r
+  published, tables will continue to be updated as tables are modified with \r
+  EFI_ACPI_SUPPORT_PROTOCOL.SetAcpiTable(). \r
+\r
   @param  This                  A pointer to the EFI_ACPI_SUPPORT_PROTOCOL instance.\r
   @param  Version               Indicates to which version(s) of ACPI that the table should be published.\r
 \r
@@ -137,7 +144,6 @@ EFI_STATUS
 // ACPI Support Protocol\r
 //\r
 /**\r
-  @par Protocol Description:\r
   This protocol provides some basic services to support publishing ACPI system\r
   tables. The services handle many of the more mundane tasks that are required\r
   to publish a set of tables.\r
index d79f9b49cfe211e16163c0667483773afa807cfc..696ea693b89afb5d005e97b9cabb715f61ccb420 100644 (file)
@@ -101,7 +101,6 @@ typedef struct {
 // *******************************************************\r
 //\r
 /**\r
-  @par Protocol Description:\r
   Provides the basic memory and I/O interfaces that are used to abstract\r
   accesses to devices in a system.\r
 \r
index 9f7743156249b3bb3ffb70b6c70803898e05f961..d49d73f18ba23ad6f5fcc1502e7f19aebc79472c 100644 (file)
@@ -101,10 +101,10 @@ EFI_STATUS
   IN  BOOLEAN                         UseDatabase,\r
   IN  FRAMEWORK_EFI_HII_HANDLE        *Handle,\r
   IN  UINTN                           HandleCount,\r
-  IN  FRAMEWORK_EFI_IFR_PACKET                  *Packet, OPTIONAL\r
+  IN  FRAMEWORK_EFI_IFR_PACKET        *Packet, OPTIONAL\r
   IN  EFI_HANDLE                      CallbackHandle, OPTIONAL\r
   IN  UINT8                           *NvMapOverride, OPTIONAL\r
-  IN  FRAMEWORK_EFI_SCREEN_DESCRIPTOR            *ScreenDimensions, OPTIONAL\r
+  IN  FRAMEWORK_EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL\r
   OUT BOOLEAN                         *ResetRequired OPTIONAL\r
   );\r
 \r
index db625f1df82cc74c4dd3b982c776ee37a8d39eaf..f44c90643f3586d39e9f9c69c0fa25b47207b496 100644 (file)
@@ -178,7 +178,7 @@ EFI_STATUS
 (EFIAPI *EFI_FORM_CALLBACK)(\r
   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
   IN     UINT16                        KeyValue,\r
-  IN     FRAMEWORK_EFI_IFR_DATA_ARRAY            *Data,\r
+  IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,\r
   OUT    EFI_HII_CALLBACK_PACKET       **Packet\r
   );\r
 \r
index 17fc81a37b6590ac79a92dae5bcf9e8eeada35a7..c6e131e922fa2e44bdc644e0cf1e7dbd774bd535 100644 (file)
@@ -311,7 +311,7 @@ typedef struct _EFI_HII_VARIABLE_PACK_LIST {
 \r
   @param  This                  A pointer to the EFI_HII_PROTOCOL instance.\r
   @param  Packages              A pointer to an EFI_HII_PACKAGES package instance.\r
-  @param  Handle                A pointer to the FRAMEWORK_EFI_HII_HANDLE  instance.\r
+  @param  Handle                A pointer to the FRAMEWORK_EFI_HII_HANDLE instance.\r
 \r
   @retval EFI_SUCCESS           Data was extracted from Packages, the database\r
                                 was updated with the data, and Handle returned successfully.\r
index bb586c1363697713f5791cef7b9270a0427304b4..ac2760ddc9a658ff3b3cf395ce7fef16de8111db 100644 (file)
@@ -355,7 +355,8 @@ EFI_STATUS
 \r
   @retval EFI_SUCCESS           The modes were accepted without any errors.\r
   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
-                                Or Device is invalid.\r
+                                Or Device is invalid, \r
+                                Or IdentifyData is NULL.\r
 \r
 **/\r
 typedef\r
index f56e4480e4e28372112cdf851d0f9fc2551dde9d..4b51bdb81e3bcf9e0f000632b24074ceae8e3e0d 100644 (file)
@@ -144,6 +144,7 @@ typedef enum {
 \r
   @retval EFI_SUCCESS           Success\r
   @retval EFI_OUT_OF_RESOURCES  If SubmitResources ( ) could not allocate resources\r
+  @retval EFI_INVALID_PARAMETER The Phase is invalid\r
   @retval EFI_NOT_READY         This phase cannot be entered at this time\r
   @retval EFI_DEVICE_ERROR      SetResources failed due to HW error.\r
 \r
@@ -168,6 +169,7 @@ EFI_STATUS
 \r
   @retval EFI_SUCCESS           Success\r
   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
+  @retval EFI_NOT_FOUND        There are no more PCI root bridge device handles.\r
 \r
 **/\r
 typedef\r
@@ -265,7 +267,7 @@ EFI_STATUS
   @retval EFI_INVALID_PARAMETER Configuration is NULL\r
   @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor\r
   @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type\r
-\r
+  \r
 **/\r
 typedef\r
 EFI_STATUS\r
index 5887951e98debb9832182e0333eacc5721f5c344..c2f70aceebaa73be3aeeec6b9f22f221b94c0f3a 100644 (file)
@@ -41,7 +41,18 @@ typedef enum {
 } EFI_USB_SMI_TYPE;\r
 \r
 typedef struct {\r
+  ///\r
+  /// Describes whether this child handler will be invoked in response to a USB legacy\r
+  /// emulation event, such as port-trap on the PS/2* keyboard control registers, or to a\r
+  /// USB wake event, such as resumption from a sleep state. \r
+  ///\r
   EFI_USB_SMI_TYPE          Type;\r
+  ///\r
+  /// The device path is part of the context structure and describes the location of the\r
+  /// particular USB host controller in the system for which this register event will occur.\r
+  /// This location is important because of the possible integration of several USB host\r
+  /// controllers in a system. \r
+  ///\r
   EFI_DEVICE_PATH_PROTOCOL  *Device;\r
 } EFI_SMM_USB_DISPATCH_CONTEXT;\r
 \r