MdePkg/Include/Protocol/PciHotPlugRequest.h - third_party/edk2 - Git at Google

 /** @file
   Provides services to notify the PCI bus driver that some events have happened
   in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the
   PCI bus driver to create or destroy handles for PCI-like devices.

   A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request
   protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)
   is installed after PCI bus does the enumeration, the PCI bus driver can be
   notified through this protocol. For example, when a 32-bit PC Card is inserted
   into the PC Card socket, the PC Card bus driver can call interface of this
   protocol to notify PCI bus driver to allocate resource and create handles for
   this PC Card.

   The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a
   separate handle when PCI bus driver starts up. There is only one instance in
   the system.  Any driver that wants to use this protocol must locate it globally.
   The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,
   for example, PC Card Bus driver, to notify PCI bus driver that an event has
   happened in the hot-plug controller, and the PCI bus driver is requested to
   create (add) or destroy (remove) handles for the specified PCI-like devices.
   For example, when a 32-bit PC Card is inserted, this protocol interface will
   be called with an add operation, and the PCI bus driver will enumerate and
   start the devices inserted; when a 32-bit PC Card is removed, this protocol
   interface will be called with a remove operation, and the PCI bus driver will
   stop the devices and destroy their handles.  The existence of this protocol
   represents the capability of the PCI bus driver. If this protocol exists in
   system, it means PCI bus driver is hot-plug capable, thus together with the
   effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,
   the hot-plug capability is not provided.

   Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR>
   This program and the accompanying materials
   are licensed and made available under the terms and conditions of the BSD License
   which accompanies this distribution.  The full text of the license may be found at
   http://opensource.org/licenses/bsd-license.php

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

   @par Revision Reference:
   This Protocol is defined in UEFI Platform Initialization Specification 1.2
   Volume 5: Standards

 **/

 #ifndef __PCI_HOTPLUG_REQUEST_H_
 #define __PCI_HOTPLUG_REQUEST_H_

 ///
 /// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
 ///
 #define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \
   { \
     0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \
   }

 ///
 /// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
 ///
 typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;

 ///
 /// Enumeration of PCI hot plug operations
 ///
 typedef enum {
   ///
   /// The PCI bus driver is requested to create handles for the specified devices.
   /// An array of EFI_HANDLE is returned, with a NULL element marking the end of
   /// the array.
   ///
   EfiPciHotPlugRequestAdd,

   ///
   /// The PCI bus driver is requested to destroy handles for the specified devices.
   ///
   EfiPciHotplugRequestRemove
 } EFI_PCI_HOTPLUG_OPERATION;

 /**
   This function is used to notify PCI bus driver that some events happened in a
   hot-plug controller, and the PCI bus driver is requested to start or stop
   specified PCI-like devices.

   This function allows the PCI bus driver to be notified to act as requested when
   a hot-plug event has happened on the hot-plug controller. Currently, the
   operations include add operation and remove operation.  If it is a add operation,
   the PCI bus driver will enumerate, allocate resources for devices behind the
   hot-plug controller, and create handle for the device specified by RemainingDevicePath.
   The RemainingDevicePath is an optional parameter. If it is not NULL, only the
   specified device is started; if it is NULL, all devices behind the hot-plug
   controller are started.  The newly created handles of PC Card functions are
   returned in the ChildHandleBuffer, together with the number of child handle in
   NumberOfChildren.  If it is a remove operation, when NumberOfChildren contains
   a non-zero value, child handles specified in ChildHandleBuffer are stopped and
   destroyed; otherwise, PCI bus driver is notified to stop managing the controller
   handle.

     @param[in] This                    A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
                                        instance.
     @param[in] Operation               The operation the PCI bus driver is requested
                                        to make.
     @param[in] Controller              The handle of the hot-plug controller.
     @param[in] RemainingDevicePath     The remaining device path for the PCI-like
                                        hot-plug device.  It only contains device
                                        path nodes behind the hot-plug controller.
                                        It is an optional parameter and only valid
                                        when the Operation is a add operation. If
                                        it is NULL, all devices behind the PC Card
                                        socket are started.
     @param[in,out] NumberOfChildren    The number of child handles. For an add
                                        operation, it is an output parameter.  For
                                        a remove operation, it's an input parameter.
                                        When it contains a non-zero value, children
                                        handles specified in ChildHandleBuffer are
                                        destroyed.  Otherwise, PCI bus driver is
                                        notified to stop managing the controller
                                        handle.
     @param[in,out] ChildHandleBuffer   The buffer which contains the child handles.
                                        For an add operation, it is an output
                                        parameter and contains all newly created
                                        child handles.  For a remove operation, it
                                        contains child handles to be destroyed when
                                        NumberOfChildren contains a non-zero value.
                                        It can be NULL when NumberOfChildren is 0.
                                        It's the caller's responsibility to allocate
                                        and free memory for this buffer.

   @retval EFI_SUCCESS             The handles for the specified device have been
                                   created or destroyed as requested, and for an
                                   add operation, the new handles are returned in
                                   ChildHandleBuffer.
   @retval EFI_INVALID_PARAMETER   Operation is not a legal value.
   @retval EFI_INVALID_PARAMETER   Controller is NULL or not a valid handle.
   @retval EFI_INVALID_PARAMETER   NumberOfChildren is NULL.
   @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is
                                   remove and NumberOfChildren contains a non-zero
                                   value.
   @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is add.
   @retval EFI_OUT_OF_RESOURCES    There are no enough resources to start the
                                   devices.
 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(
   IN     EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  *This,
   IN     EFI_PCI_HOTPLUG_OPERATION         Operation,
   IN     EFI_HANDLE                        Controller,
   IN     EFI_DEVICE_PATH_PROTOCOL          *RemainingDevicePath  OPTIONAL,
   IN OUT UINT8                             *NumberOfChildren,
   IN OUT EFI_HANDLE                        *ChildHandleBuffer
   );

 ///
 /// Provides services to notify PCI bus driver that some events have happened in
 /// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus
 /// driver to create or destroy handles for the PCI-like devices.
 ///
 struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {
   ///
   /// Notify the PCI bus driver that some events have happened in a hot-plug
   /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver
   /// to create or destroy handles for the PCI-like devices. See Section 0 for
   /// a detailed description.
   ///
   EFI_PCI_HOTPLUG_REQUEST_NOTIFY  Notify;
 };

 extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;

 #endif
	/** @file
	Provides services to notify the PCI bus driver that some events have happened
	in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the
	PCI bus driver to create or destroy handles for PCI-like devices.

	A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request
	protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)
	is installed after PCI bus does the enumeration, the PCI bus driver can be
	notified through this protocol. For example, when a 32-bit PC Card is inserted
	into the PC Card socket, the PC Card bus driver can call interface of this
	protocol to notify PCI bus driver to allocate resource and create handles for
	this PC Card.

	The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a
	separate handle when PCI bus driver starts up. There is only one instance in
	the system. Any driver that wants to use this protocol must locate it globally.
	The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,
	for example, PC Card Bus driver, to notify PCI bus driver that an event has
	happened in the hot-plug controller, and the PCI bus driver is requested to
	create (add) or destroy (remove) handles for the specified PCI-like devices.
	For example, when a 32-bit PC Card is inserted, this protocol interface will
	be called with an add operation, and the PCI bus driver will enumerate and
	start the devices inserted; when a 32-bit PC Card is removed, this protocol
	interface will be called with a remove operation, and the PCI bus driver will
	stop the devices and destroy their handles. The existence of this protocol
	represents the capability of the PCI bus driver. If this protocol exists in
	system, it means PCI bus driver is hot-plug capable, thus together with the
	effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,
	the hot-plug capability is not provided.

	Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR>
	This program and the accompanying materials
	are licensed and made available under the terms and conditions of the BSD License
	which accompanies this distribution. The full text of the license may be found at
	http://opensource.org/licenses/bsd-license.php

	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

	@par Revision Reference:
	This Protocol is defined in UEFI Platform Initialization Specification 1.2
	Volume 5: Standards

	**/

	#ifndef __PCI_HOTPLUG_REQUEST_H_
	#define __PCI_HOTPLUG_REQUEST_H_

	///
	/// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
	///
	#define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \
	{ \
	0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \
	}

	///
	/// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
	///
	typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;

	///
	/// Enumeration of PCI hot plug operations
	///
	typedef enum {
	///
	/// The PCI bus driver is requested to create handles for the specified devices.
	/// An array of EFI_HANDLE is returned, with a NULL element marking the end of
	/// the array.
	///
	EfiPciHotPlugRequestAdd,

	///
	/// The PCI bus driver is requested to destroy handles for the specified devices.
	///
	EfiPciHotplugRequestRemove
	} EFI_PCI_HOTPLUG_OPERATION;

	/**
	This function is used to notify PCI bus driver that some events happened in a
	hot-plug controller, and the PCI bus driver is requested to start or stop
	specified PCI-like devices.

	This function allows the PCI bus driver to be notified to act as requested when
	a hot-plug event has happened on the hot-plug controller. Currently, the
	operations include add operation and remove operation. If it is a add operation,
	the PCI bus driver will enumerate, allocate resources for devices behind the
	hot-plug controller, and create handle for the device specified by RemainingDevicePath.
	The RemainingDevicePath is an optional parameter. If it is not NULL, only the
	specified device is started; if it is NULL, all devices behind the hot-plug
	controller are started. The newly created handles of PC Card functions are
	returned in the ChildHandleBuffer, together with the number of child handle in
	NumberOfChildren. If it is a remove operation, when NumberOfChildren contains
	a non-zero value, child handles specified in ChildHandleBuffer are stopped and
	destroyed; otherwise, PCI bus driver is notified to stop managing the controller
	handle.

	@param[in] This A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
	instance.
	@param[in] Operation The operation the PCI bus driver is requested
	to make.
	@param[in] Controller The handle of the hot-plug controller.
	@param[in] RemainingDevicePath The remaining device path for the PCI-like
	hot-plug device. It only contains device
	path nodes behind the hot-plug controller.
	It is an optional parameter and only valid
	when the Operation is a add operation. If
	it is NULL, all devices behind the PC Card
	socket are started.
	@param[in,out] NumberOfChildren The number of child handles. For an add
	operation, it is an output parameter. For
	a remove operation, it's an input parameter.
	When it contains a non-zero value, children
	handles specified in ChildHandleBuffer are
	destroyed. Otherwise, PCI bus driver is
	notified to stop managing the controller
	handle.
	@param[in,out] ChildHandleBuffer The buffer which contains the child handles.
	For an add operation, it is an output
	parameter and contains all newly created
	child handles. For a remove operation, it
	contains child handles to be destroyed when
	NumberOfChildren contains a non-zero value.
	It can be NULL when NumberOfChildren is 0.
	It's the caller's responsibility to allocate
	and free memory for this buffer.

	@retval EFI_SUCCESS The handles for the specified device have been
	created or destroyed as requested, and for an
	add operation, the new handles are returned in
	ChildHandleBuffer.
	@retval EFI_INVALID_PARAMETER Operation is not a legal value.
	@retval EFI_INVALID_PARAMETER Controller is NULL or not a valid handle.
	@retval EFI_INVALID_PARAMETER NumberOfChildren is NULL.
	@retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is
	remove and NumberOfChildren contains a non-zero
	value.
	@retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is add.
	@retval EFI_OUT_OF_RESOURCES There are no enough resources to start the
	devices.
	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(
	IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL *This,
	IN EFI_PCI_HOTPLUG_OPERATION Operation,
	IN EFI_HANDLE Controller,
	IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL,
	IN OUT UINT8 *NumberOfChildren,
	IN OUT EFI_HANDLE *ChildHandleBuffer
	);

	///
	/// Provides services to notify PCI bus driver that some events have happened in
	/// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus
	/// driver to create or destroy handles for the PCI-like devices.
	///
	struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {
	///
	/// Notify the PCI bus driver that some events have happened in a hot-plug
	/// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver
	/// to create or destroy handles for the PCI-like devices. See Section 0 for
	/// a detailed description.
	///
	EFI_PCI_HOTPLUG_REQUEST_NOTIFY Notify;
	};

	extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;

	#endif