Update the copyright notice format

[mirror_edk2.git] / EdkCompatibilityPkg / Foundation / Framework / Protocol / PciHostBridgeResourceAllocation / PciHostBridgeResourceAllocation.h

/*++\r
\r
Copyright (c) 2004, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials                          \r
are licensed and made available under the terms and conditions of the BSD License         \r
which accompanies this distribution.  The full text of the license may be found at        \r
http://opensource.org/licenses/bsd-license.php                                            \r
                                                                                          \r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
Module Name:\r
\r
  PciHostBridgeResourceAllocation.h\r
\r
Abstract:\r
\r
\r
--*/\r
\r
#ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_\r
#define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_\r
\r
#include "Tiano.h"\r
#include EFI_PROTOCOL_DEFINITION(PciRootBridgeIo)\r
\r
\r
#define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \\r
  { 0xCF8034BE,0x6768,0x4d8b,{0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE} }\r
\r
\r
EFI_FORWARD_DECLARATION (EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL);\r
\r
\r
//\r
// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES\r
//\r
\r
// If this bit is set, then the PCI Root Bridge does not \r
// support separate windows for Non-prefetchable and Prefetchable \r
// memory. A PCI bus driver needs to include requests for Prefetchable \r
// memory in the Non-prefetchable memory pool.\r
//\r
#define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM  1\r
\r
//\r
// If this bit is set, then the PCI Root Bridge supports \r
// 64 bit memory windows.  If this bit is not set, \r
// the PCI bus driver needs to include requests for 64 bit \r
// memory address in the corresponding 32 bit memory pool. \r
//\r
#define EFI_PCI_HOST_BRIDGE_MEM64_DECODE   2\r
\r
\r
//\r
// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE\r
//\r
typedef enum {\r
  EfiPciHostBridgeBeginEnumeration,\r
  EfiPciHostBridgeBeginBusAllocation,\r
  EfiPciHostBridgeEndBusAllocation,\r
  EfiPciHostBridgeBeginResourceAllocation,\r
  EfiPciHostBridgeAllocateResources,\r
  EfiPciHostBridgeSetResources,\r
  EfiPciHostBridgeFreeResources,\r
  EfiPciHostBridgeEndResourceAllocation\r
} EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE;\r
\r
//\r
// EfiPciHostBridgeBeginEnumeration\r
// Reset the host bridge PCI apertures and internal data structures. \r
// PCI enumerator should issue this notification before starting fresh \r
// enumeration process. Enumeration cannot be restarted after sending \r
// any other notification such as EfiPciHostBridgeBeginBusAllocation. \r
//\r
// EfiPciHostBridgeBeginBusAllocation  \r
// The bus allocation phase is about to begin. No specific action \r
// is required here. This notification can be used to perform any \r
// chipset specific programming. \r
//\r
// EfiPciHostBridgeEndBusAllocation\r
// The bus allocation and bus programming phase is complete. No specific\r
// action is required here. This notification can be used to perform any \r
// chipset specific programming. \r
//\r
// EfiPciHostBridgeBeginResourceAllocation\r
// The resource allocation phase is about to begin.No specific action is \r
// required here. This notification can be used to perform any chipset specific programming. \r
//\r
// EfiPciHostBridgeAllocateResources\r
// Allocate resources per previously submitted requests for all the PCI Root \r
// Bridges. These resource settings are returned on the next call to \r
// GetProposedResources(). \r
//\r
// EfiPciHostBridgeSetResources\r
// Program the Host Bridge hardware to decode previously allocated resources\r
// (proposed resources) for all the PCI Root Bridges. \r
//\r
// EfiPciHostBridgeFreeResources\r
// De-allocate previously allocated resources previously for all the PCI \r
// Root Bridges and reset the I/O and memory apertures to initial state. \r
//\r
// EfiPciHostBridgeEndResourceAllocation\r
// The resource allocation phase is completed.  No specific action is required \r
// here. This notification can be used to perform any chipset specific programming. \r
\r
\r
\r
//\r
// EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE\r
//\r
typedef enum {\r
  EfiPciBeforeChildBusEnumeration,        \r
  EfiPciBeforeResourceCollection\r
} EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE;\r
\r
//\r
// EfiPciBeforeChildBusEnumeration\r
// This notification is only applicable to PCI-PCI bridges and \r
// indicates that the PCI enumerator is about to begin enumerating \r
// the bus behind the PCI-PCI Bridge. This notification is sent after \r
// the primary bus number, the secondary bus number and the subordinate \r
// bus number registers in the PCI-PCI Bridge are programmed to valid \r
// (not necessary final) values\r
//\r
// EfiPciBeforeResourceCollection\r
// This notification is sent before the PCI enumerator probes BAR registers \r
// for every valid PCI function.\r
//\r
\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE            Phase\r
  );\r
/*++\r
\r
Routine Description:\r
  Enter a certain phase of the PCI enumeration process\r
\r
Arguments:\r
  This  -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance\r
  Phase -- The phase during enumeration\r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_OUT_OF_RESOURCES - If SubmitResources ( ) could not allocate resources\r
  EFI_NOT_READY        - This phase cannot be entered at this time\r
  EFI_DEVICE_ERROR     - SetResources failed due to HW error.\r
\r
--*/  \r
\r
  \r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN OUT EFI_HANDLE                                       *RootBridgeHandle\r
  );\r
/*++\r
\r
Routine Description:\r
  Return the device handle of the next PCI root bridge that is associated with \r
  this Host Bridge\r
\r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- Returns the device handle of the next PCI Root Bridge. \r
                      On input, it holds the RootBridgeHandle returned by the most \r
                      recent call to GetNextRootBridge().The handle for the first \r
                      PCI Root Bridge is returned if RootBridgeHandle is NULL on input\r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
\r
--*/  \r
\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN  EFI_HANDLE                                                RootBridgeHandle,\r
  OUT UINT64                                                    *Attributes\r
  );\r
/*++\r
\r
Routine Description:\r
  Returns the attributes of a PCI Root Bridge.\r
\r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- The device handle of the PCI Root Bridge \r
                      that the caller is interested in\r
  Attribute -- The pointer to attributes of the PCI Root Bridge                    \r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
  EFI_INVALID_PARAMETER - Attributes is NULL\r
\r
--*/    \r
\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN  EFI_HANDLE                                                RootBridgeHandle,\r
  OUT VOID                                                      **Configuration\r
  );\r
/*++\r
\r
Routine Description:\r
  This is the request from the PCI enumerator to set up \r
  the specified PCI Root Bridge for bus enumeration process. \r
\r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- The PCI Root Bridge to be set up\r
  Configuration -- Pointer to the pointer to the PCI bus resource descriptor\r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
  EFI_DEVICE_ERROR      - Request failed due to hardware error\r
  EFI_OUT_OF_RESOURCES  - Request failed due to lack of resources\r
--*/\r
\r
  \r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN EFI_HANDLE                                                RootBridgeHandle,\r
  IN VOID                                                      *Configuration\r
  );\r
/*++\r
\r
Routine Description:\r
  This function programs the PCI Root Bridge hardware so that \r
  it decodes the specified PCI bus range\r
\r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- The PCI Root Bridge whose bus range is to be programmed\r
  Configuration -- The pointer to the PCI bus resource descriptor\r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
  EFI_INVALID_PARAMETER - Configuration is NULL\r
  EFI_INVALID_PARAMETER - Configuration does not point to a valid ACPI resource descriptor\r
  EFI_INVALID_PARAMETER - Configuration contains one or more memory or IO ACPI resource descriptor\r
  EFI_INVALID_PARAMETER - Address Range Minimum or Address Range Length fields in Configuration \r
                          are invalid for this Root Bridge.\r
  EFI_INVALID_PARAMETER - Configuration contains one or more invalid ACPI resource descriptor\r
  EFI_DEVICE_ERROR      - Request failed due to hardware error\r
  EFI_OUT_OF_RESOURCES  - Request failed due to lack of resources\r
\r
--*/    \r
\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN EFI_HANDLE                                                RootBridgeHandle,\r
  IN VOID                                                      *Configuration\r
  );\r
/*++\r
\r
Routine Description:\r
  Submits the I/O and memory resource requirements for the specified PCI Root Bridge\r
  \r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- The PCI Root Bridge whose I/O and memory resource requirements \r
                      are being submitted\r
  Configuration -- The pointer to the PCI I/O and PCI memory resource descriptor                    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
  EFI_INVALID_PARAMETER - Configuration is NULL\r
  EFI_INVALID_PARAMETER - Configuration does not point to a valid ACPI resource descriptor\r
  EFI_INVALID_PARAMETER - Configuration includes a resource descriptor of unsupported type\r
\r
--*/    \r
\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN  EFI_HANDLE                                                RootBridgeHandle,\r
  OUT VOID                                                      **Configuration\r
  );\r
/*++\r
\r
Routine Description:\r
  This function returns the proposed resource settings for the specified \r
  PCI Root Bridge\r
\r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- The PCI Root Bridge handle\r
  Configuration -- The pointer to the pointer to the PCI I/O \r
                   and memory resource descriptor\r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
  EFI_DEVICE_ERROR      - Request failed due to hardware error\r
  EFI_OUT_OF_RESOURCES  - Request failed due to lack of resources\r
\r
--*/    \r
\r
\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER) (\r
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,\r
  IN  EFI_HANDLE                                                RootBridgeHandle,\r
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS                PciAddress,\r
  IN  EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE               Phase\r
  );\r
/*++\r
\r
Routine Description:\r
  This function is called for all the PCI controllers that the PCI \r
  bus driver finds. Can be used to Preprogram the controller.\r
\r
Arguments:\r
  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
  RootBridgeHandle -- The PCI Root Bridge handle\r
  PciBusAddress -- Address of the controller on the PCI bus\r
  Phase         -- The Phase during resource allocation\r
    \r
Returns:\r
  EFI_SUCCESS - Success\r
  EFI_INVALID_PARAMETER - RootBridgeHandle is invalid\r
  EFI_DEVICE_ERROR      - Device pre-initialization failed due to hardware error.\r
--*/    \r
\r
\r
\r
struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL {\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE           NotifyPhase;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE   GetNextRootBridge;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES         GetAllocAttributes;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION  StartBusEnumeration;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS        SetBusNumbers;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES       SubmitResources;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources;\r
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER  PreprocessController;\r
};\r
\r
extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid;\r
\r
#endif\r