From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.81]) by mx.groups.io with SMTP id smtpd.web12.5035.1574855320807095503 for ; Wed, 27 Nov 2019 03:48:41 -0800 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=EZEFYuNN; spf=pass (domain: redhat.com, ip: 207.211.31.81, mailfrom: philmd@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1574855319; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=u8Ls5hFs8CRLIN52qPXyWlIRqAy1M7G7liNW7CxF+zk=; b=EZEFYuNNwUlIRh5T8+BBFKbLtgqRsODJufuZL18EWgh8NNcnBKE7/U3Yda4IeVFQiCzPy5 DQ6UEqIPX2zbCCYuXYe32JjOj8qjRCT5kQlRE/ufbNrdYoqOcQAaoqLClZy5CP7EX3S6/E 0yZlNd/6QcImL3QURIc42ezNIXVnevM= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-113-16Cz1QpVNceqLbvB_6TDXQ-1; Wed, 27 Nov 2019 06:48:38 -0500 Received: by mail-wm1-f71.google.com with SMTP id p5so2405301wmc.4 for ; Wed, 27 Nov 2019 03:48:38 -0800 (PST) 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:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=u8Ls5hFs8CRLIN52qPXyWlIRqAy1M7G7liNW7CxF+zk=; b=Ph00+rL3SZpFsC1TzxZVRhOJ+UxlwelfNorzRB9x6NJIDauyX1/Q9G/wgw24BwOM6D FKKCr1J7OF7i3PW+XQZKJZ7rhpqoo0wAwxjsQDUrsh/B1gH/dvDosLodymBxz72POEq1 Cppm9r1craSI3qqdLc94kTJZqWx4Imr56J2NJV6qMN7XTDdRB+Let3q62cqnqS8Ne84f uECAryKld0SwSD2WkA606Z6e7BjDI+H1f/b3IDF54b4bBUOaIWYM/O59+8lMQMIFY9xE gSFmTBMHy+IpwnqxTVaTy3/ty5aYspIwXpmEGDCb55jWv/p18ZIuy1hnf0I32yfCsLK/ 2Vuw== X-Gm-Message-State: APjAAAWtGy8Mu6hmAkUoCOB2jHqGthuJG3NL3e+BjNg+wDwSqeRdVUr0 XAVHr7Db2LrzWaof4kn1/UPTaf58R2s+5dtVnLPUFHXwAjtuwnGoCkehFmWkk6DjY/uhKqacEhY TCayvHHzFG3YvhA== X-Received: by 2002:adf:fe4d:: with SMTP id m13mr19514575wrs.179.1574855316419; Wed, 27 Nov 2019 03:48:36 -0800 (PST) X-Google-Smtp-Source: APXvYqyzn8eUPY7WURBhOpT7juC6Gdc/sXJjU+mLhMnXFga6E4tDvzklINAmXKNMVu2EKHCDHUHh1w== X-Received: by 2002:adf:fe4d:: with SMTP id m13mr19514563wrs.179.1574855316191; Wed, 27 Nov 2019 03:48:36 -0800 (PST) Return-Path: Received: from [10.201.33.36] ([195.166.127.210]) by smtp.gmail.com with ESMTPSA id a26sm6310389wmm.14.2019.11.27.03.48.35 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 27 Nov 2019 03:48:35 -0800 (PST) Subject: Re: [edk2-devel] [PATCH V1 2/2] MdeModulePkg PeiCore: Improve comment semantics To: devel@edk2.groups.io, michael.a.kubacki@intel.com Cc: Dandan Bi , Liming Gao , Jian J Wang , Hao A Wu References: <20191127040648.8656-1-michael.a.kubacki@intel.com> <20191127040648.8656-3-michael.a.kubacki@intel.com> From: =?UTF-8?B?UGhpbGlwcGUgTWF0aGlldS1EYXVkw6k=?= Message-ID: <6dc9556d-8ef2-00d2-12cc-c2d8a84d9e06@redhat.com> Date: Wed, 27 Nov 2019 12:48:34 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.1.1 MIME-Version: 1.0 In-Reply-To: <20191127040648.8656-3-michael.a.kubacki@intel.com> X-MC-Unique: 16Cz1QpVNceqLbvB_6TDXQ-1 X-Mimecast-Spam-Score: 0 Content-Language: en-US Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit On 11/27/19 5:06 AM, Kubacki, Michael A via Groups.Io wrote: > Clarifies wording in several PeiCore comments to improve "Clarify"? > reading comprehension. > > Cc: Dandan Bi > Cc: Liming Gao > Cc: Jian J Wang > Cc: Hao A Wu > Signed-off-by: Michael Kubacki > --- > MdeModulePkg/Core/Pei/FwVol/FwVol.h | 4 ++-- > MdeModulePkg/Core/Pei/PeiMain.h | 11 +++++----- > MdeModulePkg/Core/Pei/Dependency/Dependency.c | 4 ++-- > MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c | 4 ++-- > MdeModulePkg/Core/Pei/FwVol/FwVol.c | 23 ++++++++++---------- > MdeModulePkg/Core/Pei/Memory/MemoryServices.c | 4 ++-- > 6 files changed, 26 insertions(+), 24 deletions(-) > > diff --git a/MdeModulePkg/Core/Pei/FwVol/FwVol.h b/MdeModulePkg/Core/Pei/FwVol/FwVol.h > index 263f0d7a56..8aaf84870b 100644 > --- a/MdeModulePkg/Core/Pei/FwVol/FwVol.h > +++ b/MdeModulePkg/Core/Pei/FwVol/FwVol.h > @@ -303,9 +303,9 @@ FindFileEx ( > ); > > /** > - Report the information for a new discovered FV in unknown format. > + Report the information for a newly discovered FV in an unknown format. > > - If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for specific FV format, but > + If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for a third-party FV format, but > the FV in this FV format has been discovered, then the information of this FV > will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array. > Also a notification would be installed for unknown FV format GUID, if EFI_PEI_FIRMWARE_VOLUME_PPI > diff --git a/MdeModulePkg/Core/Pei/PeiMain.h b/MdeModulePkg/Core/Pei/PeiMain.h > index 3f61247a0f..96d6df0485 100644 > --- a/MdeModulePkg/Core/Pei/PeiMain.h > +++ b/MdeModulePkg/Core/Pei/PeiMain.h > @@ -1217,8 +1217,8 @@ PeiFfsGetVolumeInfo ( > ); > > /** > - This routine enable a PEIM to register itself to shadow when PEI Foundation > - discovery permanent memory. > + This routine enables a PEIM to register itself for shadow when the PEI Foundation > + discovers permanent memory. > > @param FileHandle File handle of a PEIM. > > @@ -1314,12 +1314,13 @@ ProcessFvFile ( > ); > > /** > - Get instance of PEI_CORE_FV_HANDLE for next volume according to given index. > + Gets a PEI_CORE_FV_HANDLE instance for the next volume according to the given index. "Get"? > > - This routine also will install FvInfo PPI for FV HOB in PI ways. > + This routine also will install an instance of the FvInfo PPI for the FV HOB > + as defined in the PI specification. > > @param Private Pointer of PEI_CORE_INSTANCE > - @param Instance The index of FV want to be searched. > + @param Instance The index of the FV to search. Maybe without "The" and trailing dot? > > @return Instance of PEI_CORE_FV_HANDLE. > **/ > diff --git a/MdeModulePkg/Core/Pei/Dependency/Dependency.c b/MdeModulePkg/Core/Pei/Dependency/Dependency.c > index 9a8353aef2..b53e5f2686 100644 > --- a/MdeModulePkg/Core/Pei/Dependency/Dependency.c > +++ b/MdeModulePkg/Core/Pei/Dependency/Dependency.c > @@ -2,8 +2,8 @@ > PEI Dispatcher Dependency Evaluator > > This routine evaluates a dependency expression (DEPENDENCY_EXPRESSION) to determine > - if a driver can be scheduled for execution. The criteria for > - schedulability is that the dependency expression is satisfied. > + if a driver can be scheduled for execution. The criteria to be scheduled is > + that the dependency expression is satisfied. > > Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.
> SPDX-License-Identifier: BSD-2-Clause-Patent > diff --git a/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c b/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c > index c9f2a91264..a18ac47f61 100644 > --- a/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c > +++ b/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c > @@ -1347,8 +1347,8 @@ DepexSatisfied ( > } > > /** > - This routine enable a PEIM to register itself to shadow when PEI Foundation > - discovery permanent memory. > + This routine enables a PEIM to register itself for shadow when the PEI Foundation > + discovers permanent memory. > > @param FileHandle File handle of a PEIM. > > diff --git a/MdeModulePkg/Core/Pei/FwVol/FwVol.c b/MdeModulePkg/Core/Pei/FwVol/FwVol.c > index c21eb9c039..a9fa476846 100644 > --- a/MdeModulePkg/Core/Pei/FwVol/FwVol.c > +++ b/MdeModulePkg/Core/Pei/FwVol/FwVol.c > @@ -593,7 +593,7 @@ FirmwareVolumeInfoPpiNotifyCallback ( > } > > // > - // Locate the corresponding FV_PPI according to founded FV's format GUID > + // Locate the corresponding FV_PPI according to the format GUID of the FV found > // > Status = PeiServicesLocatePpi ( > &FvInfo2Ppi.FvFormat, > @@ -1533,7 +1533,7 @@ ProcessFvFile ( > ); > > // > - // Inform the extracted FvImage to FV HOB consumer phase, i.e. DXE phase > + // Expose the extracted FvImage to the FV HOB consumer phase, i.e. DXE phase > // > BuildFvHob ( > (EFI_PHYSICAL_ADDRESS) (UINTN) FvHeader, > @@ -2087,12 +2087,13 @@ FvHandleToCoreHandle ( > } > > /** > - Get instance of PEI_CORE_FV_HANDLE for next volume according to given index. > + Gets a PEI_CORE_FV_HANDLE instance for the next volume according to the given index. "Get"? > > - This routine also will install FvInfo PPI for FV HOB in PI ways. > + This routine also will install an instance of the FvInfo PPI for the FV HOB > + as defined in the PI specification. > > @param Private Pointer of PEI_CORE_INSTANCE > - @param Instance The index of FV want to be searched. > + @param Instance The index of the FV to search. Without "The"/trailing dot? > > @return Instance of PEI_CORE_FV_HANDLE. > **/ > @@ -2185,13 +2186,13 @@ PeiReinitializeFv ( > } > > /** > - Report the information for a new discovered FV in unknown third-party format. > + Report the information for a newly discovered FV in an unknown format. > > - If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for third-party FV format, but > - the FV in this format has been discovered, then this FV's information will be cached into > - PEI_CORE_INSTANCE's UnknownFvInfo array. > - Also a notification would be installed for unknown third-party FV format guid, if EFI_PEI_FIRMWARE_VOLUME_PPI > - is installed later by platform's PEIM, the original unknown third-party FV will be processed by > + If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for a third-party FV format, but > + the FV in this FV format has been discovered, then the information of this FV Maybe "in this FV format" is redundant? > + will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array. > + Also a notification would be installed for unknown FV format GUID, if EFI_PEI_FIRMWARE_VOLUME_PPI > + is installed later by platform's PEIM, the original unknown FV will be processed by > using new installed EFI_PEI_FIRMWARE_VOLUME_PPI. > > @param PrivateData Point to instance of PEI_CORE_INSTANCE > diff --git a/MdeModulePkg/Core/Pei/Memory/MemoryServices.c b/MdeModulePkg/Core/Pei/Memory/MemoryServices.c > index 838a003baa..e713e6811a 100644 > --- a/MdeModulePkg/Core/Pei/Memory/MemoryServices.c > +++ b/MdeModulePkg/Core/Pei/Memory/MemoryServices.c > @@ -759,7 +759,7 @@ PeiFreePages ( > /** > > Pool allocation service. Before permanent memory is discovered, the pool will > - be allocated the heap in the temporary memory. Generally, the size of heap in temporary > + be allocated in the heap in temporary memory. Generally, the size of the heap in temporary > memory does not exceed to 64K, so the biggest pool size could be allocated is > 64K. > > @@ -789,7 +789,7 @@ PeiAllocatePool ( > // > > // > - // Generally, the size of heap in temporary memory does not exceed to 64K, > + // Generally, the size of heap in temporary memory does not exceed 64K, > // HobLength is multiples of 8 bytes, so the maximum size of pool is 0xFFF8 - sizeof (EFI_HOB_MEMORY_POOL) > // > if (Size > (0xFFF8 - sizeof (EFI_HOB_MEMORY_POOL))) { >