From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by mx.groups.io with SMTP id smtpd.web11.8257.1578652737120573501 for ; Fri, 10 Jan 2020 02:38:57 -0800 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: intel.com, ip: 134.134.136.126, mailfrom: ray.ni@intel.com) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 10 Jan 2020 02:38:56 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,416,1571727600"; d="scan'208";a="396403473" Received: from fmsmsx104.amr.corp.intel.com ([10.18.124.202]) by orsmga005.jf.intel.com with ESMTP; 10 Jan 2020 02:38:54 -0800 Received: from fmsmsx112.amr.corp.intel.com (10.18.116.6) by fmsmsx104.amr.corp.intel.com (10.18.124.202) with Microsoft SMTP Server (TLS) id 14.3.439.0; Fri, 10 Jan 2020 02:38:52 -0800 Received: from shsmsx101.ccr.corp.intel.com (10.239.4.153) by FMSMSX112.amr.corp.intel.com (10.18.116.6) with Microsoft SMTP Server (TLS) id 14.3.439.0; Fri, 10 Jan 2020 02:38:51 -0800 Received: from shsmsx104.ccr.corp.intel.com ([169.254.5.197]) by SHSMSX101.ccr.corp.intel.com ([169.254.1.30]) with mapi id 14.03.0439.000; Fri, 10 Jan 2020 18:38:49 +0800 From: "Ni, Ray" To: "Chaganty, Rangasai V" , "Chen, Marc W" , "devel@edk2.groups.io" CC: "Kubacki, Michael A" , "Gao, Liming" , "Zhang, Shenglei" Subject: Re: [edk2-devel][edk2-platforms][PATCH v5] IntelSiliconPkg/Feature/SmmAccess/*: Fix incorrect Doxygen comment Thread-Topic: [edk2-devel][edk2-platforms][PATCH v5] IntelSiliconPkg/Feature/SmmAccess/*: Fix incorrect Doxygen comment Thread-Index: AQHVx3WvR8nmmxKHF0OYhCv+z5Cswafi48YAgADRAsA= Date: Fri, 10 Jan 2020 10:38:48 +0000 Deferred-Delivery: Fri, 10 Jan 2020 10:37:00 +0000 Message-ID: <734D49CCEBEEF84792F5B80ED585239D5C3E86FD@SHSMSX104.ccr.corp.intel.com> References: <20200110052023.3928-1-marc.w.chen@intel.com> In-Reply-To: Accept-Language: en-US, zh-CN X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [10.239.127.40] MIME-Version: 1.0 Return-Path: ray.ni@intel.com Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Reviewed-by: Ray Ni > -----Original Message----- > From: Chaganty, Rangasai V > Sent: Friday, January 10, 2020 2:09 PM > To: Chen, Marc W ; devel@edk2.groups.io > Cc: Kubacki, Michael A ; Ni, Ray > ; Gao, Liming ; Zhang, Shenglei > > Subject: RE: [edk2-devel][edk2-platforms][PATCH v5] > IntelSiliconPkg/Feature/SmmAccess/*: Fix incorrect Doxygen comment >=20 > Reviewed-by: Sai Chaganty >=20 > -----Original Message----- > From: Chen, Marc W > Sent: Thursday, January 09, 2020 9:20 PM > To: devel@edk2.groups.io > Cc: Kubacki, Michael A ; Chaganty, Rangasai = V > ; Ni, Ray ; Gao, Liming > ; Zhang, Shenglei ; Chen, > Marc W > Subject: [edk2-devel][edk2-platforms][PATCH v5] > IntelSiliconPkg/Feature/SmmAccess/*: Fix incorrect Doxygen comment >=20 > REF: https://bugzilla.tianocore.org/show_bug.cgi?id=3D2436 >=20 > Fixed some doxygen comment that does not follow correct doxygen format. > Updated some description of some functions. >=20 > Notes: > v1: > - Initial version of code change. > v2: > - Update some description of some functions. > v3: > - Update some description of some functions. > v4: > - Change "post" to "POST". > v5: > - Fixed typo of subject from "Doxcgen" to "Doxygen". >=20 >=20 > Cc: Michael Kubacki > Cc: Sai Chaganty > Cc: Ray Ni > Cc: Liming Gao > Cc: Shenglei Zhang > Signed-off-by: Marc Chen > --- > .../Library/PeiSmmAccessLib/PeiSmmAccessLib.c | 37 +++++++++-------= --- > .../SmmAccess/SmmAccessDxe/SmmAccessDriver.c | 35 +++++++++++-----= -- > .../SmmAccess/SmmAccessDxe/SmmAccessDriver.h | 41 ++++++++++------= --- > --- > .../IntelSiliconPkg/Include/Library/SmmAccessLib.h | 7 ++-- > 4 files changed, 60 insertions(+), 60 deletions(-) >=20 > diff --git > a/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/Library/PeiSmmAccessLib= /Pe > iSmmAccessLib.c > b/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/Library/PeiSmmAccessLib= /Pe > iSmmAccessLib.c > index da141cfa0e..d9bf4fba98 100644 > --- > a/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/Library/PeiSmmAccessLib= /Pe > iSmmAccessLib.c > +++ > b/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/Library/PeiSmmAccessLib= /Pe > iSmmAccessLib.c > @@ -1,7 +1,7 @@ > /** @file > This is to publish the SMM Access Ppi instance. >=20 > - Copyright (c) 2019, Intel Corporation. All rights reserved.
> + Copyright (c) 2019 - 2020, Intel Corporation. All rights reserved.
> SPDX-License-Identifier: BSD-2-Clause-Patent >=20 > **/ > @@ -46,9 +46,9 @@ typedef struct { > The use of "open" means that the memory is visible from all PEIM > and SMM agents. >=20 > - @param[in] This - Pointer to the SMM Access Interface. > - @param[in] DescriptorIndex - Region of SMRAM to Open. > - @param[in] PeiServices - General purpose services available to e= very PEIM. > + @param[in] PeiServices - General purpose services available t= o every > PEIM. > + @param[in] This - Pointer to the SMM Access Interface. > + @param[in] DescriptorIndex - Region of SMRAM to Open. >=20 > @retval EFI_SUCCESS - The region was successfully opened. > @retval EFI_DEVICE_ERROR - The region could not be opened becau= se > locked by > @@ -89,9 +89,9 @@ Open ( > This routine accepts a request to "close" a region of SMRAM. This is = valid for > compatible SMRAM region. >=20 > - @param[in] PeiServices - General purpose services available to e= very PEIM. > - @param[in] This - Pointer to the SMM Access Interface. > - @param[in] DescriptorIndex - Region of SMRAM to Close. > + @param[in] PeiServices - General purpose services available t= o every > PEIM. > + @param[in] This - Pointer to the SMM Access Interface. > + @param[in] DescriptorIndex - Region of SMRAM to Close. >=20 > @retval EFI_SUCCESS - The region was successfully closed. > @retval EFI_DEVICE_ERROR - The region could not be closed becau= se > locked by > @@ -151,9 +151,9 @@ Close ( > The use of "lock" means that the memory can no longer be opened > to PEIM. >=20 > - @param[in] PeiServices - General purpose services available to ev= ery PEIM. > - @param[in] This - Pointer to the SMM Access Interface. > - @param[in] DescriptorIndex - Region of SMRAM to Lock. > + @param[in] PeiServices - General purpose services available to= every > PEIM. > + @param[in] This - Pointer to the SMM Access Interface. > + @param[in] DescriptorIndex - Region of SMRAM to Lock. >=20 > @retval EFI_SUCCESS - The region was successfully locked. > @retval EFI_DEVICE_ERROR - The region could not be locked becau= se at > least > @@ -193,12 +193,12 @@ Lock ( > ranges that are possible for SMRAM access, based upon the > memory controller capabilities. >=20 > - @param[in] PeiServices - General purpose services available to every= PEIM. > - @param[in] This - Pointer to the SMRAM Access Interface. > - @param[in] SmramMapSize - Pointer to the variable containing size of= the > - buffer to contain the description informat= ion. > - @param[in] SmramMap - Buffer containing the data describing the = Smram > - region descriptors. > + @param[in] PeiServices - General purpose services available to = every > PEIM. > + @param[in] This - Pointer to the SMRAM Access Interface= . > + @param[in, out] SmramMapSize - Pointer to the variable containing si= ze of > the > + buffer to contain the description inf= ormation. > + @param[in, out] SmramMap - Buffer containing the data describing= the > Smram > + region descriptors. >=20 > @retval EFI_BUFFER_TOO_SMALL - The user did not provide a sufficient > buffer. > @retval EFI_SUCCESS - The user provided a sufficiently-size= d buffer. > @@ -234,10 +234,7 @@ GetCapabilities ( > /** > This function is to install an SMM Access PPI > - Introduction \n > - A module to install a PPI for controlling SMM mode memory access bas= ically > for S3 resume usage. > - > - - @result > - Publish _EFI_PEI_MM_ACCESS_PPI. > + An API to install an instance of EFI_PEI_MM_ACCESS_PPI. This PPI is > commonly used to control SMM mode memory access for S3 resume. >=20 > @retval EFI_SUCCESS - Ppi successfully started and install= ed. > @retval EFI_NOT_FOUND - Ppi can't be found. > diff --git > a/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.c > b/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.c > index 3d3c4ab206..1cbce1907c 100644 > --- > a/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.c > +++ > b/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.c > @@ -2,7 +2,7 @@ > This is the driver that publishes the SMM Access Protocol > instance for System Agent. >=20 > - Copyright (c) 2019, Intel Corporation. All rights reserved.
> + Copyright (c) 2019 - 2020, Intel Corporation. All rights reserved.
> SPDX-License-Identifier: BSD-2-Clause-Patent >=20 > **/ > @@ -11,14 +11,24 @@ > static SMM_ACCESS_PRIVATE_DATA mSmmAccess; >=20 > /** > - This is the standard EFI driver point that > - installs an SMM Access Protocol > - > - @param[in] ImageHandle - Handle for the image of this driver > - @param[in] SystemTable - Pointer to the EFI System Table > + SMM Access Driver Entry Point > + This driver installs an SMM Access Protocol > + - Introduction \n > + This module publishes the SMM access protocol. The protocol is used= by the > SMM Base driver to access the SMRAM region when the processor is not in S= MM. > + The SMM Base driver uses the services provided by the SMM access pro= tocol > to open SMRAM during POST and copy the SMM handler. > + SMM access protocol is also used to close the SMRAM region once the > copying is done. > + Finally, the SMM access protocol provides services to "Lock" the SMR= AM > region. > + Please refer the SMM Protocols section in the attached SMM CIS > Specification version 0.9 for further details. > + This driver is required if SMM is supported. Proper configuration of= SMM > registers is recommended even if SMM is not supported. > + > + - Porting Recommendations \n > + No modification of this module is recommended. Any modification sho= uld > be done in compliance with the _EFI_SMM_ACCESS_PROTOCOL protocol > definition. > + > + @param[in] ImageHandle - Handle for the image of this driver > + @param[in] SystemTable - Pointer to the EFI System Table >=20 > @retval EFI_SUCCESS - Protocol was installed successfully > - @exception EFI_UNSUPPORTED - Protocol was not installed > + @retval EFI_UNSUPPORTED - Protocol was not installed > @retval EFI_NOT_FOUND - Protocol can't be found. > @retval EFI_OUT_OF_RESOURCES - Protocol does not have enough resource= s > to initialize the driver. > **/ > @@ -108,8 +118,7 @@ SmmAccessDriverEntryPoint ( > @param[in] This - Pointer to the SMM Access Interface. >=20 > @retval EFI_SUCCESS - The region was successfully opened. > - @retval EFI_DEVICE_ERROR - The region could not be opened because > locked by > - chipset. > + @retval EFI_DEVICE_ERROR - The region could not be opened because > locked by chipset. > @retval EFI_INVALID_PARAMETER - The descriptor index was out of bounds= . > **/ > EFI_STATUS > @@ -229,13 +238,13 @@ Lock ( > memory controller capabilities. >=20 > @param[in] This - Pointer to the SMRAM Access Interfa= ce. > - @param[in] SmramMapSize - Pointer to the variable containing = size of > the > + @param[in, out] SmramMapSize - Pointer to the variable containing = size of > the > buffer to contain the description i= nformation. > - @param[in] SmramMap - Buffer containing the data describi= ng the > Smram > + @param[in, out] SmramMap - Buffer containing the data describi= ng the > Smram > region descriptors. >=20 > - @retval EFI_BUFFER_TOO_SMALL - The user did not provide a sufficient > buffer. > - @retval EFI_SUCCESS - The user provided a sufficiently-sized= buffer. > + @retval EFI_BUFFER_TOO_SMALL - The user did not provide a sufficie= nt > buffer. > + @retval EFI_SUCCESS - The user provided a sufficiently-si= zed buffer. > **/ > EFI_STATUS > EFIAPI > diff --git > a/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.h > b/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.h > index c0ff3a250b..bcdaef7ba6 100644 > --- > a/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.h > +++ > b/Silicon/Intel/IntelSiliconPkg/Feature/SmmAccess/SmmAccessDxe/SmmAccess > Driver.h > @@ -1,7 +1,7 @@ > /** @file > Header file for SMM Access Driver. >=20 > - Copyright (c) 2019, Intel Corporation. All rights reserved.
> + Copyright (c) 2019 - 2020, Intel Corporation. All rights reserved.
> SPDX-License-Identifier: BSD-2-Clause-Patent >=20 > **/ > @@ -53,23 +53,22 @@ typedef struct { > This driver installs an SMM Access Protocol > - Introduction \n > This module publishes the SMM access protocol. The protocol is used= by the > SMM Base driver to access the SMRAM region when the processor is not in S= MM. > - The SMM Base driver uses the services provided by the SMM access pro= tocol > to open SMRAM during post and copy the SMM handler. > + The SMM Base driver uses the services provided by the SMM access pro= tocol > to open SMRAM during POST and copy the SMM handler. > SMM access protocol is also used to close the SMRAM region once the > copying is done. > Finally, the SMM access protocol provides services to "Lock" the SMR= AM > region. > Please refer the SMM Protocols section in the attached SMM CIS > Specification version 0.9 for further details. > This driver is required if SMM is supported. Proper configuration of= SMM > registers is recommended even if SMM is not supported. >=20 > - - @result > - Publishes the _EFI_SMM_ACCESS_PROTOCOL: Documented in the System > Management Mode Core Interface Specification, available at the URL: > http://www.intel.com/technology/framework/spec.htm > - > - Porting Recommendations \n > No modification of this module is recommended. Any modification sho= uld be > done in compliance with the _EFI_SMM_ACCESS_PROTOCOL protocol definition. >=20 > - @param[in] ImageHandle - Handle for the image of this driver > - @param[in] SystemTable - Pointer to the EFI System Table > + @param[in] ImageHandle - Handle for the image of this driver > + @param[in] SystemTable - Pointer to the EFI System Table >=20 > - @retval EFI_SUCCESS - Protocol was installed successfully > - @exception EFI_UNSUPPORTED - Protocol was not installed > + @retval EFI_SUCCESS - Protocol was installed successfully > + @retval EFI_UNSUPPORTED - Protocol was not installed > + @retval EFI_NOT_FOUND - Protocol can't be found. > + @retval EFI_OUT_OF_RESOURCES - Protocol does not have enough > resources to initialize the driver. > **/ > EFI_STATUS > EFIAPI > @@ -87,8 +86,7 @@ SmmAccessDriverEntryPoint ( > @param[in] This - Pointer to the SMM Access Interface= . >=20 > @retval EFI_SUCCESS - The region was successfully opened. > - @retval EFI_DEVICE_ERROR - The region could not be opened because > locked by > - chipset. > + @retval EFI_DEVICE_ERROR - The region could not be opened because > locked by chipset. > @retval EFI_INVALID_PARAMETER - The descriptor index was out of bounds= . > **/ > EFI_STATUS > @@ -103,11 +101,10 @@ Open ( > The use of "close" means that the memory is only visible from SMM agen= ts, > not from BS or RT code. >=20 > - @param[in] This - Pointer to the SMM Access Interface= . > + @param[in] This - Pointer to the SMM Access Interface. >=20 > @retval EFI_SUCCESS - The region was successfully closed. > - @retval EFI_DEVICE_ERROR - The region could not be closed because > locked by > - chipset. > + @retval EFI_DEVICE_ERROR - The region could not be closed because > locked by chipset. > @retval EFI_INVALID_PARAMETER - The descriptor index was out of bounds= . > **/ > EFI_STATUS > @@ -122,11 +119,11 @@ Close ( > The use of "lock" means that the memory can no longer be opened > to BS state.. >=20 > - @param[in] This - Pointer to the SMM Access Interface= . > + @param[in] This - Pointer to the SMM Access Interface. >=20 > @retval EFI_SUCCESS - The region was successfully locked. > @retval EFI_DEVICE_ERROR - The region could not be locked because= at > least > - one range is still open. > + one range is still open. > @retval EFI_INVALID_PARAMETER - The descriptor index was out of bounds= . > **/ > EFI_STATUS > @@ -142,13 +139,13 @@ Lock ( > memory controller capabilities. >=20 > @param[in] This - Pointer to the SMRAM Access Interfa= ce. > - @param[in] SmramMapSize - Pointer to the variable containing = size of > the > - buffer to contain the description informatio= n. > - @param[in] SmramMap - Buffer containing the data describi= ng the > Smram > - region descriptors. > + @param[in, out] SmramMapSize - Pointer to the variable containing = size of > the > + buffer to contain the description i= nformation. > + @param[in, out] SmramMap - Buffer containing the data describi= ng the > Smram > + region descriptors. >=20 > - @retval EFI_BUFFER_TOO_SMALL - The user did not provide a sufficient > buffer. > - @retval EFI_SUCCESS - The user provided a sufficiently-sized= buffer. > + @retval EFI_BUFFER_TOO_SMALL - The user did not provide a sufficie= nt > buffer. > + @retval EFI_SUCCESS - The user provided a sufficiently-si= zed buffer. > **/ > EFI_STATUS > EFIAPI > diff --git a/Silicon/Intel/IntelSiliconPkg/Include/Library/SmmAccessLib.h > b/Silicon/Intel/IntelSiliconPkg/Include/Library/SmmAccessLib.h > index f658bac68c..9792bc4099 100644 > --- a/Silicon/Intel/IntelSiliconPkg/Include/Library/SmmAccessLib.h > +++ b/Silicon/Intel/IntelSiliconPkg/Include/Library/SmmAccessLib.h > @@ -1,7 +1,7 @@ > /** @file > Header file for SMM Access Driver. >=20 > - Copyright (c) 2019, Intel Corporation. All rights reserved.
> + Copyright (c) 2019 - 2020, Intel Corporation. All rights reserved.
> SPDX-License-Identifier: BSD-2-Clause-Patent >=20 > **/ > @@ -11,10 +11,7 @@ > /** > This function is to install an SMM Access PPI > - Introduction \n > - A module to install a PPI for controlling SMM mode memory access bas= ically > for S3 resume usage. > - > - - @result > - Publish _PEI_MM_ACCESS_PPI. > + An API to install an instance of EFI_PEI_MM_ACCESS_PPI. This PPI is > commonly used to control SMM mode memory access for S3 resume. >=20 > @retval EFI_SUCCESS - Ppi successfully started and install= ed. > @retval EFI_NOT_FOUND - Ppi can't be found. > -- > 2.16.2.windows.1 >=20