mirror of
https://git.proxmox.com/git/mirror_edk2
synced 2025-11-04 11:29:11 +00:00
73c31a3d5e
1) IDE Controller Init 2) Incompatible PCI Device Support 3) PCI Hot Bridge Resource Allocation 4) PCI Hot Plug 5) PCI Platform git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8940 6f19259b-4bc3-4df7-8a09-765794883524
345 lines
16 KiB
C
345 lines
16 KiB
C
/** @file
|
||
This file declares PlatfromOpRom protocols which provides the interface between
|
||
the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific
|
||
driver to describe the unique features of a platform. This
|
||
protocol is optional.
|
||
|
||
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.
|
||
|
||
@par Revision Reference:
|
||
This Protocol is defined in UEFI Platform Initialization Specification 1.2
|
||
Volume 5: Standards
|
||
|
||
**/
|
||
|
||
#ifndef _PCI_PLATFORM_H_
|
||
#define _PCI_PLATFORM_H_
|
||
|
||
///
|
||
/// This file must be included because the EFI_PCI_PLATFORM_PROTOCOL uses
|
||
/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
|
||
///
|
||
#include <Protocol/PciHostBridgeResourceAllocation.h>
|
||
|
||
///
|
||
/// Global ID for the EFI_PCI_PLATFORM_PROTOCOL
|
||
///
|
||
#define EFI_PCI_PLATFORM_PROTOCOL_GUID \
|
||
{ \
|
||
0x7d75280, 0x27d4, 0x4d69, {0x90, 0xd0, 0x56, 0x43, 0xe2, 0x38, 0xb3, 0x41} \
|
||
}
|
||
|
||
///
|
||
/// Forward declaration for EFI_PCI_PLATFORM_PROTOCOL
|
||
///
|
||
typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL;
|
||
|
||
///
|
||
/// EFI_PCI_PLATYFORM_POLICY that is a bitmask with the following legal combinations:
|
||
/// - EFI_RESERVE_NONE_IO_ALIAS:<BR>
|
||
/// Does not set aside either ISA or VGA I/O resources during PCI
|
||
/// enumeration. By using this selection, the platform indicates that it does
|
||
/// not want to support a PCI device that requires ISA or legacy VGA
|
||
/// resources. If a PCI device driver asks for these resources, the request
|
||
/// will be turned down.
|
||
/// - EFI_RESERVE_ISA_IO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR>
|
||
/// Sets aside the ISA I/O range and all the aliases during PCI
|
||
/// enumeration. VGA I/O ranges and aliases are included in ISA alias
|
||
/// ranges. In this scheme, 75 percent of the I/O space remains unused.
|
||
/// By using this selection, the platform indicates that it wants to support
|
||
/// PCI devices that require the following, at the cost of wasted I/O space:
|
||
/// ISA range and its aliases
|
||
/// Legacy VGA range and its aliases
|
||
/// The PCI bus driver will not allocate I/O addresses out of the ISA I/O
|
||
/// range and its aliases. The following are the ISA I/O ranges:
|
||
/// - n100..n3FF
|
||
/// - n500..n7FF
|
||
/// - n900..nBFF
|
||
/// - nD00..nFFF
|
||
///
|
||
/// In this case, the PCI bus driver will ask the PCI host bridge driver for
|
||
/// larger I/O ranges. The PCI host bridge driver is not aware of the ISA
|
||
/// aliasing policy and merely attempts to allocate the requested ranges.
|
||
/// The first device that requests the legacy VGA range will get all the
|
||
/// legacy VGA range plus its aliased addresses forwarded to it. The first
|
||
/// device that requests the legacy ISA range will get all the legacy ISA
|
||
/// range plus its aliased addresses forwarded to it.
|
||
/// - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR>
|
||
/// Sets aside the ISA I/O range (0x100<30>0x3FF) during PCI enumeration
|
||
/// and the aliases of the VGA I/O ranges. By using this selection, the
|
||
/// platform indicates that it will support VGA devices that require VGA
|
||
/// ranges, including those that require VGA aliases. The platform further
|
||
/// wants to support non-VGA devices that ask for the ISA range (0x100<30>
|
||
/// 3FF), but not if it also asks for the ISA aliases. The PCI bus driver will
|
||
/// not allocate I/O addresses out of the legacy ISA I/O range (0x100<30>
|
||
/// 0x3FF) range or the aliases of the VGA I/O range. If a PCI device
|
||
/// driver asks for the ISA I/O ranges, including aliases, the request will be
|
||
/// turned down. The first device that requests the legacy VGA range will
|
||
/// get all the legacy VGA range plus its aliased addresses forwarded to
|
||
/// it. When the legacy VGA device asks for legacy VGA ranges and its
|
||
/// aliases, all the upstream PCI-to-PCI bridges must be set up to perform
|
||
/// 10-bit decode on legacy VGA ranges. To prevent two bridges from
|
||
/// positively decoding the same address, all PCI-to-PCI bridges that are
|
||
/// peers to this bridge will have to be set up to not decode ISA aliased
|
||
/// ranges. In that case, all the devices behind the peer bridges can
|
||
/// occupy only I/O addresses that are not ISA aliases. This is a limitation
|
||
/// of PCI-to-PCI bridges and is described in the white paper PCI-to-PCI
|
||
/// Bridges and Card Bus Controllers on Windows 2000, Windows XP,
|
||
/// and Windows Server 2003. The PCI enumeration process must be
|
||
/// cognizant of this restriction.
|
||
/// - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_NO_ALIAS:<BR>
|
||
/// Sets aside the ISA I/O range (0x100<30>0x3FF) during PCI enumeration.
|
||
/// VGA I/O ranges are included in the ISA range. By using this selection,
|
||
/// the platform indicates that it wants to support PCI devices that require
|
||
/// the ISA range and legacy VGA range, but it does not want to support
|
||
/// devices that require ISA alias ranges or VGA alias ranges. The PCI
|
||
/// bus driver will not allocate I/O addresses out of the legacy ISA I/O
|
||
/// range (0x100<30>0x3FF). If a PCI device driver asks for the ISA I/O
|
||
/// ranges, including aliases, the request will be turned down. By using
|
||
/// this selection, the platform indicates that it will support VGA devices
|
||
/// that require VGA ranges, but it will not support VGA devices that
|
||
/// require VGA aliases. To truly support 16-bit VGA decode, all the PCIto-
|
||
/// PCI bridges that are upstream to a VGA device, as well as
|
||
/// upstream to the parent PCI root bridge, must support 16-bit VGA I/O
|
||
/// decode. See the PCI-to-PCI Bridge Architecture Specification for
|
||
/// information regarding the 16-bit VGA decode support. This
|
||
/// requirement must hold true for every VGA device in the system. If any
|
||
/// of these bridges does not support 16-bit VGA decode, it will positively
|
||
/// decode all the aliases of the VGA I/O ranges and this selection must
|
||
/// be treated like EFI_RESERVE_ISA_IO_NO_ALIAS |
|
||
/// EFI_RESERVE_VGA_IO_ALIAS.
|
||
///
|
||
typedef UINT32 EFI_PCI_PLATFORM_POLICY;
|
||
|
||
///
|
||
/// Does not set aside either ISA or VGA I/O resources during PCI
|
||
/// enumeration.
|
||
///
|
||
#define EFI_RESERVE_NONE_IO_ALIAS 0x0000
|
||
|
||
///
|
||
/// Sets aside ISA I/O range and all aliases
|
||
/// - n100..n3FF
|
||
/// - n500..n7FF
|
||
/// - n900..nBFF
|
||
/// - nD00..nFFF
|
||
///
|
||
#define EFI_RESERVE_ISA_IO_ALIAS 0x0001
|
||
|
||
///
|
||
/// Sets aside ISA I/O range 0x100-0x3FF
|
||
///
|
||
#define EFI_RESERVE_ISA_IO_NO_ALIAS 0x0002
|
||
|
||
///
|
||
/// Sets aside VGA I/O ranges and all aliases
|
||
///
|
||
#define EFI_RESERVE_VGA_IO_ALIAS 0x0004
|
||
|
||
///
|
||
/// Sets aside VGA I/O rangess
|
||
///
|
||
#define EFI_RESERVE_VGA_IO_NO_ALIAS 0x0008
|
||
|
||
///
|
||
/// EFI_PCI_EXECUTION_PHASE is used to call a platform protocol and execute
|
||
/// platform-specific code.
|
||
///
|
||
typedef enum {
|
||
///
|
||
/// The phase that indicates the entry point to the PCI Bus Notify phase. This
|
||
/// platform hook is called before the PCI bus driver calls the
|
||
/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL driver.
|
||
///
|
||
BeforePciHostBridge = 0,
|
||
///
|
||
/// The phase that indicates the entry point to the PCI Bus Notify phase. This
|
||
/// platform hook is called before the PCI bus driver calls the
|
||
/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL driver.
|
||
///
|
||
ChipsetEntry = 0,
|
||
///
|
||
/// The phase that indicates the exit point to the Chipset Notify phase before
|
||
/// returning to the PCI Bus Driver Notify phase. This platform hook is called after
|
||
/// the PCI bus driver calls the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
|
||
/// driver.
|
||
///
|
||
AfterPciHostBridge = 1,
|
||
///
|
||
/// The phase that indicates the exit point to the Chipset Notify phase before
|
||
/// returning to the PCI Bus Driver Notify phase. This platform hook is called after
|
||
/// the PCI bus driver calls the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
|
||
/// driver.
|
||
///
|
||
ChipsetExit = 1,
|
||
MaximumChipsetPhase
|
||
} EFI_PCI_EXECUTION_PHASE;
|
||
|
||
typedef EFI_PCI_EXECUTION_PHASE EFI_PCI_CHIPSET_EXECUTION_PHASE;
|
||
|
||
/**
|
||
The notification from the PCI bus enumerator to the platform that it is
|
||
about to enter a certain phase during the enumeration process.
|
||
|
||
The PlatformNotify() function can be used to notify the platform driver so that
|
||
it can perform platform-specific actions. No specific actions are required.
|
||
Eight notification points are defined at this time. More synchronization points
|
||
may be added as required in the future. The PCI bus driver calls the platform driver
|
||
twice for every Phase-once before the PCI Host Bridge Resource Allocation Protocol
|
||
driver is notified, and once after the PCI Host Bridge Resource Allocation Protocol
|
||
driver has been notified.
|
||
This member function may not perform any error checking on the input parameters. It
|
||
also does not return any error codes. If this member function detects any error condition,
|
||
it needs to handle those errors on its own because there is no way to surface any
|
||
errors to the caller.
|
||
|
||
@param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
|
||
@param[in] HostBridge The handle of the host bridge controller.
|
||
@param[in] Phase The phase of the PCI bus enumeration.
|
||
@param[in] ChipsetPhase Defines the execution phase of the PCI chipset driver.
|
||
|
||
@retval EFI_SUCCESS The function completed successfully.
|
||
|
||
**/
|
||
typedef
|
||
EFI_STATUS
|
||
(EFIAPI *EFI_PCI_PLATFORM_PHASE_NOTIFY)(
|
||
IN EFI_PCI_PLATFORM_PROTOCOL *This,
|
||
IN EFI_HANDLE HostBridge,
|
||
IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase,
|
||
IN EFI_PCI_CHIPSET_EXECUTION_PHASE ChipsetPhase
|
||
);
|
||
|
||
/**
|
||
The notification from the PCI bus enumerator to the platform for each PCI
|
||
controller at several predefined points during PCI controller initialization.
|
||
|
||
The PlatformPrepController() function can be used to notify the platform driver so that
|
||
it can perform platform-specific actions. No specific actions are required.
|
||
Several notification points are defined at this time. More synchronization points may be
|
||
added as required in the future. The PCI bus driver calls the platform driver twice for
|
||
every PCI controller-once before the PCI Host Bridge Resource Allocation Protocol driver
|
||
is notified, and once after the PCI Host Bridge Resource Allocation Protocol driver has
|
||
been notified.
|
||
This member function may not perform any error checking on the input parameters. It also
|
||
does not return any error codes. If this member function detects any error condition, it
|
||
needs to handle those errors on its own because there is no way to surface any errors to
|
||
the caller.
|
||
|
||
@param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
|
||
@param[in] HostBridge The associated PCI host bridge handle.
|
||
@param[in] RootBridge The associated PCI root bridge handle.
|
||
@param[in] PciAddress The address of the PCI device on the PCI bus.
|
||
@param[in] Phase The phase of the PCI controller enumeration.
|
||
@param[in] ChipsetPhase Defines the execution phase of the PCI chipset driver.
|
||
|
||
@retval EFI_SUCCESS The function completed successfully.
|
||
|
||
**/
|
||
typedef
|
||
EFI_STATUS
|
||
(EFIAPI *EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER)(
|
||
IN EFI_PCI_PLATFORM_PROTOCOL *This,
|
||
IN EFI_HANDLE HostBridge,
|
||
IN EFI_HANDLE RootBridge,
|
||
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress,
|
||
IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase,
|
||
IN EFI_PCI_CHIPSET_EXECUTION_PHASE ChipsetPhase
|
||
);
|
||
|
||
/**
|
||
Retrieves the platform policy regarding enumeration.
|
||
|
||
The GetPlatformPolicy() function retrieves the platform policy regarding PCI
|
||
enumeration. The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol
|
||
driver can call this member function to retrieve the policy.
|
||
|
||
@param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
|
||
@param[out] PciPolicy The platform policy with respect to VGA and ISA aliasing.
|
||
|
||
@retval EFI_SUCCESS The function completed successfully.
|
||
@retval EFI_INVALID_PARAMETER PciPolicy is NULL.
|
||
|
||
**/
|
||
typedef
|
||
EFI_STATUS
|
||
(EFIAPI *EFI_PCI_PLATFORM_GET_PLATFORM_POLICY)(
|
||
IN EFI_PCI_PLATFORM_PROTOCOL *This,
|
||
OUT EFI_PCI_PLATFORM_POLICY *PciPolicy
|
||
);
|
||
|
||
/**
|
||
Gets the PCI device's option ROM from a platform-specific location.
|
||
|
||
The GetPciRom() function gets the PCI device's option ROM from a platform-specific location.
|
||
The option ROM will be loaded into memory. This member function is used to return an image
|
||
that is packaged as a PCI 2.2 option ROM. The image may contain both legacy and EFI option
|
||
ROMs. See the UEFI 2.0 Specification for details. This member function can be used to return
|
||
option ROM images for embedded controllers. Option ROMs for embedded controllers are typically
|
||
stored in platform-specific storage, and this member function can retrieve it from that storage
|
||
and return it to the PCI bus driver. The PCI bus driver will call this member function before
|
||
scanning the ROM that is attached to any controller, which allows a platform to specify a ROM
|
||
image that is different from the ROM image on a PCI card.
|
||
|
||
@param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
|
||
@param[in] PciHandle The handle of the PCI device.
|
||
@param[out] RomImage If the call succeeds, the pointer to the pointer to the option ROM image.
|
||
Otherwise, this field is undefined. The memory for RomImage is allocated
|
||
by EFI_PCI_PLATFORM_PROTOCOL.GetPciRom() using the EFI Boot Service AllocatePool().
|
||
It is the caller's responsibility to free the memory using the EFI Boot Service
|
||
FreePool(), when the caller is done with the option ROM.
|
||
@param[out] RomSize If the call succeeds, a pointer to the size of the option ROM size. Otherwise,
|
||
this field is undefined.
|
||
|
||
@retval EFI_SUCCESS The option ROM was available for this device and loaded into memory.
|
||
@retval EFI_NOT_FOUND No option ROM was available for this device.
|
||
@retval EFI_OUT_OF_RESOURCES No memory was available to load the option ROM.
|
||
@retval EFI_DEVICE_ERROR An error occurred in getting the option ROM.
|
||
|
||
**/
|
||
typedef
|
||
EFI_STATUS
|
||
(EFIAPI *EFI_PCI_PLATFORM_GET_PCI_ROM)(
|
||
IN EFI_PCI_PLATFORM_PROTOCOL *This,
|
||
IN EFI_HANDLE PciHandle,
|
||
OUT VOID **RomImage,
|
||
OUT UINTN *RomSize
|
||
);
|
||
|
||
///
|
||
/// This protocol provides the interface between the PCI bus driver/PCI Host
|
||
/// Bridge Resource Allocation driver and a platform-specific driver to describe
|
||
/// the unique features of a platform.
|
||
///
|
||
struct _EFI_PCI_PLATFORM_PROTOCOL {
|
||
///
|
||
/// The notification from the PCI bus enumerator to the platform that it is about to
|
||
/// enter a certain phase during the enumeration process.
|
||
///
|
||
EFI_PCI_PLATFORM_PHASE_NOTIFY PlatformNotify;
|
||
///
|
||
/// The notification from the PCI bus enumerator to the platform for each PCI
|
||
/// controller at several predefined points during PCI controller initialization.
|
||
///
|
||
EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER PlatformPrepController;
|
||
///
|
||
/// Retrieves the platform policy regarding enumeration.
|
||
///
|
||
EFI_PCI_PLATFORM_GET_PLATFORM_POLICY GetPlatformPolicy;
|
||
///
|
||
/// Gets the PCI device<63>s option ROM from a platform-specific location.
|
||
///
|
||
EFI_PCI_PLATFORM_GET_PCI_ROM GetPciRom;
|
||
};
|
||
|
||
extern EFI_GUID gEfiPciPlatformProtocolGuid;
|
||
|
||
#endif
|