Committing changes to the comments, after review with engineers.
authorpkandel <pkandel@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 28 Jul 2009 13:25:37 +0000 (13:25 +0000)
committerpkandel <pkandel@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 28 Jul 2009 13:25:37 +0000 (13:25 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@9018 6f19259b-4bc3-4df7-8a09-765794883524

36 files changed:
IntelFrameworkPkg/Include/Framework/FirmwareVolumeHeader.h
IntelFrameworkPkg/Include/Framework/FrameworkInternalFormRepresentation.h
IntelFrameworkPkg/Include/Framework/PeiCis.h
IntelFrameworkPkg/Include/Framework/SmmCis.h
IntelFrameworkPkg/Include/Guid/Capsule.h
IntelFrameworkPkg/Include/Library/SmmLib.h
IntelFrameworkPkg/Include/Ppi/BootScriptExecuter.h
IntelFrameworkPkg/Include/Ppi/FindFv.h
IntelFrameworkPkg/Include/Ppi/PciCfg.h
IntelFrameworkPkg/Include/Ppi/ReadOnlyVariable.h
IntelFrameworkPkg/Include/Ppi/SectionExtraction.h
IntelFrameworkPkg/Include/Ppi/Smbus.h
IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
IntelFrameworkPkg/Include/Protocol/AcpiSupport.h
IntelFrameworkPkg/Include/Protocol/BootScriptSave.h
IntelFrameworkPkg/Include/Protocol/CpuIo.h
IntelFrameworkPkg/Include/Protocol/DataHub.h
IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h
IntelFrameworkPkg/Include/Protocol/FrameworkFirmwareVolumeBlock.h
IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h
IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
IntelFrameworkPkg/Include/Protocol/FrameworkHii.h
IntelFrameworkPkg/Include/Protocol/Legacy8259.h
IntelFrameworkPkg/Include/Protocol/LegacyBios.h
IntelFrameworkPkg/Include/Protocol/LegacyBiosPlatform.h
IntelFrameworkPkg/Include/Protocol/SectionExtraction.h
IntelFrameworkPkg/Include/Protocol/SmmAccess.h
IntelFrameworkPkg/Include/Protocol/SmmBase.h
IntelFrameworkPkg/Include/Protocol/SmmControl.h
IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h

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