1 /** @file 2 Supporting functions declaration for PCI devices management. 3 4 Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef _EFI_PCI_DEVICE_SUPPORT_H_ 16 #define _EFI_PCI_DEVICE_SUPPORT_H_ 17 18 /** 19 Initialize the PCI devices pool. 20 21 **/ 22 VOID 23 InitializePciDevicePool ( 24 VOID 25 ); 26 27 /** 28 Insert a root bridge into PCI device pool. 29 30 @param RootBridge A pointer to the PCI_IO_DEVICE. 31 32 **/ 33 VOID 34 InsertRootBridge ( 35 IN PCI_IO_DEVICE *RootBridge 36 ); 37 38 /** 39 This function is used to insert a PCI device node under 40 a bridge. 41 42 @param Bridge The PCI bridge. 43 @param PciDeviceNode The PCI device needs inserting. 44 45 **/ 46 VOID 47 InsertPciDevice ( 48 IN PCI_IO_DEVICE *Bridge, 49 IN PCI_IO_DEVICE *PciDeviceNode 50 ); 51 52 /** 53 Destroy root bridge and remove it from deivce tree. 54 55 @param RootBridge The bridge want to be removed. 56 57 **/ 58 VOID 59 DestroyRootBridge ( 60 IN PCI_IO_DEVICE *RootBridge 61 ); 62 63 /** 64 Destroy all the pci device node under the bridge. 65 Bridge itself is not included. 66 67 @param Bridge A pointer to the PCI_IO_DEVICE. 68 69 **/ 70 VOID 71 DestroyPciDeviceTree ( 72 IN PCI_IO_DEVICE *Bridge 73 ); 74 75 /** 76 Destroy all device nodes under the root bridge 77 specified by Controller. 78 79 The root bridge itself is also included. 80 81 @param Controller Root bridge handle. 82 83 @retval EFI_SUCCESS Destory all devcie nodes successfully. 84 @retval EFI_NOT_FOUND Cannot find any PCI device under specified 85 root bridge. 86 87 **/ 88 EFI_STATUS 89 DestroyRootBridgeByHandle ( 90 IN EFI_HANDLE Controller 91 ); 92 93 /** 94 This function registers the PCI IO device. 95 96 It creates a handle for this PCI IO device (if the handle does not exist), attaches 97 appropriate protocols onto the handle, does necessary initialization, and sets up 98 parent/child relationship with its bus controller. 99 100 @param Controller An EFI handle for the PCI bus controller. 101 @param PciIoDevice A PCI_IO_DEVICE pointer to the PCI IO device to be registered. 102 @param Handle A pointer to hold the returned EFI handle for the PCI IO device. 103 104 @retval EFI_SUCCESS The PCI device is successfully registered. 105 @retval other An error occurred when registering the PCI device. 106 107 **/ 108 EFI_STATUS 109 RegisterPciDevice ( 110 IN EFI_HANDLE Controller, 111 IN PCI_IO_DEVICE *PciIoDevice, 112 OUT EFI_HANDLE *Handle OPTIONAL 113 ); 114 115 /** 116 This function is used to remove the whole PCI devices on the specified bridge from 117 the root bridge. 118 119 @param RootBridgeHandle The root bridge device handle. 120 @param Bridge The bridge device to be removed. 121 122 **/ 123 VOID 124 RemoveAllPciDeviceOnBridge ( 125 EFI_HANDLE RootBridgeHandle, 126 PCI_IO_DEVICE *Bridge 127 ); 128 129 /** 130 This function is used to de-register the PCI IO device. 131 132 That includes un-installing PciIo protocol from the specified PCI 133 device handle. 134 135 @param Controller An EFI handle for the PCI bus controller. 136 @param Handle PCI device handle. 137 138 @retval EFI_SUCCESS The PCI device is successfully de-registered. 139 @retval other An error occurred when de-registering the PCI device. 140 141 **/ 142 EFI_STATUS 143 DeRegisterPciDevice ( 144 IN EFI_HANDLE Controller, 145 IN EFI_HANDLE Handle 146 ); 147 148 /** 149 Start to manage the PCI device on the specified root bridge or PCI-PCI Bridge. 150 151 @param Controller The root bridge handle. 152 @param RootBridge A pointer to the PCI_IO_DEVICE. 153 @param RemainingDevicePath A pointer to the EFI_DEVICE_PATH_PROTOCOL. 154 @param NumberOfChildren Children number. 155 @param ChildHandleBuffer A pointer to the child handle buffer. 156 157 @retval EFI_NOT_READY Device is not allocated. 158 @retval EFI_UNSUPPORTED Device only support PCI-PCI bridge. 159 @retval EFI_NOT_FOUND Can not find the specific device. 160 @retval EFI_SUCCESS Success to start Pci devices on bridge. 161 162 **/ 163 EFI_STATUS 164 StartPciDevicesOnBridge ( 165 IN EFI_HANDLE Controller, 166 IN PCI_IO_DEVICE *RootBridge, 167 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath, 168 IN OUT UINT8 *NumberOfChildren, 169 IN OUT EFI_HANDLE *ChildHandleBuffer 170 ); 171 172 /** 173 Start to manage all the PCI devices it found previously under 174 the entire host bridge. 175 176 @param Controller The root bridge handle. 177 178 @retval EFI_NOT_READY Device is not allocated. 179 @retval EFI_SUCCESS Success to start Pci device on host bridge. 180 181 **/ 182 EFI_STATUS 183 StartPciDevices ( 184 IN EFI_HANDLE Controller 185 ); 186 187 /** 188 Create root bridge device. 189 190 @param RootBridgeHandle Specified root bridge hanle. 191 192 @return The crated root bridge device instance, NULL means no 193 root bridge device instance created. 194 195 **/ 196 PCI_IO_DEVICE * 197 CreateRootBridge ( 198 IN EFI_HANDLE RootBridgeHandle 199 ); 200 201 /** 202 Get root bridge device instance by specific root bridge handle. 203 204 @param RootBridgeHandle Given root bridge handle. 205 206 @return The root bridge device instance, NULL means no root bridge 207 device instance found. 208 209 **/ 210 PCI_IO_DEVICE * 211 GetRootBridgeByHandle ( 212 EFI_HANDLE RootBridgeHandle 213 ); 214 215 216 /** 217 Judege whether Pci device existed. 218 219 @param Bridge Parent bridege instance. 220 @param PciIoDevice Device instance. 221 222 @retval TRUE Pci device existed. 223 @retval FALSE Pci device did not exist. 224 225 **/ 226 BOOLEAN 227 PciDeviceExisted ( 228 IN PCI_IO_DEVICE *Bridge, 229 IN PCI_IO_DEVICE *PciIoDevice 230 ); 231 232 /** 233 Get the active VGA device on the same segment. 234 235 @param VgaDevice PCI IO instance for the VGA device. 236 237 @return The active VGA device on the same segment. 238 239 **/ 240 PCI_IO_DEVICE * 241 ActiveVGADeviceOnTheSameSegment ( 242 IN PCI_IO_DEVICE *VgaDevice 243 ); 244 245 /** 246 Get the active VGA device on the root bridge. 247 248 @param RootBridge PCI IO instance for the root bridge. 249 250 @return The active VGA device. 251 252 **/ 253 PCI_IO_DEVICE * 254 ActiveVGADeviceOnTheRootBridge ( 255 IN PCI_IO_DEVICE *RootBridge 256 ); 257 258 /** 259 Get HPC PCI address according to its device path. 260 261 @param RootBridge Root bridege Io instance. 262 @param RemainingDevicePath Given searching device path. 263 @param PciAddress Buffer holding searched result. 264 265 @retval EFI_SUCCESS PCI address was stored in PciAddress. 266 @retval EFI_NOT_FOUND Can not find the specific device path. 267 268 **/ 269 EFI_STATUS 270 GetHpcPciAddressFromRootBridge ( 271 IN PCI_IO_DEVICE *RootBridge, 272 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath, 273 OUT UINT64 *PciAddress 274 ); 275 276 /** 277 Destroy a pci device node. 278 279 All direct or indirect allocated resource for this node will be freed. 280 281 @param PciIoDevice A pointer to the PCI_IO_DEVICE to be destoried. 282 283 **/ 284 VOID 285 FreePciDevice ( 286 IN PCI_IO_DEVICE *PciIoDevice 287 ); 288 289 #endif 290