X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FPciPlatform.h;h=15d735e1fe7ed3b21ffeece8597544176d91b51c;hp=5b0add1ea7051c8b1f76c3e8f9e68ca2550eacd3;hb=08855193cafebaa2e071ffb5f083bcb3cb6d4df0;hpb=878ddf1fc3540a715f63594ed22b6929e881afb4 diff --git a/MdePkg/Include/Protocol/PciPlatform.h b/MdePkg/Include/Protocol/PciPlatform.h index 5b0add1ea7..15d735e1fe 100644 --- a/MdePkg/Include/Protocol/PciPlatform.h +++ b/MdePkg/Include/Protocol/PciPlatform.h @@ -1,207 +1,344 @@ /** @file - This file declares PlatfromOpRom protocols. - - Copyright (c) 2006, 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. - - Module Name: PciPlatform.h + This file declares PlatfromOpRom protocols that provide 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 - 2010, 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 that 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 PCI Platform Support Specification - Version 0.9 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 + Volume 5: Standards **/ #ifndef _PCI_PLATFORM_H_ #define _PCI_PLATFORM_H_ -// -// Protocol for GUID. -// +/// +/// This file must be included because the EFI_PCI_PLATFORM_PROTOCOL uses +/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE. +/// +#include +/// +/// 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} } + { \ + 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; -typedef UINT32 EFI_PCI_PLATFORM_POLICY; - - +/// +/// EFI_PCI_PLATFORM_POLICY that is a bitmask with the following legal combinations: +/// - EFI_RESERVE_NONE_IO_ALIAS:
+/// 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:
+/// 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, seventy-five 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:
+/// Sets aside the ISA I/O range (0x100 - 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 - +/// 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 - +/// 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:
+/// Sets aside the ISA I/O range (0x100 - 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-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 -#define EFI_RESERVE_VGA_IO_NO_ALIAS 0x0008 +/// +/// Sets aside VGA I/O ranges +/// +#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 { - ChipsetEntry, - ChipsetExit, + /// + /// 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_CHIPSET_EXECUTION_PHASE; +} EFI_PCI_EXECUTION_PHASE; +typedef EFI_PCI_EXECUTION_PHASE EFI_PCI_CHIPSET_EXECUTION_PHASE; /** - 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 + 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 This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. - @param HostBridge The handle of the host bridge controller. - @param Phase The phase of the PCI bus enumeration. - @param ChipsetPhase Defines the execution phase of the PCI chipset driver. + @param[in] This The 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] ExecPhase Defines the execution phase of the PCI chipset driver. - @retval EFI_SUCCESS The function completed successfully. + @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 -) -; - +(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_EXECUTION_PHASE ExecPhase + ); /** - 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 This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. - @param HostBridge The associated PCI host bridge handle. - @param RootBridge The associated PCI root bridge handle. - @param PciAddress The address of the PCI device on the PCI bus. - @param Phase The phase of the PCI controller enumeration. - @param ChipsetPhase Defines the execution phase of the PCI chipset driver. - - @retval EFI_SUCCESS The function completed successfully. + 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 The 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] ExecPhase 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 -) -; - +(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_EXECUTION_PHASE ExecPhase + ); /** - The GetPlatformPolicy() function retrieves the platform policy regarding PCI - enumeration. The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol + 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 This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. - @param PciPolicy The platform policy with respect to VGA and ISA aliasing. + @param[in] This The 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. + @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 -) -; - +(EFIAPI *EFI_PCI_PLATFORM_GET_PLATFORM_POLICY)( + IN CONST EFI_PCI_PLATFORM_PROTOCOL *This, + OUT EFI_PCI_PLATFORM_POLICY *PciPolicy + ); /** - 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 EFI 1.10 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 + 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 This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. - @param PciHandle The handle of the PCI device. - @param 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 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. + @param[in] This The 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 obtaining 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 -) -; - -/** - @par Protocol Description: - 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. - - @param PlatformNotify - The notification from the PCI bus enumerator to the platform that it is - about to enter a certain phase during the enumeration process. - - @param PlatformPrepController - The notification from the PCI bus enumerator to the platform for each PCI - controller at several predefined points during PCI controller initialization. - - @param GetPlatformPolicy - Retrieves the platform policy regarding enumeration. - - @param GetPciRom - Gets the PCI device¡¯s option ROM from a platform-specific location. - -**/ +(EFIAPI *EFI_PCI_PLATFORM_GET_PCI_ROM)( + IN CONST 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 { - EFI_PCI_PLATFORM_PHASE_NOTIFY PhaseNotify; + /// + /// 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's option ROM from a platform-specific location. + /// EFI_PCI_PLATFORM_GET_PCI_ROM GetPciRom; }; extern EFI_GUID gEfiPciPlatformProtocolGuid; - #endif