From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: redhat.com, ip: 209.85.128.66, mailfrom: philmd@redhat.com) Received: from mail-wm1-f66.google.com (mail-wm1-f66.google.com [209.85.128.66]) by groups.io with SMTP; Mon, 29 Apr 2019 22:12:57 -0700 Received: by mail-wm1-f66.google.com with SMTP id h18so2295567wml.1 for ; Mon, 29 Apr 2019 22:12:57 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:openpgp:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=MLGRSC6rTrzo045qBKZh///IKqviBBIS0mHBDvf9AzA=; b=LtHl/+K1+0Gw0Vz10Vz9nG1l8XKjAb9hIlFyb73ITmQgpnp2Qz6mKzfXaalzAGdNY2 zDzJcaxIPUCMoj6qxOUSmszyt8l0WXh1fHRJslUS5xGxUulWDru30XSweo55PMu7CSZO Up2+WZMU331ah0Wa1m87F3O1Lu2db9rCDLpSIDvRW7rWw5JS/799JPAE17Q2lb/TuzFs WezciRYXK5aCLrqJTgEzwB1U/Cf4FJJChcUAM3IWNJTUSey7TKF+MQsJViYJD1jmxAft rpjrW6I/G3CsC593PNioUpUu2AMnxQ7050+F0viRMg2NcnM896o4ikn8T2MXoxdOdGtj ttuQ== X-Gm-Message-State: APjAAAU/sjd3YRZtrwXKRsrrzQSP2nU4JcRZIkT3YjMmmcrZz7Sfuqx4 sFEQNjwLcetrcJZnm1M7aVcOpqDMb9o= X-Google-Smtp-Source: APXvYqxjNtM+tmSRHqKQ33IORa9+i7kzzMgLY48DqDHTOkGdsu/drPj/T+IBU42fcOMhWGixEii1EA== X-Received: by 2002:a1c:41d7:: with SMTP id o206mr1662663wma.130.1556601175832; Mon, 29 Apr 2019 22:12:55 -0700 (PDT) Return-Path: Received: from [192.168.1.37] (193.red-88-21-103.staticip.rima-tde.net. [88.21.103.193]) by smtp.gmail.com with ESMTPSA id k6sm25383422wrd.20.2019.04.29.22.12.55 (version=TLS1_3 cipher=AEAD-AES128-GCM-SHA256 bits=128/128); Mon, 29 Apr 2019 22:12:55 -0700 (PDT) Subject: Re: [edk2-devel] [PATCH 12/16] OvmfPkg/EnrollDefaultKeys: describe functions with leading comment blocks To: devel@edk2.groups.io, lersek@redhat.com Cc: Anthony Perard , Ard Biesheuvel , Jordan Justen , Julien Grall References: <20190427005328.27005-1-lersek@redhat.com> <20190427005328.27005-13-lersek@redhat.com> From: =?UTF-8?B?UGhpbGlwcGUgTWF0aGlldS1EYXVkw6k=?= Openpgp: id=89C1E78F601EE86C867495CBA2A3FD6EDEADC0DE; url=http://pgp.mit.edu/pks/lookup?op=get&search=0xA2A3FD6EDEADC0DE Message-ID: <0a9e51f9-5677-6946-db7f-ae0179afb82e@redhat.com> Date: Tue, 30 Apr 2019 07:12:54 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 MIME-Version: 1.0 In-Reply-To: <20190427005328.27005-13-lersek@redhat.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit On 4/27/19 2:53 AM, Laszlo Ersek wrote: > 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=1747 > Signed-off-by: Laszlo Ersek > --- > OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c | 73 ++++++++++++++++++++ > 1 file changed, 73 insertions(+) > > diff --git a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c b/OvmfPkg/EnrollDefaultKeys/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 > > #include "EnrollDefaultKeys.h" > > + > /** > Enroll a set of certificates in a global variable, overwriting it. > > The variable will be rewritten with NV+BS+RT+AT attributes. > > @param[in] VariableName The name of the variable to overwrite. > > @param[in] VendorGuid The namespace (ie. vendor GUID) of the variable to > @@ -188,16 +189,54 @@ Out: > if (EFI_ERROR (Status)) { > AsciiPrint ("error: %a(\"%s\", %g): %r\n", __FUNCTION__, VariableName, > VendorGuid, Status); > } > return Status; > } > > > +/** > + Read a UEFI variable into a caller-allocated buffer, enforcing an exact 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 to read; > + passed to gRT->GetVariable(). > + > + @param[out] Data The caller-allocated buffer that is supposed to > + receive the variable's contents. On error, the > + contents of Data are indeterminate. > + > + @param[in] DataSize The size in bytes that the caller requires the UEFI > + variable to have. The caller is responsible for > + 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 required 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 is > + greater than DataSize. > + > + @retval EFI_PROTOCOL_ERROR The UEFI variable exists, but its size is > + smaller than DataSize. > + > + @return Error codes propagated from gRT->GetVariable(). > +**/ > 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; > } > > return EFI_SUCCESS; > } > > + > +/** > + 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 which > + case the corresponding field in the SETTINGS object will be zeroed out. The > + rest of the covered UEFI variables are required to exist; otherwise, the > + 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() function. The > + contents of Settings are indeterminate. > +**/ > STATIC > EFI_STATUS > GetSettings ( > OUT SETTINGS *Settings > ) > { > EFI_STATUS Status; > > @@ -261,28 +325,37 @@ GetSettings ( > return Status; > } > > Status = GetExact (EFI_VENDOR_KEYS_VARIABLE_NAME, &gEfiGlobalVariableGuid, > &Settings->VendorKeys, sizeof Settings->VendorKeys, FALSE); > return Status; > } > > + > +/** > + 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=%d SecureBoot=%d SecureBootEnable=%d " > "CustomMode=%d VendorKeys=%d\n", Settings->SetupMode, Settings->SecureBoot, > Settings->SecureBootEnable, Settings->CustomMode, Settings->VendorKeys); > } > > > +/** > + Entry point function of this shell application. > +**/ > INTN > EFIAPI > ShellAppMain ( > IN UINTN Argc, > IN CHAR16 **Argv > ) > { > EFI_STATUS Status; > Reviewed-by: Philippe Mathieu-Daude