Committing changes to the comments, after review with engineers.

[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / AcpiS3Save.h

diff --git a/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h b/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
index 0e095f8148149e267150e54854e695f45331f93e..de68e324ee4ec5394ae47d178072b2501ae7957e 100644 (file)
--- a/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
+++ b/IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h
@@ -38,30 +38,7 @@ typedef struct _EFI_ACPI_S3_SAVE_PROTOCOL EFI_ACPI_S3_SAVE_PROTOCOL;
 //\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