1 /** @file 2 This file declares PlatfromOpRom protocols that provide the interface between 3 the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific 4 driver to describe the unique features of a platform. 5 This protocol is optional. 6 7 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> 8 This program and the accompanying materials are licensed and made available under 9 the terms and conditions of the BSD License that accompanies this distribution. 10 The full text of the license may be found at 11 http://opensource.org/licenses/bsd-license.php. 12 13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 15 16 @par Revision Reference: 17 This Protocol is defined in UEFI Platform Initialization Specification 1.2 18 Volume 5: Standards 19 20 **/ 21 22 #ifndef _PCI_PLATFORM_H_ 23 #define _PCI_PLATFORM_H_ 24 25 /// 26 /// This file must be included because the EFI_PCI_PLATFORM_PROTOCOL uses 27 /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE. 28 /// 29 #include <Protocol/PciHostBridgeResourceAllocation.h> 30 31 /// 32 /// Global ID for the EFI_PCI_PLATFORM_PROTOCOL. 33 /// 34 #define EFI_PCI_PLATFORM_PROTOCOL_GUID \ 35 { \ 36 0x7d75280, 0x27d4, 0x4d69, {0x90, 0xd0, 0x56, 0x43, 0xe2, 0x38, 0xb3, 0x41} \ 37 } 38 39 /// 40 /// Forward declaration for EFI_PCI_PLATFORM_PROTOCOL. 41 /// 42 typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL; 43 44 /// 45 /// EFI_PCI_PLATFORM_POLICY that is a bitmask with the following legal combinations: 46 /// - EFI_RESERVE_NONE_IO_ALIAS:<BR> 47 /// Does not set aside either ISA or VGA I/O resources during PCI 48 /// enumeration. By using this selection, the platform indicates that it does 49 /// not want to support a PCI device that requires ISA or legacy VGA 50 /// resources. If a PCI device driver asks for these resources, the request 51 /// will be turned down. 52 /// - EFI_RESERVE_ISA_IO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR> 53 /// Sets aside the ISA I/O range and all the aliases during PCI 54 /// enumeration. VGA I/O ranges and aliases are included in ISA alias 55 /// ranges. In this scheme, seventy-five percent of the I/O space remains unused. 56 /// By using this selection, the platform indicates that it wants to support 57 /// PCI devices that require the following, at the cost of wasted I/O space: 58 /// ISA range and its aliases 59 /// Legacy VGA range and its aliases 60 /// The PCI bus driver will not allocate I/O addresses out of the ISA I/O 61 /// range and its aliases. The following are the ISA I/O ranges: 62 /// - n100..n3FF 63 /// - n500..n7FF 64 /// - n900..nBFF 65 /// - nD00..nFFF 66 /// 67 /// In this case, the PCI bus driver will ask the PCI host bridge driver for 68 /// larger I/O ranges. The PCI host bridge driver is not aware of the ISA 69 /// aliasing policy and merely attempts to allocate the requested ranges. 70 /// The first device that requests the legacy VGA range will get all the 71 /// legacy VGA range plus its aliased addresses forwarded to it. The first 72 /// device that requests the legacy ISA range will get all the legacy ISA 73 /// range, plus its aliased addresses, forwarded to it. 74 /// - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR> 75 /// Sets aside the ISA I/O range (0x100 - 0x3FF) during PCI enumeration 76 /// and the aliases of the VGA I/O ranges. By using this selection, the 77 /// platform indicates that it will support VGA devices that require VGA 78 /// ranges, including those that require VGA aliases. The platform further 79 /// wants to support non-VGA devices that ask for the ISA range (0x100 - 80 /// 3FF), but not if it also asks for the ISA aliases. The PCI bus driver will 81 /// not allocate I/O addresses out of the legacy ISA I/O range (0x100 - 82 /// 0x3FF) range or the aliases of the VGA I/O range. If a PCI device 83 /// driver asks for the ISA I/O ranges, including aliases, the request will be 84 /// turned down. The first device that requests the legacy VGA range will 85 /// get all the legacy VGA range plus its aliased addresses forwarded to 86 /// it. When the legacy VGA device asks for legacy VGA ranges and its 87 /// aliases, all the upstream PCI-to-PCI bridges must be set up to perform 88 /// 10-bit decode on legacy VGA ranges. To prevent two bridges from 89 /// positively decoding the same address, all PCI-to-PCI bridges that are 90 /// peers to this bridge will have to be set up to not decode ISA aliased 91 /// ranges. In that case, all the devices behind the peer bridges can 92 /// occupy only I/O addresses that are not ISA aliases. This is a limitation 93 /// of PCI-to-PCI bridges and is described in the white paper PCI-to-PCI 94 /// Bridges and Card Bus Controllers on Windows 2000, Windows XP, 95 /// and Windows Server 2003. The PCI enumeration process must be 96 /// cognizant of this restriction. 97 /// - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_NO_ALIAS:<BR> 98 /// Sets aside the ISA I/O range (0x100 - 0x3FF) during PCI enumeration. 99 /// VGA I/O ranges are included in the ISA range. By using this selection, 100 /// the platform indicates that it wants to support PCI devices that require 101 /// the ISA range and legacy VGA range, but it does not want to support 102 /// devices that require ISA alias ranges or VGA alias ranges. The PCI 103 /// bus driver will not allocate I/O addresses out of the legacy ISA I/O 104 /// range (0x100-0x3FF). If a PCI device driver asks for the ISA I/O 105 /// ranges, including aliases, the request will be turned down. By using 106 /// this selection, the platform indicates that it will support VGA devices 107 /// that require VGA ranges, but it will not support VGA devices that 108 /// require VGA aliases. To truly support 16-bit VGA decode, all the PCIto- 109 /// PCI bridges that are upstream to a VGA device, as well as 110 /// upstream to the parent PCI root bridge, must support 16-bit VGA I/O 111 /// decode. See the PCI-to-PCI Bridge Architecture Specification for 112 /// information regarding the 16-bit VGA decode support. This 113 /// requirement must hold true for every VGA device in the system. If any 114 /// of these bridges does not support 16-bit VGA decode, it will positively 115 /// decode all the aliases of the VGA I/O ranges and this selection must 116 /// be treated like EFI_RESERVE_ISA_IO_NO_ALIAS | 117 /// EFI_RESERVE_VGA_IO_ALIAS. 118 /// 119 typedef UINT32 EFI_PCI_PLATFORM_POLICY; 120 121 /// 122 /// Does not set aside either ISA or VGA I/O resources during PCI 123 /// enumeration. 124 /// 125 #define EFI_RESERVE_NONE_IO_ALIAS 0x0000 126 127 /// 128 /// Sets aside ISA I/O range and all aliases: 129 /// - n100..n3FF 130 /// - n500..n7FF 131 /// - n900..nBFF 132 /// - nD00..nFFF. 133 /// 134 #define EFI_RESERVE_ISA_IO_ALIAS 0x0001 135 136 /// 137 /// Sets aside ISA I/O range 0x100-0x3FF. 138 /// 139 #define EFI_RESERVE_ISA_IO_NO_ALIAS 0x0002 140 141 /// 142 /// Sets aside VGA I/O ranges and all aliases. 143 /// 144 #define EFI_RESERVE_VGA_IO_ALIAS 0x0004 145 146 /// 147 /// Sets aside VGA I/O ranges 148 /// 149 #define EFI_RESERVE_VGA_IO_NO_ALIAS 0x0008 150 151 /// 152 /// EFI_PCI_EXECUTION_PHASE is used to call a platform protocol and execute 153 /// platform-specific code. 154 /// 155 typedef enum { 156 /// 157 /// The phase that indicates the entry point to the PCI Bus Notify phase. This 158 /// platform hook is called before the PCI bus driver calls the 159 /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL driver. 160 /// 161 BeforePciHostBridge = 0, 162 /// 163 /// The phase that indicates the entry point to the PCI Bus Notify phase. This 164 /// platform hook is called before the PCI bus driver calls the 165 /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL driver. 166 /// 167 ChipsetEntry = 0, 168 /// 169 /// The phase that indicates the exit point to the Chipset Notify phase before 170 /// returning to the PCI Bus Driver Notify phase. This platform hook is called after 171 /// the PCI bus driver calls the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 172 /// driver. 173 /// 174 AfterPciHostBridge = 1, 175 /// 176 /// The phase that indicates the exit point to the Chipset Notify phase before 177 /// returning to the PCI Bus Driver Notify phase. This platform hook is called after 178 /// the PCI bus driver calls the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 179 /// driver. 180 /// 181 ChipsetExit = 1, 182 MaximumChipsetPhase 183 } EFI_PCI_EXECUTION_PHASE; 184 185 typedef EFI_PCI_EXECUTION_PHASE EFI_PCI_CHIPSET_EXECUTION_PHASE; 186 187 /** 188 The notification from the PCI bus enumerator to the platform that it is 189 about to enter a certain phase during the enumeration process. 190 191 The PlatformNotify() function can be used to notify the platform driver so that 192 it can perform platform-specific actions. No specific actions are required. 193 Eight notification points are defined at this time. More synchronization points 194 may be added as required in the future. The PCI bus driver calls the platform driver 195 twice for every Phase-once before the PCI Host Bridge Resource Allocation Protocol 196 driver is notified, and once after the PCI Host Bridge Resource Allocation Protocol 197 driver has been notified. 198 This member function may not perform any error checking on the input parameters. It 199 also does not return any error codes. If this member function detects any error condition, 200 it needs to handle those errors on its own because there is no way to surface any 201 errors to the caller. 202 203 @param[in] This The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. 204 @param[in] HostBridge The handle of the host bridge controller. 205 @param[in] Phase The phase of the PCI bus enumeration. 206 @param[in] ExecPhase Defines the execution phase of the PCI chipset driver. 207 208 @retval EFI_SUCCESS The function completed successfully. 209 210 **/ 211 typedef 212 EFI_STATUS 213 (EFIAPI *EFI_PCI_PLATFORM_PHASE_NOTIFY)( 214 IN EFI_PCI_PLATFORM_PROTOCOL *This, 215 IN EFI_HANDLE HostBridge, 216 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase, 217 IN EFI_PCI_EXECUTION_PHASE ExecPhase 218 ); 219 220 /** 221 The notification from the PCI bus enumerator to the platform for each PCI 222 controller at several predefined points during PCI controller initialization. 223 224 The PlatformPrepController() function can be used to notify the platform driver so that 225 it can perform platform-specific actions. No specific actions are required. 226 Several notification points are defined at this time. More synchronization points may be 227 added as required in the future. The PCI bus driver calls the platform driver twice for 228 every PCI controller-once before the PCI Host Bridge Resource Allocation Protocol driver 229 is notified, and once after the PCI Host Bridge Resource Allocation Protocol driver has 230 been notified. 231 This member function may not perform any error checking on the input parameters. It also 232 does not return any error codes. If this member function detects any error condition, it 233 needs to handle those errors on its own because there is no way to surface any errors to 234 the caller. 235 236 @param[in] This The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. 237 @param[in] HostBridge The associated PCI host bridge handle. 238 @param[in] RootBridge The associated PCI root bridge handle. 239 @param[in] PciAddress The address of the PCI device on the PCI bus. 240 @param[in] Phase The phase of the PCI controller enumeration. 241 @param[in] ExecPhase Defines the execution phase of the PCI chipset driver. 242 243 @retval EFI_SUCCESS The function completed successfully. 244 245 **/ 246 typedef 247 EFI_STATUS 248 (EFIAPI *EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER)( 249 IN EFI_PCI_PLATFORM_PROTOCOL *This, 250 IN EFI_HANDLE HostBridge, 251 IN EFI_HANDLE RootBridge, 252 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress, 253 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase, 254 IN EFI_PCI_EXECUTION_PHASE ExecPhase 255 ); 256 257 /** 258 Retrieves the platform policy regarding enumeration. 259 260 The GetPlatformPolicy() function retrieves the platform policy regarding PCI 261 enumeration. The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol 262 driver can call this member function to retrieve the policy. 263 264 @param[in] This The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. 265 @param[out] PciPolicy The platform policy with respect to VGA and ISA aliasing. 266 267 @retval EFI_SUCCESS The function completed successfully. 268 @retval EFI_INVALID_PARAMETER PciPolicy is NULL. 269 270 **/ 271 typedef 272 EFI_STATUS 273 (EFIAPI *EFI_PCI_PLATFORM_GET_PLATFORM_POLICY)( 274 IN CONST EFI_PCI_PLATFORM_PROTOCOL *This, 275 OUT EFI_PCI_PLATFORM_POLICY *PciPolicy 276 ); 277 278 /** 279 Gets the PCI device's option ROM from a platform-specific location. 280 281 The GetPciRom() function gets the PCI device's option ROM from a platform-specific location. 282 The option ROM will be loaded into memory. This member function is used to return an image 283 that is packaged as a PCI 2.2 option ROM. The image may contain both legacy and EFI option 284 ROMs. See the UEFI 2.0 Specification for details. This member function can be used to return 285 option ROM images for embedded controllers. Option ROMs for embedded controllers are typically 286 stored in platform-specific storage, and this member function can retrieve it from that storage 287 and return it to the PCI bus driver. The PCI bus driver will call this member function before 288 scanning the ROM that is attached to any controller, which allows a platform to specify a ROM 289 image that is different from the ROM image on a PCI card. 290 291 @param[in] This The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. 292 @param[in] PciHandle The handle of the PCI device. 293 @param[out] RomImage If the call succeeds, the pointer to the pointer to the option ROM image. 294 Otherwise, this field is undefined. The memory for RomImage is allocated 295 by EFI_PCI_PLATFORM_PROTOCOL.GetPciRom() using the EFI Boot Service AllocatePool(). 296 It is the caller's responsibility to free the memory using the EFI Boot Service 297 FreePool(), when the caller is done with the option ROM. 298 @param[out] RomSize If the call succeeds, a pointer to the size of the option ROM size. Otherwise, 299 this field is undefined. 300 301 @retval EFI_SUCCESS The option ROM was available for this device and loaded into memory. 302 @retval EFI_NOT_FOUND No option ROM was available for this device. 303 @retval EFI_OUT_OF_RESOURCES No memory was available to load the option ROM. 304 @retval EFI_DEVICE_ERROR An error occurred in obtaining the option ROM. 305 306 **/ 307 typedef 308 EFI_STATUS 309 (EFIAPI *EFI_PCI_PLATFORM_GET_PCI_ROM)( 310 IN CONST EFI_PCI_PLATFORM_PROTOCOL *This, 311 IN EFI_HANDLE PciHandle, 312 OUT VOID **RomImage, 313 OUT UINTN *RomSize 314 ); 315 316 /// 317 /// This protocol provides the interface between the PCI bus driver/PCI Host 318 /// Bridge Resource Allocation driver and a platform-specific driver to describe 319 /// the unique features of a platform. 320 /// 321 struct _EFI_PCI_PLATFORM_PROTOCOL { 322 /// 323 /// The notification from the PCI bus enumerator to the platform that it is about to 324 /// enter a certain phase during the enumeration process. 325 /// 326 EFI_PCI_PLATFORM_PHASE_NOTIFY PlatformNotify; 327 /// 328 /// The notification from the PCI bus enumerator to the platform for each PCI 329 /// controller at several predefined points during PCI controller initialization. 330 /// 331 EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER PlatformPrepController; 332 /// 333 /// Retrieves the platform policy regarding enumeration. 334 /// 335 EFI_PCI_PLATFORM_GET_PLATFORM_POLICY GetPlatformPolicy; 336 /// 337 /// Gets the PCI device's option ROM from a platform-specific location. 338 /// 339 EFI_PCI_PLATFORM_GET_PCI_ROM GetPciRom; 340 }; 341 342 extern EFI_GUID gEfiPciPlatformProtocolGuid; 343 344 #endif 345