MdeModulePkg/Include/Library/ResetUtilityLib.h

   1 /** @file
   2   This header describes various helper functions for resetting the system.
   3
   4   Copyright (c) 2017 - 2019 Intel Corporation. All rights reserved.<BR>
   5   Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10 #ifndef _RESET_UTILITY_LIB_H_
  11 #define _RESET_UTILITY_LIB_H_
  12
  13 #include <Uefi/UefiMultiPhase.h>
  14
  15 /**
  16   This is a shorthand helper function to reset with reset type and a subtype
  17   so that the caller doesn't have to bother with a function that has half
  18   a dozen parameters.
  19
  20   This will generate a reset with status EFI_SUCCESS, a NULL string, and
  21   no custom data. The subtype will be formatted in such a way that it can be
  22   picked up by notification registrations and custom handlers.
  23
  24   NOTE: This call will fail if the architectural ResetSystem underpinnings
  25         are not initialized. For DXE, you can add gEfiResetArchProtocolGuid
  26         to your DEPEX.
  27
  28   @param[in]  ResetType     The default EFI_RESET_TYPE of the reset.
  29   @param[in]  ResetSubtype  GUID pointer for the reset subtype to be used.
  30
  31 **/
  32 VOID
  33 EFIAPI
  34 ResetSystemWithSubtype (
  35   IN EFI_RESET_TYPE     ResetType,
  36   IN CONST  GUID        *ResetSubtype
  37   );
  38
  39 /**
  40   This is a shorthand helper function to reset with the reset type
  41   'EfiResetPlatformSpecific' and a subtype so that the caller doesn't
  42   have to bother with a function that has half a dozen parameters.
  43
  44   This will generate a reset with status EFI_SUCCESS, a NULL string, and
  45   no custom data. The subtype will be formatted in such a way that it can be
  46   picked up by notification registrations and custom handlers.
  47
  48   NOTE: This call will fail if the architectural ResetSystem underpinnings
  49         are not initialized. For DXE, you can add gEfiResetArchProtocolGuid
  50         to your DEPEX.
  51
  52   @param[in]  ResetSubtype  GUID pointer for the reset subtype to be used.
  53
  54 **/
  55 VOID
  56 EFIAPI
  57 ResetPlatformSpecificGuid (
  58   IN CONST  GUID        *ResetSubtype
  59   );
  60
  61 /**
  62   This function examines the DataSize and ResetData parameters passed to
  63   to ResetSystem() and detemrines if the ResetData contains a Null-terminated
  64   Unicode string followed by a GUID specific subtype.  If the GUID specific
  65   subtype is present, then a pointer to the GUID value in ResetData is returned.
  66
  67   @param[in]  DataSize    The size, in bytes, of ResetData.
  68   @param[in]  ResetData   Pointer to the data buffer passed into ResetSystem().
  69
  70   @retval     Pointer     Pointer to the GUID value in ResetData.
  71   @retval     NULL        ResetData is NULL.
  72   @retval     NULL        ResetData does not start with a Null-terminated
  73                           Unicode string.
  74   @retval     NULL        A Null-terminated Unicode string is present, but there
  75                           are less than sizeof (GUID) bytes after the string.
  76   @retval     NULL        No subtype is found.
  77
  78 **/
  79 GUID *
  80 EFIAPI
  81 GetResetPlatformSpecificGuid (
  82   IN UINTN       DataSize,
  83   IN CONST VOID  *ResetData
  84   );
  85
  86 /**
  87   This is a helper function that creates the reset data buffer that can be
  88   passed into ResetSystem().
  89
  90   The reset data buffer is returned in ResetData and contains ResetString
  91   followed by the ResetSubtype GUID followed by the ExtraData.
  92
  93   NOTE: Strings are internally limited by MAX_UINT16.
  94
  95   @param[in, out] ResetDataSize  On input, the size of the ResetData buffer. On
  96                                  output, either the total number of bytes
  97                                  copied, or the required buffer size.
  98   @param[in, out] ResetData      A pointer to the buffer in which to place the
  99                                  final structure.
 100   @param[in]      ResetSubtype   Pointer to the GUID specific subtype.  This
 101                                  parameter is optional and may be NULL.
 102   @param[in]      ResetString    Pointer to a Null-terminated Unicode string
 103                                  that describes the reset.  This parameter is
 104                                  optional and may be NULL.
 105   @param[in]      ExtraDataSize  The size, in bytes, of ExtraData buffer.
 106   @param[in]      ExtraData      Pointer to a buffer of extra data.  This
 107                                  parameter is optional and may be NULL.
 108
 109   @retval     RETURN_SUCCESS             ResetDataSize and ResetData are updated.
 110   @retval     RETURN_INVALID_PARAMETER   ResetDataSize is NULL.
 111   @retval     RETURN_INVALID_PARAMETER   ResetData is NULL.
 112   @retval     RETURN_INVALID_PARAMETER   ExtraData was provided without a
 113                                          ResetSubtype. This is not supported by the
 114                                          UEFI spec.
 115   @retval     RETURN_BUFFER_TOO_SMALL    An insufficient buffer was provided.
 116                                          ResetDataSize is updated with minimum size
 117                                          required.
 118 **/
 119 RETURN_STATUS
 120 EFIAPI
 121 BuildResetData (
 122   IN OUT   UINTN     *ResetDataSize,
 123   IN OUT   VOID      *ResetData,
 124   IN CONST GUID      *ResetSubtype  OPTIONAL,
 125   IN CONST CHAR16    *ResetString   OPTIONAL,
 126   IN       UINTN     ExtraDataSize  OPTIONAL,
 127   IN CONST VOID      *ExtraData     OPTIONAL
 128   );
 129
 130 #endif // _RESET_UTILITY_LIB_H_