You've already forked edk2-upstream
mirror of
https://github.com/Dasharo/edk2-upstream.git
synced 2026-03-06 15:03:57 -08:00
7a934d0bef
Replace traditional `#ifndef`/`#define`/`#endif` include guards with
`#pragma` once.
`#pragma once` is a widely supported preprocessor directive that
prevents header files from being included multiple times. It is
supported by all toolchains used to build edk2: GCC, Clang/LLVM, and
MSVC.
Compared to macro-based include guards, `#pragma once`:
- Eliminates the risk of macro name collisions or copy/paste errors
where two headers inadvertently use the same guard macro.
- Eliminate inconsistency in the way include guard macros are named
(e.g., some files use `__FILE_H__`, others use `FILE_H_`, etc.).
- Reduces boilerplate (three lines replaced by one).
- Avoids polluting the macro namespace with guard symbols.
- Can improve build times as the preprocessor can skip re-opening the
file entirely, rather than re-reading it to find the matching
`#endif` ("multiple-include optimization").
- Note that some compilers may already optimize traditional include
guards, by recognzining the idiomatic pattern.
This change is made acknowledging that overall portability of the
code will technically be reduced, as `#pragma once` is not part of the
C/C++ standards.
However, this is considered acceptable given:
1. edk2 already defines a subset of supported compilers in
BaseTools/Conf/tools_def.template, all of which have supported
`#pragma once` for over two decades.
2. There have been concerns raised to the project about inconsistent
include guard naming and potential macro collisions.
Approximate compiler support dates:
- MSVC: Supported since Visual C++ 4.2 (1996)
- GCC: Supported since 3.4 (2004)
(http://gnu.ist.utl.pt/software/gcc/gcc-3.4/changes.html)
- Clang (LLVM based): Since initial release in 2007
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
129 lines
5.1 KiB
C
129 lines
5.1 KiB
C
/** @file
|
|
This header describes various helper functions for resetting the system.
|
|
|
|
Copyright (c) 2017 - 2019 Intel Corporation. All rights reserved.<BR>
|
|
Copyright (c) 2016 Microsoft Corporation. All rights reserved.<BR>
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#include <Uefi/UefiMultiPhase.h>
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] ResetType The default EFI_RESET_TYPE of the reset.
|
|
@param[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 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.
|
|
|
|
@param[in] ResetSubtype GUID pointer for the reset subtype to be used.
|
|
|
|
**/
|
|
VOID
|
|
EFIAPI
|
|
ResetPlatformSpecificGuid (
|
|
IN CONST GUID *ResetSubtype
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] DataSize The size, in bytes, of ResetData.
|
|
@param[in] ResetData Pointer to the data buffer passed into ResetSystem().
|
|
|
|
@retval Pointer Pointer to the GUID value in ResetData.
|
|
@retval NULL ResetData is NULL.
|
|
@retval NULL ResetData does not start with a Null-terminated
|
|
Unicode string.
|
|
@retval NULL A Null-terminated Unicode string is present, but there
|
|
are less than sizeof (GUID) bytes after the string.
|
|
@retval NULL No subtype is found.
|
|
|
|
**/
|
|
GUID *
|
|
EFIAPI
|
|
GetResetPlatformSpecificGuid (
|
|
IN UINTN DataSize,
|
|
IN CONST VOID *ResetData
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[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.
|
|
@param[in, out] ResetData A pointer to the buffer in which to place the
|
|
final structure.
|
|
@param[in] ResetSubtype Pointer to the GUID specific subtype. This
|
|
parameter is optional and may be NULL.
|
|
@param[in] ResetString Pointer to a Null-terminated Unicode string
|
|
that describes the reset. This parameter is
|
|
optional and may be NULL.
|
|
@param[in] ExtraDataSize The size, in bytes, of ExtraData buffer.
|
|
@param[in] ExtraData Pointer to a buffer of extra data. This
|
|
parameter is optional and may be NULL.
|
|
|
|
@retval RETURN_SUCCESS ResetDataSize and ResetData are updated.
|
|
@retval RETURN_INVALID_PARAMETER ResetDataSize is NULL.
|
|
@retval RETURN_INVALID_PARAMETER ResetData is NULL.
|
|
@retval RETURN_INVALID_PARAMETER ExtraData was provided without a
|
|
ResetSubtype. This is not supported by the
|
|
UEFI spec.
|
|
@retval RETURN_BUFFER_TOO_SMALL An insufficient buffer was provided.
|
|
ResetDataSize is updated with minimum size
|
|
required.
|
|
**/
|
|
RETURN_STATUS
|
|
EFIAPI
|
|
BuildResetData (
|
|
IN OUT UINTN *ResetDataSize,
|
|
IN OUT VOID *ResetData,
|
|
IN CONST GUID *ResetSubtype OPTIONAL,
|
|
IN CONST CHAR16 *ResetString OPTIONAL,
|
|
IN UINTN ExtraDataSize OPTIONAL,
|
|
IN CONST VOID *ExtraData OPTIONAL
|
|
);
|