Include/Protocol/LegacyBios.h

   1 /** @file
   2   The EFI Legacy BIOS Protocol is used to abstract legacy Option ROM usage
   3   under EFI and Legacy OS boot.
   4
   5   Note: The names for EFI_IA32_REGISTER_SET elements were picked to follow
   6   well known naming conventions.
   7
   8   Thunk - A thunk is a transition from one processor mode to another. A Thunk
   9   is a transition from native EFI mode to 16-bit mode. A reverse thunk
  10   would be a transition from 16-bit mode to native EFI mode.
  11
  12   You most likely should not use this protocol! Find the EFI way to solve the
  13   problem to make your code portable
  14
  15   Copyright (c) 2007, Intel Corporation
  16   All rights reserved. This program and the accompanying materials
  17   are licensed and made available under the terms and conditions of the BSD License
  18   which accompanies this distribution.  The full text of the license may be found at
  19   http://opensource.org/licenses/bsd-license.php
  20
  21   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  22   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  23
  24   Module Name:  LegacyBios.h
  25
  26   @par Revision Reference:
  27   This protocol is defined in Framework for EFI Compatibility Support Module spec
  28   Version 0.96
  29
  30 **/
  31
  32 #ifndef _EFI_LEGACY_BIOS_H_
  33 #define _EFI_LEGACY_BIOS_H_
  34
  35 #define EFI_LEGACY_BIOS_PROTOCOL_GUID \
  36   { \
  37     0xdb9a1e3d, 0x45cb, 0x4abb, {0x85, 0x3b, 0xe5, 0x38, 0x7f, 0xdb, 0x2e, 0x2d } \
  38   }
  39
  40 typedef struct _EFI_LEGACY_BIOS_PROTOCOL EFI_LEGACY_BIOS_PROTOCOL;
  41
  42 //
  43 /// @bug: These macros appear in no specifications and are kept for backward
  44 //        compatibility only.
  45 // Convert from 32-bit address (_Adr) to Segment:Offset 16-bit form
  46 //
  47 #define EFI_SEGMENT(_Adr)     (UINT16) ((UINT16) (((UINTN) (_Adr)) >> 4) & 0xf000)
  48 #define EFI_OFFSET(_Adr)      (UINT16) (((UINT16) ((UINTN) (_Adr))) & 0xffff)
  49 #define BYTE_GRANULARITY      0x01
  50 #define WORD_GRANULARITY      0x02
  51 #define DWORD_GRANULARITY     0x04
  52 #define QWORD_GRANULARITY     0x08
  53 #define PARAGRAPH_GRANULARITY 0x10
  54
  55 #define CARRY_FLAG            0x01
  56
  57 //*********************************************************
  58 // EFI_EFLAGS_REG
  59 //*********************************************************
  60 typedef struct {
  61   UINT32 CF:1;
  62   UINT32 Reserved1:1;
  63   UINT32 PF:1;
  64   UINT32 Reserved2:1;
  65   UINT32 AF:1;
  66   UINT32 Reserved3:1;
  67   UINT32 ZF:1;
  68   UINT32 SF:1;
  69   UINT32 TF:1;
  70   UINT32 IF:1;
  71   UINT32 DF:1;
  72   UINT32 OF:1;
  73   UINT32 IOPL:2;
  74   UINT32 NT:1;
  75   UINT32 Reserved4:2;
  76   UINT32 VM:1;
  77   UINT32 Reserved5:14;
  78 } EFI_EFLAGS_REG;
  79
  80 //*********************************************************
  81 // EFI_DWORD_REGS
  82 //*********************************************************
  83
  84 typedef struct {
  85     UINT32           EAX;
  86     UINT32           EBX;
  87     UINT32           ECX;
  88     UINT32           EDX;
  89     UINT32           ESI;
  90     UINT32           EDI;
  91     EFI_EFLAGS_REG   EFlags;
  92     UINT16           ES;
  93     UINT16           CS;
  94     UINT16           SS;
  95     UINT16           DS;
  96     UINT16           FS;
  97     UINT16           GS;
  98     UINT32           EBP;
  99     UINT32           ESP;
 100 } EFI_DWORD_REGS;
 101
 102 //*******************************************
 103 // EFI_FLAGS_REG
 104 //*******************************************
 105 typedef struct {
 106   UINT16     CF:1;
 107   UINT16     Reserved1:1;
 108   UINT16     PF:1;
 109   UINT16     Reserved2:1;
 110   UINT16     AF:1;
 111   UINT16     Reserved3:1;
 112   UINT16     ZF:1;
 113   UINT16     SF:1;
 114   UINT16     TF:1;
 115   UINT16     IF:1;
 116   UINT16     DF:1;
 117   UINT16     OF:1;
 118   UINT16     IOPL:2;
 119   UINT16     NT:1;
 120   UINT16     Reserved4:1;
 121 } EFI_FLAGS_REG;
 122
 123
 124 //*********************************************************
 125 // EFI_WORD_REGS
 126 //*********************************************************
 127
 128 typedef struct {
 129     UINT16           AX;
 130     UINT16           ReservedAX;
 131     UINT16           BX;
 132     UINT16           ReservedBX;
 133     UINT16           CX;
 134     UINT16           ReservedCX;
 135     UINT16           DX;
 136     UINT16           ReservedDX;
 137     UINT16           SI;
 138     UINT16           ReservedSI;
 139     UINT16           DI;
 140     UINT16           ReservedDI;
 141     EFI_FLAGS_REG    Flags;
 142     UINT16           ReservedFlags;
 143     UINT16           ES;
 144     UINT16           CS;
 145     UINT16           SS;
 146     UINT16           DS;
 147     UINT16           FS;
 148     UINT16           GS;
 149     UINT16           BP;
 150     UINT16           ReservedBP;
 151     UINT16           SP;
 152     UINT16           ReservedSP;
 153 } EFI_WORD_REGS;
 154
 155 //*********************************************************
 156 // EFI_BYTE_REGS
 157 //*********************************************************
 158
 159 typedef struct {
 160     UINT8   AL, AH;
 161     UINT16  ReservedAX;
 162     UINT8   BL, BH;
 163     UINT16  ReservedBX;
 164     UINT8   CL, CH;
 165     UINT16  ReservedCX;
 166     UINT8   DL, DH;
 167     UINT16  ReservedDX;
 168 } EFI_BYTE_REGS;
 169
 170 typedef union {
 171   EFI_DWORD_REGS  E;
 172   EFI_WORD_REGS   X;
 173   EFI_BYTE_REGS   H;
 174 } EFI_IA32_REGISTER_SET;
 175
 176 /**
 177   Thunk to 16-bit real mode and execute a software interrupt with a vector
 178   of BiosInt. Regs will contain the 16-bit register context on entry and
 179   exit.
 180
 181   @param  This                  Protocol instance pointer.
 182   @param  BiosInt               Processor interrupt vector to invoke
 183   @param  Reg                   Register contexted passed into (and returned) from thunk to
 184                                 16-bit mode
 185
 186   @retval FALSE                 Thunk completed, and there were no BIOS errors in the target code.
 187                                 See Regs for status.
 188   @retval TRUE                  There was a BIOS erro in the target code.
 189
 190 **/
 191 typedef
 192 BOOLEAN
 193 (EFIAPI *EFI_LEGACY_BIOS_INT86) (
 194   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 195   IN  UINT8                           BiosInt,
 196   IN OUT  EFI_IA32_REGISTER_SET       *Regs
 197   );
 198
 199 /**
 200   Thunk to 16-bit real mode and call Segment:Offset. Regs will contain the
 201   16-bit register context on entry and exit. Arguments can be passed on
 202   the Stack argument
 203
 204   @param  This                  Protocol instance pointer.
 205   @param  Segment               Segemnt of 16-bit mode call
 206   @param  Offset                Offset of 16-bit mdoe call
 207   @param  Reg                   Register contexted passed into (and returned) from thunk to
 208                                 16-bit mode
 209   @param  Stack                 Caller allocated stack used to pass arguments
 210   @param  StackSize             Size of Stack in bytes
 211
 212   @retval FALSE                 Thunk completed, and there were no BIOS errors in the target code.
 213                                 See Regs for status.
 214   @retval TRUE                  There was a BIOS erro in the target code.
 215
 216 **/
 217 typedef
 218 BOOLEAN
 219 (EFIAPI *EFI_LEGACY_BIOS_FARCALL86) (
 220   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 221   IN  UINT16                          Segment,
 222   IN  UINT16                          Offset,
 223   IN  EFI_IA32_REGISTER_SET           *Regs,
 224   IN  VOID                            *Stack,
 225   IN  UINTN                           StackSize
 226   );
 227
 228 /**
 229   Test to see if a legacy PCI ROM exists for this device. Optionally return
 230   the Legacy ROM instance for this PCI device.
 231
 232   @param  This                  Protocol instance pointer.
 233   @param  PciHandle             The PCI PC-AT OPROM from this devices ROM BAR will be loaded
 234   @param  RomImage              Return the legacy PCI ROM for this device
 235   @param  RomSize               Size of ROM Image
 236   @param  Flags                 Indicates if ROM found and if PC-AT.
 237
 238   @retval EFI_SUCCESS           Legacy Option ROM availible for this device
 239   @retval EFI_UNSUPPORTED       Legacy Option ROM not supported.
 240
 241 **/
 242 typedef
 243 EFI_STATUS
 244 (EFIAPI *EFI_LEGACY_BIOS_CHECK_ROM) (
 245   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 246   IN  EFI_HANDLE                      PciHandle,
 247   OUT VOID                            **RomImage, OPTIONAL
 248   OUT UINTN                           *RomSize, OPTIONAL
 249   OUT UINTN                           *Flags
 250   );
 251
 252 /**
 253   Load a legacy PC-AT OPROM on the PciHandle device. Return information
 254   about how many disks were added by the OPROM and the shadow address and
 255   size. DiskStart & DiskEnd are INT 13h drive letters. Thus 0x80 is C:
 256
 257   @param  This                  Protocol instance pointer.
 258   @param  PciHandle             The PCI PC-AT OPROM from this devices ROM BAR will be loaded.
 259                                 This value is NULL if RomImage is non-NULL. This is the normal
 260                                 case.
 261   @param  RomImage              A PCI PC-AT ROM image. This argument is non-NULL if there is
 262                                 no hardware associated with the ROM and thus no PciHandle,
 263                                 otherwise is must be NULL.
 264                                 Example is PXE base code.
 265   @param  Flags                 Return Status if ROM was found and if was Legacy OPROM.
 266   @param  DiskStart             Disk number of first device hooked by the ROM. If DiskStart
 267                                 is the same as DiskEnd no disked were hooked.
 268   @param  DiskEnd               Disk number of the last device hooked by the ROM.
 269   @param  RomShadowAddress      Shadow address of PC-AT ROM
 270   @param  RomShadowSize         Size of RomShadowAddress in bytes
 271
 272   @retval EFI_SUCCESS           Thunk completed, see Regs for status.
 273   @retval EFI_INVALID_PARAMETER PciHandle not found
 274
 275 **/
 276 typedef
 277 EFI_STATUS
 278 (EFIAPI *EFI_LEGACY_BIOS_INSTALL_ROM) (
 279   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 280   IN  EFI_HANDLE                      PciHandle,
 281   IN  VOID                            **RomImage,
 282   OUT UINTN                           *Flags,
 283   OUT UINT8                           *DiskStart, OPTIONAL
 284   OUT UINT8                           *DiskEnd, OPTIONAL
 285   OUT VOID                            **RomShadowAddress, OPTIONAL
 286   OUT UINT32                          *ShadowedRomSize OPTIONAL
 287   );
 288
 289 /**
 290   Attempt to legacy boot the BootOption. If the EFI contexted has been
 291   compromised this function will not return.
 292
 293   @param  This                  Protocol instance pointer.
 294   @param  BootOption            EFI Device Path from BootXXXX variable.
 295   @param  LoadOptionSize        Size of LoadOption in size.
 296   @param  LoadOption            LoadOption from BootXXXX variable
 297
 298   @retval EFI_SUCCESS           Removable media not present
 299
 300 **/
 301 typedef
 302 EFI_STATUS
 303 (EFIAPI *EFI_LEGACY_BIOS_BOOT) (
 304   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 305   IN  BBS_BBS_DEVICE_PATH             *BootOption,
 306   IN  UINT32                          LoadOptionsSize,
 307   IN  VOID                            *LoadOptions
 308   );
 309
 310 /**
 311   Update BDA with current Scroll, Num & Cap lock LEDS
 312
 313   @param  This                  Protocol instance pointer.
 314   @param  Leds                  Status of current Scroll, Num & Cap lock LEDS
 315                                 Bit 0 is Scroll Lock 0 = Not locked
 316                                 Bit 1 is Num Lock
 317                                 Bit 2 is Caps Lock
 318
 319   @retval EFI_SUCCESS           Removable media not present
 320
 321 **/
 322 typedef
 323 EFI_STATUS
 324 (EFIAPI *EFI_LEGACY_BIOS_UPDATE_KEYBOARD_LED_STATUS) (
 325   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 326   IN  UINT8                           Leds
 327   );
 328
 329 /**
 330   Retrieve legacy BBS info and assign boot priority.
 331
 332   @param  This                  Protocol instance pointer.
 333   @param  HddCount              Number of HDD_INFO structures
 334   @param  HddInfo               Onboard IDE controller information
 335   @param  BbsCount              Number of BBS_TABLE structures
 336   @param  BbsTable              List BBS entries
 337
 338   @retval EFI_SUCCESS           Tables returned
 339
 340 **/
 341 typedef
 342 EFI_STATUS
 343 (EFIAPI *EFI_LEGACY_BIOS_GET_BBS_INFO) (
 344   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 345   OUT UINT16                          *HddCount,
 346   OUT HDD_INFO                        **HddInfo,
 347   OUT UINT16                          *BbsCount,
 348   IN OUT BBS_TABLE                    **BbsTable
 349   );
 350
 351 /**
 352   Assign drive number to legacy HDD drives prior to booting an EFI
 353   aware OS so the OS can access drives without an EFI driver.
 354
 355   @param  This                  Protocol instance pointer.
 356   @param  BbsCount              Number of BBS_TABLE structures
 357   @param  BbsTable              List BBS entries
 358
 359   @retval EFI_SUCCESS           Drive numbers assigned
 360
 361 **/
 362 typedef
 363 EFI_STATUS
 364 (EFIAPI *EFI_LEGACY_BIOS_PREPARE_TO_BOOT_EFI) (
 365   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 366   OUT UINT16                          *BbsCount,
 367   OUT BBS_TABLE                       **BbsTable
 368   );
 369
 370 /**
 371   To boot from an unconventional device like parties and/or execute
 372   HDD diagnostics.
 373
 374   @param  This                  Protocol instance pointer.
 375   @param  Attributes            How to interpret the other input parameters
 376   @param  BbsEntry              The 0-based index into the BbsTable for the parent
 377                                 device.
 378   @param  BeerData              Pointer to the 128 bytes of ram BEER data.
 379   @param  ServiceAreaData       Pointer to the 64 bytes of raw Service Area data. The
 380                                 caller must provide a pointer to the specific Service
 381                                 Area and not the start all Service Areas.
 382
 383   EFI_INVALID_PARAMETER if error. Does NOT return if no error.
 384
 385 **/
 386 typedef
 387 EFI_STATUS
 388 (EFIAPI *EFI_LEGACY_BIOS_BOOT_UNCONVENTIONAL_DEVICE) (
 389   IN EFI_LEGACY_BIOS_PROTOCOL         *This,
 390   IN UDC_ATTRIBUTES                   Attributes,
 391   IN UINTN                            BbsEntry,
 392   IN VOID                             *BeerData,
 393   IN VOID                             *ServiceAreaData
 394   );
 395
 396 /**
 397   Shadow all legacy16 OPROMs that haven't been shadowed.
 398   Warning: Use this with caution. This routine disconnects all EFI
 399   drivers. If used externally then caller must re-connect EFI
 400   drivers.
 401
 402   @retval EFI_SUCCESS           OPROMs shadowed
 403
 404 **/
 405 typedef
 406 EFI_STATUS
 407 (EFIAPI *EFI_LEGACY_BIOS_SHADOW_ALL_LEGACY_OPROMS) (
 408   IN EFI_LEGACY_BIOS_PROTOCOL *This
 409   );
 410
 411 /**
 412   Get a region from the LegacyBios for S3 usage.
 413
 414   @param  This                  Protocol instance pointer.
 415   @param  LegacyMemorySize      Size of required region
 416   @param  Region                Region to use.
 417                                 00 = Either 0xE0000 or 0xF0000 block
 418                                 Bit0 = 1 0xF0000 block
 419                                 Bit1 = 1 0xE0000 block
 420   @param  Alignment             Address alignment. Bit mapped. First non-zero
 421                                 bit from right is alignment.
 422   @param  LegacyMemoryAddress   Region Assigned
 423
 424   @retval EFI_SUCCESS           Region assigned
 425   @retval Other                 Region not assigned
 426
 427 **/
 428 typedef
 429 EFI_STATUS
 430 (EFIAPI *EFI_LEGACY_BIOS_GET_LEGACY_REGION) (
 431   IN EFI_LEGACY_BIOS_PROTOCOL *This,
 432   IN    UINTN                 LegacyMemorySize,
 433   IN    UINTN                 Region,
 434   IN    UINTN                 Alignment,
 435   OUT   VOID                  **LegacyMemoryAddress
 436   );
 437
 438 /**
 439   Get a region from the LegacyBios for Tiano usage. Can only be invoked once.
 440
 441   @param  This                  Protocol instance pointer.
 442   @param  LegacyMemorySize      Size of data to copy
 443   @param  LegacyMemoryAddress   Legacy Region destination address
 444                                 Note: must be in region assigned by
 445                                 LegacyBiosGetLegacyRegion
 446   @param  LegacyMemorySourceAddress
 447                                 Source of data
 448
 449   @retval EFI_SUCCESS           Region assigned
 450   @retval EFI_ACCESS_DENIED     Destination outside assigned region
 451
 452 **/
 453 typedef
 454 EFI_STATUS
 455 (EFIAPI *EFI_LEGACY_BIOS_COPY_LEGACY_REGION) (
 456   IN EFI_LEGACY_BIOS_PROTOCOL *This,
 457   IN    UINTN                 LegacyMemorySize,
 458   IN    VOID                  *LegacyMemoryAddress,
 459   IN    VOID                  *LegacyMemorySourceAddress
 460   );
 461
 462 /**
 463   @par Protocol Description:
 464   Abstracts the traditional BIOS from the rest of EFI. The LegacyBoot()
 465   member function allows the BDS to support booting a traditional OS.
 466   EFI thunks drivers that make EFI bindings for BIOS INT services use
 467   all the other member functions.
 468
 469   @param Int86
 470   Performs traditional software INT. See the Int86() function description.
 471
 472   @param FarCall86
 473   Performs a far call into Compatibility16 or traditional OpROM code.
 474
 475   @param CheckPciRom
 476   Checks if a traditional OpROM exists for this device.
 477
 478   @param InstallPciRom
 479   Loads a traditional OpROM in traditional OpROM address space.
 480
 481   @param LegacyBoot
 482   Boots a traditional OS.
 483
 484   @param UpdateKeyboardLedStatus
 485   Updates BDA to reflect the current EFI keyboard LED status.
 486
 487   @param GetBbsInfo
 488   Allows an external agent, such as BIOS Setup, to get the BBS data.
 489
 490   @param ShadowAllLegacyOproms
 491   Causes all legacy OpROMs to be shadowed.
 492
 493   @param PrepareToBootEfi
 494   Performs all actions prior to boot. Used when booting an EFI-aware OS
 495   rather than a legacy OS.
 496
 497   @param GetLegacyRegion
 498   Allows EFI to reserve an area in the 0xE0000 or 0xF0000 block.
 499
 500   @param CopyLegacyRegion
 501   Allows EFI to copy data to the area specified by GetLegacyRegion.
 502
 503   @param BootUnconventionalDevice
 504   Allows the user to boot off an unconventional device such as a PARTIES partition.
 505
 506 **/
 507 struct _EFI_LEGACY_BIOS_PROTOCOL {
 508   EFI_LEGACY_BIOS_INT86                       Int86;
 509   EFI_LEGACY_BIOS_FARCALL86                   FarCall86;
 510   EFI_LEGACY_BIOS_CHECK_ROM                   CheckPciRom;
 511   EFI_LEGACY_BIOS_INSTALL_ROM                 InstallPciRom;
 512   EFI_LEGACY_BIOS_BOOT                        LegacyBoot;
 513   EFI_LEGACY_BIOS_UPDATE_KEYBOARD_LED_STATUS  UpdateKeyboardLedStatus;
 514   EFI_LEGACY_BIOS_GET_BBS_INFO                GetBbsInfo;
 515   EFI_LEGACY_BIOS_SHADOW_ALL_LEGACY_OPROMS    ShadowAllLegacyOproms;
 516   EFI_LEGACY_BIOS_PREPARE_TO_BOOT_EFI         PrepareToBootEfi;
 517   EFI_LEGACY_BIOS_GET_LEGACY_REGION           GetLegacyRegion;
 518   EFI_LEGACY_BIOS_COPY_LEGACY_REGION          CopyLegacyRegion;
 519   EFI_LEGACY_BIOS_BOOT_UNCONVENTIONAL_DEVICE  BootUnconventionalDevice;
 520 };
 521
 522 extern EFI_GUID gEfiLegacyBiosProtocolGuid;
 523
 524 #endif