IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h

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