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