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