MdeModulePkg/Bus/Pci/PciBusDxe/PciDeviceSupport.h

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