mirror of
https://github.com/tianocore/edk2
synced 2026-08-27 00:23:19 -04:00
a536e5d699
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.
Note: Headers taken directly from external projects, such as those
in OvmfPkg/Include/IndustryStandard/Xen/ were not modified since they
may be periodically re-synced and do not follow other edk2 coding
stadards.
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>
175 lines
6.2 KiB
C
175 lines
6.2 KiB
C
/** @file
|
|
Provide common utility functions to PciHostBridgeLib instances in
|
|
ArmVirtPkg and OvmfPkg.
|
|
|
|
Copyright (C) 2016, Red Hat, Inc.
|
|
Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
|
|
Copyright (c) 2020, Huawei Corporation. All rights reserved.<BR>
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#include <Library/PciHostBridgeLib.h>
|
|
|
|
/**
|
|
Utility function to initialize a PCI_ROOT_BRIDGE structure.
|
|
|
|
@param[in] Supports Supported attributes.
|
|
|
|
@param[in] Attributes Initial attributes.
|
|
|
|
@param[in] AllocAttributes Allocation attributes.
|
|
|
|
@param[in] DmaAbove4G DMA above 4GB memory.
|
|
|
|
@param[in] NoExtendedConfigSpace No Extended Config Space.
|
|
|
|
@param[in] RootBusNumber The bus number to store in RootBus.
|
|
|
|
@param[in] MaxSubBusNumber The inclusive maximum bus number that can
|
|
be assigned to any subordinate bus found
|
|
behind any PCI bridge hanging off this
|
|
root bus.
|
|
|
|
The caller is repsonsible for ensuring
|
|
that RootBusNumber <= MaxSubBusNumber. If
|
|
RootBusNumber equals MaxSubBusNumber, then
|
|
the root bus has no room for subordinate
|
|
buses.
|
|
|
|
@param[in] Io IO aperture.
|
|
|
|
@param[in] Mem MMIO aperture.
|
|
|
|
@param[in] MemAbove4G MMIO aperture above 4G.
|
|
|
|
@param[in] PMem Prefetchable MMIO aperture.
|
|
|
|
@param[in] PMemAbove4G Prefetchable MMIO aperture above 4G.
|
|
|
|
@param[out] RootBus The PCI_ROOT_BRIDGE structure (allocated
|
|
by the caller) that should be filled in by
|
|
this function.
|
|
|
|
@retval EFI_SUCCESS Initialization successful. A device path
|
|
consisting of an ACPI device path node,
|
|
with UID = RootBusNumber, has been
|
|
allocated and linked into RootBus.
|
|
|
|
@retval EFI_OUT_OF_RESOURCES Memory allocation failed.
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
PciHostBridgeUtilityInitRootBridge (
|
|
IN UINT64 Supports,
|
|
IN UINT64 Attributes,
|
|
IN UINT64 AllocAttributes,
|
|
IN BOOLEAN DmaAbove4G,
|
|
IN BOOLEAN NoExtendedConfigSpace,
|
|
IN UINT8 RootBusNumber,
|
|
IN UINT8 MaxSubBusNumber,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *Io,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *Mem,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *MemAbove4G,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *PMem,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G,
|
|
OUT PCI_ROOT_BRIDGE *RootBus
|
|
);
|
|
|
|
/**
|
|
Utility function to uninitialize a PCI_ROOT_BRIDGE structure set up with
|
|
PciHostBridgeUtilityInitRootBridge().
|
|
|
|
@param[in] RootBus The PCI_ROOT_BRIDGE structure, allocated by the caller and
|
|
initialized with PciHostBridgeUtilityInitRootBridge(),
|
|
that should be uninitialized. This function doesn't free
|
|
RootBus.
|
|
**/
|
|
VOID
|
|
EFIAPI
|
|
PciHostBridgeUtilityUninitRootBridge (
|
|
IN PCI_ROOT_BRIDGE *RootBus
|
|
);
|
|
|
|
/**
|
|
Utility function to return all the root bridge instances in an array.
|
|
|
|
@param[out] Count The number of root bridge instances.
|
|
|
|
@param[in] Attributes Initial attributes.
|
|
|
|
@param[in] AllocAttributes Allocation attributes.
|
|
|
|
@param[in] DmaAbove4G DMA above 4GB memory.
|
|
|
|
@param[in] NoExtendedConfigSpace No Extended Config Space.
|
|
|
|
@param[in] BusMin Minimum Bus number, inclusive.
|
|
|
|
@param[in] BusMax Maximum Bus number, inclusive.
|
|
|
|
@param[in] Io IO aperture.
|
|
|
|
@param[in] Mem MMIO aperture.
|
|
|
|
@param[in] MemAbove4G MMIO aperture above 4G.
|
|
|
|
@param[in] PMem Prefetchable MMIO aperture.
|
|
|
|
@param[in] PMemAbove4G Prefetchable MMIO aperture above 4G.
|
|
|
|
@return All the root bridge instances in an array.
|
|
**/
|
|
PCI_ROOT_BRIDGE *
|
|
EFIAPI
|
|
PciHostBridgeUtilityGetRootBridges (
|
|
OUT UINTN *Count,
|
|
IN UINT64 Attributes,
|
|
IN UINT64 AllocationAttributes,
|
|
IN BOOLEAN DmaAbove4G,
|
|
IN BOOLEAN NoExtendedConfigSpace,
|
|
IN UINTN BusMin,
|
|
IN UINTN BusMax,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *Io,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *Mem,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *MemAbove4G,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *PMem,
|
|
IN PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G
|
|
);
|
|
|
|
/**
|
|
Utility function to free root bridge instances array from
|
|
PciHostBridgeUtilityGetRootBridges().
|
|
|
|
@param[in] Bridges The root bridge instances array.
|
|
@param[in] Count The count of the array.
|
|
**/
|
|
VOID
|
|
EFIAPI
|
|
PciHostBridgeUtilityFreeRootBridges (
|
|
IN PCI_ROOT_BRIDGE *Bridges,
|
|
IN UINTN Count
|
|
);
|
|
|
|
/**
|
|
Utility function to inform the platform that the resource conflict happens.
|
|
|
|
@param[in] Configuration Pointer to PCI I/O and PCI memory resource
|
|
descriptors. The Configuration contains the
|
|
resources for all the root bridges. The resource
|
|
for each root bridge is terminated with END
|
|
descriptor and an additional END is appended
|
|
indicating the end of the entire resources. The
|
|
resource descriptor field values follow the
|
|
description in
|
|
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
|
|
.SubmitResources().
|
|
**/
|
|
VOID
|
|
EFIAPI
|
|
PciHostBridgeUtilityResourceConflict (
|
|
IN VOID *Configuration
|
|
);
|