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