mirror of
https://github.com/Dasharo/edk2-upstream.git
synced 2026-06-13 19:16:19 -07:00
Michael Kubacki
8b7617151e
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>
144 lines
5.4 KiB
C
144 lines
5.4 KiB
C
/** @file
|
|
EDKII System Capsule library.
|
|
|
|
Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#include <Guid/EdkiiSystemFmpCapsule.h>
|
|
|
|
/**
|
|
Extract ImageFmpInfo from system firmware.
|
|
|
|
@param[in] SystemFirmwareImage The System Firmware image.
|
|
@param[in] SystemFirmwareImageSize The size of the System Firmware image in bytes.
|
|
@param[out] ImageFmpInfo The ImageFmpInfo.
|
|
@param[out] ImageFmpInfoSize The size of the ImageFmpInfo in bytes.
|
|
|
|
@retval TRUE The ImageFmpInfo is extracted.
|
|
@retval FALSE The ImageFmpInfo is not extracted.
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
ExtractSystemFirmwareImageFmpInfo (
|
|
IN VOID *SystemFirmwareImage,
|
|
IN UINTN SystemFirmwareImageSize,
|
|
OUT EDKII_SYSTEM_FIRMWARE_IMAGE_DESCRIPTOR **ImageFmpInfo,
|
|
OUT UINTN *ImageFmpInfoSize
|
|
);
|
|
|
|
/**
|
|
Extract the driver FV from an authenticated image.
|
|
|
|
@param[in] AuthenticatedImage The authenticated capsule image.
|
|
@param[in] AuthenticatedImageSize The size of the authenticated capsule image in bytes.
|
|
@param[out] DriverFvImage The driver FV image.
|
|
@param[out] DriverFvImageSize The size of the driver FV image in bytes.
|
|
|
|
@retval TRUE The driver Fv is extracted.
|
|
@retval FALSE The driver Fv is not extracted.
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
ExtractDriverFvImage (
|
|
IN VOID *AuthenticatedImage,
|
|
IN UINTN AuthenticatedImageSize,
|
|
OUT VOID **DriverFvImage,
|
|
OUT UINTN *DriverFvImageSize
|
|
);
|
|
|
|
/**
|
|
Extract the config image from an authenticated image.
|
|
|
|
@param[in] AuthenticatedImage The authenticated capsule image.
|
|
@param[in] AuthenticatedImageSize The size of the authenticated capsule image in bytes.
|
|
@param[out] ConfigImage The config image.
|
|
@param[out] ConfigImageSize The size of the config image in bytes.
|
|
|
|
@retval TRUE The config image is extracted.
|
|
@retval FALSE The config image is not extracted.
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
ExtractConfigImage (
|
|
IN VOID *AuthenticatedImage,
|
|
IN UINTN AuthenticatedImageSize,
|
|
OUT VOID **ConfigImage,
|
|
OUT UINTN *ConfigImageSize
|
|
);
|
|
|
|
/**
|
|
Extract the System Firmware image from an authenticated image.
|
|
|
|
@param[in] AuthenticatedImage The authenticated capsule image.
|
|
@param[in] AuthenticatedImageSize The size of the authenticated capsule image in bytes.
|
|
@param[out] SystemFirmwareImage The System Firmware image.
|
|
@param[out] SystemFirmwareImageSize The size of the System Firmware image in bytes.
|
|
|
|
@retval TRUE The System Firmware image is extracted.
|
|
@retval FALSE The System Firmware image is not extracted.
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
ExtractSystemFirmwareImage (
|
|
IN VOID *AuthenticatedImage,
|
|
IN UINTN AuthenticatedImageSize,
|
|
OUT VOID **SystemFirmwareImage,
|
|
OUT UINTN *SystemFirmwareImageSize
|
|
);
|
|
|
|
/**
|
|
Extract the authenticated image from an FMP capsule image.
|
|
|
|
@param[in] Image The FMP capsule image, including EFI_FIRMWARE_IMAGE_AUTHENTICATION.
|
|
@param[in] ImageSize The size of FMP capsule image in bytes.
|
|
@param[out] LastAttemptStatus The last attempt status, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
|
|
@param[out] AuthenticatedImage The authenticated capsule image, excluding EFI_FIRMWARE_IMAGE_AUTHENTICATION.
|
|
@param[out] AuthenticatedImageSize The size of the authenticated capsule image in bytes.
|
|
|
|
@retval TRUE The authenticated image is extracted.
|
|
@retval FALSE The authenticated image is not extracted.
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
ExtractAuthenticatedImage (
|
|
IN VOID *Image,
|
|
IN UINTN ImageSize,
|
|
OUT UINT32 *LastAttemptStatus,
|
|
OUT VOID **AuthenticatedImage,
|
|
OUT UINTN *AuthenticatedImageSize
|
|
);
|
|
|
|
/**
|
|
Authenticated system firmware FMP capsule image.
|
|
|
|
Caution: This function may receive untrusted input.
|
|
|
|
@param[in] Image The FMP capsule image, including EFI_FIRMWARE_IMAGE_AUTHENTICATION.
|
|
@param[in] ImageSize The size of FMP capsule image in bytes.
|
|
@param[in] ForceVersionMatch TRUE: The version of capsule must be as same as the version of current image.
|
|
FALSE: The version of capsule must be as same as greater than the lowest
|
|
supported version of current image.
|
|
@param[out] LastAttemptVersion The last attempt version, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
|
|
@param[out] LastAttemptStatus The last attempt status, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
|
|
@param[out] AuthenticatedImage The authenticated capsule image, excluding EFI_FIRMWARE_IMAGE_AUTHENTICATION.
|
|
@param[out] AuthenticatedImageSize The size of the authenticated capsule image in bytes.
|
|
|
|
@retval TRUE Authentication passes and the authenticated image is extracted.
|
|
@retval FALSE Authentication fails and the authenticated image is not extracted.
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
CapsuleAuthenticateSystemFirmware (
|
|
IN VOID *Image,
|
|
IN UINTN ImageSize,
|
|
IN BOOLEAN ForceVersionMatch,
|
|
OUT UINT32 *LastAttemptVersion,
|
|
OUT UINT32 *LastAttemptStatus,
|
|
OUT VOID **AuthenticatedImage,
|
|
OUT UINTN *AuthenticatedImageSize
|
|
);
|