mirror of
https://github.com/Dasharo/edk2-upstream.git
synced 2026-06-13 19:16:19 -07:00
Michael Kubackiandmergify[bot]
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>
94 lines
4.2 KiB
C
94 lines
4.2 KiB
C
/** @file
|
|
|
|
Load Pe32 Image protocol enables loading and unloading EFI images into memory and executing those images.
|
|
This protocol uses File Device Path to get an EFI image.
|
|
|
|
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#define PE32_IMAGE_PROTOCOL_GUID \
|
|
{0x5cb5c776,0x60d5,0x45ee,{0x88,0x3c,0x45,0x27,0x8,0xcd,0x74,0x3f }}
|
|
|
|
#define EFI_LOAD_PE_IMAGE_ATTRIBUTE_NONE 0x00
|
|
#define EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION 0x01
|
|
#define EFI_LOAD_PE_IMAGE_ATTRIBUTE_DEBUG_IMAGE_INFO_TABLE_REGISTRATION 0x02
|
|
|
|
typedef struct _EFI_PE32_IMAGE_PROTOCOL EFI_PE32_IMAGE_PROTOCOL;
|
|
|
|
/**
|
|
|
|
Loads an EFI image into memory and returns a handle to the image with extended parameters.
|
|
|
|
@param This The pointer to the LoadPe32Image protocol instance
|
|
@param ParentImageHandle The caller's image handle.
|
|
@param FilePath The specific file path from which the image is loaded.
|
|
@param SourceBuffer If not NULL, a pointer to the memory location containing a copy of
|
|
the image to be loaded.
|
|
@param SourceSize The size in bytes of SourceBuffer.
|
|
@param DstBuffer The buffer to store the image.
|
|
@param NumberOfPages For input, specifies the space size of the image by caller if not NULL.
|
|
For output, specifies the actual space size needed.
|
|
@param ImageHandle The image handle for output.
|
|
@param EntryPoint The image entry point for output.
|
|
@param Attribute The bit mask of attributes to set for the load PE image.
|
|
|
|
@retval EFI_SUCCESS The image was loaded into memory.
|
|
@retval EFI_NOT_FOUND The FilePath was not found.
|
|
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
|
|
@retval EFI_UNSUPPORTED The image type is not supported, or the device path cannot be
|
|
parsed to locate the proper protocol for loading the file.
|
|
@retval EFI_OUT_OF_RESOURCES The image was not loaded due to insufficient memory resources.
|
|
@retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
|
|
understood.
|
|
@retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
|
|
@retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
|
|
image from being loaded. NULL is returned in *ImageHandle.
|
|
@retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
|
|
valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
|
|
platform policy specifies that the image should not be started.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *LOAD_PE_IMAGE)(
|
|
IN EFI_PE32_IMAGE_PROTOCOL *This,
|
|
IN EFI_HANDLE ParentImageHandle,
|
|
IN EFI_DEVICE_PATH_PROTOCOL *FilePath,
|
|
IN VOID *SourceBuffer OPTIONAL,
|
|
IN UINTN SourceSize,
|
|
IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL,
|
|
IN OUT UINTN *NumberOfPages OPTIONAL,
|
|
OUT EFI_HANDLE *ImageHandle,
|
|
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
|
|
IN UINT32 Attribute
|
|
);
|
|
|
|
/**
|
|
|
|
Unload the specified image.
|
|
|
|
@param This The pointer to the LoadPe32Image protocol instance
|
|
@param ImageHandle The specified image handle to be unloaded.
|
|
|
|
@retval EFI_INVALID_PARAMETER Image handle is NULL.
|
|
@retval EFI_UNSUPPORTED Attempted to unload an unsupported image.
|
|
@retval EFI_SUCCESS The image successfully unloaded.
|
|
|
|
--*/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *UNLOAD_PE_IMAGE)(
|
|
IN EFI_PE32_IMAGE_PROTOCOL *This,
|
|
IN EFI_HANDLE ImageHandle
|
|
);
|
|
|
|
struct _EFI_PE32_IMAGE_PROTOCOL {
|
|
LOAD_PE_IMAGE LoadPeImage;
|
|
UNLOAD_PE_IMAGE UnLoadPeImage;
|
|
};
|
|
|
|
extern EFI_GUID gEfiLoadPeImageProtocolGuid;
|