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   { 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } }
  31
  32
  33 typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;
  34
  35 ///
  36 /// Current state of an HPC
  37 ///
  38 typedef UINT16 EFI_HPC_STATE;
  39
  40 ///
  41 /// The HPC initialization function was called and the HPC completed
  42 /// initialization, but it was not enabled for some reason. The HPC may be
  43 /// disabled in hardware, or it may be disabled due to user preferences,
  44 /// hardware failure, or other reasons. No resource padding is required.
  45 ///
  46 #define  EFI_HPC_STATE_INITIALIZED    0x01
  47
  48 ///
  49 /// The HPC initialization function was called, the HPC completed
  50 /// initialization, and it was enabled. Resource padding is required.
  51 ///
  52 #define  EFI_HPC_STATE_ENABLED        0x02
  53
  54 ///
  55 /// Location definition for PCI Hot Plug Controller
  56 ///
  57 typedef struct{
  58   ///
  59   /// The device path to the Root HPC
  60   ///
  61   EFI_DEVICE_PATH_PROTOCOL  *HpcDevicePath;
  62   ///
  63   /// The device path to the Hot Plug Bus (HPB) that is controlled by
  64   /// the root HPC.
  65   ///
  66   EFI_DEVICE_PATH_PROTOCOL  *HpbDevicePath;
  67 } EFI_HPC_LOCATION;
  68
  69
  70 typedef enum{
  71   EfiPaddingPciBus,
  72   EfiPaddingPciRootBridge
  73 } EFI_HPC_PADDING_ATTRIBUTES;
  74
  75 /**
  76   Returns a list of root Hot Plug Controllers (HPCs) that require initialization
  77   during the boot process.
  78
  79   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
  80   @param  HpcCount              The number of root HPCs that were returned.
  81   @param  HpcList               The list of root HPCs. HpcCount defines the number of
  82                                 elements in this list.
  83
  84   @retval EFI_SUCCESS           HpcList was returned.
  85   @retval EFI_OUT_OF_RESOURCES  HpcList was not returned due to insufficient resources.
  86   @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.
  87
  88 **/
  89 typedef
  90 EFI_STATUS
  91 (EFIAPI *EFI_GET_ROOT_HPC_LIST)(
  92   IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL   *This,
  93   OUT UINTN                           *HpcCount,
  94   OUT EFI_HPC_LOCATION                **HpcList
  95 );
  96
  97 /**
  98   Initializes one root Hot Plug Controller (HPC). This process may causes
  99   initialization of its subordinate buses.
 100
 101   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 102   @param  HpcDevicePath         The device path to the HPC that is being initialized.
 103   @param  HpcPciAddress         The address of the HPC function on the PCI bus.
 104   @param  Event                 The event that should be signaled when the HPC initialization
 105                                 is complete.
 106   @param  HpcState              The state of the HPC hardware.
 107
 108   @retval EFI_SUCCESS           If Event is NULL, the specific HPC was successfully
 109                                 initialized. If Event is not NULL, Event will be signaled at a later time
 110                                 when initialization is complete.
 111   @retval EFI_UNSUPPORTED       This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL
 112                                 does not support the specified HPC.
 113   @retval EFI_OUT_OF_RESOURCES  Initialization failed due to insufficient
 114                                 resources.
 115   @retval EFI_INVALID_PARAMETER HpcState is NULL.
 116
 117 **/
 118 typedef
 119 EFI_STATUS
 120 (EFIAPI *EFI_INITIALIZE_ROOT_HPC)(
 121   IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL     *This,
 122   IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,
 123   IN  UINT64                            HpcPciAddress,
 124   IN  EFI_EVENT                         Event, OPTIONAL
 125   OUT EFI_HPC_STATE                     *HpcState
 126 );
 127
 128 /**
 129   Returns the resource padding that is required by the PCI bus that is controlled
 130   by the specified Hot Plug Controller (HPC).
 131
 132   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
 133   @param  HpcDevicePath         The device path to the HPC.
 134   @param  HpcPciAddress         The address of the HPC function on the PCI bus.
 135   @param  HpcState              The state of the HPC hardware.
 136   @param  Padding               The amount of resource padding that is required by the
 137                                 PCI bus under the control of the specified HPC.
 138   @param  Attributes            Describes how padding is accounted for. The padding
 139                                 is returned in the form of ACPI 2.0 resource descriptors.
 140
 141   @retval EFI_SUCCESS           The resource padding was successfully returned.
 142   @retval EFI_UNSUPPORTED       This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
 143                                 does not support the specified HPC.
 144   @retval EFI_NOT_READY         This function was called before HPC initialization is complete.
 145   @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.
 146   @retval EFI_OUT_OF_RESOURCES  ACPI 2.0 resource descriptors for Padding
 147                                 cannot be allocated due to insufficient resources.
 148
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_GET_PCI_HOT_PLUG_PADDING)(
 153   IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL     *This,
 154   IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,
 155   IN  UINT64                            HpcPciAddress,
 156   OUT EFI_HPC_STATE                     *HpcState,
 157   OUT VOID                              **Padding,
 158   OUT EFI_HPC_PADDING_ATTRIBUTES        *Attributes
 159 );
 160
 161
 162 //
 163 // Prototypes for the PCI Hot Plug Init Protocol
 164 //
 165
 166 ///
 167 /// This protocol provides the necessary functionality to initialize the
 168 /// Hot Plug Controllers (HPCs) and the buses that they control. This protocol
 169 /// also provides information regarding resource padding.
 170 ///
 171 struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {
 172   ///
 173   /// Returns a list of root HPCs and the buses that they control.
 174   ///
 175   EFI_GET_ROOT_HPC_LIST                                  GetRootHpcList;
 176
 177   ///
 178   /// Initializes the specified root HPC.
 179   ///
 180   EFI_INITIALIZE_ROOT_HPC                                InitializeRootHpc;
 181
 182   ///
 183   /// Returns the resource padding that is required by the HPC.
 184   ///
 185   EFI_GET_PCI_HOT_PLUG_PADDING                           GetResourcePadding;
 186 };
 187
 188 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;
 189
 190 #endif