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