MdePkg/Include/Protocol/PciHotPlugInit.h

   1 /** @file
   2   This file declares EFI PCI Hot Plug Init Protocol.
   3
   4   This protocol provides the necessary functionality to initialize the Hot Plug
   5   Controllers (HPCs) and the buses that they control. This protocol also provides
   6   information regarding resource padding.
   7
   8   @par Note:
   9     This protocol is required only on platforms that support one or more PCI Hot
  10     Plug* slots or CardBus sockets.
  11
  12   The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator
  13   to properly initialize the HPCs and CardBus sockets that require initialization.
  14   The HPC initialization takes place before the PCI enumeration process is complete.
  15   There cannot be more than one instance of this protocol in a system. This protocol
  16   is installed on its own separate handle.
  17
  18   Because the system may include multiple HPCs, one instance of this protocol
  19   should represent all of them. The protocol functions use the device path of
  20   the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it
  21   will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc()
  22   is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC
  23   and continue the enumeration process. If the HPC is not initialized, the devices
  24   that it controls may not be initialized, and no resource padding will be provided.
  25
  26   From the standpoint of the PCI bus enumerator, HPCs are divided into the following
  27   two classes:
  28
  29     - Root HPC:
  30         These HPCs must be initialized by calling InitializeRootHpc() during the
  31         enumeration process. These HPCs will also require resource padding. The
  32         platform code must have a priori knowledge of these devices and must know
  33         how to initialize them. There may not be any way to access their PCI
  34         configuration space before the PCI enumerator programs all the upstream
  35         bridges and thus enables the path to these devices. The PCI bus enumerator
  36         is responsible for determining the PCI bus address of the HPC before it
  37         calls InitializeRootHpc().
  38     - Nonroot HPC:
  39         These HPCs will not need explicit initialization during enumeration process.
  40         These HPCs will require resource padding. The platform code does not have
  41         to have a priori knowledge of these devices.
  42
  43   Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR>
  44   This program and the accompanying materials
  45   are licensed and made available under the terms and conditions of the BSD License
  46   which accompanies this distribution.  The full text of the license may be found at
  47   http://opensource.org/licenses/bsd-license.php
  48
  49   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  50   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  51
  52   @par Revision Reference:
  53   This Protocol is defined in UEFI Platform Initialization Specification 1.2
  54   Volume 5: Standards
  55
  56 **/
  57
  58 #ifndef _EFI_PCI_HOT_PLUG_INIT_H_
  59 #define _EFI_PCI_HOT_PLUG_INIT_H_
  60
  61 ///
  62 /// Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
  63 ///
  64 #define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \
  65   { \
  66     0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \
  67   }
  68
  69 ///
  70 /// Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL
  71 ///
  72 typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;
  73
  74 ///
  75 /// Describes the current state of an HPC
  76 ///
  77 typedef UINT16 EFI_HPC_STATE;
  78
  79 ///
  80 /// The HPC initialization function was called and the HPC completed
  81 /// initialization, but it was not enabled for some reason. The HPC may be
  82 /// disabled in hardware, or it may be disabled due to user preferences,
  83 /// hardware failure, or other reasons. No resource padding is required.
  84 ///
  85 #define  EFI_HPC_STATE_INITIALIZED    0x01
  86
  87 ///
  88 /// The HPC initialization function was called, the HPC completed
  89 /// initialization, and it was enabled. Resource padding is required.
  90 ///
  91 #define  EFI_HPC_STATE_ENABLED        0x02
  92
  93 ///
  94 /// Location definition for PCI Hot Plug Controller
  95 ///
  96 typedef struct{
  97   ///
  98   ///
  99   /// The device path to the root HPC. An HPC cannot control its parent buses.
 100   /// The PCI bus driver requires this information so that it can pass the
 101   /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding()
 102   /// functions.
 103   ///
 104   EFI_DEVICE_PATH_PROTOCOL  *HpcDevicePath;
 105   ///
 106   /// The device path to the Hot Plug Bus (HPB) that is controlled by the root
 107   /// HPC. The PCI bus driver uses this information to check if a particular PCI
 108   /// bus has hot-plug slots.  The device path of a PCI bus is the same as the
 109   /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs)
 110   /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath.
 111   ///
 112   EFI_DEVICE_PATH_PROTOCOL  *HpbDevicePath;
 113 } EFI_HPC_LOCATION;
 114
 115 ///
 116 /// Describes how resource padding should be applied
 117 ///
 118 typedef enum {
 119   ///
 120   /// Apply the padding at a PCI bus level. In other words, the resources
 121   /// that are allocated to the bus containing hot-plug slots are padded by
 122   /// the specified amount. If the hot-plug bus is behind a PCI-to-PCI
 123   /// bridge, the PCI-to-PCI bridge apertures will indicate the padding
 124   ///
 125   EfiPaddingPciBus,
 126   ///
 127   /// Apply the padding at a PCI root bridge level. If a PCI root bridge
 128   /// includes more than one hot-plug bus, the resource padding requests
 129   /// for these buses are added together and the resources that are
 130   /// allocated to the root bridge are padded by the specified amount. This
 131   /// strategy may reduce the total amount of padding, but requires
 132   /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug
 133   /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge
 134   /// apertures do not indicate the padding for that bus.
 135   ///
 136   EfiPaddingPciRootBridge
 137 } EFI_HPC_PADDING_ATTRIBUTES;
 138
 139 /**
 140   Returns a list of root Hot Plug Controllers (HPCs) that require initialization
 141   during the boot process.
 142
 143   This procedure returns a list of root HPCs. The PCI bus driver must initialize
 144   these controllers during the boot process. The PCI bus driver may or may not be
 145   able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it
 146   can be included in this list if it requires initialization.  The HpcList must be
 147   self consistent. An HPC cannot control any of its parent buses. Only one HPC can
 148   control a PCI bus. Because this list includes only root HPCs, no HPC in the list
 149   can be a child of another HPC. This policy must be enforced by the
 150   EFI_PCI_HOT_PLUG_INIT_PROTOCOL.   The PCI bus driver may not check for such
 151   invalid conditions.  The callee allocates the buffer HpcList
 152
 153   @param[in]  This       Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 154   @param[out] HpcCount   The number of root HPCs that were returned.
 155   @param[out] HpcList    The list of root HPCs. HpcCount defines the number of
 156                          elements in this list.
 157
 158   @retval EFI_SUCCESS             HpcList was returned.
 159   @retval EFI_OUT_OF_RESOURCES    HpcList was not returned due to insufficient
 160                                   resources.
 161   @retval EFI_INVALID_PARAMETER   HpcCount is NULL or HpcList is NULL.
 162
 163 **/
 164 typedef
 165 EFI_STATUS
 166 (EFIAPI *EFI_GET_ROOT_HPC_LIST)(
 167   IN  EFI_PCI_HOT_PLUG_INIT_PROTOCOL  *This,
 168   OUT UINTN                           *HpcCount,
 169   OUT EFI_HPC_LOCATION                **HpcList
 170   );
 171
 172 /**
 173   Initializes one root Hot Plug Controller (HPC). This process may causes
 174   initialization of its subordinate buses.
 175
 176   This function initializes the specified HPC. At the end of initialization,
 177   the hot-plug slots or sockets (controlled by this HPC) are powered and are
 178   connected to the bus. All the necessary registers in the HPC are set up. For
 179   a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set
 180   up are defined in the PCI Standard Hot Plug Controller and Subsystem
 181   Specification.
 182
 183   @param[in]  This            Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 184   @param[in]  HpcDevicePath   The device path to the HPC that is being initialized.
 185   @param[in]  HpcPciAddress   The address of the HPC function on the PCI bus.
 186   @param[in]  Event           The event that should be signaled when the HPC
 187                               initialization is complete.  Set to NULL if the
 188                               caller wants to wait until the entire initialization
 189                               process is complete.
 190   @param[out] HpcState        The state of the HPC hardware. The state is
 191                               EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED.
 192
 193   @retval EFI_SUCCESS             If Event is NULL, the specific HPC was successfully
 194                                   initialized. If Event is not NULL, Event will be
 195                                   signaled at a later time when initialization is complete.
 196   @retval EFI_UNSUPPORTED         This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL
 197                                   does not support the specified HPC.
 198   @retval EFI_OUT_OF_RESOURCES    Initialization failed due to insufficient
 199                                   resources.
 200   @retval EFI_INVALID_PARAMETER   HpcState is NULL.
 201
 202 **/
 203 typedef
 204 EFI_STATUS
 205 (EFIAPI *EFI_INITIALIZE_ROOT_HPC)(
 206   IN  EFI_PCI_HOT_PLUG_INIT_PROTOCOL  *This,
 207   IN  EFI_DEVICE_PATH_PROTOCOL        *HpcDevicePath,
 208   IN  UINT64                          HpcPciAddress,
 209   IN  EFI_EVENT                       Event,           OPTIONAL
 210   OUT EFI_HPC_STATE                   *HpcState
 211   );
 212
 213 /**
 214   Returns the resource padding that is required by the PCI bus that is controlled
 215   by the specified Hot Plug Controller (HPC).
 216
 217   This function returns the resource padding that is required by the PCI bus that
 218   is controlled by the specified HPC. This member function is called for all the
 219   root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This
 220   function will be called before PCI resource allocation is completed. This function
 221   must be called after all the root HPCs, with the possible exception of a
 222   PCI-to-CardBus bridge, have completed initialization.
 223
 224   @param[in]  This            Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 225   @param[in]  HpcDevicePath   The device path to the HPC.
 226   @param[in]  HpcPciAddress   The address of the HPC function on the PCI bus.
 227   @param[in]  HpcState        The state of the HPC hardware.
 228   @param[out] Padding         The amount of resource padding that is required by the
 229                               PCI bus under the control of the specified HPC.
 230   @param[out] Attributes      Describes how padding is accounted for. The padding
 231                               is returned in the form of ACPI 2.0 resource descriptors.
 232
 233   @retval EFI_SUCCESS             The resource padding was successfully returned.
 234   @retval EFI_UNSUPPORTED         This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
 235                                   does not support the specified HPC.
 236   @retval EFI_NOT_READY           This function was called before HPC initialization
 237                                   is complete.
 238   @retval EFI_INVALID_PARAMETER   HpcState or Padding or Attributes is NULL.
 239   @retval EFI_OUT_OF_RESOURCES    ACPI 2.0 resource descriptors for Padding
 240                                   cannot be allocated due to insufficient resources.
 241
 242 **/
 243 typedef
 244 EFI_STATUS
 245 (EFIAPI *EFI_GET_HOT_PLUG_PADDING)(
 246   IN  EFI_PCI_HOT_PLUG_INIT_PROTOCOL  *This,
 247   IN  EFI_DEVICE_PATH_PROTOCOL        *HpcDevicePath,
 248   IN  UINT64                          HpcPciAddress,
 249   OUT EFI_HPC_STATE                   *HpcState,
 250   OUT VOID                            **Padding,
 251   OUT EFI_HPC_PADDING_ATTRIBUTES      *Attributes
 252   );
 253
 254 ///
 255 /// This protocol provides the necessary functionality to initialize the
 256 /// Hot Plug Controllers (HPCs) and the buses that they control. This protocol
 257 /// also provides information regarding resource padding.
 258 ///
 259 struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {
 260   ///
 261   /// Returns a list of root HPCs and the buses that they control.
 262   ///
 263   EFI_GET_ROOT_HPC_LIST     GetRootHpcList;
 264
 265   ///
 266   /// Initializes the specified root HPC.
 267   ///
 268   EFI_INITIALIZE_ROOT_HPC   InitializeRootHpc;
 269
 270   ///
 271   /// Returns the resource padding that is required by the HPC.
 272   ///
 273   EFI_GET_HOT_PLUG_PADDING  GetResourcePadding;
 274 };
 275
 276 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;
 277
 278 #endif