MdeModulePkg/Bus/Pci/PciBusDxe/PciDeviceSupport.h

   1 /** @file
   2   Supporting functions declaration for PCI devices management.
   3
   4 Copyright (c) 2006 - 2009, Intel Corporation
   5 All rights reserved. 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