From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=192.55.52.93; helo=mga11.intel.com; envelope-from=star.zeng@intel.com; receiver=edk2-devel@lists.01.org Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 23CAB223972DC for ; Wed, 7 Feb 2018 04:23:36 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 07 Feb 2018 04:29:19 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,473,1511856000"; d="scan'208";a="28110462" Received: from shzintpr02.sh.intel.com (HELO [10.253.24.48]) ([10.239.4.160]) by fmsmga004.fm.intel.com with ESMTP; 07 Feb 2018 04:29:18 -0800 To: Ruiyu Ni , edk2-devel@lists.01.org Cc: Michael D Kinney , Liming Gao , star.zeng@intel.com References: <20180202064530.407028-1-ruiyu.ni@intel.com> <20180202064530.407028-8-ruiyu.ni@intel.com> From: "Zeng, Star" Message-ID: <3b0d88cd-a8c3-83c0-7051-e286023be882@intel.com> Date: Wed, 7 Feb 2018 20:28:48 +0800 User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.5.2 MIME-Version: 1.0 In-Reply-To: <20180202064530.407028-8-ruiyu.ni@intel.com> Subject: Re: [PATCH 07/10] MdeModulePkg: Add ResetUtility librray class and BASE instance X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 07 Feb 2018 12:23:36 -0000 Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit On 2018/2/2 14:45, Ruiyu Ni wrote: > From: Michael D Kinney > > The library class that provides services to generate a GUID specific > reset, parse the GUID from a GUID specific reset, and build the > ResetData buffer for any type of reset that requires extra data. > > Cc: Liming Gao > Reviewed-by: Ruiyu Ni > Cc: Star Zeng > Contributed-under: TianoCore Contribution Agreement 1.1 > Signed-off-by: Michael D Kinney > Signed-off-by: Ruiyu Ni Should we also add below lines in MdeModulePkg.dec? ## @libraryclass Defines a set of helper functions for resetting the system ResetUtilityLib|Include/Library/ResetUtilityLib.h Thanks, Star > --- > MdeModulePkg/Include/Library/ResetUtilityLib.h | 111 +++++++++++ > .../Library/ResetUtilityLib/ResetUtility.c | 221 +++++++++++++++++++++ > .../Library/ResetUtilityLib/ResetUtilityLib.inf | 43 ++++ > MdeModulePkg/MdeModulePkg.dsc | 7 + > 4 files changed, 382 insertions(+) > create mode 100644 MdeModulePkg/Include/Library/ResetUtilityLib.h > create mode 100644 MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c > create mode 100644 MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf > > diff --git a/MdeModulePkg/Include/Library/ResetUtilityLib.h b/MdeModulePkg/Include/Library/ResetUtilityLib.h > new file mode 100644 > index 0000000000..94828785e2 > --- /dev/null > +++ b/MdeModulePkg/Include/Library/ResetUtilityLib.h > @@ -0,0 +1,111 @@ > +/** @file > + This header describes various helper functions for resetting the system. > + > + Copyright (c) 2017 Intel Corporation. All rights reserved.
> + Copyright (c) 2016 Microsoft Corporation. All rights reserved.
> + > + This program and the accompanying materials are licensed and made available under > + the terms and conditions of the BSD License that accompanies this distribution. > + The full text of the license may be found at > + http://opensource.org/licenses/bsd-license.php. > + > + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, > + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. > + > +**/ > +#ifndef _RESET_UTILITY_LIB_H_ > +#define _RESET_UTILITY_LIB_H_ > + > +/** > + This is a shorthand helper function to reset with a subtype so that > + the caller doesn't have to bother with a function that has half a dozen > + parameters. > + > + This will generate a reset with status EFI_SUCCESS, a NULL string, and > + no custom data. The subtype will be formatted in such a way that it can be > + picked up by notification registrations and custom handlers. > + > + NOTE: This call will fail if the architectural ResetSystem underpinnings > + are not initialized. For DXE, you can add gEfiResetArchProtocolGuid > + to your DEPEX. > + > + @param[in] ResetType Base reset type as defined in UEFI spec. > + @param[in] ResetSubtype GUID pointer for the reset subtype to be used. > + > +**/ > +VOID > +EFIAPI > +ResetPlatformSpecificGuid ( > + IN CONST GUID *ResetSubtype > + ); > + > +/** > + This function examines the DataSize and ResetData parameters passed to > + to ResetSystem() and detemrines if the ResetData contains a Null-terminated > + Unicode string followed by a GUID specific subtype. If the GUID specific > + subtype is present, then a pointer to the GUID value in ResetData is returned. > + > + @param[in] DataSize The size, in bytes, of ResetData. > + @param[in] ResetData Pointer to the data buffer passed into ResetSystem(). > + > + @retval Pointer Pointer to the GUID value in ResetData. > + @retval NULL ResetData is NULL. > + @retval NULL ResetData does not start with a Null-terminated > + Unicode string. > + @retval NULL A Null-terminated Unicode string is present, but there > + are less than sizeof (GUID) bytes after the string. > + @retval NULL No subtype is found. > + > +**/ > +GUID * > +EFIAPI > +GetResetPlatformSpecificGuid ( > + IN UINTN DataSize, > + IN CONST VOID *ResetData > + ); > + > +/** > + This is a helper function that creates the reset data buffer that can be > + passed into ResetSystem(). > + > + The reset data buffer is returned in ResetData and contains ResetString > + followed by the ResetSubtype GUID followed by the ExtraData. > + > + NOTE: Strings are internally limited by MAX_UINT16. > + > + @param[in, out] ResetDataSize On input, the size of the ResetData buffer. On > + output, either the total number of bytes > + copied, or the required buffer size. > + @param[in, out] ResetData A pointer to the buffer in which to place the > + final structure. > + @param[in] ResetSubtype Pointer to the GUID specific subtype. This > + parameter is optional and may be NULL. > + @param[in] ResetString Pointer to a Null-terminated Unicode string > + that describes the reset. This parameter is > + optional and may be NULL. > + @param[in] ExtraDataSize The size, in bytes, of ExtraData buffer. > + @param[in] ExtraData Pointer to a buffer of extra data. This > + parameter is optional and may be NULL. > + > + @retval RETURN_SUCCESS ResetDataSize and ResetData are updated. > + @retval RETURN_INVALID_PARAMETER ResetDataSize is NULL. > + @retval RETURN_INVALID_PARAMETER ResetData is NULL. > + @retval RETURN_INVALID_PARAMETER ExtraData was provided without a > + ResetSubtype. This is not supported by the > + UEFI spec. > + @retval RETURN_BUFFER_TOO_SMALL An insufficient buffer was provided. > + ResetDataSize is updated with minimum size > + required. > +**/ > +RETURN_STATUS > +EFIAPI > +BuildResetData ( > + IN OUT UINTN *ResetDataSize, > + IN OUT VOID *ResetData, > + IN CONST GUID *ResetSubtype OPTIONAL, > + IN CONST CHAR16 *ResetString OPTIONAL, > + IN UINTN ExtraDataSize OPTIONAL, > + IN CONST VOID *ExtraData OPTIONAL > + ); > + > +#endif // _RESET_UTILITY_LIB_H_ > diff --git a/MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c b/MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c > new file mode 100644 > index 0000000000..5bbe002be0 > --- /dev/null > +++ b/MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c > @@ -0,0 +1,221 @@ > +/** @file > + This contains the business logic for the module-specific Reset Helper functions. > + > + Copyright (c) 2017 Intel Corporation. All rights reserved.
> + Copyright (c) 2016 Microsoft Corporation. All rights reserved.
> + > + This program and the accompanying materials are licensed and made available under > + the terms and conditions of the BSD License that accompanies this distribution. > + The full text of the license may be found at > + http://opensource.org/licenses/bsd-license.php. > + > + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, > + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. > + > +**/ > +#include > +#include > +#include > +#include > +#include > + > +typedef struct { > + CHAR16 NullTerminator; > + GUID ResetSubtype; > +} RESET_UTILITY_GUID_SPECIFIC_RESET_DATA; > + > +/** > + This is a shorthand helper function to reset with a subtype so that > + the caller doesn't have to bother with a function that has half a dozen > + parameters. > + > + This will generate a reset with status EFI_SUCCESS, a NULL string, and > + no custom data. The subtype will be formatted in such a way that it can be > + picked up by notification registrations and custom handlers. > + > + NOTE: This call will fail if the architectural ResetSystem underpinnings > + are not initialized. For DXE, you can add gEfiResetArchProtocolGuid > + to your DEPEX. > + > + @param[in] ResetType Base reset type as defined in UEFI spec. > + @param[in] ResetSubtype GUID pointer for the reset subtype to be used. > + > +**/ > +VOID > +EFIAPI > +ResetPlatformSpecificGuid ( > + IN CONST GUID *ResetSubtype > + ) > +{ > + RESET_UTILITY_GUID_SPECIFIC_RESET_DATA ResetData; > + > + ResetData.NullTerminator = CHAR_NULL; > + CopyGuid (&ResetData.ResetSubtype, ResetSubtype); > + ResetPlatformSpecific (sizeof (ResetData), &ResetData); > +} > + > +/** > + This function examines the DataSize and ResetData parameters passed to > + to ResetSystem() and detemrines if the ResetData contains a Null-terminated > + Unicode string followed by a GUID specific subtype. If the GUID specific > + subtype is present, then a pointer to the GUID value in ResetData is returned. > + > + @param[in] DataSize The size, in bytes, of ResetData. > + @param[in] ResetData Pointer to the data buffer passed into ResetSystem(). > + > + @retval Pointer Pointer to the GUID value in ResetData. > + @retval NULL ResetData is NULL. > + @retval NULL ResetData does not start with a Null-terminated > + Unicode string. > + @retval NULL A Null-terminated Unicode string is present, but there > + are less than sizeof (GUID) bytes after the string. > + @retval NULL No subtype is found. > + > +**/ > +GUID * > +EFIAPI > +GetResetPlatformSpecificGuid ( > + IN UINTN DataSize, > + IN CONST VOID *ResetData > + ) > +{ > + UINTN ResetDataStringSize; > + GUID *ResetSubtypeGuid; > + > + // > + // Make sure parameters are valid > + // > + if ((ResetData == NULL) || (DataSize < sizeof (GUID))) { > + return NULL; > + } > + > + // > + // Determine the number of bytes in in the Null-terminated Unicode string > + // at the beginning of ResetData including the Null terminator. > + // > + ResetDataStringSize = StrnSizeS (ResetData, (DataSize / sizeof (CHAR16))); > + > + // > + // Now, assuming that we have enough data for a GUID after the string, the > + // GUID should be immediately after the string itself. > + // > + if ((ResetDataStringSize < DataSize) && (DataSize - ResetDataStringSize) >= sizeof (GUID)) { > + ResetSubtypeGuid = (GUID *)((UINT8 *)ResetData + ResetDataStringSize); > + DEBUG ((DEBUG_VERBOSE, __FUNCTION__" - Detected reset subtype %g...\n", ResetSubtypeGuid)); > + return ResetSubtypeGuid; > + } > + return NULL; > +} > + > +/** > + This is a helper function that creates the reset data buffer that can be > + passed into ResetSystem(). > + > + The reset data buffer is returned in ResetData and contains ResetString > + followed by the ResetSubtype GUID followed by the ExtraData. > + > + NOTE: Strings are internally limited by MAX_UINT16. > + > + @param[in, out] ResetDataSize On input, the size of the ResetData buffer. On > + output, either the total number of bytes > + copied, or the required buffer size. > + @param[in, out] ResetData A pointer to the buffer in which to place the > + final structure. > + @param[in] ResetSubtype Pointer to the GUID specific subtype. This > + parameter is optional and may be NULL. > + @param[in] ResetString Pointer to a Null-terminated Unicode string > + that describes the reset. This parameter is > + optional and may be NULL. > + @param[in] ExtraDataSize The size, in bytes, of ExtraData buffer. > + @param[in] ExtraData Pointer to a buffer of extra data. This > + parameter is optional and may be NULL. > + > + @retval RETURN_SUCCESS ResetDataSize and ResetData are updated. > + @retval RETURN_INVALID_PARAMETER ResetDataSize is NULL. > + @retval RETURN_INVALID_PARAMETER ResetData is NULL. > + @retval RETURN_INVALID_PARAMETER ExtraData was provided without a > + ResetSubtype. This is not supported by the > + UEFI spec. > + @retval RETURN_BUFFER_TOO_SMALL An insufficient buffer was provided. > + ResetDataSize is updated with minimum size > + required. > +**/ > +RETURN_STATUS > +EFIAPI > +BuildResetData ( > + IN OUT UINTN *ResetDataSize, > + IN OUT VOID *ResetData, > + IN CONST GUID *ResetSubtype OPTIONAL, > + IN CONST CHAR16 *ResetString OPTIONAL, > + IN UINTN ExtraDataSize OPTIONAL, > + IN CONST VOID *ExtraData OPTIONAL > + ) > +{ > + UINTN ResetStringSize; > + UINTN ResetDataBufferSize; > + UINT8 *Data; > + > + // > + // If the size return pointer is NULL. > + // > + if (ResetDataSize == NULL) { > + return RETURN_INVALID_PARAMETER; > + } > + // > + // If extra data is indicated, but pointer is NULL. > + // > + if (ExtraDataSize > 0 && ExtraData == NULL) { > + return RETURN_INVALID_PARAMETER; > + } > + // > + // If extra data is indicated, but no subtype GUID is supplied. > + // > + if (ResetSubtype == NULL && ExtraDataSize > 0) { > + return RETURN_INVALID_PARAMETER; > + } > + > + // > + // Determine the final string. > + // > + if (ResetString == NULL) { > + ResetString = L""; // Use an empty string. > + } > + > + // > + // Calculate the total buffer required for ResetData. > + // > + ResetStringSize = StrnSizeS (ResetString, MAX_UINT16); > + ResetDataBufferSize = ResetStringSize + ExtraDataSize; > + if (ResetSubtype != NULL) { > + ResetDataBufferSize += sizeof (GUID); > + } > + > + // > + // At this point, if the buffer isn't large enough (or if > + // the buffer is NULL) we cannot proceed. > + // > + if (*ResetDataSize < ResetDataBufferSize) { > + *ResetDataSize = ResetDataBufferSize; > + return RETURN_BUFFER_TOO_SMALL; > + } > + *ResetDataSize = ResetDataBufferSize; > + if (ResetData == NULL) { > + return RETURN_INVALID_PARAMETER; > + } > + > + // > + // Fill in ResetData with ResetString, the ResetSubtype GUID, and extra data > + // > + Data = (UINT8 *)ResetData; > + CopyMem (Data, ResetString, ResetStringSize); > + Data += ResetStringSize; > + if (ResetSubtype != NULL) { > + CopyMem (Data, ResetSubtype, sizeof (GUID)); > + Data += sizeof (GUID); > + } > + if (ExtraDataSize > 0) { > + CopyMem (Data, ExtraData, ExtraDataSize); > + } > + > + return RETURN_SUCCESS; > +} > diff --git a/MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf b/MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf > new file mode 100644 > index 0000000000..7a403749c5 > --- /dev/null > +++ b/MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf > @@ -0,0 +1,43 @@ > +## @file > +# This file contains the Reset Utility functions. > +# > +# The application pops up a menu showing all the boot options referenced by > +# BootOrder NV variable and user can choose to boot from one of them. > +# > +# Copyright (c) 2017, Intel Corporation. All rights reserved.
> +# Copyright (c) 2016, Microsoft Corporation. All rights reserved.
> +# This program and the accompanying materials > +# are licensed and made available under the terms and conditions of the BSD License > +# which accompanies this distribution. The full text of the license may be found at > +# http://opensource.org/licenses/bsd-license.php > +# > +# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, > +# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. > +# > +## > +[Defines] > + INF_VERSION = 0x00010017 > + BASE_NAME = ResetUtilityLib > + FILE_GUID = CAFC3CA1-3E32-449F-9B0E-40BA3CB73A12 > + VERSION_STRING = 1.0 > + MODULE_TYPE = BASE > + LIBRARY_CLASS = ResetUtilityLib > + > +# > +# The following information is for reference only and not required by the build tools. > +# > +# VALID_ARCHITECTURES = IA32 X64 > +# > + > +[Sources] > + ResetUtility.c > + > +[Packages] > + MdePkg/MdePkg.dec > + MdeModulePkg/MdeModulePkg.dec > + > +[LibraryClasses] > + BaseLib > + DebugLib > + BaseMemoryLib > + ResetSystemLib > diff --git a/MdeModulePkg/MdeModulePkg.dsc b/MdeModulePkg/MdeModulePkg.dsc > index dd7e9d5988..d96bff90b0 100644 > --- a/MdeModulePkg/MdeModulePkg.dsc > +++ b/MdeModulePkg/MdeModulePkg.dsc > @@ -285,13 +285,16 @@ [Components] > MdeModulePkg/Library/DxeIpIoLib/DxeIpIoLib.inf > MdeModulePkg/Library/DxeNetLib/DxeNetLib.inf > MdeModulePkg/Library/DxePerformanceLib/DxePerformanceLib.inf > + MdeModulePkg/Library/DxeResetSystemLib/DxeResetSystemLib.inf > MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.inf > MdeModulePkg/Library/DxePrintLibPrint2Protocol/DxePrintLibPrint2Protocol.inf > MdeModulePkg/Library/PeiCrc32GuidedSectionExtractLib/PeiCrc32GuidedSectionExtractLib.inf > MdeModulePkg/Library/PeiPerformanceLib/PeiPerformanceLib.inf > MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.inf > + MdeModulePkg/Library/PeiResetSystemLib/PeiResetSystemLib.inf > MdeModulePkg/Library/PeiS3LibNull/PeiS3LibNull.inf > MdeModulePkg/Library/UefiHiiLib/UefiHiiLib.inf > + MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf > MdeModulePkg/Library/BaseResetSystemLibNull/BaseResetSystemLibNull.inf > MdeModulePkg/Library/DxeSecurityManagementLib/DxeSecurityManagementLib.inf > MdeModulePkg/Library/OemHookStatusCodeLibNull/OemHookStatusCodeLibNull.inf > @@ -358,6 +361,10 @@ [Components] > MdeModulePkg/Universal/MemoryTest/NullMemoryTestDxe/NullMemoryTestDxe.inf > MdeModulePkg/Universal/Metronome/Metronome.inf > MdeModulePkg/Universal/MonotonicCounterRuntimeDxe/MonotonicCounterRuntimeDxe.inf > + MdeModulePkg/Universal/ResetSystemPei/ResetSystemPei.inf { > + > + ResetSystemLib|MdeModulePkg/Library/BaseResetSystemLibNull/BaseResetSystemLibNull.inf > + } > MdeModulePkg/Universal/ResetSystemRuntimeDxe/ResetSystemRuntimeDxe.inf > MdeModulePkg/Universal/SmbiosDxe/SmbiosDxe.inf > MdeModulePkg/Universal/SmbiosMeasurementDxe/SmbiosMeasurementDxe.inf >