EFI LEGACY BIOS PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Abstracts the traditional BIOS from the rest of EFI. The LegacyBoot() member function allows the BDS to support booting a traditional OS. EFI thunks drivers that make EFI bindings for BIOS INT services use all the other member functions.

Contents

GUID

#define EFI_LEGACY_BIOS_PROTOCOL_GUID \
  { 0xdb9a1e3d, 0x45cb, 0x4abb, 0x85, 0x3b, 0xe5, 0x38, 0x7f, 0xdb, 0x2e, 0x2d}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(LegacyBios)

extern EFI_GUID gEfiLegacyBiosProtocolGuid;

typedef struct _EFI_LEGACY_BIOS_PROTOCOL {
  EFI_LEGACY_BIOS_INT86                      Int86;
  EFI_LEGACY_BIOS_FARCALL86                  FarCall86;
  EFI_LEGACY_BIOS_CHECK_ROM                  CheckPciRom;
  EFI_LEGACY_BIOS_INSTALL_ROM                InstallPciRom;
  EFI_LEGACY_BIOS_BOOT                       LegacyBoot;
  EFI_LEGACY_BIOS_UPDATE_KEYBOARD_LED_STATUS UpdateKeyboardLedStatus;
  EFI_LEGACY_BIOS_GET_BBS_INFO               GetBbsInfo;
  EFI_LEGACY_BIOS_SHADOW_ALL_LEGACY_OPROMS   ShadowAllLegacyOproms;
  EFI_LEGACY_BIOS_PREPARE_TO_BOOT_EFI        PrepareToBootEFI;
  EFI_LEGACY_BIOS_GET_LEGACY_REGION          GetLegacyRegion;
  EFI_LEGACY_BIOS_COPY_LEGACY_REGION         CopyLegacyRegion;
  EFI_LEGACY_BIOS_BOOT_UNCONVENTIONAL_DEVICE BootUnconventionalDevice;
} EFI_LEGACY_BIOS_PROTOCOL;

Members

Member Description
Int86 Performs traditional software INT.
FarCall86 Performs a far call into Compatibility16 or traditional OpROM code.
CheckPciRom Checks if a traditional OpROM exists for this device.
InstallPciRom Loads a traditional OpROM in traditional OpROM address space.
LegacyBoot Boots a traditional OS. See the LegacyBoot() function description.
UpdateKeyboardLedStatus Updates BDA to reflect the current EFI keyboard LED status.
GetBbsInfo Allows an external agent, such as BIOS Setup, to get the BBS data.
ShadowAllLegacyOproms Causes all legacy OpROMs to be shadowed.
PrepareToBootEfi Performs all actions prior to boot. Used when booting an EFI-aware OS rather than a legacy OS.
GetLegacyRegion Allows EFI to reserve an area in the 0xE0000 or 0xF0000 block.
CopyLegacyRegion Allows EFI to copy data to the area specified by GetLegacyRegion.
BootUnconventionalDevice Allows the user to boot off an unconventional device such as a PARTIES partition.

Description

The EFI_LEGACY_BIOS_PROTOCOL is used to abstract the traditional BIOS for UEFI.

Int86()

Issues a traditional software INT.

Prototype
typedef BOOLEAN (EFIAPI *EFI_LEGACY_BIOS_INT86) ( 

 IN     EFI_LEGACY_BIOS_PROTOCOL *This,
 IN     UINT8                    BiosInt,
 IN OUT EFI_IA32_REGISTER_SET    *Regs 
 );

Parameters
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance. BiosInt The software INT requested. Regs The IA-32 registers.

Description
This function issues a software INT and gets the results.

Status Codes Returned

Status Code Description
FALSE INT completed. See Regs for status.
TRUE INT was not completed.

FarCall86()

Performs a far call into Compatibility16 or traditional OpROM code.

Prototype

typedef
BOOLEAN
(EFIAPI *EFI_LEGACY_BIOS_FARCALL86) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This,
  IN UINT16                   Segment,
  IN UINT16                   Offset,
  IN EFI_IA32_REGISTER_SET    *Regs,
  IN VOID                     *Stack,
  IN UINTN                    StackSize
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
Segment Segment of 16-bit mode call.
Offset Offset of 16-bit mode call.
Regs The IA-32 registers.
Stack Caller-allocated stack that is used to pass arguments.
StackSize Size of Stack in bytes.

Description
This function performs a far call into Compatibility16 or traditional Option ROM code at the specified Segment:Offset.

Status Codes Returned

Status Code Description
FALSE FarCall() completed. See Regs for status.
TRUE FarCall() was not completed.

CheckPciRom()

Tests to see if a traditional PCI ROM exists for this device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_CHECK_ROM) (
  IN  EFI_LEGACY_BIOS_PROTOCOL *This,
  IN  EFI_HANDLE               PciHandle
  OUT VOID                     **RomImage, OPTIONAL
  OUT UINTN                    *RomSize, OPTIONAL
  OUT UINTN                    *Flags
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
PciHandle The handle for this device.
RomImage A pointer to the returned byte of the ROM image. If NULL, then no value is returned.
RomSize A pointer to the returned size of the ROM image. If NULL, then no value is returned.
Flags A pointer to the returned type of ROM discovered. Multiple bits can be set, as follows:
  • 00 = No ROM
  • 01 = ROM Found
  • 02 = ROM is a valid legacy ROM

Description
This function tests to see if a traditional PCI ROM exists for this device.

Status Codes Returned

Status Code Description
EFI_SUCCESS A traditional Option ROM is available for this device.
EFI_UNSUPPORTED A traditional Option ROM is not supported.

InstallPciRom()

Shadows an Option ROM.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_INSTALL_ROM) (
  IN  EFI_LEGACY_BIOS_PROTOCOL *This,
  IN  EFI_HANDLE               PciHandle,
  IN  VOID                     **RomImage,
  OUT UINTN                    *Flags
  OUT UINT8                    *DiskStart, OPTIONAL
  OUT UINT8                    *DiskEnd, OPTIONAL
  OUT VOID                     **RomShadowAddress, OPTIONAL
  OUT UINT32                   *ShadowedRomSize OPTIONAL
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
PciHandle The PCI PC-AT* Option ROM from this device’s ROM BAR will be loaded.
RomImage A pointer to a PCI PC-AT ROM option ROM image. This argument is non-NULL if there is no hardware associated with the ROM and thus no PciHandle; otherwise it must be NULL. An example is the PXE base code.
Flags The type of ROM discovered. Multiple bits can be set, as follows:
  • 00 = No ROM.
  • 01 = ROM found.
  • 02 = ROM is a valid legacy ROM.
DiskStart Disk number of the first device hooked by the ROM. If DiskStart is the same as DiskEnd, no disks were hooked.
DiskEnd Disk number of the last device hooked by the ROM.
RomShadowAddress A pointer to the pointer to the shadowed PC-AT ROM. If NULL, then no value is returned.
ShadowedRomSize A pointer to the size of hte shadowed PC-AT ROM. If NULL, then no value is returned.

Description
This function loads a traditional PC-AT Option ROM on the PciHandle device and returns information about how many disks were added by the Option ROM and the shadow address and size. DiskStart and DiskEnd are INT13h drive letters. Thus 0x80 is C:.

Status Codes Returned

Status Code Description
EFI_SUCCESS The Option ROM was shadowed
EFI_UNSUPPORTED The PciHandle was not found

LegacyBoot()

Boots a traditional OS

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_BOOT) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This,
  IN BBS_BBS_DEVICE_PATH      *BootOption,
  IN UINT32                   LoadOptionsSize,
  IN VOID                     *LoadOptions
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
BootOption The EFI device path from BootXXXX variable.
LoadOptionSize Size of LoadOption.
LoadOption The load option from BootXXXX variable.


Description
This function attempts to traditionally boot the specified BootOption. If the UEFI context has been compromised, this function will not return. This procedure is not used for loading an EFI-aware OS off a traditional device. The following actions occur:

  • Get SMBIOS data structures, convert them to a traditional format, and copy to Compatibility16.
  • Get a pointer to ACPI data structures and copy the Compatibility16 RSD PTR to F0000 block.
  • Find the traditional SMI handler from a firmware volume and register the traditional SMI handler with the SMI handler.
  • Build onboard IDE information and pass this information to the Compatibility16 code.
  • Make sure all PCI Interrupt Line registers are programmed to match 8259.
  • Reconfigure SIO devices from EFI mode (polled) into traditional mode (interrupt driven).
  • Shadow all PCI ROMs.
  • Set up BDA and EBDA standard areas before the legacy boot.
  • Construct the Compatibility16 boot memory map and pass it to the Compatibility16 code.
  • Invoke the Compatibility16 table function Compatibility16PrepareToBoot(). This invocation causes a thunk into the Compatibility16 code, which sets all appropriate internal data structures. The boot device list is a parameter.
  • Invoke the Compatibility16 Table function Compatibility16Boot(). This invocation causes a thunk into the Compatibility16 code, which does an INT19.
  • If the Compatibility16Boot() function returns, then the boot failed in a graceful manner—i.e., EFI code is still valid. An ungraceful boot failure causes a reset because the state of EFI code is unknown.

Status Codes Returned

Status Code Description
EFI_DEVICE_ERROR Failed to boot from any boot device and memory is uncorrupted. Note: This function normally never returns. It will either boot the OS or reset the system if memory has been "corrupted" by loading a boot sector and passing control to it.

UpdateKeyboardLedStatus()

Updates the BDA to reflect status of the Scroll Lock, Num Lock, and Caps Lock keys and LEDs.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_UPDATE_KEYBOARD_LED_STATUS) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This,
  IN UINT8                     Leds
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
Leds Current LED status, as follows:
  • Bit 0 – Scroll Lock 0 = Off
  • Bit 1 – Num Lock
  • Bit 2 – Caps Lock

Description
This function takes the Leds input parameter and sets/resets the BDA accordingly. Leds is also passed to Compatibility16 code, in case any special processing is required. This function is normally called from EFI Setup drivers that handle user-selectable keyboard options such as boot with NUM LOCK on/off. This function does not touch the keyboard or keyboard LEDs but only the BDA.

Status Codes Returned

Status Code Description
EFI_SUCCESS The BDA was updated successfully.

GetBbsInfo()

Presents BBS information to external agents.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_GET_BBS_INFO) (
  IN     EFI_LEGACY_BIOS_PROTOCOL *This,
  OUT    UINT16                   *HddCount,
  OUT    HDD_INFO                **HddInfo,
  OUT    UINT16                   *BbsCount,
  IN OUT BBS_TABLE                **BbsTable
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
HddCount Number of HDD_INFO structures.
HddInfo Onboard IDE controller information.
BbsCount Number of BBS_TABLE structures.
BbsTable BBS entry.

Description
This function presents the internal BBS data structures to external agents such as BIOS Setup and allows them to assign boot priorities.

Status Codes Returned

Status Code Description
EFI_SUCCESS Tables returned successfully.

ShadowAllLegacyOproms()

Allows external agents to force loading of all legacy OpROMs. This function can be invoked before GetBbsInfo() to ensure all devices are counted.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_SHADOW_ALL_LEGACY_OPROMS) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.

Description
This function forces loading and invocation of the legacy OpROMs, which causes the BBS table to be updated.

Status Codes Returned

Status Code Description
EFI_SUCCESS Tables returned successfully.

PrepareToBootEfi()

This function is called when booting an EFI-aware OS with legacy hard disks. The legacy hard disks may or may not be the boot device but will be accessed by the EFI-aware OS.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_PREPARE_TO_BOOT) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.

Description
This function is called when booting an EFI-aware OS with legacy hard disks. The Compatibility16 code needs to assign drive numbers for BBS entries. Use LegacyBoot() for booting a legacy OS.

Status Codes Returned

Status Code Description
EFI_SUCCESS Tables returned successfully.

GetLegacyRegion()

This function is called when EFI needs to reserve an area in the 0xE0000 or 0xF0000 64 KB blocks.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_GET_LEGACY_REGION) (
  IN  EFI_LEGACY_BIOS_PROTOCOL *This,
  IN  UINTN                    LegacyMemorySize,
  IN  UINTN                    Region,
  IN  UINTN                    Alignment,
  OUT VOID                     *LegacyMemoryAddress
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
LegacyMemorySize Requested size in bytes of the region.
Region Requested region.
  • 0 = Either 0xE0000 or 0xF0000 blocks.
  • 1 = 0xF0000 block
  • 2 = 0xE0000 block
Alignment Bit-mapped value specifying the address alignment of the requested region. The first nonzero value from the right is alignment.
LegacyMemoryAddress A pointer to the returned assigned address.

Description
This function is called when EFI needs to reserve an area in the 0xE0000 or 0xF0000 64 KB blocks. This function may be invoked only once. Use CopyLegacyRegion() to move data to the returned region.

Status Codes Returned

Status Code Description
EFI_SUCCESS The requested region was assigned.
EFI_ACCESS_DENIED The function was previously invoked.
Other The requested region was not assigned.

CopyLegacyRegion()

This function is called when copying data to the region assigned by GetLegacyRegion().

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_COPY_LEGACY_REGION) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This,
  IN UINTN                    LegacyMemorySize,
  IN VOID                     *LegacyMemoryAddress,
  IN VOID                     *LegacyMemorySourceAddress
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
LegacyMemorySize Size in bytes of the memory to copy.
LegacyMemoryAddress The location within the region returned by GetLegacyRegion().
LegacyMemorySourceAddress Source of the data to copy.

Description
This function is called when copying data to the region that was assigned by GetLegacyRegion(). It may be invoked multiple times. This function performs boundary checking via information passed into the GetLegacyRegion(). The user is responsible for any internal checking, if this function is invoked multiple times.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was copied successfully.
EFI_ACCESS_DENIED Either the starting or ending address is out of bounds.

BootUnconventionalDevice()

This function is called when either booting to an unconventional device such as a PARTIES partition and/or executing hard disk diagnostics.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_BIOS_BOOT_UNCONVENTIONAL_DEVICE) (
  IN EFI_LEGACY_BIOS_PROTOCOL *This,
  IN UDC_ATTRIBUTES           Attributes,
  IN UINTN                    BbsEntry,
  IN VOID                     *BeerData,
  IN VOID                     *ServiceAreaData
  );

Parameters

Parameter Description
This Indicates the EFI_LEGACY_BIOS_PROTOCOL instance.
Attributes Flags used to interpret the rest of the input parameters.
BbsEntry The zero-based index into the BbsTable for the parent device.
BeerData Pointer to the 128 bytes of raw Beer data.
ServiceAreaData Pointer to the 64 bytes of raw service area data. It is up to the caller to select the appropriate service area and point to it.

Description
This function is called when booting from an unconventional device such as a PARTIES partition and/or executing hard disk diagnostics. All other BbsTable entries are set to ignore and, depending upon Attributes, one or two entries are created. If executing hard disk diagnostics, a BbsEntry is created and given the highest priority. If booting from an unconventional device, a BbsEntry is created and given the highest priority after the diagnostic entry. It is the caller’s responsibility to lock all other drives with hidden partitions, if they exist. If an unconventional boot fails, the system is reset to preserve device partition security.

Status Codes Returned

Status Code Description
EFI_INVALID_PARAMETER Either the Attribute and/or pointers do not match.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions (C) 1999-2003 Intel Corporation. Used with permission.

Retrieved from "http://wiki.phoenix.com/wiki/index.php/EFI_LEGACY_BIOS_PROTOCOL"
Personal tools