MdeModulePkg: Add ResetUtility library class and BASE instance
authorMichael D Kinney <michael.d.kinney@intel.com>
Fri, 1 Sep 2017 08:16:50 +0000 (16:16 +0800)
committerRuiyu Ni <ruiyu.ni@intel.com>
Fri, 9 Feb 2018 07:29:58 +0000 (15:29 +0800)
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 <liming.gao@intel.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>
Reviewed-by: Star Zeng <star.zeng@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
MdeModulePkg/Include/Library/ResetUtilityLib.h [new file with mode: 0644]
MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c [new file with mode: 0644]
MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf [new file with mode: 0644]
MdeModulePkg/MdeModulePkg.dec
MdeModulePkg/MdeModulePkg.dsc

diff --git a/MdeModulePkg/Include/Library/ResetUtilityLib.h b/MdeModulePkg/Include/Library/ResetUtilityLib.h
new file mode 100644 (file)
index 0000000..c556dca
--- /dev/null
@@ -0,0 +1,110 @@
+/** @file\r
+  This header describes various helper functions for resetting the system.\r
+\r
+  Copyright (c) 2017 Intel Corporation. All rights reserved.<BR>\r
+  Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>\r
+\r
+  This program and the accompanying materials are licensed and made available under\r
+  the terms and conditions of the BSD License that accompanies this distribution.\r
+  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php.\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+#ifndef _RESET_UTILITY_LIB_H_\r
+#define _RESET_UTILITY_LIB_H_\r
+\r
+/**\r
+  This is a shorthand helper function to reset with a subtype so that\r
+  the caller doesn't have to bother with a function that has half a dozen\r
+  parameters.\r
+\r
+  This will generate a reset with status EFI_SUCCESS, a NULL string, and\r
+  no custom data. The subtype will be formatted in such a way that it can be\r
+  picked up by notification registrations and custom handlers.\r
+\r
+  NOTE: This call will fail if the architectural ResetSystem underpinnings\r
+        are not initialized. For DXE, you can add gEfiResetArchProtocolGuid\r
+        to your DEPEX.\r
+\r
+  @param[in]  ResetSubtype  GUID pointer for the reset subtype to be used.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+ResetPlatformSpecificGuid (\r
+  IN CONST  GUID        *ResetSubtype\r
+  );\r
+\r
+/**\r
+  This function examines the DataSize and ResetData parameters passed to\r
+  to ResetSystem() and detemrines if the ResetData contains a Null-terminated\r
+  Unicode string followed by a GUID specific subtype.  If the GUID specific \r
+  subtype is present, then a pointer to the GUID value in ResetData is returned.\r
+\r
+  @param[in]  DataSize    The size, in bytes, of ResetData.\r
+  @param[in]  ResetData   Pointer to the data buffer passed into ResetSystem().\r
+\r
+  @retval     Pointer     Pointer to the GUID value in ResetData.\r
+  @retval     NULL        ResetData is NULL.\r
+  @retval     NULL        ResetData does not start with a Null-terminated\r
+                          Unicode string.\r
+  @retval     NULL        A Null-terminated Unicode string is present, but there\r
+                          are less than sizeof (GUID) bytes after the string.\r
+  @retval     NULL        No subtype is found.\r
+\r
+**/\r
+GUID *\r
+EFIAPI\r
+GetResetPlatformSpecificGuid (\r
+  IN UINTN       DataSize,\r
+  IN CONST VOID  *ResetData\r
+  );\r
+\r
+/**\r
+  This is a helper function that creates the reset data buffer that can be \r
+  passed into ResetSystem().\r
+\r
+  The reset data buffer is returned in ResetData and contains ResetString\r
+  followed by the ResetSubtype GUID followed by the ExtraData.\r
+\r
+  NOTE: Strings are internally limited by MAX_UINT16.\r
+\r
+  @param[in, out] ResetDataSize  On input, the size of the ResetData buffer. On\r
+                                 output, either the total number of bytes\r
+                                 copied, or the required buffer size.\r
+  @param[in, out] ResetData      A pointer to the buffer in which to place the\r
+                                 final structure.\r
+  @param[in]      ResetSubtype   Pointer to the GUID specific subtype.  This\r
+                                 parameter is optional and may be NULL.\r
+  @param[in]      ResetString    Pointer to a Null-terminated Unicode string\r
+                                 that describes the reset.  This parameter is\r
+                                 optional and may be NULL.\r
+  @param[in]      ExtraDataSize  The size, in bytes, of ExtraData buffer.\r
+  @param[in]      ExtraData      Pointer to a buffer of extra data.  This\r
+                                 parameter is optional and may be NULL.\r
+\r
+  @retval     RETURN_SUCCESS             ResetDataSize and ResetData are updated.\r
+  @retval     RETURN_INVALID_PARAMETER   ResetDataSize is NULL.\r
+  @retval     RETURN_INVALID_PARAMETER   ResetData is NULL.\r
+  @retval     RETURN_INVALID_PARAMETER   ExtraData was provided without a\r
+                                         ResetSubtype. This is not supported by the\r
+                                         UEFI spec.\r
+  @retval     RETURN_BUFFER_TOO_SMALL    An insufficient buffer was provided.\r
+                                         ResetDataSize is updated with minimum size\r
+                                         required.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+BuildResetData (\r
+  IN OUT   UINTN     *ResetDataSize,\r
+  IN OUT   VOID      *ResetData,\r
+  IN CONST GUID      *ResetSubtype  OPTIONAL,\r
+  IN CONST CHAR16    *ResetString   OPTIONAL,\r
+  IN       UINTN     ExtraDataSize  OPTIONAL,\r
+  IN CONST VOID      *ExtraData     OPTIONAL\r
+  );\r
+\r
+#endif // _RESET_UTILITY_LIB_H_\r
diff --git a/MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c b/MdeModulePkg/Library/ResetUtilityLib/ResetUtility.c
new file mode 100644 (file)
index 0000000..90de94c
--- /dev/null
@@ -0,0 +1,220 @@
+/** @file\r
+  This contains the business logic for the module-specific Reset Helper functions.\r
+\r
+  Copyright (c) 2017 Intel Corporation. All rights reserved.<BR>\r
+  Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>\r
+\r
+  This program and the accompanying materials are licensed and made available under\r
+  the terms and conditions of the BSD License that accompanies this distribution.\r
+  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php.\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+#include <Uefi.h>\r
+#include <Library/BaseLib.h>\r
+#include <Library/DebugLib.h>\r
+#include <Library/BaseMemoryLib.h>\r
+#include <Library/ResetSystemLib.h>\r
+\r
+typedef struct {\r
+  CHAR16 NullTerminator;\r
+  GUID   ResetSubtype;\r
+} RESET_UTILITY_GUID_SPECIFIC_RESET_DATA;\r
+\r
+/**\r
+  This is a shorthand helper function to reset with a subtype so that\r
+  the caller doesn't have to bother with a function that has half a dozen\r
+  parameters.\r
+\r
+  This will generate a reset with status EFI_SUCCESS, a NULL string, and\r
+  no custom data. The subtype will be formatted in such a way that it can be\r
+  picked up by notification registrations and custom handlers.\r
+\r
+  NOTE: This call will fail if the architectural ResetSystem underpinnings\r
+        are not initialized. For DXE, you can add gEfiResetArchProtocolGuid\r
+        to your DEPEX.\r
+\r
+  @param[in]  ResetSubtype  GUID pointer for the reset subtype to be used.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+ResetPlatformSpecificGuid (\r
+  IN CONST  GUID        *ResetSubtype\r
+  )\r
+{\r
+  RESET_UTILITY_GUID_SPECIFIC_RESET_DATA  ResetData;\r
+\r
+  ResetData.NullTerminator = CHAR_NULL;\r
+  CopyGuid (&ResetData.ResetSubtype, ResetSubtype);\r
+  ResetPlatformSpecific (sizeof (ResetData), &ResetData);\r
+}\r
+\r
+/**\r
+  This function examines the DataSize and ResetData parameters passed to\r
+  to ResetSystem() and detemrines if the ResetData contains a Null-terminated\r
+  Unicode string followed by a GUID specific subtype.  If the GUID specific \r
+  subtype is present, then a pointer to the GUID value in ResetData is returned.\r
+\r
+  @param[in]  DataSize    The size, in bytes, of ResetData.\r
+  @param[in]  ResetData   Pointer to the data buffer passed into ResetSystem().\r
+\r
+  @retval     Pointer     Pointer to the GUID value in ResetData.\r
+  @retval     NULL        ResetData is NULL.\r
+  @retval     NULL        ResetData does not start with a Null-terminated\r
+                          Unicode string.\r
+  @retval     NULL        A Null-terminated Unicode string is present, but there\r
+                          are less than sizeof (GUID) bytes after the string.\r
+  @retval     NULL        No subtype is found.\r
+\r
+**/\r
+GUID *\r
+EFIAPI\r
+GetResetPlatformSpecificGuid (\r
+  IN UINTN       DataSize,\r
+  IN CONST VOID  *ResetData\r
+  )\r
+{\r
+  UINTN          ResetDataStringSize;\r
+  GUID           *ResetSubtypeGuid;\r
+\r
+  //\r
+  // Make sure parameters are valid\r
+  //\r
+  if ((ResetData == NULL) || (DataSize < sizeof (GUID))) {\r
+    return NULL;\r
+  }\r
+\r
+  //\r
+  // Determine the number of bytes in the Null-terminated Unicode string\r
+  // at the beginning of ResetData including the Null terminator.\r
+  //\r
+  ResetDataStringSize = StrnSizeS (ResetData, (DataSize / sizeof (CHAR16)));\r
+\r
+  //\r
+  // Now, assuming that we have enough data for a GUID after the string, the\r
+  // GUID should be immediately after the string itself.\r
+  //\r
+  if ((ResetDataStringSize < DataSize) && (DataSize - ResetDataStringSize) >= sizeof (GUID)) {\r
+    ResetSubtypeGuid = (GUID *)((UINT8 *)ResetData + ResetDataStringSize);\r
+    DEBUG ((DEBUG_VERBOSE, __FUNCTION__" - Detected reset subtype %g...\n", ResetSubtypeGuid));\r
+    return ResetSubtypeGuid;\r
+  }\r
+  return NULL;\r
+}\r
+\r
+/**\r
+  This is a helper function that creates the reset data buffer that can be \r
+  passed into ResetSystem().\r
+\r
+  The reset data buffer is returned in ResetData and contains ResetString\r
+  followed by the ResetSubtype GUID followed by the ExtraData.\r
+\r
+  NOTE: Strings are internally limited by MAX_UINT16.\r
+\r
+  @param[in, out] ResetDataSize  On input, the size of the ResetData buffer. On\r
+                                 output, either the total number of bytes\r
+                                 copied, or the required buffer size.\r
+  @param[in, out] ResetData      A pointer to the buffer in which to place the\r
+                                 final structure.\r
+  @param[in]      ResetSubtype   Pointer to the GUID specific subtype.  This\r
+                                 parameter is optional and may be NULL.\r
+  @param[in]      ResetString    Pointer to a Null-terminated Unicode string\r
+                                 that describes the reset.  This parameter is\r
+                                 optional and may be NULL.\r
+  @param[in]      ExtraDataSize  The size, in bytes, of ExtraData buffer.\r
+  @param[in]      ExtraData      Pointer to a buffer of extra data.  This\r
+                                 parameter is optional and may be NULL.\r
+\r
+  @retval     RETURN_SUCCESS             ResetDataSize and ResetData are updated.\r
+  @retval     RETURN_INVALID_PARAMETER   ResetDataSize is NULL.\r
+  @retval     RETURN_INVALID_PARAMETER   ResetData is NULL.\r
+  @retval     RETURN_INVALID_PARAMETER   ExtraData was provided without a\r
+                                         ResetSubtype. This is not supported by the\r
+                                         UEFI spec.\r
+  @retval     RETURN_BUFFER_TOO_SMALL    An insufficient buffer was provided.\r
+                                         ResetDataSize is updated with minimum size\r
+                                         required.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+BuildResetData (\r
+  IN OUT   UINTN     *ResetDataSize,\r
+  IN OUT   VOID      *ResetData,\r
+  IN CONST GUID      *ResetSubtype  OPTIONAL,\r
+  IN CONST CHAR16    *ResetString   OPTIONAL,\r
+  IN       UINTN     ExtraDataSize  OPTIONAL,\r
+  IN CONST VOID      *ExtraData     OPTIONAL\r
+  )\r
+{\r
+  UINTN  ResetStringSize;\r
+  UINTN  ResetDataBufferSize;\r
+  UINT8  *Data;\r
+\r
+  //\r
+  // If the size return pointer is NULL.\r
+  //\r
+  if (ResetDataSize == NULL) {\r
+    return RETURN_INVALID_PARAMETER;\r
+  }\r
+  //\r
+  // If extra data is indicated, but pointer is NULL.\r
+  //\r
+  if (ExtraDataSize > 0 && ExtraData == NULL) {\r
+    return RETURN_INVALID_PARAMETER;\r
+  }\r
+  //\r
+  // If extra data is indicated, but no subtype GUID is supplied.\r
+  //\r
+  if (ResetSubtype == NULL && ExtraDataSize > 0) {\r
+    return RETURN_INVALID_PARAMETER;\r
+  }\r
+\r
+  //\r
+  // Determine the final string.\r
+  //\r
+  if (ResetString == NULL) {\r
+    ResetString = L"";     // Use an empty string.\r
+  }\r
+  \r
+  //\r
+  // Calculate the total buffer required for ResetData.\r
+  //\r
+  ResetStringSize     = StrnSizeS (ResetString, MAX_UINT16);\r
+  ResetDataBufferSize = ResetStringSize + ExtraDataSize;\r
+  if (ResetSubtype != NULL) {\r
+    ResetDataBufferSize += sizeof (GUID);\r
+  }\r
+\r
+  //\r
+  // At this point, if the buffer isn't large enough (or if\r
+  // the buffer is NULL) we cannot proceed.\r
+  //\r
+  if (*ResetDataSize < ResetDataBufferSize) {\r
+    *ResetDataSize = ResetDataBufferSize;\r
+    return RETURN_BUFFER_TOO_SMALL;\r
+  }\r
+  *ResetDataSize = ResetDataBufferSize;\r
+  if (ResetData == NULL) {\r
+    return RETURN_INVALID_PARAMETER;\r
+  }\r
+\r
+  //\r
+  // Fill in ResetData with ResetString, the ResetSubtype GUID, and extra data\r
+  //\r
+  Data = (UINT8 *)ResetData;\r
+  CopyMem (Data, ResetString, ResetStringSize);\r
+  Data += ResetStringSize;\r
+  if (ResetSubtype != NULL) {\r
+    CopyMem (Data, ResetSubtype, sizeof (GUID));\r
+    Data += sizeof (GUID);\r
+  }\r
+  if (ExtraDataSize > 0) {\r
+    CopyMem (Data, ExtraData, ExtraDataSize);\r
+  }\r
+  \r
+  return RETURN_SUCCESS;\r
+}\r
diff --git a/MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf b/MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf
new file mode 100644 (file)
index 0000000..2a4e53a
--- /dev/null
@@ -0,0 +1,40 @@
+## @file\r
+# This file contains the Reset Utility functions.\r
+#\r
+#  Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.<BR>\r
+#  Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
+#  This program and the accompanying materials\r
+#  are licensed and made available under the terms and conditions of the BSD License\r
+#  which accompanies this distribution.  The full text of the license may be found at\r
+#  http://opensource.org/licenses/bsd-license.php\r
+#  \r
+#  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+#  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+#  \r
+##\r
+[Defines]\r
+  INF_VERSION         = 0x00010017\r
+  BASE_NAME           = ResetUtilityLib\r
+  FILE_GUID           = CAFC3CA1-3E32-449F-9B0E-40BA3CB73A12\r
+  VERSION_STRING      = 1.0\r
+  MODULE_TYPE         = BASE\r
+  LIBRARY_CLASS       = ResetUtilityLib\r
+\r
+#\r
+# The following information is for reference only and not required by the build tools.\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources]\r
+  ResetUtility.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+  MdeModulePkg/MdeModulePkg.dec\r
+\r
+[LibraryClasses]\r
+  BaseLib\r
+  DebugLib\r
+  BaseMemoryLib\r
+  ResetSystemLib\r
index 5dc0f57..0d567d0 100644 (file)
@@ -54,6 +54,9 @@
   ##  @libraryclass  Defines a set of methods to reset whole system.\r
   ResetSystemLib|Include/Library/ResetSystemLib.h\r
 \r
+  ##  @libraryclass  Defines a set of helper functions for resetting the system.\r
+  ResetUtilityLib|Include/Library/ResetUtilityLib.h\r
+\r
   ##  @libraryclass  Defines a set of methods related do S3 mode.\r
   #   This library class is no longer used and modules using this library should\r
   #   directly locate EFI_PEI_S3_RESUME_PPI defined in PI 1.2 specification.\r
index 1c0085a..34bb1a1 100644 (file)
   MdeModulePkg/Library/DxeIpIoLib/DxeIpIoLib.inf\r
   MdeModulePkg/Library/DxeNetLib/DxeNetLib.inf\r
   MdeModulePkg/Library/DxePerformanceLib/DxePerformanceLib.inf\r
+  MdeModulePkg/Library/DxeResetSystemLib/DxeResetSystemLib.inf\r
   MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.inf\r
   MdeModulePkg/Library/DxePrintLibPrint2Protocol/DxePrintLibPrint2Protocol.inf\r
   MdeModulePkg/Library/PeiCrc32GuidedSectionExtractLib/PeiCrc32GuidedSectionExtractLib.inf\r
   MdeModulePkg/Library/PeiPerformanceLib/PeiPerformanceLib.inf\r
   MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.inf\r
+  MdeModulePkg/Library/PeiResetSystemLib/PeiResetSystemLib.inf\r
   MdeModulePkg/Library/PeiS3LibNull/PeiS3LibNull.inf\r
   MdeModulePkg/Library/UefiHiiLib/UefiHiiLib.inf\r
+  MdeModulePkg/Library/ResetUtilityLib/ResetUtilityLib.inf\r
   MdeModulePkg/Library/BaseResetSystemLibNull/BaseResetSystemLibNull.inf\r
   MdeModulePkg/Library/DxeSecurityManagementLib/DxeSecurityManagementLib.inf\r
   MdeModulePkg/Library/OemHookStatusCodeLibNull/OemHookStatusCodeLibNull.inf\r