OvmfPkg/PciHostBridgeLib: Extract InitRootBridge() / UninitRootBridge()

[mirror_edk2.git] / OvmfPkg / Include / Library / PciHostBridgeUtilityLib.h

/** @file\r
  Provide common utility functions to PciHostBridgeLib instances in\r
  ArmVirtPkg and OvmfPkg.\r
\r
  Copyright (C) 2016, Red Hat, Inc.\r
  Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>\r
  Copyright (c) 2020, Huawei Corporation. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r
#define __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r
\r
\r
#include <Library/PciHostBridgeLib.h>\r
\r
\r
/**\r
  Utility function to initialize a PCI_ROOT_BRIDGE structure.\r
\r
  @param[in]  Supports         Supported attributes.\r
\r
  @param[in]  Attributes       Initial attributes.\r
\r
  @param[in]  AllocAttributes  Allocation attributes.\r
\r
  @param[in]  RootBusNumber    The bus number to store in RootBus.\r
\r
  @param[in]  MaxSubBusNumber  The inclusive maximum bus number that can be\r
                               assigned to any subordinate bus found behind any\r
                               PCI bridge hanging off this root bus.\r
\r
                               The caller is repsonsible for ensuring that\r
                               RootBusNumber <= MaxSubBusNumber. If\r
                               RootBusNumber equals MaxSubBusNumber, then the\r
                               root bus has no room for subordinate buses.\r
\r
  @param[in]  Io               IO aperture.\r
\r
  @param[in]  Mem              MMIO aperture.\r
\r
  @param[in]  MemAbove4G       MMIO aperture above 4G.\r
\r
  @param[in]  PMem             Prefetchable MMIO aperture.\r
\r
  @param[in]  PMemAbove4G      Prefetchable MMIO aperture above 4G.\r
\r
  @param[out] RootBus          The PCI_ROOT_BRIDGE structure (allocated by the\r
                               caller) that should be filled in by this\r
                               function.\r
\r
  @retval EFI_SUCCESS           Initialization successful. A device path\r
                                consisting of an ACPI device path node, with\r
                                UID = RootBusNumber, has been allocated and\r
                                linked into RootBus.\r
\r
  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.\r
**/\r
EFI_STATUS\r
EFIAPI\r
PciHostBridgeUtilityInitRootBridge (\r
  IN  UINT64                   Supports,\r
  IN  UINT64                   Attributes,\r
  IN  UINT64                   AllocAttributes,\r
  IN  UINT8                    RootBusNumber,\r
  IN  UINT8                    MaxSubBusNumber,\r
  IN  PCI_ROOT_BRIDGE_APERTURE *Io,\r
  IN  PCI_ROOT_BRIDGE_APERTURE *Mem,\r
  IN  PCI_ROOT_BRIDGE_APERTURE *MemAbove4G,\r
  IN  PCI_ROOT_BRIDGE_APERTURE *PMem,\r
  IN  PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G,\r
  OUT PCI_ROOT_BRIDGE          *RootBus\r
  );\r
\r
\r
/**\r
  Utility function to uninitialize a PCI_ROOT_BRIDGE structure set up with\r
  PciHostBridgeUtilityInitRootBridge().\r
\r
  @param[in] RootBus  The PCI_ROOT_BRIDGE structure, allocated by the caller and\r
                      initialized with PciHostBridgeUtilityInitRootBridge(),\r
                      that should be uninitialized. This function doesn't free\r
                      RootBus.\r
**/\r
VOID\r
EFIAPI\r
PciHostBridgeUtilityUninitRootBridge (\r
  IN PCI_ROOT_BRIDGE *RootBus\r
  );\r
\r
\r
/**\r
  Utility function to inform the platform that the resource conflict happens.\r
\r
  @param[in] Configuration  Pointer to PCI I/O and PCI memory resource\r
                            descriptors. The Configuration contains the\r
                            resources for all the root bridges. The resource\r
                            for each root bridge is terminated with END\r
                            descriptor and an additional END is appended\r
                            indicating the end of the entire resources. The\r
                            resource descriptor field values follow the\r
                            description in\r
                            EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
                            .SubmitResources().\r
**/\r
VOID\r
EFIAPI\r
PciHostBridgeUtilityResourceConflict (\r
  IN VOID  *Configuration\r
  );\r
\r
\r
#endif // __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r