OvmfPkg/EnrollDefaultKeys: describe functions with leading comment blocks

The GetExact(), GetSettings(), PrintSettings(), and ShellAppMain()
functions lack leading comment blocks. Supply those.

While at it, make sure that every such comment block is preceded by two
blank lines.

Cc: Anthony Perard <anthony.perard@citrix.com>
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Julien Grall <julien.grall@arm.com>
Bugzilla: https://bugzilla.tianocore.org/show_bug.cgi?id=1747
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Philippe Mathieu-Daude <philmd@redhat.com>
Acked-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Reviewed-by: Gary Lin <glin@suse.com>

diff --git a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c b/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c
index e4f6a50e008b00fd41f3e01743099a9ee1a70a88..07297c631f3823e3adc200bcf26f031d317679d6 100644 (file)
--- a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c
+++ b/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c
@@ -18,6 +18,7 @@
 \r
 #include "EnrollDefaultKeys.h"\r
 \r
+\r
 /**\r
   Enroll a set of certificates in a global variable, overwriting it.\r
 \r
@@ -193,6 +194,44 @@ Out:
 }\r
 \r
 \r
+/**\r
+  Read a UEFI variable into a caller-allocated buffer, enforcing an exact size.\r
+\r
+  @param[in] VariableName  The name of the variable to read; passed to\r
+                           gRT->GetVariable().\r
+\r
+  @param[in] VendorGuid    The vendor (namespace) GUID of the variable to read;\r
+                           passed to gRT->GetVariable().\r
+\r
+  @param[out] Data         The caller-allocated buffer that is supposed to\r
+                           receive the variable's contents. On error, the\r
+                           contents of Data are indeterminate.\r
+\r
+  @param[in] DataSize      The size in bytes that the caller requires the UEFI\r
+                           variable to have. The caller is responsible for\r
+                           providing room for DataSize bytes in Data.\r
+\r
+  @param[in] AllowMissing  If FALSE, the variable is required to exist. If\r
+                           TRUE, the variable is permitted to be missing.\r
+\r
+  @retval EFI_SUCCESS           The UEFI variable exists, has the required size\r
+                                (DataSize), and has been read into Data.\r
+\r
+  @retval EFI_SUCCESS           The UEFI variable doesn't exist, and\r
+                                AllowMissing is TRUE. DataSize bytes in Data\r
+                                have been zeroed out.\r
+\r
+  @retval EFI_NOT_FOUND         The UEFI variable doesn't exist, and\r
+                                AllowMissing is FALSE.\r
+\r
+  @retval EFI_BUFFER_TOO_SMALL  The UEFI variable exists, but its size is\r
+                                greater than DataSize.\r
+\r
+  @retval EFI_PROTOCOL_ERROR    The UEFI variable exists, but its size is\r
+                                smaller than DataSize.\r
+\r
+  @return                       Error codes propagated from gRT->GetVariable().\r
+**/\r
 STATIC\r
 EFI_STATUS\r
 GetExact (\r
@@ -228,6 +267,31 @@ GetExact (
   return EFI_SUCCESS;\r
 }\r
 \r
+\r
+/**\r
+  Populate a SETTINGS structure from the underlying UEFI variables.\r
+\r
+  The following UEFI variables are standard variables:\r
+  - L"SetupMode"  (EFI_SETUP_MODE_NAME)\r
+  - L"SecureBoot" (EFI_SECURE_BOOT_MODE_NAME)\r
+  - L"VendorKeys" (EFI_VENDOR_KEYS_VARIABLE_NAME)\r
+\r
+  The following UEFI variables are edk2 extensions:\r
+  - L"SecureBootEnable" (EFI_SECURE_BOOT_ENABLE_NAME)\r
+  - L"CustomMode"       (EFI_CUSTOM_MODE_NAME)\r
+\r
+  The L"SecureBootEnable" UEFI variable is permitted to be missing, in which\r
+  case the corresponding field in the SETTINGS object will be zeroed out. The\r
+  rest of the covered UEFI variables are required to exist; otherwise, the\r
+  function will fail.\r
+\r
+  @param[out] Settings  The SETTINGS object to fill.\r
+\r
+  @retval EFI_SUCCESS  Settings has been populated.\r
+\r
+  @return              Error codes propagated from the GetExact() function. The\r
+                       contents of Settings are indeterminate.\r
+**/\r
 STATIC\r
 EFI_STATUS\r
 GetSettings (\r
@@ -266,6 +330,12 @@ GetSettings (
   return Status;\r
 }\r
 \r
+\r
+/**\r
+  Print the contents of a SETTINGS structure to the UEFI console.\r
+\r
+  @param[in] Settings  The SETTINGS object to print the contents of.\r
+**/\r
 STATIC\r
 VOID\r
 PrintSettings (\r
@@ -278,6 +348,9 @@ PrintSettings (
 }\r
 \r
 \r
+/**\r
+  Entry point function of this shell application.\r
+**/\r
 INTN\r
 EFIAPI\r
 ShellAppMain (\r