[mirror_edk2.git] / MdePkg / Include / Protocol / PciHotPlugRequest.h

/** @file\r
  Provides services to notify the PCI bus driver that some events have happened\r
  in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the\r
  PCI bus driver to create or destroy handles for PCI-like devices.\r
\r
  A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request\r
  protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)\r
  is installed after PCI bus does the enumeration, the PCI bus driver can be\r
  notified through this protocol. For example, when a 32-bit PC Card is inserted\r
  into the PC Card socket, the PC Card bus driver can call interface of this\r
  protocol to notify PCI bus driver to allocate resource and create handles for\r
  this PC Card.\r
\r
  The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a\r
  separate handle when PCI bus driver starts up. There is only one instance in\r
  the system.  Any driver that wants to use this protocol must locate it globally.\r
  The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,\r
  for example, PC Card Bus driver, to notify PCI bus driver that an event has\r
  happened in the hot-plug controller, and the PCI bus driver is requested to\r
  create (add) or destroy (remove) handles for the specified PCI-like devices.\r
  For example, when a 32-bit PC Card is inserted, this protocol interface will\r
  be called with an add operation, and the PCI bus driver will enumerate and\r
  start the devices inserted; when a 32-bit PC Card is removed, this protocol\r
  interface will be called with a remove operation, and the PCI bus driver will\r
  stop the devices and destroy their handles.  The existence of this protocol\r
  represents the capability of the PCI bus driver. If this protocol exists in\r
  system, it means PCI bus driver is hot-plug capable, thus together with the\r
  effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,\r
  the hot-plug capability is not provided.\r
\r
  Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  @par Revision Reference:\r
  This Protocol is defined in UEFI Platform Initialization Specification 1.2\r
  Volume 5: Standards\r
\r
**/\r
\r
#ifndef __PCI_HOTPLUG_REQUEST_H_\r
#define __PCI_HOTPLUG_REQUEST_H_\r
\r
///\r
/// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r
///\r
#define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \\r
  { \\r
    0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \\r
  }\r
\r
///\r
/// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r
///\r
typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;\r
\r
///\r
/// Enumeration of PCI hot plug operations\r
///\r
typedef enum {\r
  ///\r
  /// The PCI bus driver is requested to create handles for the specified devices.\r
  /// An array of EFI_HANDLE is returned, with a NULL element marking the end of\r
  /// the array.\r
  ///\r
  EfiPciHotPlugRequestAdd,\r
\r
  ///\r
  /// The PCI bus driver is requested to destroy handles for the specified devices.\r
  ///\r
  EfiPciHotplugRequestRemove\r
} EFI_PCI_HOTPLUG_OPERATION;\r
\r
/**\r
  This function is used to notify PCI bus driver that some events happened in a\r
  hot-plug controller, and the PCI bus driver is requested to start or stop\r
  specified PCI-like devices.\r
\r
  This function allows the PCI bus driver to be notified to act as requested when\r
  a hot-plug event has happened on the hot-plug controller. Currently, the\r
  operations include add operation and remove operation.  If it is a add operation,\r
  the PCI bus driver will enumerate, allocate resources for devices behind the\r
  hot-plug controller, and create handle for the device specified by RemainingDevicePath.\r
  The RemainingDevicePath is an optional parameter. If it is not NULL, only the\r
  specified device is started; if it is NULL, all devices behind the hot-plug\r
  controller are started.  The newly created handles of PC Card functions are\r
  returned in the ChildHandleBuffer, together with the number of child handle in\r
  NumberOfChildren.  If it is a remove operation, when NumberOfChildren contains\r
  a non-zero value, child handles specified in ChildHandleBuffer are stopped and\r
  destroyed; otherwise, PCI bus driver is notified to stop managing the controller\r
  handle.\r
\r
    @param[in] This                    A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r
                                       instance.\r
    @param[in] Operation               The operation the PCI bus driver is requested\r
                                       to make.\r
    @param[in] Controller              The handle of the hot-plug controller.\r
    @param[in] RemainingDevicePath     The remaining device path for the PCI-like\r
                                       hot-plug device.  It only contains device\r
                                       path nodes behind the hot-plug controller.\r
                                       It is an optional parameter and only valid\r
                                       when the Operation is a add operation. If\r
                                       it is NULL, all devices behind the PC Card\r
                                       socket are started.\r
    @param[in,out] NumberOfChildren    The number of child handles. For an add\r
                                       operation, it is an output parameter.  For\r
                                       a remove operation, it's an input parameter.\r
                                       When it contains a non-zero value, children\r
                                       handles specified in ChildHandleBuffer are\r
                                       destroyed.  Otherwise, PCI bus driver is\r
                                       notified to stop managing the controller\r
                                       handle.\r
    @param[in,out] ChildHandleBuffer   The buffer which contains the child handles.\r
                                       For an add operation, it is an output\r
                                       parameter and contains all newly created\r
                                       child handles.  For a remove operation, it\r
                                       contains child handles to be destroyed when\r
                                       NumberOfChildren contains a non-zero value.\r
                                       It can be NULL when NumberOfChildren is 0.\r
                                       It's the caller's responsibility to allocate\r
                                       and free memory for this buffer.\r
\r
  @retval EFI_SUCCESS             The handles for the specified device have been\r
                                  created or destroyed as requested, and for an\r
                                  add operation, the new handles are returned in\r
                                  ChildHandleBuffer.\r
  @retval EFI_INVALID_PARAMETER   Operation is not a legal value.\r
  @retval EFI_INVALID_PARAMETER   Controller is NULL or not a valid handle.\r
  @retval EFI_INVALID_PARAMETER   NumberOfChildren is NULL.\r
  @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is\r
                                  remove and NumberOfChildren contains a non-zero\r
                                  value.\r
  @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is add.\r
  @retval EFI_OUT_OF_RESOURCES    There are no enough resources to start the\r
                                  devices.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(\r
  IN     EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  *This,\r
  IN     EFI_PCI_HOTPLUG_OPERATION         Operation,\r
  IN     EFI_HANDLE                        Controller,\r
  IN     EFI_DEVICE_PATH_PROTOCOL          *RemainingDevicePath  OPTIONAL,\r
  IN OUT UINT8                             *NumberOfChildren,\r
  IN OUT EFI_HANDLE                        *ChildHandleBuffer\r
  );\r
\r
///\r
/// Provides services to notify PCI bus driver that some events have happened in\r
/// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus\r
/// driver to create or destroy handles for the PCI-like devices.\r
///\r
struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {\r
  ///\r
  /// Notify the PCI bus driver that some events have happened in a hot-plug\r
  /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver\r
  /// to create or destroy handles for the PCI-like devices. See Section 0 for\r
  /// a detailed description.\r
  ///\r
  EFI_PCI_HOTPLUG_REQUEST_NOTIFY  Notify;\r
};\r
\r
extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
1e22c4d9	1	/** @file\r
9095d37b LG	2	Provides services to notify the PCI bus driver that some events have happened\r
9095d37b LG	3	in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the\r
1e22c4d9	4	PCI bus driver to create or destroy handles for PCI-like devices.\r
1e22c4d9	5	\r
9095d37b	6	A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request\r
1e22c4d9	7	protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)\r
9095d37b	8	is installed after PCI bus does the enumeration, the PCI bus driver can be\r
1e22c4d9	9	notified through this protocol. For example, when a 32-bit PC Card is inserted\r
	10	into the PC Card socket, the PC Card bus driver can call interface of this\r
	11	protocol to notify PCI bus driver to allocate resource and create handles for\r
	12	this PC Card.\r
9095d37b LG	13	\r
	14	The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a\r
	15	separate handle when PCI bus driver starts up. There is only one instance in\r
1e22c4d9	16	the system. Any driver that wants to use this protocol must locate it globally.\r
9095d37b LG	17	The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,\r
	18	for example, PC Card Bus driver, to notify PCI bus driver that an event has\r
	19	happened in the hot-plug controller, and the PCI bus driver is requested to\r
	20	create (add) or destroy (remove) handles for the specified PCI-like devices.\r
	21	For example, when a 32-bit PC Card is inserted, this protocol interface will\r
	22	be called with an add operation, and the PCI bus driver will enumerate and\r
	23	start the devices inserted; when a 32-bit PC Card is removed, this protocol\r
	24	interface will be called with a remove operation, and the PCI bus driver will\r
	25	stop the devices and destroy their handles. The existence of this protocol\r
1e22c4d9	26	represents the capability of the PCI bus driver. If this protocol exists in\r
9095d37b	27	system, it means PCI bus driver is hot-plug capable, thus together with the\r
1e22c4d9	28	effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,\r
9095d37b LG	29	the hot-plug capability is not provided.\r
	30	\r
	31	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
9344f092	32	SPDX-License-Identifier: BSD-2-Clause-Patent\r
1e22c4d9	33	\r
1e22c4d9	34	@par Revision Reference:\r
9095d37b	35	This Protocol is defined in UEFI Platform Initialization Specification 1.2\r
1e22c4d9	36	Volume 5: Standards\r
9095d37b	37	\r
1e22c4d9	38	**/\r
	39	\r
	40	#ifndef __PCI_HOTPLUG_REQUEST_H_\r
	41	#define __PCI_HOTPLUG_REQUEST_H_\r
	42	\r
	43	///\r
	44	/// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r
	45	///\r
	46	#define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \\r
	47	{ \\r
	48	0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \\r
	49	}\r
	50	\r
	51	///\r
	52	/// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r
	53	///\r
	54	typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;\r
	55	\r
	56	///\r
	57	/// Enumeration of PCI hot plug operations\r
9095d37b	58	///\r
1e22c4d9	59	typedef enum {\r
	60	///\r
	61	/// The PCI bus driver is requested to create handles for the specified devices.\r
	62	/// An array of EFI_HANDLE is returned, with a NULL element marking the end of\r
	63	/// the array.\r
	64	///\r
	65	EfiPciHotPlugRequestAdd,\r
	66	\r
	67	///\r
	68	/// The PCI bus driver is requested to destroy handles for the specified devices.\r
	69	///\r
	70	EfiPciHotplugRequestRemove\r
	71	} EFI_PCI_HOTPLUG_OPERATION;\r
	72	\r
	73	/**\r
	74	This function is used to notify PCI bus driver that some events happened in a\r
9095d37b	75	hot-plug controller, and the PCI bus driver is requested to start or stop\r
1e22c4d9	76	specified PCI-like devices.\r
9095d37b	77	\r
1e22c4d9	78	This function allows the PCI bus driver to be notified to act as requested when\r
9095d37b	79	a hot-plug event has happened on the hot-plug controller. Currently, the\r
1e22c4d9	80	operations include add operation and remove operation. If it is a add operation,\r
9095d37b	81	the PCI bus driver will enumerate, allocate resources for devices behind the\r
1e22c4d9	82	hot-plug controller, and create handle for the device specified by RemainingDevicePath.\r
9095d37b LG	83	The RemainingDevicePath is an optional parameter. If it is not NULL, only the\r
	84	specified device is started; if it is NULL, all devices behind the hot-plug\r
	85	controller are started. The newly created handles of PC Card functions are\r
1e22c4d9	86	returned in the ChildHandleBuffer, together with the number of child handle in\r
	87	NumberOfChildren. If it is a remove operation, when NumberOfChildren contains\r
	88	a non-zero value, child handles specified in ChildHandleBuffer are stopped and\r
	89	destroyed; otherwise, PCI bus driver is notified to stop managing the controller\r
9095d37b LG	90	handle.\r
	91	\r
	92	@param[in] This A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL\r
1e22c4d9	93	instance.\r
9095d37b LG	94	@param[in] Operation The operation the PCI bus driver is requested\r
9095d37b LG	95	to make.\r
1e22c4d9	96	@param[in] Controller The handle of the hot-plug controller.\r
	97	@param[in] RemainingDevicePath The remaining device path for the PCI-like\r
	98	hot-plug device. It only contains device\r
9095d37b	99	path nodes behind the hot-plug controller.\r
1e22c4d9	100	It is an optional parameter and only valid\r
9095d37b LG	101	when the Operation is a add operation. If\r
9095d37b LG	102	it is NULL, all devices behind the PC Card\r
1e22c4d9	103	socket are started.\r
9095d37b	104	@param[in,out] NumberOfChildren The number of child handles. For an add\r
1e22c4d9	105	operation, it is an output parameter. For\r
	106	a remove operation, it's an input parameter.\r
	107	When it contains a non-zero value, children\r
	108	handles specified in ChildHandleBuffer are\r
9095d37b LG	109	destroyed. Otherwise, PCI bus driver is\r
9095d37b LG	110	notified to stop managing the controller\r
1e22c4d9	111	handle.\r
9095d37b LG	112	@param[in,out] ChildHandleBuffer The buffer which contains the child handles.\r
	113	For an add operation, it is an output\r
	114	parameter and contains all newly created\r
1e22c4d9	115	child handles. For a remove operation, it\r
	116	contains child handles to be destroyed when\r
	117	NumberOfChildren contains a non-zero value.\r
	118	It can be NULL when NumberOfChildren is 0.\r
	119	It's the caller's responsibility to allocate\r
	120	and free memory for this buffer.\r
9095d37b LG	121	\r
	122	@retval EFI_SUCCESS The handles for the specified device have been\r
	123	created or destroyed as requested, and for an\r
	124	add operation, the new handles are returned in\r
1e22c4d9	125	ChildHandleBuffer.\r
	126	@retval EFI_INVALID_PARAMETER Operation is not a legal value.\r
	127	@retval EFI_INVALID_PARAMETER Controller is NULL or not a valid handle.\r
	128	@retval EFI_INVALID_PARAMETER NumberOfChildren is NULL.\r
9095d37b LG	129	@retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is\r
9095d37b LG	130	remove and NumberOfChildren contains a non-zero\r
1e22c4d9	131	value.\r
1e22c4d9	132	@retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is add.\r
9095d37b	133	@retval EFI_OUT_OF_RESOURCES There are no enough resources to start the\r
1e22c4d9	134	devices.\r
	135	**/\r
	136	typedef\r
	137	EFI_STATUS\r
	138	(EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(\r
	139	IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL *This,\r
	140	IN EFI_PCI_HOTPLUG_OPERATION Operation,\r
	141	IN EFI_HANDLE Controller,\r
	142	IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL,\r
	143	IN OUT UINT8 *NumberOfChildren,\r
	144	IN OUT EFI_HANDLE *ChildHandleBuffer\r
	145	);\r
	146	\r
	147	///\r
9095d37b LG	148	/// Provides services to notify PCI bus driver that some events have happened in\r
9095d37b LG	149	/// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus\r
1e22c4d9	150	/// driver to create or destroy handles for the PCI-like devices.\r
	151	///\r
	152	struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {\r
	153	///\r
9095d37b LG	154	/// Notify the PCI bus driver that some events have happened in a hot-plug\r
	155	/// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver\r
	156	/// to create or destroy handles for the PCI-like devices. See Section 0 for\r
1e22c4d9	157	/// a detailed description.\r
	158	///\r
	159	EFI_PCI_HOTPLUG_REQUEST_NOTIFY Notify;\r
	160	};\r
	161	\r
	162	extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;\r
	163	\r
	164	#endif\r