IntelFrameworkPkg/Include/Protocol/LegacyBiosPlatform.h

   1 /** @file
   2   The EFI Legacy BIOS Patform Protocol is used to mate a Legacy16
   3   implementation with this EFI code. The EFI driver that produces
   4   the Legacy BIOS protocol is generic and consumes this protocol.
   5   A driver that matches the Legacy16 produces this protocol
   6
   7   Copyright (c) 2007, Intel Corporation
   8   All rights reserved. This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  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   Module Name:  LegacyBiosPlatform.h
  17
  18   @par Revision Reference:
  19   This protocol is defined in Framework for EFI Compatibility Support Module spec
  20   Version 0.97.
  21
  22 **/
  23
  24 #ifndef _EFI_LEGACY_BIOS_PLATFORM_H_
  25 #define _EFI_LEGACY_BIOS_PLATFORM_H_
  26
  27 #include <FrameworkDxe.h>
  28
  29 #define EFI_LEGACY_BIOS_PLATFORM_PROTOCOL_GUID \
  30   { \
  31     0x783658a3, 0x4172, 0x4421, {0xa2, 0x99, 0xe0, 0x9, 0x7, 0x9c, 0xc, 0xb4 } \
  32   }
  33
  34 typedef struct _EFI_LEGACY_BIOS_PLATFORM_PROTOCOL EFI_LEGACY_BIOS_PLATFORM_PROTOCOL;
  35
  36 typedef enum {
  37   EfiGetPlatformBinaryMpTable      = 0,
  38   EfiGetPlatformBinaryOemIntData   = 1,
  39   EfiGetPlatformBinaryOem16Data    = 2,
  40   EfiGetPlatformBinaryOem32Data    = 3,
  41   EfiGetPlatformBinaryTpmBinary    = 4,
  42   EfiGetPlatformBinarySystemRom    = 5,
  43   EfiGetPlatformPciExpressBase     = 6,
  44   EfiGetPlatformPmmSize            = 7,
  45   EfiGetPlatformEndOpromShadowAddr = 8,
  46
  47 } EFI_GET_PLATFORM_INFO_MODE;
  48
  49 typedef enum {
  50   EfiGetPlatformVgaHandle       = 0,
  51   EfiGetPlatformIdeHandle       = 1,
  52   EfiGetPlatformIsaBusHandle    = 2,
  53   EfiGetPlatformUsbHandle       = 3
  54 } EFI_GET_PLATFORM_HANDLE_MODE;
  55
  56 typedef enum {
  57   EfiPlatformHookPrepareToScanRom = 0,
  58   EfiPlatformHookShadowServiceRoms= 1,
  59   EfiPlatformHookAfterRomInit     = 2
  60 } EFI_GET_PLATFORM_HOOK_MODE;
  61
  62
  63 //
  64 //
  65 //
  66
  67 #define PCI_UNUSED        0x00
  68 #define PCI_USED          0xFF
  69 #define LEGACY_USED       0xFE
  70
  71 #pragma pack(1)
  72
  73 //
  74 //
  75 //
  76 typedef struct {
  77   UINT8 Irq;
  78   UINT8 Used;
  79 } EFI_LEGACY_IRQ_PRIORITY_TABLE_ENTRY;
  80
  81 //
  82 // Define PIR table structures
  83 //
  84 #define EFI_LEGACY_PIRQ_TABLE_SIGNATURE SIGNATURE_32 ('$', 'P', 'I', 'R')
  85
  86 typedef struct {
  87   UINT32  Signature;
  88   UINT8   MinorVersion;
  89   UINT8   MajorVersion;
  90   UINT16  TableSize;
  91   UINT8   Bus;
  92   UINT8   DevFun;
  93   UINT16  PciOnlyIrq;
  94   UINT16  CompatibleVid;
  95   UINT16  CompatibleDid;
  96   UINT32  Miniport;
  97   UINT8   Reserved[11];
  98   UINT8   Checksum;
  99 } EFI_LEGACY_PIRQ_TABLE_HEADER;
 100
 101
 102 typedef struct {
 103   UINT8   Pirq;
 104   UINT16  IrqMask;
 105 } EFI_LEGACY_PIRQ_ENTRY;
 106
 107 typedef struct {
 108   UINT8                 Bus;
 109   UINT8                 Device;
 110   EFI_LEGACY_PIRQ_ENTRY PirqEntry[4];
 111   UINT8                 Slot;
 112   UINT8                 Reserved;
 113 } EFI_LEGACY_IRQ_ROUTING_ENTRY;
 114
 115 #pragma pack()
 116
 117
 118 /**
 119   Finds the binary data or other platform information.
 120
 121   @param  This                  Protocol instance pointer.
 122   @param  Mode                  Specifies what data to return
 123   @param  Table                 Pointer to MP table.
 124   @param  TableSize             Size in bytes of table.
 125   @param  Location              Legacy region requested
 126                                 0x00 = Any location
 127                                 Bit 0 = 0xF0000 region
 128                                 Bit 1 = 0xE0000 region
 129                                 Multiple bits can be set
 130   @param  Alignment             Address alignment for allocation.
 131                                 Bit mapped. First non-zero bit from right
 132                                 is alignment.
 133   @param  LegacySegment         Segment in LegacyBios where Table is stored
 134   @param  LegacyOffset          Offset in LegacyBios where Table is stored
 135
 136   @retval EFI_SUCCESS           Data was returned successfully.
 137   @retval EFI_UNSUPPORTED       Mode is not supported on the platform.
 138   @retval EFI_NOT_FOUND         Binary image or table not found.
 139
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_GET_PLATFORM_INFO)(
 144   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 145   IN EFI_GET_PLATFORM_INFO_MODE          Mode,
 146   OUT VOID                               **Table,
 147   OUT UINTN                              *TableSize,
 148   OUT UINTN                              *Location,
 149   OUT UINTN                              *Alignment,
 150   IN  UINT16                             LegacySegment,
 151   IN  UINT16                             LegacyOffset
 152   );
 153
 154 /**
 155   Returns a buffer of handles for the requested sub-function.
 156
 157   @param  This                  Protocol instance pointer.
 158   @param  Mode                  Specifies what handle to return.
 159   @param  Type                  Type from Device Path for Handle to represent.
 160   @param  HandleBuffer          Handles of the device/controller in priority order
 161                                 with HandleBuffer[0] highest priority.
 162   @param  HandleCount           Number of handles in the buffer.
 163   @param  AdditionalData        Mode specific.
 164
 165   @retval EFI_SUCCESS           Handle is valid
 166   @retval EFI_UNSUPPORTED       Mode is not supported on the platform.
 167   @retval EFI_NOT_FOUND         Handle is not known
 168
 169 **/
 170 typedef
 171 EFI_STATUS
 172 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_GET_PLATFORM_HANDLE)(
 173   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 174   IN EFI_GET_PLATFORM_HANDLE_MODE        Mode,
 175   IN UINT16                              Type,
 176   OUT EFI_HANDLE                         **HandleBuffer,
 177   OUT UINTN                              *HandleCount,
 178   IN  VOID                               **AdditionalData OPTIONAL
 179   );
 180
 181 /**
 182   Load and initialize the Legacy BIOS SMM handler.
 183
 184   @param  This                   Protocol instance pointer.
 185   @param  EfiToLegacy16BootTable Pointer to Legacy16 boot table.
 186
 187   @retval EFI_SUCCESS           SMM code loaded.
 188   @retval EFI_DEVICE_ERROR      SMM code failed to load
 189
 190 **/
 191 typedef
 192 EFI_STATUS
 193 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_SMM_INIT)(
 194   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 195   IN  VOID                               *EfiToLegacy16BootTable
 196   );
 197
 198 /**
 199   Allows platform to perform any required action after a LegacyBios operation.
 200
 201   @param  This                  Protocol instance pointer.
 202   @param  Mode                  Specifies what handle to return.
 203   @param  Type                  Mode specific.
 204   @param  DeviceHandle          List of PCI devices in the system.
 205   @param  ShadowAddress         First free OpROM area, after other OpROMs have been dispatched.
 206   @param  Compatibility16Table  Pointer to Compatibility16Table.
 207   @param  AdditionalData        Mode specific Pointer to additional data returned - mode specific.
 208
 209   @retval EFI_SUCCESS           RomImage is valid
 210   @retval EFI_UNSUPPORTED       Mode is not supported on the platform.
 211
 212 **/
 213 typedef
 214 EFI_STATUS
 215 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_HOOKS)(
 216   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 217   IN EFI_GET_PLATFORM_HOOK_MODE          Mode,
 218   IN UINT16                              Type,
 219   IN  EFI_HANDLE                         DeviceHandle,
 220   IN  OUT UINTN                          *ShadowAddress,
 221   IN  EFI_COMPATIBILITY16_TABLE          *Compatibility16Table,
 222   IN  VOID                               **AdditionalData OPTIONAL
 223   );
 224
 225 /**
 226   Returns information associated with PCI IRQ routing.
 227
 228   @param  This                    Protocol instance pointer.
 229   @param  RoutingTable            Pointer to PCI IRQ Routing table.
 230   @param  RoutingTableEntries     Number of entries in table.
 231   @param  LocalPirqTable          $PIR table
 232   @param  PirqTableSize           $PIR table size
 233   @param  LocalIrqPriorityTable   List of interrupts in priority order to assign
 234   @param  IrqPriorityTableEntries Number of entries in priority table
 235
 236   @retval EFI_SUCCESS           Data was successfully returned.
 237
 238 **/
 239 typedef
 240 EFI_STATUS
 241 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_GET_ROUTING_TABLE)(
 242   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 243   OUT VOID                               **RoutingTable,
 244   OUT UINTN                              *RoutingTableEntries,
 245   OUT VOID                               **LocalPirqTable, OPTIONAL
 246   OUT UINTN                              *PirqTableSize, OPTIONAL
 247   OUT VOID                               **LocalIrqPriorityTable, OPTIONAL
 248   OUT UINTN                              *IrqPriorityTableEntries OPTIONAL
 249   );
 250
 251 /**
 252   Translates the given PIRQ accounting for bridge
 253
 254   @param  This                  Protocol instance pointer.
 255   @param  PciBus                PCI bus number for this device.
 256   @param  PciDevice             PCI device number for this device.
 257   @param  PciFunction           PCI function number for this device.
 258   @param  Pirq                  Input is PIRQ reported by device, output is true PIRQ.
 259   @param  PciIrq                The IRQ already assigned to the PIRQ or the IRQ to be
 260                                 assigned to the PIRQ.
 261
 262   @retval EFI_SUCCESS           The PIRQ was translated.
 263
 264 **/
 265 typedef
 266 EFI_STATUS
 267 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_TRANSLATE_PIRQ)(
 268   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 269   IN  UINTN                              PciBus,
 270   IN  UINTN                              PciDevice,
 271   IN  UINTN                              PciFunction,
 272   IN  OUT UINT8                          *Pirq,
 273   OUT UINT8                              *PciIrq
 274   );
 275
 276 /**
 277   Attempt to legacy boot the BootOption. If the EFI contexted has been
 278   compromised this function will not return.
 279
 280   @param  This                   Protocol instance pointer.
 281   @param  BbsDevicePath          EFI Device Path from BootXXXX variable.
 282   @param  BbsTable               Internal BBS table.
 283   @param  LoadOptionSize         Size of LoadOption in size.
 284   @param  LoadOption             LoadOption from BootXXXX variable
 285   @param  EfiToLegacy16BootTable Pointer to BootTable structure
 286
 287   @retval EFI_SUCCESS           Ready to boot.
 288
 289 **/
 290 typedef
 291 EFI_STATUS
 292 (EFIAPI *EFI_LEGACY_BIOS_PLATFORM_PREPARE_TO_BOOT)(
 293   IN EFI_LEGACY_BIOS_PLATFORM_PROTOCOL   *This,
 294   IN  BBS_BBS_DEVICE_PATH                *BbsDevicePath,
 295   IN  VOID                               *BbsTable,
 296   IN  UINT32                             LoadOptionsSize,
 297   IN  VOID                               *LoadOptions,
 298   IN  VOID                               *EfiToLegacy16BootTable
 299   );
 300
 301 /**
 302   @par Protocol Description:
 303   Abstracts the platform portion of the traditional BIOS.
 304
 305   @param GetPlatformInfo
 306   Gets binary data or other platform information.
 307
 308   @param GetPlatformHandle
 309   Returns a buffer of all handles matching the requested subfunction.
 310
 311   @param SmmInit
 312   Loads and initializes the traditional BIOS SMM handler.
 313
 314   @param PlatformHooks
 315   Allows platform to perform any required actions after a LegacyBios operation.
 316
 317   @param GetRoutingTable
 318   Gets $PIR table.
 319
 320   @param TranslatePirq
 321   Translates the given PIRQ to the final value after traversing any PCI bridges.
 322
 323   @param PrepareToBoot
 324   Final platform function before the system attempts to boot to a traditional OS.
 325
 326 **/
 327 struct _EFI_LEGACY_BIOS_PLATFORM_PROTOCOL {
 328   EFI_LEGACY_BIOS_PLATFORM_GET_PLATFORM_INFO    GetPlatformInfo;
 329   EFI_LEGACY_BIOS_PLATFORM_GET_PLATFORM_HANDLE  GetPlatformHandle;
 330   EFI_LEGACY_BIOS_PLATFORM_SMM_INIT             SmmInit;
 331   EFI_LEGACY_BIOS_PLATFORM_HOOKS                PlatformHooks;
 332   EFI_LEGACY_BIOS_PLATFORM_GET_ROUTING_TABLE    GetRoutingTable;
 333   EFI_LEGACY_BIOS_PLATFORM_TRANSLATE_PIRQ       TranslatePirq;
 334   EFI_LEGACY_BIOS_PLATFORM_PREPARE_TO_BOOT      PrepareToBoot;
 335 };
 336
 337 extern EFI_GUID gEfiLegacyBiosPlatformProtocolGuid;
 338
 339 #endif