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