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