MdePkg/Include/Protocol/PciHotPlugInit.h

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