From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: redhat.com, ip: 209.132.183.28, mailfrom: lersek@redhat.com) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Fri, 26 Apr 2019 17:54:09 -0700 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 31A576EB97; Sat, 27 Apr 2019 00:54:09 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-121-104.rdu2.redhat.com [10.10.121.104]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4F67C5D70A; Sat, 27 Apr 2019 00:54:07 +0000 (UTC) From: "Laszlo Ersek" To: edk2-devel-groups-io Cc: Anthony Perard , Ard Biesheuvel , Jordan Justen , Julien Grall Subject: [PATCH 12/16] OvmfPkg/EnrollDefaultKeys: describe functions with leading comment blocks Date: Sat, 27 Apr 2019 02:53:24 +0200 Message-Id: <20190427005328.27005-13-lersek@redhat.com> In-Reply-To: <20190427005328.27005-1-lersek@redhat.com> References: <20190427005328.27005-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Sat, 27 Apr 2019 00:54:09 +0000 (UTC) Content-Transfer-Encoding: quoted-printable 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 Cc: Ard Biesheuvel Cc: Jordan Justen Cc: Julien Grall Bugzilla: https://bugzilla.tianocore.org/show_bug.cgi?id=3D1747 Signed-off-by: Laszlo Ersek --- OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c | 73 ++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c b/OvmfPkg/Enro= llDefaultKeys/EnrollDefaultKeys.c index e4f6a50e008b..07297c631f38 100644 --- a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c +++ b/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c @@ -13,16 +13,17 @@ #include // ASSERT() #include // FreePool() #include // ShellAppMain() #include // AsciiPrint() #include // gRT =20 #include "EnrollDefaultKeys.h" =20 + /** Enroll a set of certificates in a global variable, overwriting it. =20 The variable will be rewritten with NV+BS+RT+AT attributes. =20 @param[in] VariableName The name of the variable to overwrite. =20 @param[in] VendorGuid The namespace (ie. vendor GUID) of the variab= le to @@ -188,16 +189,54 @@ Out: if (EFI_ERROR (Status)) { AsciiPrint ("error: %a(\"%s\", %g): %r\n", __FUNCTION__, VariableNam= e, VendorGuid, Status); } return Status; } =20 =20 +/** + Read a UEFI variable into a caller-allocated buffer, enforcing an exac= t size. + + @param[in] VariableName The name of the variable to read; passed to + gRT->GetVariable(). + + @param[in] VendorGuid The vendor (namespace) GUID of the variable t= o read; + passed to gRT->GetVariable(). + + @param[out] Data The caller-allocated buffer that is supposed = to + receive the variable's contents. On error, th= e + contents of Data are indeterminate. + + @param[in] DataSize The size in bytes that the caller requires th= e UEFI + variable to have. The caller is responsible f= or + providing room for DataSize bytes in Data. + + @param[in] AllowMissing If FALSE, the variable is required to exist. = If + TRUE, the variable is permitted to be missing= . + + @retval EFI_SUCCESS The UEFI variable exists, has the requir= ed size + (DataSize), and has been read into Data. + + @retval EFI_SUCCESS The UEFI variable doesn't exist, and + AllowMissing is TRUE. DataSize bytes in = Data + have been zeroed out. + + @retval EFI_NOT_FOUND The UEFI variable doesn't exist, and + AllowMissing is FALSE. + + @retval EFI_BUFFER_TOO_SMALL The UEFI variable exists, but its size i= s + greater than DataSize. + + @retval EFI_PROTOCOL_ERROR The UEFI variable exists, but its size i= s + smaller than DataSize. + + @return Error codes propagated from gRT->GetVari= able(). +**/ STATIC EFI_STATUS GetExact ( IN CHAR16 *VariableName, IN EFI_GUID *VendorGuid, OUT VOID *Data, IN UINTN DataSize, IN BOOLEAN AllowMissing @@ -223,16 +262,41 @@ GetExact ( AsciiPrint ("error: GetVariable(\"%s\", %g): expected size 0x%Lx, " "got 0x%Lx\n", VariableName, VendorGuid, (UINT64)DataSize, (UINT64= )Size); return EFI_PROTOCOL_ERROR; } =20 return EFI_SUCCESS; } =20 + +/** + Populate a SETTINGS structure from the underlying UEFI variables. + + The following UEFI variables are standard variables: + - L"SetupMode" (EFI_SETUP_MODE_NAME) + - L"SecureBoot" (EFI_SECURE_BOOT_MODE_NAME) + - L"VendorKeys" (EFI_VENDOR_KEYS_VARIABLE_NAME) + + The following UEFI variables are edk2 extensions: + - L"SecureBootEnable" (EFI_SECURE_BOOT_ENABLE_NAME) + - L"CustomMode" (EFI_CUSTOM_MODE_NAME) + + The L"SecureBootEnable" UEFI variable is permitted to be missing, in w= hich + case the corresponding field in the SETTINGS object will be zeroed out= . The + rest of the covered UEFI variables are required to exist; otherwise, t= he + function will fail. + + @param[out] Settings The SETTINGS object to fill. + + @retval EFI_SUCCESS Settings has been populated. + + @return Error codes propagated from the GetExact() functi= on. The + contents of Settings are indeterminate. +**/ STATIC EFI_STATUS GetSettings ( OUT SETTINGS *Settings ) { EFI_STATUS Status; =20 @@ -261,28 +325,37 @@ GetSettings ( return Status; } =20 Status =3D GetExact (EFI_VENDOR_KEYS_VARIABLE_NAME, &gEfiGlobalVariabl= eGuid, &Settings->VendorKeys, sizeof Settings->VendorKeys, FALSE); return Status; } =20 + +/** + Print the contents of a SETTINGS structure to the UEFI console. + + @param[in] Settings The SETTINGS object to print the contents of. +**/ STATIC VOID PrintSettings ( IN CONST SETTINGS *Settings ) { AsciiPrint ("info: SetupMode=3D%d SecureBoot=3D%d SecureBootEnable=3D%= d " "CustomMode=3D%d VendorKeys=3D%d\n", Settings->SetupMode, Settings->= SecureBoot, Settings->SecureBootEnable, Settings->CustomMode, Settings->VendorKe= ys); } =20 =20 +/** + Entry point function of this shell application. +**/ INTN EFIAPI ShellAppMain ( IN UINTN Argc, IN CHAR16 **Argv ) { EFI_STATUS Status; --=20 2.19.1.3.g30247aa5d201