2 This header describes various helper functions for resetting the system.
4 Copyright (c) 2017 - 2019 Intel Corporation. All rights reserved.<BR>
5 Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #ifndef _RESET_UTILITY_LIB_H_
11 #define _RESET_UTILITY_LIB_H_
13 #include <Uefi/UefiMultiPhase.h>
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
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.
24 NOTE: This call will fail if the architectural ResetSystem underpinnings
25 are not initialized. For DXE, you can add gEfiResetArchProtocolGuid
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.
34 ResetSystemWithSubtype (
35 IN EFI_RESET_TYPE ResetType
,
36 IN CONST GUID
*ResetSubtype
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.
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.
48 NOTE: This call will fail if the architectural ResetSystem underpinnings
49 are not initialized. For DXE, you can add gEfiResetArchProtocolGuid
52 @param[in] ResetSubtype GUID pointer for the reset subtype to be used.
57 ResetPlatformSpecificGuid (
58 IN CONST GUID
*ResetSubtype
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.
67 @param[in] DataSize The size, in bytes, of ResetData.
68 @param[in] ResetData Pointer to the data buffer passed into ResetSystem().
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
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.
81 GetResetPlatformSpecificGuid (
83 IN CONST VOID
*ResetData
87 This is a helper function that creates the reset data buffer that can be
88 passed into ResetSystem().
90 The reset data buffer is returned in ResetData and contains ResetString
91 followed by the ResetSubtype GUID followed by the ExtraData.
93 NOTE: Strings are internally limited by MAX_UINT16.
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
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.
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
115 @retval RETURN_BUFFER_TOO_SMALL An insufficient buffer was provided.
116 ResetDataSize is updated with minimum size
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
130 #endif // _RESET_UTILITY_LIB_H_