--- /dev/null
+/** @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 - 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 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
projects / mirror_edk2.git / blobdiff