IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h

   1 /** @file
   2   This file declares EFI PCI Hot Plug Init Protocol.
   3   This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and
   4   the buses that they control. This protocol also provides information regarding resource padding.
   5
   6   Copyright (c) 2007 - 2009, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15   @par Revision Reference:
  16   This protocol is defined in Framework of EFI Hot Plug Pci Initialization Protocol Spec
  17   Version 0.9
  18
  19 **/
  20
  21 #ifndef _EFI_PCI_HOT_PLUG_INIT_H_
  22 #define _EFI_PCI_HOT_PLUG_INIT_H_
  23
  24 #include <PiDxe.h>
  25
  26 ///
  27 /// Global ID for the PCI Hot Plug Protocol
  28 ///
  29 #define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \
  30   { \
  31     0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \
  32   }
  33
  34 typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;
  35
  36 ///
  37 /// Current state of an HPC
  38 ///
  39 typedef UINT16 EFI_HPC_STATE;
  40
  41 ///
  42 /// The HPC initialization function was called and the HPC completed
  43 /// initialization, but it was not enabled for some reason. The HPC may be
  44 /// disabled in hardware, or it may be disabled due to user preferences,
  45 /// hardware failure, or other reasons. No resource padding is required.
  46 ///
  47 #define  EFI_HPC_STATE_INITIALIZED    0x01
  48
  49 ///
  50 /// The HPC initialization function was called, the HPC completed
  51 /// initialization, and it was enabled. Resource padding is required.
  52 ///
  53 #define  EFI_HPC_STATE_ENABLED        0x02
  54
  55 ///
  56 /// Location definition for PCI Hot Plug Controller
  57 ///
  58 typedef struct{
  59   ///
  60   /// The device path to the Root HPC
  61   ///
  62   EFI_DEVICE_PATH_PROTOCOL  *HpcDevicePath;
  63   ///
  64   /// The device path to the Hot Plug Bus (HPB) that is controlled by
  65   /// the root HPC.
  66   ///
  67   EFI_DEVICE_PATH_PROTOCOL  *HpbDevicePath;
  68 } EFI_HPC_LOCATION;
  69
  70
  71 ///
  72 /// Describes how resource padding should be applied
  73 ///
  74 typedef enum{
  75   EfiPaddingPciBus,
  76   EfiPaddingPciRootBridge
  77 } EFI_HPC_PADDING_ATTRIBUTES;
  78
  79 /**
  80   Returns a list of root Hot Plug Controllers (HPCs) that require initialization
  81   during the boot process.
  82
  83   This procedure returns a list of root HPCs. The PCI bus driver must initialize these controllers
  84   during the boot process. The PCI bus driver may or may not be able to detect these HPCs. If the
  85   platform includes a PCI-to-CardBus bridge, it can be included in this list if it requires initialization.
  86   The HpcList must be self consistent. An HPC cannot control any of its parent buses. Only one HPC
  87   can control a PCI bus. Because this list includes only root HPCs, no HPC in the list can be a child of
  88   another HPC. This policy must be enforced by the EFI_PCI_HOT_PLUG_INIT_PROTOCOL.
  89   The PCI bus driver may not check for such invalid conditions.
  90   The callee allocates the buffer HpcList
  91
  92   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
  93   @param  HpcCount              The number of root HPCs that were returned.
  94   @param  HpcList               The list of root HPCs. HpcCount defines the number of
  95                                 elements in this list.
  96
  97   @retval EFI_SUCCESS           HpcList was returned.
  98   @retval EFI_OUT_OF_RESOURCES  HpcList was not returned due to insufficient resources.
  99   @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *EFI_GET_ROOT_HPC_LIST)(
 105   IN  EFI_PCI_HOT_PLUG_INIT_PROTOCOL  *This,
 106   OUT UINTN                           *HpcCount,
 107   OUT EFI_HPC_LOCATION                **HpcList
 108 );
 109
 110 /**
 111   Initializes one root Hot Plug Controller (HPC). This process may causes
 112   initialization of its subordinate buses.
 113
 114   This function initializes the specified HPC. At the end of initialization, the hot-plug slots or sockets
 115   (controlled by this HPC) are powered and are connected to the bus. All the necessary registers in the
 116   HPC are set up. For a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set up
 117   are defined in the PCI Standard Hot Plug Controller and Subsystem Specification.
 118
 119   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 120   @param  HpcDevicePath         The device path to the HPC that is being initialized.
 121   @param  HpcPciAddress         The address of the HPC function on the PCI bus.
 122   @param  Event                 The event that should be signaled when the HPC initialization
 123                                 is complete.
 124   @param  HpcState              The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED
 125                                 or EFI_HPC_STATE_ENABLED.
 126
 127   @retval EFI_SUCCESS           If Event is NULL, the specific HPC was successfully
 128                                 initialized. If Event is not NULL, Event will be signaled at a later time
 129                                 when initialization is complete.
 130   @retval EFI_UNSUPPORTED       This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL
 131                                 does not support the specified HPC.
 132   @retval EFI_OUT_OF_RESOURCES  Initialization failed due to insufficient
 133                                 resources.
 134   @retval EFI_INVALID_PARAMETER HpcState is NULL.
 135
 136 **/
 137 typedef
 138 EFI_STATUS
 139 (EFIAPI *EFI_INITIALIZE_ROOT_HPC)(
 140   IN  EFI_PCI_HOT_PLUG_INIT_PROTOCOL    *This,
 141   IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,
 142   IN  UINT64                            HpcPciAddress,
 143   IN  EFI_EVENT                         Event, OPTIONAL
 144   OUT EFI_HPC_STATE                     *HpcState
 145 );
 146
 147 /**
 148   Returns the resource padding that is required by the PCI bus that is controlled
 149   by the specified Hot Plug Controller (HPC).
 150
 151   This function returns the resource padding that is required by the PCI bus that is controlled by the
 152   specified HPC. This member function is called for all the root HPCs and nonroot HPCs that are
 153   detected by the PCI bus enumerator. This function will be called before PCI resource allocation is
 154   completed. This function must be called after all the root HPCs, with the possible exception of a
 155   PCI-to-CardBus bridge, have completed initialization.
 156
 157   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 158   @param  HpcDevicePath         The device path to the HPC.
 159   @param  HpcPciAddress         The address of the HPC function on the PCI bus.
 160   @param  HpcState              The state of the HPC hardware.
 161   @param  Padding               The amount of resource padding that is required by the
 162                                 PCI bus under the control of the specified HPC.
 163   @param  Attributes            Describes how padding is accounted for. The padding
 164                                 is returned in the form of ACPI 2.0 resource descriptors.
 165
 166   @retval EFI_SUCCESS           The resource padding was successfully returned.
 167   @retval EFI_UNSUPPORTED       This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
 168                                 does not support the specified HPC.
 169   @retval EFI_NOT_READY         This function was called before HPC initialization is complete.
 170   @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.
 171   @retval EFI_OUT_OF_RESOURCES  ACPI 2.0 resource descriptors for Padding
 172                                 cannot be allocated due to insufficient resources.
 173
 174 **/
 175 typedef
 176 EFI_STATUS
 177 (EFIAPI *EFI_GET_HOT_PLUG_PADDING)(
 178   IN  EFI_PCI_HOT_PLUG_INIT_PROTOCOL    *This,
 179   IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,
 180   IN  UINT64                            HpcPciAddress,
 181   OUT EFI_HPC_STATE                     *HpcState,
 182   OUT VOID                              **Padding,
 183   OUT EFI_HPC_PADDING_ATTRIBUTES        *Attributes
 184 );
 185
 186
 187 //
 188 // Prototypes for the PCI Hot Plug Init Protocol
 189 //
 190
 191 ///
 192 /// This protocol provides the necessary functionality to initialize the
 193 /// Hot Plug Controllers (HPCs) and the buses that they control. This protocol
 194 /// also provides information regarding resource padding.
 195 ///
 196 struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {
 197   ///
 198   /// Returns a list of root HPCs and the buses that they control.
 199   ///
 200   EFI_GET_ROOT_HPC_LIST                                  GetRootHpcList;
 201
 202   ///
 203   /// Initializes the specified root HPC.
 204   ///
 205   EFI_INITIALIZE_ROOT_HPC                                InitializeRootHpc;
 206
 207   ///
 208   /// Returns the resource padding that is required by the HPC.
 209   ///
 210   EFI_GET_HOT_PLUG_PADDING                               GetResourcePadding;
 211 };
 212
 213 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;
 214
 215 #endif