mirror of
https://github.com/tianocore/edk2
synced 2026-08-27 00:23:19 -04:00
01f75b3927
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>
172 lines
6.2 KiB
C
172 lines
6.2 KiB
C
/** @file
|
|
|
|
Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
@par Glossary:
|
|
- Cm or CM - Configuration Manager
|
|
- Obj or OBJ - Object
|
|
- Std or STD - Standard
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#include <TableGenerator.h>
|
|
|
|
#pragma pack(1)
|
|
|
|
/** The DT_TABLE_GENERATOR_ID type describes Device Tree table generator ID.
|
|
*/
|
|
typedef TABLE_GENERATOR_ID DT_TABLE_GENERATOR_ID;
|
|
|
|
/** The ESTD_DT_TABLE_ID enum describes the DT table IDs reserved for
|
|
the standard generators.
|
|
*/
|
|
typedef enum StdDtTableId {
|
|
EStdDtTableIdReserved = 0x0000, ///< Reserved.
|
|
EStdDtTableIdRaw, ///< RAW Generator.
|
|
EStdDtTableIdMax
|
|
} ESTD_DT_TABLE_ID;
|
|
|
|
/** This macro checks if the Table Generator ID is for an DT Table Generator.
|
|
|
|
@param [in] TableGeneratorId The table generator ID.
|
|
|
|
@return TRUE if the table generator ID is for an DT Table
|
|
Generator.
|
|
**/
|
|
#define IS_GENERATOR_TYPE_DT(TableGeneratorId) \
|
|
(GET_TABLE_TYPE(TableGeneratorId) == ETableGeneratorTypeDt)
|
|
|
|
/** This macro checks if the Table Generator ID is for a standard DT
|
|
Table Generator.
|
|
|
|
@param [in] TableGeneratorId The table generator ID.
|
|
|
|
@return TRUE if the table generator ID is for a standard DT
|
|
Table Generator.
|
|
**/
|
|
#define IS_VALID_STD_DT_GENERATOR_ID(TableGeneratorId) \
|
|
( \
|
|
IS_GENERATOR_NAMESPACE_STD(TableGeneratorId) && \
|
|
IS_GENERATOR_TYPE_DT(TableGeneratorId) && \
|
|
((GET_TABLE_ID(GeneratorId) >= EStdDtTableIdRaw) && \
|
|
(GET_TABLE_ID(GeneratorId) < EStdDtTableIdMax)) \
|
|
)
|
|
|
|
/** This macro creates a standard DT Table Generator ID.
|
|
|
|
@param [in] TableId The table generator ID.
|
|
|
|
@return a standard DT table generator ID.
|
|
**/
|
|
#define CREATE_STD_DT_TABLE_GEN_ID(TableId) \
|
|
CREATE_TABLE_GEN_ID ( \
|
|
ETableGeneratorTypeDt, \
|
|
ETableGeneratorNameSpaceStd, \
|
|
TableId \
|
|
)
|
|
|
|
/** Forward declarations.
|
|
*/
|
|
typedef struct ConfigurationManagerProtocol EDKII_CONFIGURATION_MANAGER_PROTOCOL;
|
|
typedef struct CmAStdObjDtTableInfo CM_STD_OBJ_DT_TABLE_INFO;
|
|
typedef struct DtTableGenerator DT_TABLE_GENERATOR;
|
|
|
|
/** This function pointer describes the interface to DT table build
|
|
functions provided by the DT table generator and called by the
|
|
Table Manager to build an DT table.
|
|
|
|
@param [in] Generator Pointer to the DT table generator.
|
|
@param [in] DtTableInfo Pointer to the DT table information.
|
|
@param [in] CfgMgrProtocol Pointer to the Configuration Manager
|
|
Protocol interface.
|
|
@param [out] Table Pointer to the generated DT table.
|
|
|
|
@return EFI_SUCCESS If the table is generated successfully or other
|
|
failure codes as returned by the generator.
|
|
**/
|
|
typedef EFI_STATUS (*DT_TABLE_GENERATOR_BUILD_TABLE) (
|
|
IN CONST DT_TABLE_GENERATOR *Generator,
|
|
IN CONST CM_STD_OBJ_DT_TABLE_INFO *CONST DtTableInfo,
|
|
IN CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL *CONST CfgMgrProtocol,
|
|
OUT VOID **Table
|
|
);
|
|
|
|
/** This function pointer describes the interface to used by the
|
|
Table Manager to give the generator an opportunity to free
|
|
any resources allocated for building the DT table.
|
|
|
|
@param [in] Generator Pointer to the DT table generator.
|
|
@param [in] DtTableInfo Pointer to the DT table information.
|
|
@param [in] CfgMgrProtocol Pointer to the Configuration Manager
|
|
Protocol interface.
|
|
@param [in] Table Pointer to the generated DT table.
|
|
|
|
@return EFI_SUCCESS If freed successfully or other failure codes
|
|
as returned by the generator.
|
|
**/
|
|
typedef EFI_STATUS (*DT_TABLE_GENERATOR_FREE_TABLE) (
|
|
IN CONST DT_TABLE_GENERATOR *Generator,
|
|
IN CONST CM_STD_OBJ_DT_TABLE_INFO *CONST DtTableInfo,
|
|
IN CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL *CONST CfgMgrProtocol,
|
|
IN VOID **Table
|
|
);
|
|
|
|
/** The DT_TABLE_GENERATOR structure provides an interface that the
|
|
Table Manager can use to invoke the functions to build DT tables.
|
|
*/
|
|
typedef struct DtTableGenerator {
|
|
/// The DT table generator ID.
|
|
DT_TABLE_GENERATOR_ID GeneratorID;
|
|
|
|
/// String describing the DT table generator.
|
|
CONST CHAR16 *Description;
|
|
|
|
/// DT table build function pointer.
|
|
DT_TABLE_GENERATOR_BUILD_TABLE BuildDtTable;
|
|
|
|
/// The function to free any resources allocated for building the DT table.
|
|
DT_TABLE_GENERATOR_FREE_TABLE FreeTableResources;
|
|
} DT_TABLE_GENERATOR;
|
|
|
|
/** Register DT table factory generator.
|
|
|
|
The DT table factory maintains a list of the Standard and OEM DT
|
|
table generators.
|
|
|
|
@param [in] Generator Pointer to the DT table generator.
|
|
|
|
@retval EFI_SUCCESS The Generator was registered
|
|
successfully.
|
|
@retval EFI_INVALID_PARAMETER The Generator ID is invalid or
|
|
the Generator pointer is NULL.
|
|
@retval EFI_ALREADY_STARTED The Generator for the Table ID is
|
|
already registered.
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
RegisterDtTableGenerator (
|
|
IN CONST DT_TABLE_GENERATOR *CONST Generator
|
|
);
|
|
|
|
/** Deregister DT generator.
|
|
|
|
This function is called by the DT table generator to deregister itself
|
|
from the DT table factory.
|
|
|
|
@param [in] Generator Pointer to the DT table generator.
|
|
|
|
@retval EFI_SUCCESS Success.
|
|
@retval EFI_INVALID_PARAMETER The generator is invalid.
|
|
@retval EFI_NOT_FOUND The requested generator is not found
|
|
in the list of registered generators.
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
DeregisterDtTableGenerator (
|
|
IN CONST DT_TABLE_GENERATOR *CONST Generator
|
|
);
|
|
|
|
#pragma pack()
|