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