From 5259c97d7ac7f464c134c3a15186b30e8e8eadff Mon Sep 17 00:00:00 2001 From: pkandel Date: Tue, 28 Jul 2009 13:25:37 +0000 Subject: [PATCH] Committing changes to the comments, after review with engineers. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@9018 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Include/Framework/FirmwareVolumeHeader.h | 2 +- .../FrameworkInternalFormRepresentation.h | 4 +- IntelFrameworkPkg/Include/Framework/PeiCis.h | 8 +- IntelFrameworkPkg/Include/Framework/SmmCis.h | 24 ++--- IntelFrameworkPkg/Include/Guid/Capsule.h | 12 +-- IntelFrameworkPkg/Include/Library/SmmLib.h | 2 +- .../Include/Ppi/BootScriptExecuter.h | 2 +- IntelFrameworkPkg/Include/Ppi/FindFv.h | 4 +- IntelFrameworkPkg/Include/Ppi/PciCfg.h | 2 +- .../Include/Ppi/ReadOnlyVariable.h | 4 +- .../Include/Ppi/SectionExtraction.h | 6 +- IntelFrameworkPkg/Include/Ppi/Smbus.h | 32 ++++--- .../Include/Protocol/AcpiS3Save.h | 59 ++++++------- .../Include/Protocol/AcpiSupport.h | 12 +-- .../Include/Protocol/BootScriptSave.h | 2 +- IntelFrameworkPkg/Include/Protocol/CpuIo.h | 8 +- IntelFrameworkPkg/Include/Protocol/DataHub.h | 21 +++-- .../Include/Protocol/FirmwareVolume.h | 40 ++++----- .../Protocol/FrameworkFirmwareVolumeBlock.h | 10 +-- .../Include/Protocol/FrameworkFormBrowser.h | 10 +-- .../Include/Protocol/FrameworkFormCallback.h | 6 +- .../Include/Protocol/FrameworkHii.h | 88 ++++--------------- .../Include/Protocol/Legacy8259.h | 2 +- .../Include/Protocol/LegacyBios.h | 32 +++---- .../Include/Protocol/LegacyBiosPlatform.h | 58 ++++++------ .../Include/Protocol/SectionExtraction.h | 10 +-- .../Include/Protocol/SmmAccess.h | 2 +- IntelFrameworkPkg/Include/Protocol/SmmBase.h | 34 +++---- .../Include/Protocol/SmmControl.h | 21 +++-- .../Include/Protocol/SmmGpiDispatch.h | 7 +- .../Include/Protocol/SmmIchnDispatch.h | 4 +- .../Protocol/SmmPeriodicTimerDispatch.h | 11 ++- .../Include/Protocol/SmmPowerButtonDispatch.h | 7 +- .../Protocol/SmmStandbyButtonDispatch.h | 9 +- .../Include/Protocol/SmmSwDispatch.h | 9 +- .../Include/Protocol/SmmSxDispatch.h | 8 +- 36 files changed, 248 insertions(+), 324 deletions(-) diff --git a/IntelFrameworkPkg/Include/Framework/FirmwareVolumeHeader.h b/IntelFrameworkPkg/Include/Framework/FirmwareVolumeHeader.h index d5d432efaa..7a41d48522 100644 --- a/IntelFrameworkPkg/Include/Framework/FirmwareVolumeHeader.h +++ b/IntelFrameworkPkg/Include/Framework/FirmwareVolumeHeader.h @@ -1,6 +1,6 @@ /** @file Defines data structure that is the volume header found at the beginning of - all firmware volumes that are either memory mapped, or have an + all firmware volumes that are either memory mapped or have an associated FirmwareVolumeBlock protocol. Copyright (c) 2006-2009, Intel Corporation diff --git a/IntelFrameworkPkg/Include/Framework/FrameworkInternalFormRepresentation.h b/IntelFrameworkPkg/Include/Framework/FrameworkInternalFormRepresentation.h index a00b7cf1d8..925defebf3 100644 --- a/IntelFrameworkPkg/Include/Framework/FrameworkInternalFormRepresentation.h +++ b/IntelFrameworkPkg/Include/Framework/FrameworkInternalFormRepresentation.h @@ -95,7 +95,7 @@ typedef UINT16 STRING_REF; /// /// Used to flag dynamically created op-codes. This is meaningful to the IFR Library set /// and the browser since we need to distinguish between compiled NV map data and created data. -/// We do not allow new entries to be created in the NV map dynamically however we still need +/// We do not allow new entries to be created in the NV map dynamically, but we do need /// to display this information correctly. To dynamically create op-codes and assume that their /// data will be saved, ensure that the NV starting location they refer to is pre-defined in the /// NV map. @@ -222,7 +222,7 @@ typedef struct { // // There is an interesting twist with regards to Time and Date. This is one of the few items which can accept input -// from a user, however may or may not need to use storage in the NVRAM space. The decided method for determining +// from a user, and may or may not need to use storage in the NVRAM space. The decided method for determining // if NVRAM space will be used (only for a TimeOp or DateOp) is: If .QuestionId == 0 && .Width == 0 (normally an // impossibility) then use system resources to store the data away and not NV resources. In other words, the setup // engine will call gRT->SetTime, and gRT->SetDate for the saving of data, and the values displayed will be from the diff --git a/IntelFrameworkPkg/Include/Framework/PeiCis.h b/IntelFrameworkPkg/Include/Framework/PeiCis.h index db0b185a1f..042ec269fe 100644 --- a/IntelFrameworkPkg/Include/Framework/PeiCis.h +++ b/IntelFrameworkPkg/Include/Framework/PeiCis.h @@ -52,7 +52,7 @@ EFI_STATUS ); /** - The purpose of the service is to abstract the capability of the PEI + This service abstracts the capability of the PEI Foundation to discover instances of firmware volumes in the system. Given the input file pointer, this service searches for the next matching file in the Firmware File System (FFS) volume. @@ -75,16 +75,16 @@ EFI_STATUS ); /** - The purpose of the service is to abstract the capability of the PEI + This service abstracts the capability of the PEI Foundation to discover instances of firmware files in the system. Given the input file pointer, this service searches for the next matching file in the Firmware File System (FFS) volume. @param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation. @param SearchType A filter to find files only of this type. - @param FwVolHeader Pointer to the firmware volume header of the volume to search.This parameter + @param FwVolHeader Pointer to the firmware volume header of the volume to search. This parameter must point to a valid FFS volume. - @param FileHeader Pointer to the current file from which to begin searching.This pointer will be + @param FileHeader Pointer to the current file from which to begin searching. This pointer will be updated upon return to reflect the file found. @retval EFI_SUCCESS The file was found. diff --git a/IntelFrameworkPkg/Include/Framework/SmmCis.h b/IntelFrameworkPkg/Include/Framework/SmmCis.h index b580dbe639..708e4b1c59 100644 --- a/IntelFrameworkPkg/Include/Framework/SmmCis.h +++ b/IntelFrameworkPkg/Include/Framework/SmmCis.h @@ -51,8 +51,8 @@ typedef enum { @param Width Signifies the width of the I/O operations. @param Address The base address of the I/O operations. @param Count The number of I/O operations to perform. - @param Buffer For read operations, the destination buffer to store the results. - For write operations, the source buffer from which to write data. + @param Buffer For read operations, the destination buffer to store the results (out parameter). + For write operations, the source buffer from which to write data (in parameter). @retval EFI_SUCCESS The data was read from or written to the device. @retval EFI_UNSUPPORTED The Address is not valid for this system. @@ -94,7 +94,7 @@ struct _EFI_SMM_CPU_IO_INTERFACE { Allocates pool memory from SMRAM for IA-32 or runtime memory for the Itanium processor family. - @param PoolType The type of pool to allocate.The only supported type is EfiRuntimeServicesData + @param PoolType The type of pool to allocate. The only supported type is EfiRuntimeServicesData @param Size The number of bytes to allocate from the pool. @param Buffer A pointer to a pointer to the allocated buffer if the call succeeds; undefined otherwise. @@ -123,8 +123,8 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER Buffer was invalid. @retval EFI_UNSUPPORTED In runtime. @note: Inconsistent with specification here: - In Framework Spec, This definition is naming EFI_SMM_FREE_POOL However, - To avoid the naming conflict, the definition is renamed. + In the Framework Spec, this definition is named EFI_SMM_FREE_POOL. + To avoid a naming conflict, the definition here is renamed. **/ typedef EFI_STATUS @@ -148,8 +148,8 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER Type is not AllocateAnyPages or AllocateMaxAddress or AllocateAddress. Or MemoryType is in the range EfiMaxMemoryType..0x7FFFFFFF. @note: Inconsistent with specification here: - In Framework Spec, This definition is naming EFI_SMM_ALLOCATE_PAGES However, - To avoid the naming conflict, the definition is renamed. + In the Framework Spec, this definition is named EFI_SMM_ALLOCATE_PAGES. + To avoid a naming conflict, the definition here is renamed. **/ typedef EFI_STATUS @@ -171,8 +171,8 @@ EFI_STATUS @retval EFI_NOT_FOUND The requested memory pages were not allocated with SmmAllocatePages(). @note: Inconsistent with specification here: - In Framework Spec, This definition is naming EFI_SMM_FREE_PAGES However, - To avoid the naming conflict, the definition is renamed. + In the Framework Spec, this definition is named EFI_SMM_FREE_PAGES. + To avoid a naming conflict, the definition here is renamed. **/ typedef EFI_STATUS @@ -197,8 +197,8 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER The CPU cannot support an additional service invocation. @note: Inconsistent with specification here: - In Framework Spec, No this definition. This method is introduced in PI1.0 spec for - implementation needed. + In Framework Spec, this definition does not exist. This method is introduced in PI1.0 spec for + implementation needs. **/ typedef @@ -592,7 +592,7 @@ struct _EFI_SMM_SYSTEM_TABLE { // ///Inconsistent with specification here: - /// In Framework Spec, No this definition. This method is introduced in PI1.0 spec for + /// In Framework Spec, this definition does not exist. This method is introduced in PI1.0 spec for /// implementation needed. EFI_SMM_STARTUP_THIS_AP SmmStartupThisAp; diff --git a/IntelFrameworkPkg/Include/Guid/Capsule.h b/IntelFrameworkPkg/Include/Guid/Capsule.h index 53fb956fe6..6413cbabf4 100644 --- a/IntelFrameworkPkg/Include/Guid/Capsule.h +++ b/IntelFrameworkPkg/Include/Guid/Capsule.h @@ -36,14 +36,14 @@ /// /// Bits in the flags field of the capsule header -/// This flag is set if the capsule can support setup changes and clear if it cannot. +/// This flag is set if the capsule can support setup changes, and cleared if it cannot. /// #define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001 #define CAPSULE_BLOCK_DESCRIPTOR_SIGNATURE SIGNATURE_32 ('C', 'B', 'D', 'S') // -// An array of these describe the blocks that make up a capsule for +// An array of these structs describe the blocks that make up a capsule for // a capsule update. // typedef struct { @@ -71,14 +71,14 @@ typedef struct { /// UINT32 HeaderSize; /// - /// A bit-mapped list describing the capsule¡¯s attributes. + /// A bit-mapped list describing the capsule's attributes. /// All undefined bits should be written as zero (0) /// UINT32 Flags; /// /// The length in bytes (27,415 for an image containing 27,415 bytes) of the entire image - /// including all headers. If the this value is greater than the size of the data presented in - /// the capsule body, this means that the image is separated across multiple media. If this + /// including all headers. If this value is greater than the size of the data presented in + /// the capsule body, the image is separated across multiple media. If this /// value is less than the size of the data, it is an error. /// UINT32 CapsuleImageSize; @@ -119,7 +119,7 @@ typedef struct { UINT32 OffsetToAuthorInformation; /// /// The offset in bytes from the beginning of the header to the start of human-readable - /// text that describes the revision of the capsule and/or the capsule¡¯s contents. This + /// text that describes the revision of the capsule and/or the capsule's contents. This /// value must be less than OffsetToCapsuleBody. /// UINT32 OffsetToRevisionInformation; diff --git a/IntelFrameworkPkg/Include/Library/SmmLib.h b/IntelFrameworkPkg/Include/Library/SmmLib.h index ba1cb437bd..2857afce29 100644 --- a/IntelFrameworkPkg/Include/Library/SmmLib.h +++ b/IntelFrameworkPkg/Include/Library/SmmLib.h @@ -51,7 +51,7 @@ TriggerRuntimeSoftwareSmi ( it was triggered at boot time, it returns TRUE. Otherwise, it returns FALSE. @retval TRUE A software SMI triggered at boot time happened. - @retval FLASE No software SMI happened or the software SMI was triggered at run time. + @retval FLASE No software SMI happened, or the software SMI was triggered at run time. **/ BOOLEAN diff --git a/IntelFrameworkPkg/Include/Ppi/BootScriptExecuter.h b/IntelFrameworkPkg/Include/Ppi/BootScriptExecuter.h index 0976deb840..9f5ca5054d 100644 --- a/IntelFrameworkPkg/Include/Ppi/BootScriptExecuter.h +++ b/IntelFrameworkPkg/Include/Ppi/BootScriptExecuter.h @@ -3,7 +3,7 @@ This PPI is published by a PEIM upon dispatch and provides an execution engine for the Framework boot script. This PEIM should be platform neutral and have no specific knowledge of - platform instructions and other information. The ability to interpret the boot script depends on the + platform instructions or other information. The ability to interpret the boot script depends on the abundance of other PPIs that are available. For example, if the script requests an SMBus command execution, the PEIM looks for a relevant PPI that is available to execute it, rather than executing it by issuing the native IA-32 instruction. diff --git a/IntelFrameworkPkg/Include/Ppi/FindFv.h b/IntelFrameworkPkg/Include/Ppi/FindFv.h index a130cc5cd1..40c3177f9f 100644 --- a/IntelFrameworkPkg/Include/Ppi/FindFv.h +++ b/IntelFrameworkPkg/Include/Ppi/FindFv.h @@ -21,7 +21,7 @@ /// /// Inconsistent with specification here: -/// GUID value format has been changed to the standard guid format. +/// GUID value format has been changed to the standard GUID format. /// #define EFI_PEI_FIND_FV_PPI_GUID \ { \ @@ -32,7 +32,7 @@ typedef struct _EFI_PEI_FIND_FV_PPI EFI_PEI_FIND_FV_PPI; /** This interface returns the base address of the firmware volume whose index - was passed in FvNumber.Once this function reports a firmware volume + was passed in FvNumber. Once this function reports a firmware volume index/base address pair, that index/address pairing must continue throughout PEI. @param PeiServices Pointer to the PEI Services Table. diff --git a/IntelFrameworkPkg/Include/Ppi/PciCfg.h b/IntelFrameworkPkg/Include/Ppi/PciCfg.h index 09ec3d9cea..708e51280d 100644 --- a/IntelFrameworkPkg/Include/Ppi/PciCfg.h +++ b/IntelFrameworkPkg/Include/Ppi/PciCfg.h @@ -1,5 +1,5 @@ /** @file - This file declares PciCfg PPI used to access PCI configuration space in PEI + This file declares the PciCfg PPI used to access the PCI configuration space in PEI Copyright (c) 2006 - 2009, Intel Corporation All rights reserved. This program and the accompanying materials diff --git a/IntelFrameworkPkg/Include/Ppi/ReadOnlyVariable.h b/IntelFrameworkPkg/Include/Ppi/ReadOnlyVariable.h index d99de161a7..62e98a8aeb 100644 --- a/IntelFrameworkPkg/Include/Ppi/ReadOnlyVariable.h +++ b/IntelFrameworkPkg/Include/Ppi/ReadOnlyVariable.h @@ -1,5 +1,5 @@ /** @file - This file declares Read-only Variable Service PPI, which is required PPI by framework spec. + This file declares the Read-only Variable Service PPI, which is required by the framework spec. These services provide a lightweight, read-only variant of the full EFI variable services. The reason that these services are read-only is to reduce the complexity of flash management. Also, @@ -79,7 +79,7 @@ EFI_STATUS /** This function can be called multiple times to retrieve the VariableName and VendorGuid of all variables currently available in the system. On each call - to GetNextVariableName() the previous results are passed into the interface, + to GetNextVariableName(), the previous results are passed into the interface, and on output the interface returns the next variable name data. When the entire variable list has been returned, the error EFI_NOT_FOUND is returned. diff --git a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h b/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h index 4489c18ba2..e2885b42e5 100644 --- a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h +++ b/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h @@ -52,8 +52,8 @@ typedef struct _EFI_PEI_SECTION_EXTRACTION_PPI EFI_PEI_SECTION_EXTRACTION_PPI; instance of the requested section type to return. @param Buffer Pointer to a pointer to a buffer in which the section contents are returned. - @param BufferSize A pointer to a caller-allocated UINT32.On input, *BufferSize - indicates the size in bytes of the memory region pointed to by Buffer.On output, + @param BufferSize A pointer to a caller-allocated UINT32. On input, *BufferSize + indicates the size in bytes of the memory region pointed to by Buffer. On output, *BufferSize contains the number of bytes required to read the section. @param AuthenticationStatus A pointer to a caller-allocated UINT32 in which any metadata from encapsulating GUID-defined sections is returned. @@ -63,7 +63,7 @@ typedef struct _EFI_PEI_SECTION_EXTRACTION_PPI EFI_PEI_SECTION_EXTRACTION_PPI; @retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered in the file with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set, but there was no corresponding GUIDed Section Extraction Protocol in the - handle database.*Buffer is unmodified. + handle database. *Buffer is unmodified. @retval EFI_NOT_FOUND The requested section does not exist.*Buffer is unmodified. @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process the request. @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist. diff --git a/IntelFrameworkPkg/Include/Ppi/Smbus.h b/IntelFrameworkPkg/Include/Ppi/Smbus.h index 3833937adb..8834bd2a7d 100644 --- a/IntelFrameworkPkg/Include/Ppi/Smbus.h +++ b/IntelFrameworkPkg/Include/Ppi/Smbus.h @@ -1,5 +1,5 @@ /** @file - This file declares Smbus PPI which provides the basic I/O interfaces that a PEIM + This file declares the Smbus PPI, which provides the basic I/O interfaces that a PEIM uses to access its SMBus controller and the slave devices attached to it. Copyright (c) 2007 - 2009, Intel Corporation @@ -40,10 +40,10 @@ typedef struct _EFI_PEI_SMBUS_PPI EFI_PEI_SMBUS_PPI; controller to the SMBus slave device and the interpretation is SMBus slave device specific. @param[in] Operation Signifies which particular SMBus hardware protocol - instance that it will use to execute the SMBus transactions. + instance to use to execute the SMBus transactions. @param[in] PecCheck Defines if Packet Error Code (PEC) checking is required for this operation. - @param[in, out] Length Signifies the number of bytes that this operation will do. + @param[in, out] Length The number of bytes for this operation @param[in, out] Buffer Contains the value of data to execute to the SMBus slave device. @retval EFI_SUCCESS The last data that was returned from the access @@ -54,7 +54,7 @@ typedef struct _EFI_PEI_SMBUS_PPI EFI_PEI_SMBUS_PPI; @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_DEVICE_ERROR The request was not completed because - a failure reflected in the Host Status Register bit. + a failure was recorded in the Host Status Register bit. @retval EFI_INVALID_PARAMETER Operation is not defined in EFI_SMBUS_OPERATION. @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for operations except for EfiSmbusQuickRead and EfiSmbusQuickWrite. Length is outside the range of valid values. @@ -76,15 +76,13 @@ EFI_STATUS ); /** - CallBack function can be registered in EFI_PEI_SMBUS_PPI_NOTIFY. - - This function is user-defined and will called when the SlaveAddress/Data pair happens. + This function is user-defined, and is called when the SlaveAddress/Data pair happens. @param[in] PeiServices A pointer to the system PEI Services Table. @param[in] This A pointer to the EFI_PEI_SMBUS_PPI instance. @param[in] SlaveAddress The SMBUS hardware address to which the SMBUS device is preassigned or allocated. - @param[in] Data Data of the SMBus host notify command that + @param[in] Data Data of the SMBus host notify command, which denotes that the caller wants to be called. @return Status Code returned by callback function. @@ -100,14 +98,14 @@ EFI_STATUS ); /** - The ArpDevice() function enumerates the entire bus or enumerates a specific - device that is identified by SmbusUdid. + The ArpDevice() function enumerates either the entire bus or a specific + device identified by SmbusUdid. @param[in] PeiServices A pointer to the system PEI Services Table. @param[in] This A pointer to the EFI_PEI_SMBUS_PPI instance. @param[in] ArpAll A Boolean expression that indicates if the host drivers need to enumerate all the devices or enumerate only the device that is identified - by SmbusUdid. If ArpAll is TRUE, SmbusUdid and SlaveAddress are optional. + by SmbusUdid. If ArpAll is TRUE, SmbusUdid and SlaveAddress are optional and ignored if entered. If ArpAll is FALSE, ArpDevice will enumerate SmbusUdid and the address will be at SlaveAddress. @param[in] SmbusUdid The targeted SMBus Unique Device Identifier (UDID). @@ -122,9 +120,9 @@ EFI_STATUS due to a lack of resources. @retval EFI_TIMEOUT The SMBus slave device did not respond. @retval EFI_DEVICE_ERROR The request was not completed because the transaction failed. - @retval EFI_UNSUPPORTED ArpDevice() are not implemented by this PEIM. + @retval EFI_UNSUPPORTED ArpDevice() is not implemented by this PEIM. This return value is not defined in Framwork Specification. - This return value had been intruduced in PI Specification. + This return value was introduced in the PI Specification. **/ typedef @@ -150,7 +148,7 @@ EFI_STATUS @retval EFI_SUCCESS The device map was returned correctly in the buffer. @retval EFI_UNSUPPORTED GetArpMap() are not implemented by this PEIM. This return value was not defined in Framwork Specification. - This return value had been intruduced in PI Specification. + This return value was introduced in the PI Specification. **/ typedef @@ -174,16 +172,16 @@ EFI_STATUS @param[in] PeiServices A pointer to the system PEI Services Table. @param[in] This A pointer to the EFI_PEI_SMBUS_PPI instance. @param[in] SlaveAddress Address that the host controller detects as - sending a message and calls all the registered functions. + sending a message and triggers all the registered functions. @param[in] Data Data that the host controller detects as sending a message - and calls all the registered functions. + and triggers all the registered functions. @param[in] NotifyFunction The function to call when the bus driver detects the SlaveAddress and Data pair. @retval EFI_SUCCESS NotifyFunction has been registered. @retval EFI_UNSUPPORTED Notify() are not implemented by this PEIM. This return value is not defined in Framwork Specification. - This return value had been intruduced in PI Specification. + This return value was introduced in the PI Specification. **/ typedef diff --git a/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h b/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h index 0e095f8148..de68e324ee 100644 --- a/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h +++ b/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h @@ -38,30 +38,7 @@ typedef struct _EFI_ACPI_S3_SAVE_PROTOCOL EFI_ACPI_S3_SAVE_PROTOCOL; // /** - 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)( - IN EFI_ACPI_S3_SAVE_PROTOCOL * This, - IN VOID * LegacyMemoryAddress - ); - -/** - This function is used to do the following: + This function is used to: - Prepare all information that is needed in the S3 resume boot path. This information can include the following: @@ -69,7 +46,7 @@ EFI_STATUS -- 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. + - Get the minimum legacy memory length (meaning 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 @@ -82,8 +59,31 @@ EFI_STATUS @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. - + @retval EFI_NOT_FOUND Some necessary information cannot be found. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_ACPI_S3_SAVE)( + IN EFI_ACPI_S3_SAVE_PROTOCOL * This, + IN VOID * LegacyMemoryAddress + ); + +/** + This function returns the size of the legacy memory (meaning 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. After getting the size of legacy memory + below, 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 Size 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 @@ -100,9 +100,8 @@ EFI_STATUS - 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. + that no hardware has been left unconfigured. Where to call this protocol to save information is implementation-specific. + 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. diff --git a/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h b/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h index 6573b5a9f8..d24a052823 100644 --- a/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h +++ b/IntelFrameworkPkg/Include/Protocol/AcpiSupport.h @@ -1,8 +1,8 @@ /** @file 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. The - services will do the following: - - Generate common tables. + services will: + - Generate common tables. - Update the table links. - Ensure that tables are properly aligned and use correct types of memory. - Update checksum values and IDs. @@ -50,10 +50,10 @@ typedef struct _EFI_ACPI_SUPPORT_PROTOCOL EFI_ACPI_SUPPORT_PROTOCOL; // that is not part of the ACPI "tree" but must still be found // in ACPI memory space and/or managed by the core ACPI driver. // -// Note that EFI provides discrete GUIDs for each version of ACPI -// that is supported. It is expected that each EFI GUIDed +// Note that EFI provides discrete GUIDs for each supported version of ACPI. +// It is expected that each EFI GUIDed // version of ACPI will also have a corresponding bitmap -// definition. This allows maintenance of separate ACPI trees +// definition. This bitmap definition enables maintenance of separate ACPI trees // for each distinctly different version of ACPI. // #define EFI_ACPI_TABLE_VERSION UINT32 @@ -125,7 +125,7 @@ EFI_STATUS 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. + @param Version Indicates to which version(s) of ACPI the table should be published. @retval EFI_SUCCESS The function completed successfully. @retval EFI_ABORTED An error occurred and the function could not complete successfully. diff --git a/IntelFrameworkPkg/Include/Protocol/BootScriptSave.h b/IntelFrameworkPkg/Include/Protocol/BootScriptSave.h index 62ea4cbd54..eb0c2925c1 100644 --- a/IntelFrameworkPkg/Include/Protocol/BootScriptSave.h +++ b/IntelFrameworkPkg/Include/Protocol/BootScriptSave.h @@ -33,7 +33,7 @@ typedef struct _EFI_BOOT_SCRIPT_SAVE_PROTOCOL EFI_BOOT_SCRIPT_SAVE_PROTOCOL; Adds a record into a specified Framework boot script table. @param This A pointer to the EFI_BOOT_SCRIPT_SAVE_PROTOCOL instance. - @param TableName Name of the script table.Currently, the only meaningful + @param TableName Name of the script table. Currently, the only meaningful value is EFI_ACPI_S3_RESUME_SCRIPT_TABLE. @param OpCode The operation code (opcode) number. @param ... Argument list that is specific to each opcode. diff --git a/IntelFrameworkPkg/Include/Protocol/CpuIo.h b/IntelFrameworkPkg/Include/Protocol/CpuIo.h index f1855e2aa1..52658806ea 100644 --- a/IntelFrameworkPkg/Include/Protocol/CpuIo.h +++ b/IntelFrameworkPkg/Include/Protocol/CpuIo.h @@ -49,18 +49,18 @@ typedef enum { /** Enables a driver to access memory-mapped registers in the EFI system memory space. - Or, Enables a driver to access registers in the EFI CPU I/O space. + Or, enables a driver to access registers in the EFI CPU I/O space. @param[in] This A pointer to the EFI_CPU_IO_PROTOCOL instance. @param[in] Width Signifies the width of the I/O or Memory operation. - @param[in] Address The base address of the I/O or Memoryoperation. + @param[in] Address The base address of the I/O or Memory operation. @param[in] Count The number of I/O or Memory operations to perform. The number of bytes moved is Width size * Count, starting at Address. @param[in, out] Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer from which to write data. @retval EFI_SUCCESS The data was read from or written to the EFI system. - @retval EFI_INVALID_PARAMETER Width is invalid for this EFI system.Or Buffer is NULL. + @retval EFI_INVALID_PARAMETER Width is invalid for this EFI system. Or Buffer is NULL. @retval EFI_UNSUPPORTED The Buffer is not aligned for the given Width. Or,The address range specified by Address, Width, and Count is not valid for this EFI system. @@ -76,7 +76,7 @@ EFI_STATUS ); /// -/// Servies for read and write accesses. +/// Service for read and write accesses. /// typedef struct { /// diff --git a/IntelFrameworkPkg/Include/Protocol/DataHub.h b/IntelFrameworkPkg/Include/Protocol/DataHub.h index d0db839794..d6e7647ca7 100644 --- a/IntelFrameworkPkg/Include/Protocol/DataHub.h +++ b/IntelFrameworkPkg/Include/Protocol/DataHub.h @@ -31,9 +31,8 @@ // A Data Record is an EFI_DATA_RECORD_HEADER followed by RecordSize bytes of // data. The format of the data is defined by the DataRecordGuid. // -// If EFI_DATA_RECORD_HEADER is extended in the future the Version number must -// change and the HeaderSize will change if the definition of -// EFI_DATA_RECORD_HEADER is extended. +// If EFI_DATA_RECORD_HEADER is extended in the future, the Version number and HeaderSize must +// change. // // The logger is responcible for initializing: // Version, HeaderSize, RecordSize, DataRecordGuid, DataRecordClass @@ -56,7 +55,7 @@ typedef struct { // // Definition of DataRecordClass. These are used to filter out class types // at a very high level. The DataRecordGuid still defines the format of -// the data. See DateHub.doc for rules on what can and can not be a +// the data. See the Data Hub Specification for rules on what can and can not be a // new DataRecordClass // #define EFI_DATA_RECORD_CLASS_DEBUG 0x0000000000000001 @@ -99,7 +98,7 @@ EFI_STATUS @param This The EFI_DATA_HUB_PROTOCOL instance. @param MonotonicCount On input, it specifies the Record to return. - An input of zero means to return the first record. + An input of zero means to return the first record, as does an input of one. @param FilterDriver If FilterDriver is not passed in a MonotonicCount of zero, it means to return the first data record. If FilterDriver is passed in, then a MonotonicCount of zero means to return the first data not yet read @@ -115,8 +114,8 @@ EFI_STATUS @retval EFI_OUT_OF_RESOURCES Record was not returned due to lack of system resources. @note: Inconsistent with specification here: - In Framework for EFI Data Hub Specification,Version 0.9, This definition is named as - EFI_DATA_HUB_GET_NEXT_DATA_RECORD. The inconsistance is remained for backward compatibility + In Framework for EFI Data Hub Specification, Version 0.9, This definition is named as + EFI_DATA_HUB_GET_NEXT_DATA_RECORD. The inconsistency is maintained for backward compatibility. **/ typedef EFI_STATUS @@ -147,8 +146,8 @@ EFI_STATUS @retval EFI_OUT_OF_RESOURCES The filter driver event was not registered due to lack of system resources. @note: Inconsistent with specification here: - In Framework for EFI Data Hub Specification,Version 0.9, This definition is named as - EFI_DATA_HUB_REGISTER_DATA_FILTER_DRIVER. The inconsistance is remained for backward compatibility + In Framework for EFI Data Hub Specification, Version 0.9, This definition is named as + EFI_DATA_HUB_REGISTER_DATA_FILTER_DRIVER. The inconsistency is maintained for backward compatibility. **/ typedef EFI_STATUS @@ -170,8 +169,8 @@ EFI_STATUS @retval EFI_SUCCESS The filter driver represented by FilterEvent was shut off. @retval EFI_NOT_FOUND FilterEvent did not exist. @note: Inconsistent with specification here: - In Framework for EFI Data Hub Specification,Version 0.9, This definition is named as - EFI_DATA_HUB_UNREGISTER_DATA_FILTER_DRIVER. The inconsistance is remained for backward compatibility + In Framework for EFI Data Hub Specification, Version 0.9, This definition is named as + EFI_DATA_HUB_UNREGISTER_DATA_FILTER_DRIVER. The inconsistency is maintained for backward compatibility. **/ typedef EFI_STATUS diff --git a/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h b/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h index 981fb57704..8e6f450c6c 100644 --- a/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h +++ b/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h @@ -83,11 +83,11 @@ typedef UINT64 FRAMEWORK_EFI_FV_ATTRIBUTES; // /** - Retrieves attributes, insures positive polarity of attribute bits, returns + Retrieves attributes, insures positive polarity of attribute bits, and returns resulting attributes in output parameter @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. - @param Attributes output buffer which contains attributes + @param Attributes Output buffer containing attributes @retval EFI_SUCCESS The firmware volume attributes were returned. **/ @@ -104,7 +104,7 @@ EFI_STATUS @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. @param Attributes On input, Attributes is a pointer to an EFI_FV_ATTRIBUTES containing the desired firmware - volume settings.O n successful return, it contains + volume settings. On successful return, it contains the new settings of the firmware volume. On unsuccessful return, Attributes is not modified and the firmware volume settings are not changed. @@ -113,7 +113,7 @@ EFI_STATUS @retval EFI_SUCCESS The requested firmware volume attributes were set and the resulting EFI_FV_ATTRIBUTES is returned in Attributes. - @retval EFI_ACCESS_DENIED the Device is locked and does not permit modification. + @retval EFI_ACCESS_DENIED The Device is locked and does not permit modification. **/ typedef @@ -127,8 +127,8 @@ EFI_STATUS Read the requested file (NameGuid) or file information from the firmware volume and returns data in Buffer. - @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. - @param NameGuid pointer to EFI_GUID which is the filename identifying which file to read + @param This The EFI_FIRMWARE_VOLUME_PROTOCOL instance. + @param NameGuid Pointer to EFI_GUID, which is the filename of the file to read @param Buffer Pointer to pointer to buffer in which contents of file are returned.
If Buffer is NULL, only type, attributes, and size are returned as @@ -139,18 +139,18 @@ EFI_STATUS
If Buffer != NULL and *Buffer != NULL, the output buffer has been allocated by the caller and is being passed in. - @param BufferSize Indicates the buffer size passed in, and on output the size + @param BufferSize On input: The buffer size. On output: The size required to complete the read - @param FoundType pointer to type of the file who's data is returned - @param FileAttributes pointer to attributes of the file who's data is resturned - @param AuthenticationStatus pointer to authentication status of the data + @param FoundType Pointer to type of the file whose data is returned + @param FileAttributes Pointer to attributes of the file whose data is returned + @param AuthenticationStatus Pointer to authentication status of the data @retval EFI_SUCCESS The call completed successfully @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output. The buffer is filled and the output is truncated. - @retval EFI_NOT_FOUND NameGuid was not found int he firmware volume. + @retval EFI_NOT_FOUND NameGuid was not found in the firmware volume. @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access the firmware volume. - @retval EFI_ACCESS_DENIED The firmware volumen is configured to disallow reads. + @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads. @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. **/ @@ -171,8 +171,8 @@ EFI_STATUS @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. @param NameGuid Filename identifying the file from which to read - @param SectionType Indicates what section type to retrieve - @param SectionInstance Indicates which instance of SectionType to retrieve + @param SectionType The section type to retrieve + @param SectionInstance The instance of SectionType to retrieve @param Buffer Pointer to pointer to buffer in which contents of file are returned.
If Buffer is NULL, only type, attributes, and size are returned as @@ -183,9 +183,9 @@ EFI_STATUS
If Buffer != NULL and *Buffer != NULL, the output buffer has been allocated by the caller and is being passed in. - @param BufferSize pointer to the buffer size passed in, and on output the size + @param BufferSize Pointer to the buffer size passed in, and on output the size required to complete the read - @param AuthenticationStatus pointer to the authentication status of the data + @param AuthenticationStatus Pointer to the authentication status of the data @retval EFI_SUCCESS The call completed successfully. @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output. @@ -259,10 +259,10 @@ EFI_STATUS @param Key Pointer to a caller allocated buffer that contains an implementation specific key that is used to track where to begin searching on successive calls. - @param FileType pointer to the file type to filter for - @param NameGuid pointer to Guid filename of the file found - @param Attributes pointer to Attributes of the file found - @param Size pointer to Size in bytes of the file found + @param FileType Pointer to the file type to filter for + @param NameGuid Pointer to Guid filename of the file found + @param Attributes Pointer to Attributes of the file found + @param Size Pointer to Size in bytes of the file found @retval EFI_SUCCESS The output parameters are filled with data obtained from the first matching file that was found. diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h index 8ad5b1f1e2..1404e0583c 100644 --- a/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h +++ b/IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h @@ -27,7 +27,7 @@ typedef UINT32 EFI_FVB_ATTRIBUTES; /** The GetAttributes() function retrieves the attributes and - current settings of the block. Status Codes Returned + current settings of the block. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance. @@ -228,10 +228,8 @@ EFI_STATUS @param Offset Offset into the block at which to begin writing. - @param NumBytes Pointer to a UINTN. At entry, *NumBytes - contains the total size of the buffer. At - exit, *NumBytes contains the total number of - bytes actually written. + @param NumBytes Pointer to a UINTN. Input: the total size of the buffer. + Output: the total number of bytes actually written. @param Buffer Pointer to a caller-allocated buffer that contains the source for the write. @@ -291,7 +289,7 @@ EFI_STATUS @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance. - @param ... The variable argument list is a list of tuples. + @param ... A list of tuples. Each tuple describes a range of LBAs to erase and consists of the following: - An EFI_LBA that indicates the starting LBA diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h index 9fca00f28f..4aa3dd1acb 100644 --- a/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h +++ b/IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h @@ -1,8 +1,8 @@ /** @file The EFI_FORM_BROWSER_PROTOCOL is the interface to the EFI - Configuration Driver. This will allow the caller to direct the - configuration driver to use either the HII database or use the passed - in packet of data. This will also allow the caller to post messages + Configuration Driver. This interface enables the caller to direct the + configuration driver to use either the HII database or the passed-in + packet of data. This will also allow the caller to post messages into the configuration drivers internal mailbox. Copyright (c) 2006 - 2009, Intel Corporation @@ -81,7 +81,7 @@ typedef struct { @param ScreenDimensions Allows the browser to be called so that it occupies a portion of the physical screen instead of dynamically determining the screen dimensions. - @param ResetRequired This BOOLEAN value will tell the caller if a reset + @param ResetRequired This BOOLEAN value denotes whether a reset is required based on the data that might have been changed. The ResetRequired parameter is primarily applicable for configuration applications, and is an optional parameter. @@ -149,7 +149,7 @@ EFI_STATUS struct _EFI_FORM_BROWSER_PROTOCOL { /// /// Provides direction to the configuration driver whether to use the HII - /// database or to use a passed-in set of data. This functions also establishes + /// database or to use a passed-in set of data. This function also establishes /// a pointer to the calling driver's callback interface. /// EFI_SEND_FORM SendForm; diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h index 8cc87d9052..82b9bc54bc 100644 --- a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h +++ b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h @@ -1,9 +1,9 @@ /** @file The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom - NV storage devices as well as communication of user selections in a more + NV storage devices and for communication of user selections in a more interactive environment. This protocol should be published by hardware - specific drivers which want to export access to custom hardware storage or - publish IFR which has a requirement to call back the original driver. + specific drivers that want to export access to custom hardware storage or + publish IFR that need to call back the original driver. Copyright (c) 2006 - 2009, Intel Corporation All rights reserved. This program and the accompanying materials diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h b/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h index ad951d7269..9dfa36b5b8 100644 --- a/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h +++ b/IntelFrameworkPkg/Include/Protocol/FrameworkHii.h @@ -1,6 +1,6 @@ /** @file - This file defines the Human Interface Infrastructure protocol which will - be used by resources which want to publish IFR/Font/String data and have it + This file defines the Human Interface Infrastructure protocol, which is + used by resources that want to publish IFR/Font/String data and have it collected by the Configuration engine. This protocol is defined in the. Intel Platform Innovation Framework for EFI Human Interface Infrastructure Specification Version 0.92. @@ -20,23 +20,10 @@ #define _FRAMEWORK_HII_H_ // -// To get EFI_GRAPHICS_OUTPUT_BLT_PIXEL, -// is defined in MdePkg/Protocol/GraphicsOutput.h +// EFI_GRAPHICS_OUTPUT_BLT_PIXEL is defined in MdePkg/Protocol/GraphicsOutput.h // #include - -/// -/// In both EDK and EDK II, incompatbile change is done to Framework HII protocol. -/// This change should cause a change of GUID in both of code and HII spec. But we -/// update the GUID in code in EDK and EDK II. The 0.92 spec is not updated. This -/// is a known issue. -/// -/// -/// Note that EFI_HII_PROTOCOL_GUID is different from that defined in the Framework HII -/// 0.92 spec because the spec changed part of HII interfaces but did not update the protocol -/// GUID. -/// -#define EFI_HII_PROTOCOL_GUID \ +////// In both EDK and EDK II, incompatbile change is done to Framework HII protocol. /// This change should cause a change of GUID in both of code and HII spec. But we /// update the GUID in code in EDK and EDK II. The 0.92 spec is not updated. This/// is a known issue.///////// Note that EFI_HII_PROTOCOL_GUID is different from that defined in the Framework HII/// 0.92 spec because the spec changed part of HII interfaces but did not update the protocol/// GUID.///#define EFI_HII_PROTOCOL_GUID \ { \ 0xd7ad636e, 0xb997, 0x459b, {0xbf, 0x3f, 0x88, 0x46, 0x89, 0x79, 0x80, 0xe1} \ } @@ -90,11 +77,7 @@ typedef struct { UINT16 Type; ///< The type of the package. } EFI_HII_PACK_HEADER; -/// -/// IFR package structure. -/// Immediately following the EFI_HII_IFR_PACK structure will be a series of IFR opcodes. -/// -typedef struct { +////// IFR package structure./// Immediately following the EFI_HII_IFR_PACK structure will be a series of IFR opcodes. ///typedef struct { EFI_HII_PACK_HEADER Header; ///< Header of the IFR package. } EFI_HII_IFR_PACK; @@ -102,15 +85,7 @@ typedef struct { /// HII Handle package structure. /// typedef struct { - /// - /// Header of the package. - /// - EFI_HII_PACK_HEADER Header; // Must be filled in - /// - /// The image handle of the driver to which the package is referring. - /// - EFI_HANDLE ImageHandle; // Must be filled in - /// + /// /// Header of the package. /// EFI_HII_PACK_HEADER Header; // Must be filled in /// /// The image handle of the driver to which the package is referring. /// EFI_HANDLE ImageHandle; // Must be filled in /// /// The handle of the device that is being described by this package. /// EFI_HANDLE DeviceHandle; // Optional @@ -279,18 +254,7 @@ typedef struct { // #define LANG_RIGHT_TO_LEFT 0x00000001 -/// -/// A string package is used to localize strings to a particular -/// language. The package is associated with a particular driver -/// or set of drivers. Tools are used to associate tokens with -/// string references in forms and in programs. These tokens are -/// language agnostic. When paired with a language pack (directly -/// or indirectly), the string token resolves into an actual -/// UNICODE string. The NumStringPointers determines how many -/// StringPointers (offset values) there are as well as the total -/// number of Strings that are defined. -/// -typedef struct { +////// A string package is used to localize strings to a particular/// language. The package is associated with a particular driver/// or set of drivers. Tools are used to associate tokens with/// string references in forms and in programs. These tokens are/// language agnostic. When paired with a language pack (directly/// or indirectly), the string token resolves into an actual/// UNICODE string. The NumStringPointers determines how many/// StringPointers (offset values) there are as well as the total/// number of Strings that are defined.///typedef struct { /// /// Header of the package. /// @@ -342,14 +306,7 @@ typedef struct { //EFI_WIDE_GLYPH WideGlyphs[]; } EFI_HII_FONT_PACK; -/// -/// The definition of a specific physical key -/// -/// Note: Name difference between code and the Framework HII 0.92 spec. -/// Add FRAMEWORK_ prefix to avoid name confict with EFI_KEY_DESCRIPTOR defined in the -/// UEFI 2.1d spec. -/// -typedef struct { +////// The definition of a specific physical key////// Note: Name difference between code and the Framework HII 0.92 spec./// Add FRAMEWORK_ prefix to avoid name confict with EFI_KEY_DESCRIPTOR defined in the/// UEFI 2.1d spec.///typedef struct { /// /// Used to describe a physical key on a keyboard. /// @@ -376,20 +333,7 @@ typedef struct { UINT16 Modifier; } FRAMEWORK_EFI_KEY_DESCRIPTOR; -/// -/// This structure allows a sparse set of keys to be redefined -/// or a complete redefinition of the keyboard layout. Most -/// keyboards have a lot of commonality in their layouts, therefore -/// only defining those keys that need to change from the default -/// minimizes the passed in information. -/// -/// Additionally, when an update occurs, the active keyboard layout -/// will be switched to the newly updated keyboard layout. This -/// allows for situations that when a keyboard layout driver is -/// loaded as part of system initialization, the system will default -/// the keyboard behavior to the new layout. -/// -typedef struct { +////// This structure allows a sparse set of keys to be redefined/// or a complete redefinition of the keyboard layout. Most/// keyboards have a lot of commonality in their layouts, therefore/// only defining those keys that need to change from the default/// minimizes the passed in information.////// Additionally, when an update occurs, the active keyboard layout/// will be switched to the newly updated keyboard layout. This/// allows for situations that when a keyboard layout driver is/// loaded as part of system initialization, the system will default/// the keyboard behavior to the new layout.///typedef struct { /// /// Header of the package. EFI_HII_PACK_HEADER Header; @@ -514,9 +458,9 @@ EFI_STATUS Exports the contents of the database into a buffer. @param This A pointer to the EFI_HII_PROTOCOL instance. - @param Handle An FRAMEWORK_EFI_HII_HANDLE that corresponds to the desired + @param Handle A FRAMEWORK_EFI_HII_HANDLE that corresponds to the desired handle to export. If the value is 0, the entire database will be exported. - In either case, the data will be exported in a format described by the + The data is exported in a format described by the structure definition of EFI_HII_EXPORT_TABLE. @param BufferSize On input, a pointer to the length of the buffer. On output, the length @@ -543,7 +487,7 @@ EFI_STATUS @param This A pointer to the EFI_HII_PROTOCOL instance. @param Handle The handle on which the string resides. - @retval EFI_SUCCESS Remove strings from the handle successfully. + @retval EFI_SUCCESS Successfully removed strings from the handle. @retval EFI_INVALID_PARAMETER The Handle was unknown. **/ @@ -591,7 +535,7 @@ EFI_STATUS @param This A pointer to the EFI_HII_PROTOCOL instance. @param Source A pointer to a Unicode string. @param Index On input, the offset into the string from which to fetch - the character.On successful completion, the index is updated to the first + the character. On successful completion, the index is updated to the first character past the character(s) making up the just extracted glyph. @param GlyphBuffer Pointer to an array where the glyphs corresponding to the characters in the source may be stored. GlyphBuffer is assumed @@ -636,8 +580,8 @@ EFI_STATUS @retval EFI_SUCCESS It worked. @retval EFI_NOT_FOUND A glyph for a character was not found. @note: Inconsistent with specification here: - In Framework Spec,HII spec 0.92. The type of 3rd, 4th and 8th parameter is EFI_UGA_PIXEL. - Here the definition use the EFI_GRAPHICS_OUTPUT_BLT_PIXEL which defined in UEFI2.1 spec + In Framework Spec, HII spec 0.92. The type of 3rd, 4th and 8th parameter is EFI_UGA_PIXEL. + Here the definition uses the EFI_GRAPHICS_OUTPUT_BLT_PIXEL, which is defined in UEFI 2.1 spec **/ typedef EFI_STATUS @@ -838,7 +782,7 @@ EFI_STATUS @param Handle The HII handle from which will have default data retrieved. @param DefaultMask The mask used to specify some type of default override when extracting the default image data. - @param VariablePackList A indirect pointer to the first entry of a link list with + @param VariablePackList An indirect pointer to the first entry of a link list with type EFI_HII_VARIABLE_PACK_LIST. @retval EFI_SUCCESS The VariablePackList was populated with the appropriate diff --git a/IntelFrameworkPkg/Include/Protocol/Legacy8259.h b/IntelFrameworkPkg/Include/Protocol/Legacy8259.h index 33d81b71cb..71406aad25 100644 --- a/IntelFrameworkPkg/Include/Protocol/Legacy8259.h +++ b/IntelFrameworkPkg/Include/Protocol/Legacy8259.h @@ -1,6 +1,6 @@ /** @file This protocol abstracts the 8259 interrupt controller. This includes - PCI IRQ routing need to program the PCI Interrupt Line register. + PCI IRQ routing needed to program the PCI Interrupt Line register. Copyright (c) 2007, Intel Corporation All rights reserved. This program and the accompanying materials diff --git a/IntelFrameworkPkg/Include/Protocol/LegacyBios.h b/IntelFrameworkPkg/Include/Protocol/LegacyBios.h index 9eaaef985e..17ef9522c0 100644 --- a/IntelFrameworkPkg/Include/Protocol/LegacyBios.h +++ b/IntelFrameworkPkg/Include/Protocol/LegacyBios.h @@ -6,13 +6,10 @@ Note: The names for EFI_IA32_REGISTER_SET elements were picked to follow well known naming conventions. - Thunk - A thunk is a transition from one processor mode to another. A Thunk - is a transition from native EFI mode to 16-bit mode. A reverse thunk - would be a transition from 16-bit mode to native EFI mode. - - You most likely should not use this protocol! Find the EFI way to solve the - problem to make your code portable + Thunk is the code that switches from 32-bit protected environment into the 16-bit real-mode + environment. Reverse thunk is the code that does the opposite. + Copyright (c) 2007 - 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 @@ -1122,10 +1119,8 @@ typedef union { @param[in,out] Reg Register contexted passed into (and returned) from thunk to 16-bit mode - @retval FALSE Thunk completed, and there were no BIOS errors in the target code. - See Regs for status. - @retval TRUE There was a BIOS erro in the target code. - + @retval TRUE Thunk completed with no BIOS errors in the target code. See Regs for status. + @retval FALSE There was a BIOS error in the target code. **/ typedef BOOLEAN @@ -1148,10 +1143,7 @@ BOOLEAN @param[in] Stack Caller allocated stack used to pass arguments @param[in] StackSize Size of Stack in bytes - @retval FALSE Thunk completed, and there were no BIOS errors in the target code. - See Regs for status. - @retval TRUE There was a BIOS erro in the target code. - + @retval FALSE Thunk completed with no BIOS errors in the target code. See Regs for status. @retval TRUE There was a BIOS error in the target code. **/ typedef BOOLEAN @@ -1233,7 +1225,7 @@ EFI_STATUS /** This function attempts to traditionally boot the specified BootOption. If the EFI context has - been compromised, this function will not return. This procedure is not used for loading an EFIaware + been compromised, this function will not return. This procedure is not used for loading an EFI-aware OS off a traditional device. The following actions occur: - Get EFI SMBIOS data structures, convert them to a traditional format, and copy to Compatibility16. @@ -1252,7 +1244,7 @@ EFI_STATUS - Invoke the Compatibility16 Table function Compatibility16Boot(). This invocation causes a thunk into the Compatibility16 code, which does an INT19. - If the Compatibility16Boot() function returns, then the boot failed in a graceful - manner—i.e., EFI code is still valid. An ungraceful boot failure causes a reset because the state + manner--meaning that the EFI code is still valid. An ungraceful boot failure causes a reset because the state of EFI code is unknown. @param[in] This Protocol instance pointer. @@ -1260,11 +1252,7 @@ EFI_STATUS @param[in] LoadOptionSize Size of LoadOption in size. @param[in] LoadOption LoadOption from BootXXXX variable - @retval EFI_DEVICE_ERROR Failed to boot from any boot device and memory is uncorrupted. - Note: This function normally never returns. It will either boot the - OS or reset the system if memory has been "corrupted" by loading - a boot sector and passing control to it. - + @retval EFI_DEVICE_ERROR Failed to boot from any boot device and memory is uncorrupted. Note: This function normally does not returns. It will either boot the OS or reset the system if memory has been "corrupted" by loading a boot sector and passing control to it. **/ typedef EFI_STATUS @@ -1278,7 +1266,7 @@ EFI_STATUS /** This function takes the Leds input parameter and sets/resets the BDA accordingly. Leds is also passed to Compatibility16 code, in case any special processing is required. - This function is normally called from EFI Setup drivers that handle userselectable + This function is normally called from EFI Setup drivers that handle user-selectable keyboard options such as boot with NUM LOCK on/off. This function does not touch the keyboard or keyboard LEDs but only the BDA. diff --git a/IntelFrameworkPkg/Include/Protocol/LegacyBiosPlatform.h b/IntelFrameworkPkg/Include/Protocol/LegacyBiosPlatform.h index 0d4827104a..e0d5eac4d0 100644 --- a/IntelFrameworkPkg/Include/Protocol/LegacyBiosPlatform.h +++ b/IntelFrameworkPkg/Include/Protocol/LegacyBiosPlatform.h @@ -41,10 +41,10 @@ typedef struct _EFI_LEGACY_BIOS_PLATFORM_PROTOCOL EFI_LEGACY_BIOS_PLATFORM_PROTO typedef enum { /// /// This mode is invoked twice. The first invocation has LegacySegment and - /// LegacyOffset set to 0. The mode returns the MP table address in EFI memory and its size. + /// LegacyOffset set to 0. The mode returns the MP table address in EFI memory, along with its size. /// The second invocation has LegacySegment and LegacyOffset set to the location /// in the 0xF0000 or 0xE0000 block to which the MP table is to be copied. The second - /// invocation allows any MP table address fix ups to occur in the EFI memory copy of the + /// invocation allows any MP table address fixes to occur in the EFI memory copy of the /// MP table. The caller, not EfiGetPlatformBinaryMpTable, copies the modified MP /// table to the allocated region in 0xF0000 or 0xE0000 block after the second invocation. /// @@ -59,12 +59,12 @@ typedef enum { /// Bit 1 = 1 0xE0000 64 KB block. /// Multiple bits can be set. /// - /// Alignment Bit mapped address alignment granularity. + /// Alignment Bit-mapped address alignment granularity. /// The first nonzero bit from the right is the address granularity. /// - // LegacySegment Segment where EfiCompatibility code will place the MP table. + // LegacySegment Segment in which EfiCompatibility code will place the MP table. /// - /// LegacyOffset Offset where EfiCompatibility code will place the MP table. + /// LegacyOffset Offset in which EfiCompatibility code will place the MP table. /// /// The return values associated with this mode are: /// @@ -74,15 +74,15 @@ typedef enum { /// EfiGetPlatformBinaryMpTable = 0, /// - /// This mode returns a block of data. The contents and usage is IBV or OEM defined. + /// This mode returns a block of data. The content and usage is IBV or OEM defined. /// OEMs or IBVs normally use this function for nonstandard Compatibility16 runtime soft /// INTs. It is the responsibility of this routine to coalesce multiple OEM 16 bit functions, if /// they exist, into one coherent package that is understandable by the Compatibility16 code. /// This function is invoked twice. The first invocation has LegacySegment and - /// LegacyOffset set to 0. The function returns the table address in EFI memory and its size. + /// LegacyOffset set to 0. The function returns the table address in EFI memory, as well as its size. /// The second invocation has LegacySegment and LegacyOffset set to the location /// in the 0xF0000 or 0xE0000 block to which the data (table) is to be copied. The second - /// invocation allows any data (table) address fix ups to occur in the EFI memory copy of + /// invocation allows any data (table) address fixes to occur in the EFI memory copy of /// the table. The caller, not GetOemIntData(), copies the modified data (table) to the /// allocated region in 0xF0000 or 0xE0000 block after the second invocation. /// @@ -100,9 +100,9 @@ typedef enum { /// Alignment Bit mapped address alignment granularity. /// The first nonzero bit from the right is the address granularity. /// - /// LegacySegment Segment where EfiCompatibility code will place the table or data. + /// LegacySegment Segment in which EfiCompatibility code will place the table or data. /// - /// LegacyOffset Offset where EfiCompatibility code will place the table or data. + /// LegacyOffset Offset in which EfiCompatibility code will place the table or data. /// /// The return values associated with this mode are: /// @@ -112,17 +112,19 @@ typedef enum { /// EfiGetPlatformBinaryOemIntData = 1, /// - /// This mode returns a block of data. The contents and usage is IBV defined. OEMs or + /// This mode returns a block of data. The content and usage is IBV defined. OEMs or /// IBVs normally use this mode for nonstandard Compatibility16 runtime 16 bit routines. It /// is the responsibility of this routine to coalesce multiple OEM 16 bit functions, if they /// exist, into one coherent package that is understandable by the Compatibility16 code. - /// An example usage might be a legacy mobile BIOS that has a pre existing runtime + /// + /// Example usage: A legacy mobile BIOS that has a pre-existing runtime /// interface to return the battery status to calling applications. + /// /// This mode is invoked twice. The first invocation has LegacySegment and /// LegacyOffset set to 0. The mode returns the table address in EFI memory and its size. /// The second invocation has LegacySegment and LegacyOffset set to the location /// in the 0xF0000 or 0xE0000 block to which the table is to be copied. The second - /// invocation allows any table address fix ups to occur in the EFI memory copy of the table. + /// invocation allows any table address fixes to occur in the EFI memory copy of the table. /// The caller, not EfiGetPlatformBinaryOem16Data, copies the modified table to /// the allocated region in 0xF0000 or 0xE0000 block after the second invocation. /// @@ -140,9 +142,9 @@ typedef enum { /// Alignment Bit mapped address alignment granularity. /// The first nonzero bit from the right is the address granularity. /// - /// LegacySegment Segment where EfiCompatibility code will place the table or data. + /// LegacySegment Segment in which EfiCompatibility code will place the table or data. /// - /// LegacyOffset Offset where EfiCompatibility code will place the table or data. + /// LegacyOffset Offset in which EfiCompatibility code will place the table or data. /// /// The return values associated with this mode are: /// @@ -152,12 +154,14 @@ typedef enum { /// EfiGetPlatformBinaryOem16Data = 2, /// -/// This mode returns a block of data. The contents and usage is IBV defined. OEMs or +/// This mode returns a block of data. The content and usage are IBV defined. OEMs or /// IBVs normally use this mode for nonstandard Compatibility16 runtime 32 bit routines. It /// is the responsibility of this routine to coalesce multiple OEM 32 bit functions, if they /// exist, into one coherent package that is understandable by the Compatibility16 code. -/// An example usage might be a legacy mobile BIOS that has a pre existing runtime +/// +/// Example usage: A legacy mobile BIOS that has a pre existing runtime /// interface to return the battery status to calling applications. +/// /// This mode is invoked twice. The first invocation has LegacySegment and /// LegacyOffset set to 0. The mode returns the table address in EFI memory and its size. /// @@ -190,9 +194,9 @@ typedef enum { /// Alignment Bit mapped address alignment granularity. /// The first nonzero bit from the right is the address granularity. /// -/// LegacySegment Segment where EfiCompatibility code will place the table or data. +/// LegacySegment Segment in which EfiCompatibility code will place the table or data. /// -/// LegacyOffset Offset where EfiCompatibility code will place the table or data. +/// LegacyOffset Offset in which EfiCompatibility code will place the table or data. /// /// The return values associated with this mode are: /// EFI_SUCCESS The data was returned successfully. @@ -216,9 +220,9 @@ EfiGetPlatformBinaryOem32Data = 3, /// Alignment Bit mapped address alignment granularity. /// The first nonzero bit from the right is the address granularity. /// - /// LegacySegment Segment where EfiCompatibility code will place the table or data. + /// LegacySegment Segment in which EfiCompatibility code will place the table or data. /// - /// LegacyOffset Offset where EfiCompatibility code will place the table or data. + /// LegacyOffset Offset in which EfiCompatibility code will place the table or data. /// /// The return values associated with this mode are: /// @@ -549,11 +553,11 @@ typedef struct { @param This Protocol instance pointer. @param Mode Specifies what data to return. See See EFI_GET_PLATFORM_INFO_MODE enum. @param Table Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. - @param TableSize Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. - @param Location Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. + @param TableSize Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. + @param Location Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. @param Alignment Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. @param LegacySegment Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. - @param LegacyOffset Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. + @param LegacyOffset Mode specific. See EFI_GET_PLATFORM_INFO_MODE enum. @retval EFI_SUCCESS Data was returned successfully. @retval EFI_UNSUPPORTED Mode is not supported on the platform. @@ -647,9 +651,9 @@ EFI_STATUS /** Returns information associated with PCI IRQ routing. This function returns the following information associated with PCI IRQ routing: - An IRQ routing table and number of entries in the table - The $PIR table and its size - A list of PCI IRQs and the priority order to assign them + * An IRQ routing table and number of entries in the table + * The $PIR table and its size + * A list of PCI IRQs and the priority order to assign them @param This Protocol instance pointer. @param RoutingTable Pointer to PCI IRQ Routing table. diff --git a/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h b/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h index 4e4fe1f9fc..025695bb67 100644 --- a/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h +++ b/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h @@ -67,13 +67,13 @@ EFI_STATUS @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance. @param SectionStreamHandle Indicates from which section stream to read. - @param SectionType Pointer to an EFI_SECTION_TYPE. SectionType == NULL, the contents of the - entire section stream are returned in Buffer.If SectionType is not NULL, - only the requested section is returned. EFI_SECTION_ALL matches all section + @param SectionType Pointer to an EFI_SECTION_TYPE. If SectionType == NULL, the contents of the + entire section stream are returned in Buffer. If SectionType is not NULL, + only the requested section is returned. EFI_SECTION_ALL matches all section types and can be used as a wild card to extract all sections in order. - @param SectionDefinitionGuid Pointer to an EFI_GUID.If SectionType == + @param SectionDefinitionGuid Pointer to an EFI_GUID. If SectionType == EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid indicates what section GUID - to search for.If SectionType !=EFI_SECTION_GUID_DEFINED, then + to search for. If SectionType !=EFI_SECTION_GUID_DEFINED, then SectionDefinitionGuid is unused and is ignored. @param SectionInstance Indicates which instance of the requested section type to return when SectionType is not NULL. diff --git a/IntelFrameworkPkg/Include/Protocol/SmmAccess.h b/IntelFrameworkPkg/Include/Protocol/SmmAccess.h index a55e1126ef..da6386dbef 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmAccess.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmAccess.h @@ -1,5 +1,5 @@ /** @file - This file declares SMM SMRAM Access abstraction protocol which is used to control + This file declares the SMM SMRAM Access abstraction protocol, which is used to control the visibility of the SMRAM on the platform. The expectation is that the north bridge or memory controller would publish this protocol. For example, the Memory Controller Hub (MCH) has the hardware provision for this diff --git a/IntelFrameworkPkg/Include/Protocol/SmmBase.h b/IntelFrameworkPkg/Include/Protocol/SmmBase.h index 264c2429e0..8a73549b37 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmBase.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmBase.h @@ -1,11 +1,11 @@ /** @file This file declares SMM Base abstraction protocol. This protocol is used to install SMM handlers for support of subsequent SMI/PMI activations. This - protocol is available on both IA-32 and Itanium based systems. + protocol is available on both IA-32 and Itanium-based systems. The EFI_SMM_BASE_PROTOCOL is a set of services that is exported by a processor device. It is a required protocol for the platform processor. This protocol can be used in both boot services and - runtime mode. However, only the following member functions need to exist into runtime: + runtime mode. However, only the following member functions need to exist during runtime: - InSmm() - Communicate() This protocol is responsible for registering the handler services. The order in which the handlers are @@ -85,7 +85,7 @@ typedef struct { to uniquely designate a specific DXE SMM driver. @param[in] CommunicationBuffer A pointer to a collection of data in memory that will be conveyed from a non-SMM environment into an SMM environment. - The buffer must be contiguous, physically mapped, and be a physical address. + The buffer must be contiguous and physically mapped, and must be a physical address. @param[in] SourceSize The size of the CommunicationBuffer. @return Status code @@ -103,24 +103,24 @@ EFI_STATUS // SMM Base Protocol Definition // /** - Register a given driver into SMRAM.This is the equivalent of performing + Register a given driver into SMRAM. This is the equivalent of performing the LoadImage/StartImage into System Management Mode. @param[in] This Protocol instance pointer. @param[in] FilePath Location of the image to be installed as the handler. - @param[in] SourceBuffer Optional source buffer in case of the image file - being in memory. + @param[in] SourceBuffer Optional source buffer in case the image file + is in memory. @param[in] SourceSize Size of the source image file, if in memory. @param[out] ImageHandle The handle that the base driver uses to decode the handler. Unique among SMM handlers only, not unique across DXE/EFI. - @param[in] LegacyIA32Binary An optional parameter that details that the associated + @param[in] LegacyIA32Binary An optional parameter specifying that the associated file is a real-mode IA-32 binary. @retval EFI_SUCCESS The operation was successful. @retval EFI_OUT_OF_RESOURCES There were no additional SMRAM resources to load the handler @retval EFI_UNSUPPORTED This platform does not support 16-bit handlers. - @retval EFI_UNSUPPORTED In runtime. + @retval EFI_UNSUPPORTED Platform is in runtime. @retval EFI_INVALID_PARAMETER The handlers was not the correct image type **/ @@ -144,7 +144,7 @@ EFI_STATUS @retval EFI_SUCCESS The operation was successful @retval EFI_INVALID_PARAMETER The handler did not exist - @retval EFI_UNSUPPORTED In runtime. + @retval EFI_UNSUPPORTED Platform is in runtime. **/ typedef @@ -156,7 +156,7 @@ EFI_STATUS /** The SMM Inter-module Communicate Service Communicate() function - provides a services to send/received messages from a registered + provides a service to send/receive messages from a registered EFI service. The BASE protocol driver is responsible for doing any of the copies such that the data lives in boot-service-accessible RAM. @@ -189,14 +189,14 @@ EFI_STATUS @param[in] CallbackAddress Address of the callback service. @param[in] MakeLast If present, will stipulate that the handler is posted to be executed last in the dispatch table. - @param[in] FloatingPointSave This is an optional parameter which informs the + @param[in] FloatingPointSave An optional parameter that informs the EFI_SMM_ACCESS_PROTOCOL Driver core if it needs to save - the floating point register state. If any of the handlers - require this, then the state will be saved for all of the handlers. + the floating point register state. If any handler + require this, the state will be saved for all handlers. @retval EFI_SUCCESS The operation was successful @retval EFI_OUT_OF_RESOURCES Not enough space in the dispatch queue - @retval EFI_UNSUPPORTED In runtime. + @retval EFI_UNSUPPORTED Platform is in runtime. @retval EFI_UNSUPPORTED The caller is not in SMM. **/ @@ -228,7 +228,7 @@ EFI_STATUS @retval EFI_SUCCESS The requested number of bytes was allocated. @retval EFI_OUT_OF_RESOURCES The pool requested could not be allocated. - @retval EFI_UNSUPPORTED In runtime. + @retval EFI_UNSUPPORTED Platform is in runtime. **/ typedef @@ -250,7 +250,7 @@ EFI_STATUS @retval EFI_SUCCESS The memory was returned to the system. @retval EFI_INVALID_PARAMETER Buffer was invalid. - @retval EFI_UNSUPPORTED In runtime. + @retval EFI_UNSUPPORTED Platform is in runtime. **/ typedef @@ -280,7 +280,7 @@ EFI_STATUS ); /** - The GetSmstLocation() function returns the locatin of the System Management + The GetSmstLocation() function returns the location of the System Management Service Table. The use of the API is such that a driver can discover the location of the SMST in its entry point and then cache it in some driver global variable so that the SMST can be invoked in subsequent callbacks. diff --git a/IntelFrameworkPkg/Include/Protocol/SmmControl.h b/IntelFrameworkPkg/Include/Protocol/SmmControl.h index 16e8bcbe33..685c716c46 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmControl.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmControl.h @@ -1,12 +1,11 @@ /** @file - This file declares SMM Control abstraction protocol. - This protocol is used initiate SMI/PMI activations. This protocol could be published by either of - the following: + This file declares the SMM Control abstraction protocol. + This protocol is used to initiate SMI/PMI activations. This protocol could be published by either: - A processor driver to abstract the SMI/PMI IPI - The driver that abstracts the ASIC that is supporting the APM port, such as the ICH in an Intel chipset Because of the possibility of performing SMI or PMI IPI transactions, the ability to generate this - event from a platform chipset agent is an optional capability for both IA-32 and Itanium based + event from a platform chipset agent is an optional capability for both IA-32 and Itanium-based systems. Copyright (c) 2007,2009 Intel Corporation @@ -59,7 +58,7 @@ typedef struct { @param This The EFI_SMM_CONTROL_PROTOCOL instance. @param ArgumentBuffer Optional sized data to pass into the protocol activation. @param ArgumentBufferSize Optional size of the data. - @param Periodic Optional mechanism to engender a periodic stream. + @param Periodic Optional mechanism to periodically repeat activation. @param ActivationInterval Optional parameter to repeat at this period one time or, if the Periodic Boolean is set, periodically. @@ -118,7 +117,7 @@ EFI_STATUS /** @par Protocol Description: - This protocol is used initiate SMI/PMI activations. + This protocol is used to initiate SMI/PMI activations. @param Trigger Initiates the SMI/PMI activation. @@ -139,17 +138,17 @@ EFI_STATUS // SMM Control Protocol // /** - This protocol is used initiate SMI/PMI activations. - This protocol could be published by either of the following: + This protocol is used to initiate SMI/PMI activations. + This protocol could be published by either: - A processor driver to abstract the SMI/PMI IPI - The driver that abstracts the ASIC that is supporting the APM port, such as the ICH in an Intel chipset Because of the possibility of performing SMI or PMI IPI transactions, the ability to generate this The EFI_SMM_CONTROL_PROTOCOL is used by the platform chipset or processor driver. This - protocol is useable both in boot services and runtime. The runtime aspect is so that an - implementation of EFI_SMM_BASE_PROTOCOL.Communicate() can layer upon this service + protocol is usable both in boot services and at runtime. The runtime aspect enables an + implementation of EFI_SMM_BASE_PROTOCOL.Communicate() to layer upon this service and provide an SMI callback from a general EFI runtime driver. - The purpose of this protocol is to provide an abstraction to the platform hardware that generates an + This protocol provides an abstraction to the platform hardware that generates an SMI or PMI. There are often I/O ports that, when accessed, will engender the **/ struct _EFI_SMM_CONTROL_PROTOCOL { diff --git a/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h index e0bfa142ea..3c742dc070 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h @@ -36,8 +36,8 @@ typedef struct _EFI_SMM_GPI_DISPATCH_PROTOCOL EFI_SMM_GPI_DISPATCH_PROTOCOL; // // -// GpiMask is a bit mask of 32 possible general purpose inputs that can generate a -// a SMI. Bit 0 corresponds to logical GPI[0], 1 corresponds to logical GPI[1], etc. +// GpiMask is a bit mask of 32 possible general purpose inputs that can generate +// an SMI. Bit 0 corresponds to logical GPI[0], 1 corresponds to logical GPI[1], and so on. // // The logical GPI index to physical pin on device is described by the GPI device name // found on the same handle as the GpiSmi child dispatch protocol. The GPI device name @@ -72,8 +72,7 @@ VOID @param This Pointer to the EFI_SMM_GPI_DISPATCH_PROTOCOL instance. @param DispatchFunction Function to install. @param DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register + Indicates to the register function the GPI(s) for which the dispatch function should be invoked. @param DispatchHandle Handle generated by the dispatcher to track the diff --git a/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h index da8a096618..165d6a7e38 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h @@ -128,7 +128,7 @@ VOID @param This Pointer to the EFI_SMM_ICHN_DISPATCH_PROTOCOL instance. @param DispatchFunction Function to install. @param DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling + The caller fills in this context before calling the register function to indicate to the register function the ICHN SMI source for which the dispatch function should be invoked. @@ -137,7 +137,7 @@ VOID @retval EFI_SUCCESS The dispatch function has been successfully registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source. + @retval EFI_DEVICE_ERROR The driver could not enable the SMI source. @retval EFI_OUT_OF_RESOURCES Not enough memory (system or SMM) to manage this child. @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The ICHN input value diff --git a/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h index e035e1eba7..5cdb320f5c 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h @@ -36,7 +36,7 @@ typedef struct _EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL EFI_SMM_PERIODIC_TIMER typedef struct { /// - /// The minimum period of time in 100 nanosecond units that child gets called. + /// The minimum period of time that child gets called, in 100 nanosecond units. /// The child will be called back after a time greater than the time Period. /// UINT64 Period; @@ -49,7 +49,7 @@ typedef struct { /// UINT64 SmiTickInterval; /// - /// The actual time in 100 nanosecond units elapsed since last called, a + /// The actual time in 100 nanosecond units elapsed since last called. A /// value of 0 indicates an unknown amount of time. /// UINT64 ElapsedTime; @@ -84,8 +84,8 @@ VOID @param This Protocol instance pointer. @param SmiTickInterval Pointer to pointer of next shorter SMI interval period supported by the child. This parameter works as a get-first, - get-next field.The first time this function is called, *SmiTickInterval - should be set to NULL to get the longest SMI interval.The returned + get-next field. The first time this function is called, *SmiTickInterval + should be set to NULL to get the longest SMI interval. The returned *SmiTickInterval should be passed in on subsequent calls to get the next shorter interval period until *SmiTickInterval = NULL. @@ -105,8 +105,7 @@ EFI_STATUS @param This Pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance. @param DispatchFunction Function to install. @param DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register + Indicates to the register function the period at which the dispatch function should be invoked. @param DispatchHandle Handle generated by the dispatcher to track the function instance. diff --git a/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h index d5f4ab44af..e1ed024c7a 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h @@ -73,10 +73,9 @@ VOID @param[in] This Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance. @param[in] DispatchFunction Function to install. @param[in] DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register - function the Power Button SMI phase for which the dispatch - function should be invoked. + Indicates to the register + function the Power Button SMI phase for which to invoke the dispatch + function. @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. @retval EFI_SUCCESS The dispatch function has been successfully diff --git a/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h index 61bd0cf917..7c0ff89329 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h @@ -81,15 +81,14 @@ VOID @param This Pointer to the EFI_SMM_STANDBY_BUTTON_DISPATCH_PROTOCOL instance. @param DispatchFunction Function to install. @param DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register - function the Standby Button SMI phase for which the dispatch - function should be invoked. + Indicates to the register + function the Standby Button SMI phase for which to invoke the dispatch + function. @param DispatchHandle Handle generated by the dispatcher to track the function instance. @retval EFI_SUCCESS The dispatch function has been successfully registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source. + @retval EFI_DEVICE_ERROR The driver could not enable the SMI source. @retval EFI_OUT_OF_RESOURCES Not enough memory (system or SMM) to manage this child. @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The Standby Button SMI diff --git a/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h index fbffe71946..7a17fbdabd 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h @@ -72,15 +72,14 @@ VOID @param This Pointer to the EFI_SMM_SW_DISPATCH_PROTOCOL instance. @param DispatchFunction Function to install. @param DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register - function which Software SMI input value the - dispatch function should be invoked for. + Indicates to the register + function the Software SMI input value for which to invoke the + dispatch function. @param DispatchHandle Handle generated by the dispatcher to track the function instance. @retval EFI_SUCCESS The dispatch function has been successfully registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The SW driver was unable to enable the SMI source. + @retval EFI_DEVICE_ERROR The SW driver could not enable the SMI source. @retval EFI_OUT_OF_RESOURCES Not enough memory (system or SMM) to manage this child. @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The SW SMI input value diff --git a/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h index 938d3725de..14d5a551b8 100644 --- a/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h +++ b/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h @@ -83,15 +83,15 @@ VOID @param This Pointer to the EFI_SMM_SX_DISPATCH_PROTOCOL instance. @param DispatchFunction Function to install. @param DispatchContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register + The caller fills in this context before calling + the register function to indicates to the register function which Sx state type and phase the caller - wishes to be called back on. For this intertace, + wishes to be called back on. For this interface, the Sx driver will call the registered handlers for all Sx type and phases, so the Sx state handler(s) must check the Type and Phase field of the Dispatch context and act accordingly. - @param DispatchHandle Handle of dispatch function, for when interfacing + @param DispatchHandle Handle of dispatch function, for interfacing with the parent Sx state SMM driver. @retval EFI_SUCCESS The dispatch function has been successfully -- 2.39.2