[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
#include <Library/PciHostBridgeLib.h>\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]  DmaAbove4G             DMA above 4GB memory.\r
\r
  @param[in]  NoExtendedConfigSpace  No Extended Config Space.\r
\r
  @param[in]  RootBusNumber          The bus number to store in RootBus.\r
\r
  @param[in]  MaxSubBusNumber        The inclusive maximum bus number that can\r
                                     be assigned to any subordinate bus found\r
                                     behind any PCI bridge hanging off this\r
                                     root bus.\r
\r
                                     The caller is repsonsible for ensuring\r
                                     that RootBusNumber <= MaxSubBusNumber. If\r
                                     RootBusNumber equals MaxSubBusNumber, then\r
                                     the root bus has no room for subordinate\r
                                     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\r
                                     by the caller) that should be filled in by\r
                                     this function.\r
\r
  @retval EFI_SUCCESS                Initialization successful. A device path\r
                                     consisting of an ACPI device path node,\r
                                     with UID = RootBusNumber, has been\r
                                     allocated and 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  BOOLEAN                   DmaAbove4G,\r
  IN  BOOLEAN                   NoExtendedConfigSpace,\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
  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
  Utility function to return all the root bridge instances in an array.\r
\r
  @param[out] Count                  The number of root bridge instances.\r
\r
  @param[in]  Attributes             Initial attributes.\r
\r
  @param[in]  AllocAttributes        Allocation attributes.\r
\r
  @param[in]  DmaAbove4G             DMA above 4GB memory.\r
\r
  @param[in]  NoExtendedConfigSpace  No Extended Config Space.\r
\r
  @param[in]  BusMin                 Minimum Bus number, inclusive.\r
\r
  @param[in]  BusMax                 Maximum Bus number, inclusive.\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
  @return                            All the root bridge instances in an array.\r
**/\r
PCI_ROOT_BRIDGE *\r
EFIAPI\r
PciHostBridgeUtilityGetRootBridges (\r
  OUT UINTN                     *Count,\r
  IN  UINT64                    Attributes,\r
  IN  UINT64                    AllocationAttributes,\r
  IN  BOOLEAN                   DmaAbove4G,\r
  IN  BOOLEAN                   NoExtendedConfigSpace,\r
  IN  UINTN                     BusMin,\r
  IN  UINTN                     BusMax,\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
  );\r
\r
/**\r
  Utility function to free root bridge instances array from\r
  PciHostBridgeUtilityGetRootBridges().\r
\r
  @param[in] Bridges  The root bridge instances array.\r
  @param[in] Count    The count of the array.\r
**/\r
VOID\r
EFIAPI\r
PciHostBridgeUtilityFreeRootBridges (\r
  IN PCI_ROOT_BRIDGE  *Bridges,\r
  IN UINTN            Count\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
#endif // __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r
Commit	Line	Data
	1	/** @file\r
	2	Provide common utility functions to PciHostBridgeLib instances in\r
	3	ArmVirtPkg and OvmfPkg.\r
	4	\r
	5	Copyright (C) 2016, Red Hat, Inc.\r
	6	Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>\r
	7	Copyright (c) 2020, Huawei Corporation. All rights reserved.<BR>\r
	8	\r
	9	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	10	\r
	11	**/\r
	12	\r
	13	#ifndef __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r
	14	#define __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r
	15	\r
	16	#include <Library/PciHostBridgeLib.h>\r
	17	\r
	18	/**\r
	19	Utility function to initialize a PCI_ROOT_BRIDGE structure.\r
	20	\r
	21	@param[in] Supports Supported attributes.\r
	22	\r
	23	@param[in] Attributes Initial attributes.\r
	24	\r
	25	@param[in] AllocAttributes Allocation attributes.\r
	26	\r
	27	@param[in] DmaAbove4G DMA above 4GB memory.\r
	28	\r
	29	@param[in] NoExtendedConfigSpace No Extended Config Space.\r
	30	\r
	31	@param[in] RootBusNumber The bus number to store in RootBus.\r
	32	\r
	33	@param[in] MaxSubBusNumber The inclusive maximum bus number that can\r
	34	be assigned to any subordinate bus found\r
	35	behind any PCI bridge hanging off this\r
	36	root bus.\r
	37	\r
	38	The caller is repsonsible for ensuring\r
	39	that RootBusNumber <= MaxSubBusNumber. If\r
	40	RootBusNumber equals MaxSubBusNumber, then\r
	41	the root bus has no room for subordinate\r
	42	buses.\r
	43	\r
	44	@param[in] Io IO aperture.\r
	45	\r
	46	@param[in] Mem MMIO aperture.\r
	47	\r
	48	@param[in] MemAbove4G MMIO aperture above 4G.\r
	49	\r
	50	@param[in] PMem Prefetchable MMIO aperture.\r
	51	\r
	52	@param[in] PMemAbove4G Prefetchable MMIO aperture above 4G.\r
	53	\r
	54	@param[out] RootBus The PCI_ROOT_BRIDGE structure (allocated\r
	55	by the caller) that should be filled in by\r
	56	this function.\r
	57	\r
	58	@retval EFI_SUCCESS Initialization successful. A device path\r
	59	consisting of an ACPI device path node,\r
	60	with UID = RootBusNumber, has been\r
	61	allocated and linked into RootBus.\r
	62	\r
	63	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
	64	**/\r
	65	EFI_STATUS\r
	66	EFIAPI\r
	67	PciHostBridgeUtilityInitRootBridge (\r
	68	IN UINT64 Supports,\r
	69	IN UINT64 Attributes,\r
	70	IN UINT64 AllocAttributes,\r
	71	IN BOOLEAN DmaAbove4G,\r
	72	IN BOOLEAN NoExtendedConfigSpace,\r
	73	IN UINT8 RootBusNumber,\r
	74	IN UINT8 MaxSubBusNumber,\r
	75	IN PCI_ROOT_BRIDGE_APERTURE *Io,\r
	76	IN PCI_ROOT_BRIDGE_APERTURE *Mem,\r
	77	IN PCI_ROOT_BRIDGE_APERTURE *MemAbove4G,\r
	78	IN PCI_ROOT_BRIDGE_APERTURE *PMem,\r
	79	IN PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G,\r
	80	OUT PCI_ROOT_BRIDGE *RootBus\r
	81	);\r
	82	\r
	83	/**\r
	84	Utility function to uninitialize a PCI_ROOT_BRIDGE structure set up with\r
	85	PciHostBridgeUtilityInitRootBridge().\r
	86	\r
	87	@param[in] RootBus The PCI_ROOT_BRIDGE structure, allocated by the caller and\r
	88	initialized with PciHostBridgeUtilityInitRootBridge(),\r
	89	that should be uninitialized. This function doesn't free\r
	90	RootBus.\r
	91	**/\r
	92	VOID\r
	93	EFIAPI\r
	94	PciHostBridgeUtilityUninitRootBridge (\r
	95	IN PCI_ROOT_BRIDGE *RootBus\r
	96	);\r
	97	\r
	98	/**\r
	99	Utility function to return all the root bridge instances in an array.\r
	100	\r
	101	@param[out] Count The number of root bridge instances.\r
	102	\r
	103	@param[in] Attributes Initial attributes.\r
	104	\r
	105	@param[in] AllocAttributes Allocation attributes.\r
	106	\r
	107	@param[in] DmaAbove4G DMA above 4GB memory.\r
	108	\r
	109	@param[in] NoExtendedConfigSpace No Extended Config Space.\r
	110	\r
	111	@param[in] BusMin Minimum Bus number, inclusive.\r
	112	\r
	113	@param[in] BusMax Maximum Bus number, inclusive.\r
	114	\r
	115	@param[in] Io IO aperture.\r
	116	\r
	117	@param[in] Mem MMIO aperture.\r
	118	\r
	119	@param[in] MemAbove4G MMIO aperture above 4G.\r
	120	\r
	121	@param[in] PMem Prefetchable MMIO aperture.\r
	122	\r
	123	@param[in] PMemAbove4G Prefetchable MMIO aperture above 4G.\r
	124	\r
	125	@return All the root bridge instances in an array.\r
	126	**/\r
	127	PCI_ROOT_BRIDGE *\r
	128	EFIAPI\r
	129	PciHostBridgeUtilityGetRootBridges (\r
	130	OUT UINTN *Count,\r
	131	IN UINT64 Attributes,\r
	132	IN UINT64 AllocationAttributes,\r
	133	IN BOOLEAN DmaAbove4G,\r
	134	IN BOOLEAN NoExtendedConfigSpace,\r
	135	IN UINTN BusMin,\r
	136	IN UINTN BusMax,\r
	137	IN PCI_ROOT_BRIDGE_APERTURE *Io,\r
	138	IN PCI_ROOT_BRIDGE_APERTURE *Mem,\r
	139	IN PCI_ROOT_BRIDGE_APERTURE *MemAbove4G,\r
	140	IN PCI_ROOT_BRIDGE_APERTURE *PMem,\r
	141	IN PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G\r
	142	);\r
	143	\r
	144	/**\r
	145	Utility function to free root bridge instances array from\r
	146	PciHostBridgeUtilityGetRootBridges().\r
	147	\r
	148	@param[in] Bridges The root bridge instances array.\r
	149	@param[in] Count The count of the array.\r
	150	**/\r
	151	VOID\r
	152	EFIAPI\r
	153	PciHostBridgeUtilityFreeRootBridges (\r
	154	IN PCI_ROOT_BRIDGE *Bridges,\r
	155	IN UINTN Count\r
	156	);\r
	157	\r
	158	/**\r
	159	Utility function to inform the platform that the resource conflict happens.\r
	160	\r
	161	@param[in] Configuration Pointer to PCI I/O and PCI memory resource\r
	162	descriptors. The Configuration contains the\r
	163	resources for all the root bridges. The resource\r
	164	for each root bridge is terminated with END\r
	165	descriptor and an additional END is appended\r
	166	indicating the end of the entire resources. The\r
	167	resource descriptor field values follow the\r
	168	description in\r
	169	EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
	170	.SubmitResources().\r
	171	**/\r
	172	VOID\r
	173	EFIAPI\r
	174	PciHostBridgeUtilityResourceConflict (\r
	175	IN VOID *Configuration\r
	176	);\r
	177	\r
	178	#endif // __PCI_HOST_BRIDGE_UTILITY_LIB_H__\r