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