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