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

/** @file\r
  This file declares EFI PCI Hot Plug Init Protocol.\r
  This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and\r
  the buses that they control. This protocol also provides information regarding resource padding.\r
\r
  Copyright (c) 2007 - 2009, 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
  @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
///\r
/// Global ID for the PCI Hot Plug Protocol\r
///\r
#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \\r
  { \\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
///\r
/// Current state of an HPC\r
///\r
typedef UINT16 EFI_HPC_STATE;\r
\r
///\r
/// The HPC initialization function was called and the HPC completed \r
/// initialization, but it was not enabled for some reason. The HPC may be \r
/// disabled in hardware, or it may be disabled due to user preferences, \r
/// hardware failure, or other reasons. No resource padding is required.\r
///\r
#define  EFI_HPC_STATE_INITIALIZED    0x01\r
\r
///\r
/// The HPC initialization function was called, the HPC completed \r
/// initialization, and it was enabled. Resource padding is required.\r
///\r
#define  EFI_HPC_STATE_ENABLED        0x02\r
\r
///\r
/// Location definition for PCI Hot Plug Controller\r
///\r
typedef struct{\r
  ///\r
  /// The device path to the Root HPC\r
  ///\r
  EFI_DEVICE_PATH_PROTOCOL  *HpcDevicePath;\r
  ///\r
  /// The device path to the Hot Plug Bus (HPB) that is controlled by \r
  /// the root HPC.\r
  ///\r
  EFI_DEVICE_PATH_PROTOCOL  *HpbDevicePath;\r
} EFI_HPC_LOCATION;\r
\r
\r
///\r
/// Describes how resource padding should be applied\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
  This procedure returns a list of root HPCs. The PCI bus driver must initialize these controllers \r
  during the boot process. The PCI bus driver may or may not be able to detect these HPCs. If the \r
  platform includes a PCI-to-CardBus bridge, it can be included in this list if it requires initialization. \r
  The HpcList must be self consistent. An HPC cannot control any of its parent buses. Only one HPC \r
  can control a PCI bus. Because this list includes only root HPCs, no HPC in the list can be a child of \r
  another HPC. This policy must be enforced by the EFI_PCI_HOT_PLUG_INIT_PROTOCOL. \r
  The PCI bus driver may not check for such invalid conditions. \r
  The callee allocates the buffer HpcList\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
  This function initializes the specified HPC. At the end of initialization, the hot-plug slots or sockets \r
  (controlled by this HPC) are powered and are connected to the bus. All the necessary registers in the \r
  HPC are set up. For a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set up \r
  are defined in the PCI Standard Hot Plug Controller and Subsystem Specification.\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. The state is EFI_HPC_STATE_INITIALIZED\r
                                or EFI_HPC_STATE_ENABLED.\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
  This function returns the resource padding that is required by the PCI bus that is controlled by the \r
  specified HPC. This member function is called for all the root HPCs and nonroot HPCs that are \r
  detected by the PCI bus enumerator. This function will be called before PCI resource allocation is \r
  completed. This function must be called after all the root HPCs, with the possible exception of a \r
  PCI-to-CardBus bridge, have completed initialization.\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_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
/// 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
struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {\r
  ///\r
  /// Returns a list of root HPCs and the buses that they control.\r
  ///\r
  EFI_GET_ROOT_HPC_LIST                                  GetRootHpcList;\r
  \r
  ///\r
  /// Initializes the specified root HPC.\r
  ///\r
  EFI_INITIALIZE_ROOT_HPC                                InitializeRootHpc;\r
  \r
  ///\r
  /// Returns the resource padding that is required by the HPC.\r
  ///\r
  EFI_GET_HOT_PLUG_PADDING                               GetResourcePadding;\r
};\r
\r
extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
79964ac8	1	/** @file\r
9ca1b12e	2	This file declares EFI PCI Hot Plug Init Protocol.\r
8411f1c0	3	This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and\r
8411f1c0	4	the buses that they control. This protocol also provides information regarding resource padding.\r
79964ac8	5	\r
2bbaeb0d	6	Copyright (c) 2007 - 2009, Intel Corporation\r
79964ac8	7	All rights reserved. This program and the accompanying materials\r
	8	are licensed and made available under the terms and conditions of the BSD License\r
	9	which accompanies this distribution. The full text of the license may be found at\r
	10	http://opensource.org/licenses/bsd-license.php\r
	11	\r
	12	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	13	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	14	\r
79964ac8	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
b80fbe85	24	\r
9ca1b12e	25	///\r
	26	/// Global ID for the PCI Hot Plug Protocol\r
	27	///\r
79964ac8	28	#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \\r
8ba07297	29	{ \\r
	30	0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \\r
	31	}\r
79964ac8	32	\r
	33	typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;\r
	34	\r
9ca1b12e	35	///\r
	36	/// Current state of an HPC\r
	37	///\r
79964ac8	38	typedef UINT16 EFI_HPC_STATE;\r
79964ac8	39	\r
9ca1b12e	40	///\r
	41	/// The HPC initialization function was called and the HPC completed \r
	42	/// initialization, but it was not enabled for some reason. The HPC may be \r
	43	/// disabled in hardware, or it may be disabled due to user preferences, \r
	44	/// hardware failure, or other reasons. No resource padding is required.\r
	45	///\r
	46	#define EFI_HPC_STATE_INITIALIZED 0x01\r
79964ac8	47	\r
9ca1b12e	48	///\r
	49	/// The HPC initialization function was called, the HPC completed \r
	50	/// initialization, and it was enabled. Resource padding is required.\r
	51	///\r
	52	#define EFI_HPC_STATE_ENABLED 0x02\r
	53	\r
	54	///\r
	55	/// Location definition for PCI Hot Plug Controller\r
	56	///\r
79964ac8	57	typedef struct{\r
9ca1b12e	58	///\r
	59	/// The device path to the Root HPC\r
	60	///\r
79964ac8	61	EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath;\r
9ca1b12e	62	///\r
	63	/// The device path to the Hot Plug Bus (HPB) that is controlled by \r
	64	/// the root HPC.\r
	65	///\r
79964ac8	66	EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath;\r
	67	} EFI_HPC_LOCATION;\r
	68	\r
	69	\r
8ba07297	70	///\r
	71	/// Describes how resource padding should be applied\r
	72	///\r
79964ac8	73	typedef enum{\r
	74	EfiPaddingPciBus,\r
	75	EfiPaddingPciRootBridge\r
	76	} EFI_HPC_PADDING_ATTRIBUTES;\r
	77	\r
	78	/**\r
	79	Returns a list of root Hot Plug Controllers (HPCs) that require initialization\r
	80	during the boot process.\r
	81	\r
8ba07297	82	This procedure returns a list of root HPCs. The PCI bus driver must initialize these controllers \r
	83	during the boot process. The PCI bus driver may or may not be able to detect these HPCs. If the \r
	84	platform includes a PCI-to-CardBus bridge, it can be included in this list if it requires initialization. \r
	85	The HpcList must be self consistent. An HPC cannot control any of its parent buses. Only one HPC \r
	86	can control a PCI bus. Because this list includes only root HPCs, no HPC in the list can be a child of \r
	87	another HPC. This policy must be enforced by the EFI_PCI_HOT_PLUG_INIT_PROTOCOL. \r
	88	The PCI bus driver may not check for such invalid conditions. \r
	89	The callee allocates the buffer HpcList\r
	90	\r
79964ac8	91	@param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
	92	@param HpcCount The number of root HPCs that were returned.\r
	93	@param HpcList The list of root HPCs. HpcCount defines the number of\r
	94	elements in this list.\r
	95	\r
	96	@retval EFI_SUCCESS HpcList was returned.\r
	97	@retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources.\r
	98	@retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.\r
	99	\r
	100	**/\r
	101	typedef\r
	102	EFI_STATUS\r
69686d56	103	(EFIAPI *EFI_GET_ROOT_HPC_LIST)(\r
516e9f28	104	IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
79964ac8	105	OUT UINTN *HpcCount,\r
	106	OUT EFI_HPC_LOCATION **HpcList\r
	107	);\r
	108	\r
	109	/**\r
	110	Initializes one root Hot Plug Controller (HPC). This process may causes\r
	111	initialization of its subordinate buses.\r
8ba07297	112	\r
	113	This function initializes the specified HPC. At the end of initialization, the hot-plug slots or sockets \r
	114	(controlled by this HPC) are powered and are connected to the bus. All the necessary registers in the \r
	115	HPC are set up. For a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set up \r
	116	are defined in the PCI Standard Hot Plug Controller and Subsystem Specification.\r
79964ac8	117	\r
	118	@param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
	119	@param HpcDevicePath The device path to the HPC that is being initialized.\r
	120	@param HpcPciAddress The address of the HPC function on the PCI bus.\r
	121	@param Event The event that should be signaled when the HPC initialization\r
	122	is complete.\r
8ba07297	123	@param HpcState The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED\r
8ba07297	124	or EFI_HPC_STATE_ENABLED.\r
79964ac8	125	\r
	126	@retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully\r
	127	initialized. If Event is not NULL, Event will be signaled at a later time\r
	128	when initialization is complete.\r
	129	@retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
	130	does not support the specified HPC.\r
	131	@retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient\r
	132	resources.\r
	133	@retval EFI_INVALID_PARAMETER HpcState is NULL.\r
	134	\r
	135	**/\r
	136	typedef\r
	137	EFI_STATUS\r
69686d56	138	(EFIAPI *EFI_INITIALIZE_ROOT_HPC)(\r
516e9f28	139	IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
79964ac8	140	IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
	141	IN UINT64 HpcPciAddress,\r
	142	IN EFI_EVENT Event, OPTIONAL\r
	143	OUT EFI_HPC_STATE *HpcState\r
	144	);\r
	145	\r
	146	/**\r
	147	Returns the resource padding that is required by the PCI bus that is controlled\r
	148	by the specified Hot Plug Controller (HPC).\r
	149	\r
8ba07297	150	This function returns the resource padding that is required by the PCI bus that is controlled by the \r
	151	specified HPC. This member function is called for all the root HPCs and nonroot HPCs that are \r
	152	detected by the PCI bus enumerator. This function will be called before PCI resource allocation is \r
	153	completed. This function must be called after all the root HPCs, with the possible exception of a \r
	154	PCI-to-CardBus bridge, have completed initialization.\r
	155	\r
79964ac8	156	@param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
	157	@param HpcDevicePath The device path to the HPC.\r
	158	@param HpcPciAddress The address of the HPC function on the PCI bus.\r
	159	@param HpcState The state of the HPC hardware.\r
	160	@param Padding The amount of resource padding that is required by the\r
	161	PCI bus under the control of the specified HPC.\r
	162	@param Attributes Describes how padding is accounted for. The padding\r
	163	is returned in the form of ACPI 2.0 resource descriptors.\r
	164	\r
	165	@retval EFI_SUCCESS The resource padding was successfully returned.\r
	166	@retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
	167	does not support the specified HPC.\r
	168	@retval EFI_NOT_READY This function was called before HPC initialization is complete.\r
	169	@retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.\r
	170	@retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding\r
	171	cannot be allocated due to insufficient resources.\r
	172	\r
	173	**/\r
	174	typedef\r
	175	EFI_STATUS\r
8ba07297	176	(EFIAPI *EFI_GET_HOT_PLUG_PADDING)(\r
516e9f28	177	IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
79964ac8	178	IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
	179	IN UINT64 HpcPciAddress,\r
	180	OUT EFI_HPC_STATE *HpcState,\r
	181	OUT VOID **Padding,\r
	182	OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes\r
	183	);\r
	184	\r
	185	\r
	186	//\r
	187	// Prototypes for the PCI Hot Plug Init Protocol\r
	188	//\r
	189	\r
9ca1b12e	190	///\r
	191	/// This protocol provides the necessary functionality to initialize the\r
	192	/// Hot Plug Controllers (HPCs) and the buses that they control. This protocol\r
	193	/// also provides information regarding resource padding.\r
	194	///\r
79964ac8	195	struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {\r
2bbaeb0d	196	///\r
	197	/// Returns a list of root HPCs and the buses that they control.\r
	198	///\r
79964ac8	199	EFI_GET_ROOT_HPC_LIST GetRootHpcList;\r
2bbaeb0d	200	\r
	201	///\r
	202	/// Initializes the specified root HPC.\r
	203	///\r
79964ac8	204	EFI_INITIALIZE_ROOT_HPC InitializeRootHpc;\r
2bbaeb0d	205	\r
	206	///\r
	207	/// Returns the resource padding that is required by the HPC.\r
	208	///\r
8ba07297	209	EFI_GET_HOT_PLUG_PADDING GetResourcePadding;\r
79964ac8	210	};\r
	211	\r
	212	extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
	213	\r
	214	#endif\r