MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Library / ResetUtilityLib / ResetUtility.c

/** @file\r
  This contains the business logic for the module-specific Reset Helper functions.\r
\r
  Copyright (c) 2017 - 2018 Intel Corporation. All rights reserved.<BR>\r
  Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\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
#pragma pack(1)\r
typedef struct {\r
  CHAR16 NullTerminator;\r
  GUID   ResetSubtype;\r
} RESET_UTILITY_GUID_SPECIFIC_RESET_DATA;\r
#pragma pack()\r
\r
VERIFY_SIZE_OF (RESET_UTILITY_GUID_SPECIFIC_RESET_DATA, 18);\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 (\r
    (GUID *)((UINT8 *)&ResetData + OFFSET_OF (RESET_UTILITY_GUID_SPECIFIC_RESET_DATA, ResetSubtype)),\r
    ResetSubtype\r
    );\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, "%a - Detected reset subtype %g...\n", __FUNCTION__, 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