ResetUtilityLib.h File Reference

Functions
VOID EFIAPI	ResetSystemWithSubtype (IN EFI_RESET_TYPE ResetType, IN CONST GUID *ResetSubtype)
VOID EFIAPI	ResetPlatformSpecificGuid (IN CONST GUID *ResetSubtype)
GUID *EFIAPI	GetResetPlatformSpecificGuid (IN UINTN DataSize, IN CONST VOID *ResetData)
RETURN_STATUS EFIAPI	BuildResetData (IN OUT UINTN *ResetDataSize, IN OUT VOID *ResetData, IN CONST GUID *ResetSubtype, IN CONST CHAR16 *ResetString, IN UINTN ExtraDataSize, IN CONST VOID *ExtraData)

Detailed Description

This header describes various helper functions for resetting the system.

Copyright (c) 2017 - 2019 Intel Corporation. All rights reserved.
Copyright (c) 2016 Microsoft Corporation. All rights reserved.

SPDX-License-Identifier: BSD-2-Clause-Patent

Function Documentation

RETURN_STATUS EFIAPI BuildResetData	(	IN OUT UINTN *	ResetDataSize,
		IN OUT VOID *	ResetData,
		IN CONST GUID *	ResetSubtype,
		IN CONST CHAR16 *	ResetString,
		IN UINTN	ExtraDataSize,
		IN CONST VOID *	ExtraData
	)

This is a helper function that creates the reset data buffer that can be passed into ResetSystem().

The reset data buffer is returned in ResetData and contains ResetString followed by the ResetSubtype GUID followed by the ExtraData.

NOTE: Strings are internally limited by MAX_UINT16.

Parameters

[in,out]	ResetDataSize	On input, the size of the ResetData buffer. On output, either the total number of bytes copied, or the required buffer size.
[in,out]	ResetData	A pointer to the buffer in which to place the final structure.
[in]	ResetSubtype	Pointer to the GUID specific subtype. This parameter is optional and may be NULL.
[in]	ResetString	Pointer to a Null-terminated Unicode string that describes the reset. This parameter is optional and may be NULL.
[in]	ExtraDataSize	The size, in bytes, of ExtraData buffer.
[in]	ExtraData	Pointer to a buffer of extra data. This parameter is optional and may be NULL.

Return values

RETURN_SUCCESS	ResetDataSize and ResetData are updated.
RETURN_INVALID_PARAMETER	ResetDataSize is NULL.
RETURN_INVALID_PARAMETER	ResetData is NULL.
RETURN_INVALID_PARAMETER	ExtraData was provided without a ResetSubtype. This is not supported by the UEFI spec.
RETURN_BUFFER_TOO_SMALL	An insufficient buffer was provided. ResetDataSize is updated with minimum size required.

GUID* EFIAPI GetResetPlatformSpecificGuid	(	IN UINTN	DataSize,
		IN CONST VOID *	ResetData
	)

This function examines the DataSize and ResetData parameters passed to to ResetSystem() and detemrines if the ResetData contains a Null-terminated Unicode string followed by a GUID specific subtype. If the GUID specific subtype is present, then a pointer to the GUID value in ResetData is returned.

Parameters

[in]	DataSize	The size, in bytes, of ResetData.
[in]	ResetData	Pointer to the data buffer passed into ResetSystem().

Return values

Pointer	Pointer to the GUID value in ResetData.
NULL	ResetData is NULL.
NULL	ResetData does not start with a Null-terminated Unicode string.
NULL	A Null-terminated Unicode string is present, but there are less than sizeof (GUID) bytes after the string.
NULL	No subtype is found.

VOID EFIAPI ResetPlatformSpecificGuid

(

IN CONST GUID *

ResetSubtype

)

This is a shorthand helper function to reset with the reset type 'EfiResetPlatformSpecific' and a subtype so that the caller doesn't have to bother with a function that has half a dozen parameters.

This will generate a reset with status EFI_SUCCESS, a NULL string, and no custom data. The subtype will be formatted in such a way that it can be picked up by notification registrations and custom handlers.

NOTE: This call will fail if the architectural ResetSystem underpinnings are not initialized. For DXE, you can add gEfiResetArchProtocolGuid to your DEPEX.

Parameters

[in]

ResetSubtype

GUID pointer for the reset subtype to be used.

VOID EFIAPI ResetSystemWithSubtype	(	IN EFI_RESET_TYPE	ResetType,
		IN CONST GUID *	ResetSubtype
	)

This is a shorthand helper function to reset with reset type and a subtype so that the caller doesn't have to bother with a function that has half a dozen parameters.

This will generate a reset with status EFI_SUCCESS, a NULL string, and no custom data. The subtype will be formatted in such a way that it can be picked up by notification registrations and custom handlers.

NOTE: This call will fail if the architectural ResetSystem underpinnings are not initialized. For DXE, you can add gEfiResetArchProtocolGuid to your DEPEX.

Parameters

[in]	ResetType	The default EFI_RESET_TYPE of the reset.
[in]	ResetSubtype	GUID pointer for the reset subtype to be used.