[mirror_edk2.git] / IntelFrameworkModulePkg / Include / Protocol / PciHotPlugInit.h

/** @file\r
  This file declares EFI PCI Hot Plug Init Protocol\r
\r
  Copyright (c) 2006, Intel Corporation                                                         \r
  All rights reserved. This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
  Module Name:  PciHotPlugInit.h\r
\r
  @par Revision Reference:\r
  This protocol is defined in Framework of EFI Hot Plug Pci Initialization Protocol Spec\r
  Version 0.9\r
\r
**/\r
\r
#ifndef __EFI_PCI_HOT_PLUG_INIT_H_\r
#define __EFI_PCI_HOT_PLUG_INIT_H_\r
\r
//\r
// Global ID for the PCI Hot Plug Protocol\r
//\r
#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \\r
  { 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } }\r
\r
  \r
typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;\r
\r
#define  EFI_HPC_STATE_INITIALIZED    0x01\r
#define  EFI_HPC_STATE_ENABLED        0x02\r
\r
typedef UINT16 EFI_HPC_STATE;\r
\r
\r
typedef struct{\r
  EFI_DEVICE_PATH_PROTOCOL  *HpcDevicePath;\r
  EFI_DEVICE_PATH_PROTOCOL  *HpbDevicePath;\r
} EFI_HPC_LOCATION;\r
\r
\r
typedef enum{\r
  EfiPaddingPciBus,\r
  EfiPaddingPciRootBridge\r
} EFI_HPC_PADDING_ATTRIBUTES;\r
\r
/**\r
  Returns a list of root Hot Plug Controllers (HPCs) that require initialization \r
  during the boot process.\r
\r
  @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
  @param  HpcCount              The number of root HPCs that were returned.\r
  @param  HpcList               The list of root HPCs. HpcCount defines the number of\r
                                elements in this list.\r
\r
  @retval EFI_SUCCESS           HpcList was returned.\r
  @retval EFI_OUT_OF_RESOURCES  HpcList was not returned due to insufficient resources.\r
  @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GET_ROOT_HPC_LIST) (\r
  IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL   *This,\r
  OUT UINTN                           *HpcCount,\r
  OUT EFI_HPC_LOCATION                **HpcList\r
);\r
\r
/**\r
  Initializes one root Hot Plug Controller (HPC). This process may causes \r
  initialization of its subordinate buses. \r
\r
  @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
  @param  HpcDevicePath         The device path to the HPC that is being initialized.\r
  @param  HpcPciAddress         The address of the HPC function on the PCI bus.\r
  @param  Event                 The event that should be signaled when the HPC initialization\r
                                is complete.\r
  @param  HpcState              The state of the HPC hardware.\r
\r
  @retval EFI_SUCCESS           If Event is NULL, the specific HPC was successfully\r
                                initialized. If Event is not NULL, Event will be signaled at a later time\r
                                when initialization is complete.\r
  @retval EFI_UNSUPPORTED       This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
                                does not support the specified HPC.\r
  @retval EFI_OUT_OF_RESOURCES  Initialization failed due to insufficient\r
                                resources.\r
  @retval EFI_INVALID_PARAMETER HpcState is NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_INITIALIZE_ROOT_HPC) (\r
  IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL     *This,\r
  IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,\r
  IN  UINT64                            HpcPciAddress,\r
  IN  EFI_EVENT                         Event, OPTIONAL\r
  OUT EFI_HPC_STATE                     *HpcState\r
);\r
\r
/**\r
  Returns the resource padding that is required by the PCI bus that is controlled \r
  by the specified Hot Plug Controller (HPC).\r
\r
  @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
  @param  HpcDevicePath         The device path to the HPC.\r
  @param  HpcPciAddress         The address of the HPC function on the PCI bus.\r
  @param  HpcState              The state of the HPC hardware.\r
  @param  Padding               The amount of resource padding that is required by the\r
                                PCI bus under the control of the specified HPC.\r
  @param  Attributes            Describes how padding is accounted for. The padding\r
                                is returned in the form of ACPI 2.0 resource descriptors.\r
\r
  @retval EFI_SUCCESS           The resource padding was successfully returned.\r
  @retval EFI_UNSUPPORTED       This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
                                does not support the specified HPC.\r
  @retval EFI_NOT_READY         This function was called before HPC initialization is complete.\r
  @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.\r
  @retval EFI_OUT_OF_RESOURCES  ACPI 2.0 resource descriptors for Padding\r
                                cannot be allocated due to insufficient resources.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GET_PCI_HOT_PLUG_PADDING) (\r
  IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL     *This,\r
  IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,\r
  IN  UINT64                            HpcPciAddress,\r
  OUT EFI_HPC_STATE                     *HpcState,\r
  OUT VOID                              **Padding,\r
  OUT EFI_HPC_PADDING_ATTRIBUTES        *Attributes\r
); \r
\r
\r
//\r
// Prototypes for the PCI Hot Plug Init Protocol\r
//\r
\r
/**\r
  @par Protocol Description:\r
  This protocol provides the necessary functionality to initialize the \r
  Hot Plug Controllers (HPCs) and the buses that they control. This protocol \r
  also provides information regarding resource padding. \r
\r
  @param GetRootHpcList\r
  Returns a list of root HPCs and the buses that they control.\r
\r
  @param InitializeRootHpc\r
  Initializes the specified root HPC.\r
\r
  @param GetResourcePadding\r
  Returns the resource padding that is required by the HPC.\r
\r
**/\r
struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {\r
  EFI_GET_ROOT_HPC_LIST                                  GetRootHpcList;\r
  EFI_INITIALIZE_ROOT_HPC                                InitializeRootHpc;\r
  EFI_GET_PCI_HOT_PLUG_PADDING                           GetResourcePadding;\r
};\r
\r
extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
a9102619	1	/** @file\r
	2	This file declares EFI PCI Hot Plug Init Protocol\r
	3	\r
	4	Copyright (c) 2006, Intel Corporation \r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
	13	Module Name: PciHotPlugInit.h\r
	14	\r
	15	@par Revision Reference:\r
	16	This protocol is defined in Framework of EFI Hot Plug Pci Initialization Protocol Spec\r
	17	Version 0.9\r
	18	\r
	19	**/\r
	20	\r
	21	#ifndef __EFI_PCI_HOT_PLUG_INIT_H_\r
	22	#define __EFI_PCI_HOT_PLUG_INIT_H_\r
	23	\r
	24	//\r
	25	// Global ID for the PCI Hot Plug Protocol\r
	26	//\r
	27	#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \\r
	28	{ 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } }\r
	29	\r
	30	\r
	31	typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;\r
	32	\r
	33	#define EFI_HPC_STATE_INITIALIZED 0x01\r
	34	#define EFI_HPC_STATE_ENABLED 0x02\r
	35	\r
	36	typedef UINT16 EFI_HPC_STATE;\r
	37	\r
	38	\r
	39	typedef struct{\r
	40	EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath;\r
	41	EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath;\r
	42	} EFI_HPC_LOCATION;\r
	43	\r
	44	\r
	45	typedef enum{\r
	46	EfiPaddingPciBus,\r
	47	EfiPaddingPciRootBridge\r
	48	} EFI_HPC_PADDING_ATTRIBUTES;\r
	49	\r
	50	/**\r
	51	Returns a list of root Hot Plug Controllers (HPCs) that require initialization \r
	52	during the boot process.\r
	53	\r
	54	@param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
	55	@param HpcCount The number of root HPCs that were returned.\r
	56	@param HpcList The list of root HPCs. HpcCount defines the number of\r
	57	elements in this list.\r
	58	\r
	59	@retval EFI_SUCCESS HpcList was returned.\r
	60	@retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources.\r
	61	@retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.\r
	62	\r
	63	**/\r
	64	typedef\r
65	EFI_STATUS\r
66	(EFIAPI *EFI_GET_ROOT_HPC_LIST) (\r
67	IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
68	OUT UINTN *HpcCount,\r
69	OUT EFI_HPC_LOCATION **HpcList\r
70	);\r
71	\r
72	/**\r
73	Initializes one root Hot Plug Controller (HPC). This process may causes \r
74	initialization of its subordinate buses. \r
75	\r
76	@param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
77	@param HpcDevicePath The device path to the HPC that is being initialized.\r
78	@param HpcPciAddress The address of the HPC function on the PCI bus.\r
79	@param Event The event that should be signaled when the HPC initialization\r
80	is complete.\r
81	@param HpcState The state of the HPC hardware.\r
82	\r
83	@retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully\r
84	initialized. If Event is not NULL, Event will be signaled at a later time\r
85	when initialization is complete.\r
86	@retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
87	does not support the specified HPC.\r
88	@retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient\r
89	resources.\r
90	@retval EFI_INVALID_PARAMETER HpcState is NULL.\r
91	\r
92	**/\r
93	typedef\r
94	EFI_STATUS\r
95	(EFIAPI *EFI_INITIALIZE_ROOT_HPC) (\r
96	IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
97	IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
98	IN UINT64 HpcPciAddress,\r
99	IN EFI_EVENT Event, OPTIONAL\r
100	OUT EFI_HPC_STATE *HpcState\r
101	);\r
102	\r
103	/**\r
104	Returns the resource padding that is required by the PCI bus that is controlled \r
105	by the specified Hot Plug Controller (HPC).\r
106	\r
107	@param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
108	@param HpcDevicePath The device path to the HPC.\r
109	@param HpcPciAddress The address of the HPC function on the PCI bus.\r
110	@param HpcState The state of the HPC hardware.\r
111	@param Padding The amount of resource padding that is required by the\r
112	PCI bus under the control of the specified HPC.\r
113	@param Attributes Describes how padding is accounted for. The padding\r
114	is returned in the form of ACPI 2.0 resource descriptors.\r
115	\r
116	@retval EFI_SUCCESS The resource padding was successfully returned.\r
117	@retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
118	does not support the specified HPC.\r
119	@retval EFI_NOT_READY This function was called before HPC initialization is complete.\r
120	@retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.\r
121	@retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding\r
122	cannot be allocated due to insufficient resources.\r
123	\r
124	**/\r
125	typedef\r
126	EFI_STATUS\r
127	(EFIAPI *EFI_GET_PCI_HOT_PLUG_PADDING) (\r
128	IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
129	IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
130	IN UINT64 HpcPciAddress,\r
131	OUT EFI_HPC_STATE *HpcState,\r
132	OUT VOID **Padding,\r
133	OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes\r
134	); \r
135	\r
136	\r
137	//\r
138	// Prototypes for the PCI Hot Plug Init Protocol\r
139	//\r
140	\r
141	/**\r
142	@par Protocol Description:\r
143	This protocol provides the necessary functionality to initialize the \r
144	Hot Plug Controllers (HPCs) and the buses that they control. This protocol \r
145	also provides information regarding resource padding. \r
146	\r
147	@param GetRootHpcList\r
148	Returns a list of root HPCs and the buses that they control.\r
149	\r
150	@param InitializeRootHpc\r
151	Initializes the specified root HPC.\r
152	\r
153	@param GetResourcePadding\r
154	Returns the resource padding that is required by the HPC.\r
155	\r
156	**/\r
157	struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {\r
158	EFI_GET_ROOT_HPC_LIST GetRootHpcList;\r
159	EFI_INITIALIZE_ROOT_HPC InitializeRootHpc;\r
160	EFI_GET_PCI_HOT_PLUG_PADDING GetResourcePadding;\r
161	};\r
162	\r
163	extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
164	\r
165	#endif\r