MdeModulePkg/Include/Library/ResetUtilityLib.h

   1 /** @file
   2   This header describes various helper functions for resetting the system.
   3
   4   Copyright (c) 2017 Intel Corporation. All rights reserved.<BR>
   5   Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>
   6
   7   This program and the accompanying materials are licensed and made available under
   8   the terms and conditions of the BSD License that accompanies this distribution.
   9   The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php.
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16 #ifndef _RESET_UTILITY_LIB_H_
  17 #define _RESET_UTILITY_LIB_H_
  18
  19 /**
  20   This is a shorthand helper function to reset with a subtype so that
  21   the caller doesn't have to bother with a function that has half a dozen
  22   parameters.
  23
  24   This will generate a reset with status EFI_SUCCESS, a NULL string, and
  25   no custom data. The subtype will be formatted in such a way that it can be
  26   picked up by notification registrations and custom handlers.
  27
  28   NOTE: This call will fail if the architectural ResetSystem underpinnings
  29         are not initialized. For DXE, you can add gEfiResetArchProtocolGuid
  30         to your DEPEX.
  31
  32   @param[in]  ResetSubtype  GUID pointer for the reset subtype to be used.
  33
  34 **/
  35 VOID
  36 EFIAPI
  37 ResetPlatformSpecificGuid (
  38   IN CONST  GUID        *ResetSubtype
  39   );
  40
  41 /**
  42   This function examines the DataSize and ResetData parameters passed to
  43   to ResetSystem() and detemrines if the ResetData contains a Null-terminated
  44   Unicode string followed by a GUID specific subtype.  If the GUID specific
  45   subtype is present, then a pointer to the GUID value in ResetData is returned.
  46
  47   @param[in]  DataSize    The size, in bytes, of ResetData.
  48   @param[in]  ResetData   Pointer to the data buffer passed into ResetSystem().
  49
  50   @retval     Pointer     Pointer to the GUID value in ResetData.
  51   @retval     NULL        ResetData is NULL.
  52   @retval     NULL        ResetData does not start with a Null-terminated
  53                           Unicode string.
  54   @retval     NULL        A Null-terminated Unicode string is present, but there
  55                           are less than sizeof (GUID) bytes after the string.
  56   @retval     NULL        No subtype is found.
  57
  58 **/
  59 GUID *
  60 EFIAPI
  61 GetResetPlatformSpecificGuid (
  62   IN UINTN       DataSize,
  63   IN CONST VOID  *ResetData
  64   );
  65
  66 /**
  67   This is a helper function that creates the reset data buffer that can be
  68   passed into ResetSystem().
  69
  70   The reset data buffer is returned in ResetData and contains ResetString
  71   followed by the ResetSubtype GUID followed by the ExtraData.
  72
  73   NOTE: Strings are internally limited by MAX_UINT16.
  74
  75   @param[in, out] ResetDataSize  On input, the size of the ResetData buffer. On
  76                                  output, either the total number of bytes
  77                                  copied, or the required buffer size.
  78   @param[in, out] ResetData      A pointer to the buffer in which to place the
  79                                  final structure.
  80   @param[in]      ResetSubtype   Pointer to the GUID specific subtype.  This
  81                                  parameter is optional and may be NULL.
  82   @param[in]      ResetString    Pointer to a Null-terminated Unicode string
  83                                  that describes the reset.  This parameter is
  84                                  optional and may be NULL.
  85   @param[in]      ExtraDataSize  The size, in bytes, of ExtraData buffer.
  86   @param[in]      ExtraData      Pointer to a buffer of extra data.  This
  87                                  parameter is optional and may be NULL.
  88
  89   @retval     RETURN_SUCCESS             ResetDataSize and ResetData are updated.
  90   @retval     RETURN_INVALID_PARAMETER   ResetDataSize is NULL.
  91   @retval     RETURN_INVALID_PARAMETER   ResetData is NULL.
  92   @retval     RETURN_INVALID_PARAMETER   ExtraData was provided without a
  93                                          ResetSubtype. This is not supported by the
  94                                          UEFI spec.
  95   @retval     RETURN_BUFFER_TOO_SMALL    An insufficient buffer was provided.
  96                                          ResetDataSize is updated with minimum size
  97                                          required.
  98 **/
  99 RETURN_STATUS
 100 EFIAPI
 101 BuildResetData (
 102   IN OUT   UINTN     *ResetDataSize,
 103   IN OUT   VOID      *ResetData,
 104   IN CONST GUID      *ResetSubtype  OPTIONAL,
 105   IN CONST CHAR16    *ResetString   OPTIONAL,
 106   IN       UINTN     ExtraDataSize  OPTIONAL,
 107   IN CONST VOID      *ExtraData     OPTIONAL
 108   );
 109
 110 #endif // _RESET_UTILITY_LIB_H_