From 534b8251cc3c62a2a7cf90afb379692c1af2a35f Mon Sep 17 00:00:00 2001 From: gikidy Date: Thu, 21 May 2009 06:08:25 +0000 Subject: [PATCH] Synchronize code with specs. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8366 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Include/Protocol/AcpiS3Save.h | 89 +++++++++++++++++-- .../Include/Protocol/AcpiSupport.h | 14 ++- IntelFrameworkPkg/Include/Protocol/CpuIo.h | 1 - .../Include/Protocol/FrameworkFormBrowser.h | 4 +- .../Include/Protocol/FrameworkFormCallback.h | 2 +- .../Include/Protocol/FrameworkHii.h | 2 +- .../Include/Protocol/IdeControllerInit.h | 3 +- .../PciHostBridgeResourceAllocation.h | 4 +- .../Include/Protocol/SmmUsbDispatch.h | 11 +++ 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; -- 2.39.2