MdePkg/Include/Protocol/PciHotPlugInit.h File Reference


Data Structures

struct  EFI_HPC_LOCATION
struct  _EFI_PCI_HOT_PLUG_INIT_PROTOCOL

Defines

#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID
#define EFI_HPC_STATE_INITIALIZED   0x01
#define EFI_HPC_STATE_ENABLED   0x02

Typedefs

typedef struct
_EFI_PCI_HOT_PLUG_INIT_PROTOCOL 
EFI_PCI_HOT_PLUG_INIT_PROTOCOL
typedef UINT16 EFI_HPC_STATE
typedef EFI_STATUS(EFIAPI * EFI_GET_ROOT_HPC_LIST )(IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, OUT UINTN *HpcCount, OUT EFI_HPC_LOCATION **HpcList)
typedef EFI_STATUS(EFIAPI * EFI_INITIALIZE_ROOT_HPC )(IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, IN UINT64 HpcPciAddress, IN EFI_EVENT Event, OUT EFI_HPC_STATE *HpcState)
typedef EFI_STATUS(EFIAPI * EFI_GET_HOT_PLUG_PADDING )(IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, IN UINT64 HpcPciAddress, OUT EFI_HPC_STATE *HpcState, OUT VOID **Padding, OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes)

Enumerations

enum  EFI_HPC_PADDING_ATTRIBUTES { EfiPaddingPciBus, EfiPaddingPciRootBridge }

Variables

EFI_GUID gEfiPciHotPlugInitProtocolGuid

Detailed Description

This file declares EFI PCI Hot Plug Init Protocol.

This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and the buses that they control. This protocol also provides information regarding resource padding.

Note:
This protocol is required only on platforms that support one or more PCI Hot Plug* slots or CardBus sockets.
The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator to properly initialize the HPCs and CardBus sockets that require initialization. The HPC initialization takes place before the PCI enumeration process is complete. There cannot be more than one instance of this protocol in a system. This protocol is installed on its own separate handle.

Because the system may include multiple HPCs, one instance of this protocol should represent all of them. The protocol functions use the device path of the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc() is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC and continue the enumeration process. If the HPC is not initialized, the devices that it controls may not be initialized, and no resource padding will be provided.

From the standpoint of the PCI bus enumerator, HPCs are divided into the following two classes:

Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at http://opensource.org/licenses/bsd-license.php

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

Revision Reference:
This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards

Define Documentation

#define EFI_HPC_STATE_ENABLED   0x02

The HPC initialization function was called, the HPC completed initialization, and it was enabled. Resource padding is required.

#define EFI_HPC_STATE_INITIALIZED   0x01

The HPC initialization function was called and the HPC completed initialization, but it was not enabled for some reason. The HPC may be disabled in hardware, or it may be disabled due to user preferences, hardware failure, or other reasons. No resource padding is required.

#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID

Value:

{ \
    0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \
  }
Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL


Typedef Documentation

typedef EFI_STATUS(EFIAPI * EFI_GET_HOT_PLUG_PADDING)(IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, IN UINT64 HpcPciAddress, OUT EFI_HPC_STATE *HpcState, OUT VOID **Padding, OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes)

Returns the resource padding that is required by the PCI bus that is controlled by the specified Hot Plug Controller (HPC).

This function returns the resource padding that is required by the PCI bus that is controlled by the specified HPC. This member function is called for all the root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This function will be called before PCI resource allocation is completed. This function must be called after all the root HPCs, with the possible exception of a PCI-to-CardBus bridge, have completed initialization.

Parameters:
[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
[in] HpcDevicePath The device path to the HPC.
[in] HpcPciAddress The address of the HPC function on the PCI bus.
[in] HpcState The state of the HPC hardware.
[out] Padding The amount of resource padding that is required by the PCI bus under the control of the specified HPC.
[out] Attributes Describes how padding is accounted for. The padding is returned in the form of ACPI 2.0 resource descriptors.
Return values:
EFI_SUCCESS The resource padding was successfully returned.
EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL does not support the specified HPC.
EFI_NOT_READY This function was called before HPC initialization is complete.
EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.
EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding cannot be allocated due to insufficient resources.

typedef EFI_STATUS(EFIAPI * EFI_GET_ROOT_HPC_LIST)(IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, OUT UINTN *HpcCount, OUT EFI_HPC_LOCATION **HpcList)

Returns a list of root Hot Plug Controllers (HPCs) that require initialization during the boot process.

This procedure returns a list of root HPCs. The PCI bus driver must initialize these controllers during the boot process. The PCI bus driver may or may not be able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it can be included in this list if it requires initialization. The HpcList must be self consistent. An HPC cannot control any of its parent buses. Only one HPC can control a PCI bus. Because this list includes only root HPCs, no HPC in the list can be a child of another HPC. This policy must be enforced by the EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such invalid conditions. The callee allocates the buffer HpcList

Parameters:
[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
[out] HpcCount The number of root HPCs that were returned.
[out] HpcList The list of root HPCs. HpcCount defines the number of elements in this list.
Return values:
EFI_SUCCESS HpcList was returned.
EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources.
EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.

Describes the current state of an HPC

typedef EFI_STATUS(EFIAPI * EFI_INITIALIZE_ROOT_HPC)(IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, IN UINT64 HpcPciAddress, IN EFI_EVENT Event, OUT EFI_HPC_STATE *HpcState)

Initializes one root Hot Plug Controller (HPC). This process may causes initialization of its subordinate buses.

This function initializes the specified HPC. At the end of initialization, the hot-plug slots or sockets (controlled by this HPC) are powered and are connected to the bus. All the necessary registers in the HPC are set up. For a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set up are defined in the PCI Standard Hot Plug Controller and Subsystem Specification.

Parameters:
[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
[in] HpcDevicePath The device path to the HPC that is being initialized.
[in] HpcPciAddress The address of the HPC function on the PCI bus.
[in] Event The event that should be signaled when the HPC initialization is complete. Set to NULL if the caller wants to wait until the entire initialization process is complete.
[out] HpcState The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED.
Return values:
EFI_SUCCESS If Event is NULL, the specific HPC was successfully initialized. If Event is not NULL, Event will be signaled at a later time when initialization is complete.
EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL does not support the specified HPC.
EFI_OUT_OF_RESOURCES Initialization failed due to insufficient resources.
EFI_INVALID_PARAMETER HpcState is NULL.

Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL


Enumeration Type Documentation

Describes how resource padding should be applied

Enumerator:
EfiPaddingPciBus  Apply the padding at a PCI bus level. In other words, the resources that are allocated to the bus containing hot-plug slots are padded by the specified amount. If the hot-plug bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge apertures will indicate the padding
EfiPaddingPciRootBridge  Apply the padding at a PCI root bridge level. If a PCI root bridge includes more than one hot-plug bus, the resource padding requests for these buses are added together and the resources that are allocated to the root bridge are padded by the specified amount. This strategy may reduce the total amount of padding, but requires reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge apertures do not indicate the padding for that bus.


Variable Documentation


Generated on Wed Sep 23 16:24:23 2015 for MdePkg[ALL] by  doxygen 1.5.7.1