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