UEFI subsystem¶

Lauching UEFI images¶

Bootefi command¶

The bootefi command is used to start UEFI applications or to install UEFI drivers. It takes two parameters

bootefi <image address> [fdt address]

image address - the memory address of the UEFI binary
fdt address - the memory address of the flattened device tree

The environment variable ‘bootargs’ is passed as load options in the UEFI system table. The Linux kernel EFI stub uses the load options as command line arguments.

void efi_get_image_parameters(void **img_addr, size_t *img_size)¶: return image parameters

Parameters

void **img_addr: address of loaded image in memory
size_t *img_size: size of loaded image

void efi_clear_bootdev(void)¶: clear boot device

Parameters

void: no arguments

void efi_set_bootdev(const char *dev, const char *devnr, const char *path, void *buffer, size_t buffer_size)¶: set boot device

Parameters

const char *dev: device, e.g. “MMC”
const char *devnr: number of the device, e.g. “1:2”
const char *path: path to file loaded
void *buffer: buffer with file loaded
size_t buffer_size: size of file loaded

Description

This function is called when a file is loaded, e.g. via the ‘load’ command. We use the path to this file to inform the UEFI binary about the boot device.

efi_status_t efi_env_set_load_options(efi_handle_t handle, const char *env_var, u16 **load_options)¶: set load options from environment variable

Parameters

efi_handle_t handle: the image handle
const char *env_var: name of the environment variable
u16 **load_options: pointer to load options (output)

Return

status code

efi_status_t copy_fdt(void **fdtp)¶: Copy the device tree to a new location available to EFI

Parameters

void **fdtp: On entry a pointer to the flattened device tree. On exit a pointer to the copy of the flattened device tree. FDT start

Description

The FDT is copied to a suitable location within the EFI memory map. Additional 12 KiB are added to the space in case the device tree needs to be expanded later with fdt_open_into().

Return

status code

void *get_config_table(const efi_guid_t *guid)¶: get configuration table

Parameters

const efi_guid_t *guid: GUID of the configuration table

Return

pointer to configuration table or NULL

efi_status_t efi_install_fdt(void *fdt)¶: install device tree

Parameters

void *fdt: address of device tree or EFI_FDT_USE_INTERNAL to use the the hardware device tree as indicated by environment variable fdt_addr or as fallback the internal device tree as indicated by the environment variable fdtcontroladdr

Description

If fdt is not EFI_FDT_USE_INTERNAL, the device tree located at that memory address will will be installed as configuration table, otherwise the device tree located at the address indicated by environment variable fdt_addr or as fallback fdtcontroladdr will be used.

On architectures using ACPI tables device trees shall not be installed as configuration table.

Return

status code

efi_status_t do_bootefi_exec(efi_handle_t handle, void *load_options)¶: execute EFI binary

Parameters

efi_handle_t handle: handle of loaded image
void *load_options: load options

Description

The image indicated by handle is started. When it returns the allocated memory for the load_options is freed.

Load the EFI binary into a newly assigned memory unwinding the relocation information, install the loaded image protocol, and call the binary.

Return

status code

int do_efibootmgr(void)¶: execute EFI boot manager

Parameters

void: no arguments

Return

status code

int do_bootefi_image(const char *image_opt, const char *size_opt)¶: execute EFI binary

Parameters

const char *image_opt: string with image start address
const char *size_opt: string with image size or NULL

Description

Set up memory image for the binary to be loaded, prepare device path, and then call do_bootefi_exec() to execute it.

Return

status code

efi_status_t efi_run_image(void *source_buffer, efi_uintn_t source_size)¶: run loaded UEFI image

Parameters

void *source_buffer: memory address of the UEFI image
efi_uintn_t source_size: size of the UEFI image

Return

status code

efi_status_t bootefi_test_prepare(struct efi_loaded_image_obj **image_objp, struct efi_loaded_image **loaded_image_infop, const char *path, const char *load_options_path)¶: prepare to run an EFI test

Parameters

struct efi_loaded_image_obj **image_objp: pointer to be set to the loaded image handle
struct efi_loaded_image **loaded_image_infop: pointer to be set to the loaded image protocol
const char *path: dummy file path used to construct the device path set in the loaded image protocol
const char *load_options_path: name of a U-Boot environment variable. Its value is set as load options in the loaded image protocol.

Description

Prepare to run a test as if it were provided by a loaded image.

Return

status code

void bootefi_run_finish(struct efi_loaded_image_obj *image_obj, struct efi_loaded_image *loaded_image_info)¶: finish up after running an EFI test

Parameters

struct efi_loaded_image_obj *image_obj: Pointer to a struct which holds the loaded image object
struct efi_loaded_image *loaded_image_info: Pointer to a struct which holds the loaded image info

int do_efi_selftest(void)¶: execute EFI selftest

Parameters

void: no arguments

Return

status code

int do_bootefi(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: execute bootefi command

Parameters

struct cmd_tbl *cmdtp: table entry describing command
int flag: bitmap indicating how the command was invoked
int argc: number of arguments
char *const argv[]: command line arguments

Return

status code

Boot manager¶

The UEFI specification foresees to define boot entries and boot sequence via UEFI variables. Booting according to these variables is possible via

bootefi bootmgr [fdt address]

fdt address - the memory address of the flattened device tree

The relevant variables are:

Boot0000-BootFFFF define boot entries
BootNext specifies next boot option to be booted
BootOrder specifies in which sequence the boot options shall be tried if BootNext is not defined or booting via BootNext fails

struct efi_device_path *expand_media_path(struct efi_device_path *device_path)¶: expand a device path for default file name

Parameters

struct efi_device_path *device_path: device path to check against

Description

If device_path is a media or disk partition which houses a file system, this function returns a full device path which contains an architecture-specific default file name for removable media.

Return

a newly allocated device path

efi_status_t try_load_from_file_path(efi_handle_t *fs_handles, efi_uintn_t num, struct efi_device_path *fp, efi_handle_t *handle, bool removable)¶: try to load a file

Parameters

efi_handle_t *fs_handles: array of handles with the simple file protocol
efi_uintn_t num: number of handles in fs_handles
struct efi_device_path *fp: file path to open
efi_handle_t *handle: on return pointer to handle for loaded image
bool removable: if true only consider removable media, else only non-removable

Description

Given a file media path iterate through a list of handles and try to to load the file from each of them until the first success.

efi_status_t try_load_from_short_path(struct efi_device_path *fp, efi_handle_t *handle)¶

Parameters

struct efi_device_path *fp: file path
efi_handle_t *handle: pointer to handle for newly installed image

Description

Enumerate all the devices which support file system operations, prepend its media device path to the file path, fp, and try to load the file. This function should be called when handling a short-form path which is starting with a file device path.

Return

status code

efi_status_t try_load_entry(u16 n, efi_handle_t *handle, void **load_options)¶: try to load image for boot option

Parameters

u16 n: number of the boot option, e.g. 0x0a13 for Boot0A13
efi_handle_t *handle: on return handle for the newly installed image
void **load_options: load options set on the loaded image protocol

Description

Attempt to load load-option number ‘n’, returning device_path and file_path if successful. This checks that the EFI_LOAD_OPTION is active (enabled) and that the specified file to boot exists.

Return

status code

efi_status_t efi_bootmgr_load(efi_handle_t *handle, void **load_options)¶: try to load from BootNext or BootOrder

Parameters

efi_handle_t *handle: on return handle for the newly installed image
void **load_options: load options set on the loaded image protocol

Description

Attempt to load from BootNext or in the order specified by BootOrder EFI variable, the available load-options, finding and returning the first one that can be loaded successfully.

Return

status code

Efidebug command¶

The efidebug command is used to set and display boot options as well as to display information about internal data of the UEFI subsystem (devices, drivers, handles, loaded images, and the memory map).

int do_efi_capsule_update(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: process a capsule update

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “capsule update” sub-command. process a capsule update.

efidebug capsule update [-v] <capsule address>

int do_efi_capsule_show(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show capsule information

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “capsule show” sub-command. show capsule information.

efidebug capsule show <capsule address>

int do_efi_capsule_esrt(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: manage UEFI capsules

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “capsule esrt” sub-command. The prints the current ESRT table.

efidebug capsule esrt

int do_efi_capsule_res(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show a capsule update result

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “capsule result” sub-command. show a capsule update result. If result number is not specified, CapsuleLast will be shown.

efidebug capsule result [<capsule result number>]

int do_efi_capsule(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: manage UEFI capsules

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “capsule” sub-command.

int efi_get_driver_handle_info(efi_handle_t handle, u16 **driver_name, u16 **image_path)¶: get information of UEFI driver

Parameters

efi_handle_t handle: Handle of UEFI device
u16 **driver_name: Driver name
u16 **image_path: Pointer to text of device path

Return

0 on success, -1 on failure

Description

Currently return no useful information as all UEFI drivers are built-in..

int do_efi_show_drivers(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show UEFI drivers

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “drivers” sub-command. Show all UEFI drivers and their information.

int do_efi_show_handles(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show UEFI handles

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “dh” sub-command. Show all UEFI handles and their information, currently all protocols added to handle.

int do_efi_show_images(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show UEFI images

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “images” sub-command. Show all UEFI loaded images and their information.

void print_memory_attributes(u64 attributes)¶: print memory map attributes

Parameters

u64 attributes: Attribute value

Description

Print memory map attributes

int do_efi_show_memmap(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show UEFI memory map

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “memmap” sub-command. Show UEFI memory map.

int do_efi_show_tables(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: show UEFI configuration tables

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “tables” sub-command. Show UEFI configuration tables.

struct efi_device_path *create_initrd_dp(const char *dev, const char *part, const char *file, int shortform)¶: create a special device for our Boot### option

Parameters

const char *dev: device
const char *part: disk partition
const char *file: filename
int shortform: create short form device path

Return

pointer to the device path or ERR_PTR

int do_efi_boot_add(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: set UEFI load option

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “boot add” sub-command. Create or change UEFI load option.

efidebug boot add -b <id> <label> <interface> <devnum>[:<part>] <file>: -i <file> <interface2> <devnum2>[:<part>] <initrd> -s ‘<options>’

int do_efi_boot_rm(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: delete UEFI load options

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “boot rm” sub-command. Delete UEFI load options.

efidebug boot rm <id> …

void show_efi_boot_opt_data(u16 *varname16, void *data, size_t *size)¶: dump UEFI load option

Parameters

u16 *varname16: variable name
void *data: value of UEFI load option variable
size_t *size: size of the boot option

Description

Decode the value of UEFI load option variable and print information.

void show_efi_boot_opt(u16 *varname16)¶: dump UEFI load option

Parameters

u16 *varname16: variable name

Description

Dump information defined by UEFI load option.

int do_efi_boot_dump(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: dump all UEFI load options

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “boot dump” sub-command. Dump information of all UEFI load options defined.

efidebug boot dump

int show_efi_boot_order(void)¶: show order of UEFI load options

Parameters

void: no arguments

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Show order of UEFI load options defined by BootOrder variable.

int do_efi_boot_next(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: manage UEFI BootNext variable

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “boot next” sub-command. Set BootNext variable.

efidebug boot next <id>

int do_efi_boot_order(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: manage UEFI BootOrder variable

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success, CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “boot order” sub-command. Show order of UEFI load options, or change it in BootOrder variable.

efidebug boot order [<id> …]

int do_efi_boot_opt(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: manage UEFI load options

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “boot” sub-command.

__maybe_unused int do_efi_test_bootmgr(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: run simple bootmgr for test

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “test bootmgr” sub-command. Run simple bootmgr for test.

efidebug test bootmgr

int do_efi_test(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: manage UEFI load options

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug “test” sub-command.

int do_efi_query_info(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: QueryVariableInfo EFI service

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char * const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_FAILURE on failure

Description

Implement efidebug “test” sub-command.

int do_efidebug(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])¶: display and configure UEFI environment

Parameters

struct cmd_tbl *cmdtp: Command table
int flag: Command flag
int argc: Number of arguments
char *const argv[]: Argument array

Return

CMD_RET_SUCCESS on success,: CMD_RET_USAGE or CMD_RET_RET_FAILURE on failure

Description

Implement efidebug command which allows us to display and configure UEFI environment.

Initialization of the UEFI sub-system¶

efi_status_t efi_init_platform_lang(void)¶: define supported languages

Parameters

void: no arguments

Description

Set the PlatformLangCodes and PlatformLang variables.

Return

status code

efi_status_t efi_init_secure_boot(void)¶: initialize secure boot state

Parameters

void: no arguments

Return

status code

efi_status_t efi_init_capsule(void)¶: initialize capsule update state

Parameters

void: no arguments

Return

status code

efi_status_t efi_init_os_indications(void)¶: indicate supported features for OS requests

Parameters

void: no arguments

Description

Set the OsIndicationsSupported variable.

Return

status code

int efi_init_early(void)¶: handle initialization at early stage

Parameters

void: no arguments

Description

expected to be called in board_init_r().

Return

status code

efi_status_t efi_init_obj_list(void)¶: Initialize and populate EFI object list

Parameters

void: no arguments

Return

status code

Boot services¶

void efi_save_gd(void)¶: save global data register

Parameters

void: no arguments

Description

On the ARM and RISC-V architectures gd is mapped to a fixed register. As this register may be overwritten by an EFI payload we save it here and restore it on every callback entered.

This function is called after relocation from initr_reloc_global_data().

void efi_restore_gd(void)¶: restore global data register

Parameters

void: no arguments

Description

On the ARM and RISC-V architectures gd is mapped to a fixed register. Restore it after returning from the UEFI world to the value saved via efi_save_gd().

const char *indent_string(int level)¶: returns a string for indenting with two spaces per level

Parameters

int level: indent level

Description

A maximum of ten indent levels is supported. Higher indent levels will be truncated.

Return

A string for indenting with two spaces per level is: returned.

bool efi_event_is_queued(struct efi_event *event)¶: check if an event is queued

Parameters

struct efi_event *event: event

Return

true if event is queued

void efi_process_event_queue(void)¶: process event queue

Parameters

void: no arguments

void efi_queue_event(struct efi_event *event)¶: queue an EFI event

Parameters

struct efi_event *event: event to signal

Description

This function queues the notification function of the event for future execution.

efi_status_t is_valid_tpl(efi_uintn_t tpl)¶: check if the task priority level is valid

Parameters

efi_uintn_t tpl: TPL level to check

Return

status code

void efi_signal_event(struct efi_event *event)¶: signal an EFI event

Parameters

struct efi_event *event: event to signal

Description

This function signals an event. If the event belongs to an event group, all events of the group are signaled. If they are of type EVT_NOTIFY_SIGNAL, their notification function is queued.

For the SignalEvent service see efi_signal_event_ext.

unsigned long EFIAPI efi_raise_tpl(efi_uintn_t new_tpl)¶: raise the task priority level

Parameters

efi_uintn_t new_tpl: new value of the task priority level

Description

This function implements the RaiseTpl service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

old value of the task priority level

void EFIAPI efi_restore_tpl(efi_uintn_t old_tpl)¶: lower the task priority level

Parameters

efi_uintn_t old_tpl: value of the task priority level to be restored

Description

This function implements the RestoreTpl service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_allocate_pages_ext(int type, int memory_type, efi_uintn_t pages, uint64_t *memory)¶: allocate memory pages

Parameters

int type: type of allocation to be performed
int memory_type: usage type of the allocated memory
efi_uintn_t pages: number of pages to be allocated
uint64_t *memory: allocated memory

Description

This function implements the AllocatePages service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_free_pages_ext(uint64_t memory, efi_uintn_t pages)¶: Free memory pages.

Parameters

uint64_t memory: start of the memory area to be freed
efi_uintn_t pages: number of pages to be freed

Description

This function implements the FreePages service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_get_memory_map_ext(efi_uintn_t *memory_map_size, struct efi_mem_desc *memory_map, efi_uintn_t *map_key, efi_uintn_t *descriptor_size, uint32_t *descriptor_version)¶: get map describing memory usage

Parameters

efi_uintn_t *memory_map_size: on entry the size, in bytes, of the memory map buffer, on exit the size of the copied memory map
struct efi_mem_desc *memory_map: buffer to which the memory map is written
efi_uintn_t *map_key: key for the memory map
efi_uintn_t *descriptor_size: size of an individual memory descriptor
uint32_t *descriptor_version: version number of the memory descriptor structure

Description

This function implements the GetMemoryMap service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_allocate_pool_ext(int pool_type, efi_uintn_t size, void **buffer)¶: allocate memory from pool

Parameters

int pool_type: type of the pool from which memory is to be allocated
efi_uintn_t size: number of bytes to be allocated
void **buffer: allocated memory

Description

This function implements the AllocatePool service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_free_pool_ext(void *buffer)¶: free memory from pool

Parameters

void *buffer: start of memory to be freed

Description

This function implements the FreePool service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

void efi_add_handle(efi_handle_t handle)¶: add a new handle to the object list

Parameters

efi_handle_t handle: handle to be added

Description

The protocols list is initialized. The handle is added to the list of known UEFI objects.

efi_status_t efi_create_handle(efi_handle_t *handle)¶: create handle

Parameters

efi_handle_t *handle: new handle

Return

status code

efi_status_t efi_search_protocol(const efi_handle_t handle, const efi_guid_t *protocol_guid, struct efi_handler **handler)¶: find a protocol on a handle.

Parameters

const efi_handle_t handle: handle
const efi_guid_t *protocol_guid: GUID of the protocol
struct efi_handler **handler: reference to the protocol

Return

status code

efi_status_t efi_remove_protocol(const efi_handle_t handle, const efi_guid_t *protocol, void *protocol_interface)¶: delete protocol from a handle

Parameters

const efi_handle_t handle: handle from which the protocol shall be deleted
const efi_guid_t *protocol: GUID of the protocol to be deleted
void *protocol_interface: interface of the protocol implementation

Return

status code

efi_status_t efi_remove_all_protocols(const efi_handle_t handle)¶: delete all protocols from a handle

Parameters

const efi_handle_t handle: handle from which the protocols shall be deleted

Return

status code

void efi_delete_handle(efi_handle_t handle)¶: delete handle

Parameters

efi_handle_t handle: handle to delete

efi_status_t efi_is_event(const struct efi_event *event)¶: check if a pointer is a valid event

Parameters

const struct efi_event *event: pointer to check

Return

status code

efi_status_t efi_create_event(uint32_t type, efi_uintn_t notify_tpl, void (*notify_function)(struct efi_event *event, void *context), void *notify_context, efi_guid_t *group, struct efi_event **event, )¶: create an event

Parameters

uint32_t type: type of the event to create
efi_uintn_t notify_tpl: task priority level of the event
void ( *notify_function) ( struct efi_event *event, void *context): notification function of the event
void *notify_context: pointer passed to the notification function
efi_guid_t *group: event group
struct efi_event **event: created event

Description

This function is used inside U-Boot code to create an event.

For the API function implementing the CreateEvent service see efi_create_event_ext.

Return

status code

efi_status_t EFIAPI efi_create_event_ext(uint32_t type, efi_uintn_t notify_tpl, void (*notify_function)(struct efi_event *event, void *context), void *notify_context, struct efi_event **event, )¶: create an event

Parameters

uint32_t type: type of the event to create
efi_uintn_t notify_tpl: task priority level of the event
void ( *notify_function) ( struct efi_event *event, void *context): notification function of the event
void *notify_context: pointer passed to the notification function
struct efi_event **event: created event

Description

This function implements the CreateEvent service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

void efi_timer_check(void)¶: check if a timer event has occurred

Parameters

void: no arguments

Description

Check if a timer event has occurred or a queued notification function should be called.

Our timers have to work without interrupts, so we check whenever keyboard input or disk accesses happen if enough time elapsed for them to fire.

efi_status_t efi_set_timer(struct efi_event *event, enum efi_timer_delay type, uint64_t trigger_time)¶: set the trigger time for a timer event or stop the event

Parameters

struct efi_event *event: event for which the timer is set
enum efi_timer_delay type: type of the timer
uint64_t trigger_time: trigger period in multiples of 100 ns

Description

This is the function for internal usage in U-Boot. For the API function implementing the SetTimer service see efi_set_timer_ext.

Return

status code

efi_status_t EFIAPI efi_set_timer_ext(struct efi_event *event, enum efi_timer_delay type, uint64_t trigger_time)¶: Set the trigger time for a timer event or stop the event

Parameters

struct efi_event *event: event for which the timer is set
enum efi_timer_delay type: type of the timer
uint64_t trigger_time: trigger period in multiples of 100 ns

Description

This function implements the SetTimer service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_wait_for_event(efi_uintn_t num_events, struct efi_event **event, efi_uintn_t *index)¶: wait for events to be signaled

Parameters

efi_uintn_t num_events: number of events to be waited for
struct efi_event **event: events to be waited for
efi_uintn_t *index: index of the event that was signaled

Description

This function implements the WaitForEvent service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_signal_event_ext(struct efi_event *event)¶: signal an EFI event

Parameters

struct efi_event *event: event to signal

Description

This function implements the SignalEvent service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

This functions sets the signaled state of the event and queues the notification function for execution.

Return

status code

efi_status_t EFIAPI efi_close_event(struct efi_event *event)¶: close an EFI event

Parameters

struct efi_event *event: event to close

Description

This function implements the CloseEvent service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_check_event(struct efi_event *event)¶: check if an event is signaled

Parameters

struct efi_event *event: event to check

Description

This function implements the CheckEvent service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

If an event is not signaled yet, the notification function is queued. The signaled state is cleared.

Return

status code

struct efi_object *efi_search_obj(const efi_handle_t handle)¶: find the internal EFI object for a handle

Parameters

const efi_handle_t handle: handle to find

Return

EFI object

struct efi_open_protocol_info_entry *efi_create_open_info(struct efi_handler *handler)¶: create open protocol info entry and add it to a protocol

Parameters

struct efi_handler *handler: handler of a protocol

Return

open protocol info entry

efi_status_t efi_delete_open_info(struct efi_open_protocol_info_item *item)¶: remove an open protocol info entry from a protocol

Parameters

struct efi_open_protocol_info_item *item: open protocol info entry to delete

Return

status code

efi_status_t efi_add_protocol(const efi_handle_t handle, const efi_guid_t *protocol, void *protocol_interface)¶: install new protocol on a handle

Parameters

const efi_handle_t handle: handle on which the protocol shall be installed
const efi_guid_t *protocol: GUID of the protocol to be installed
void *protocol_interface: interface of the protocol implementation

Return

status code

efi_status_t EFIAPI efi_install_protocol_interface(efi_handle_t *handle, const efi_guid_t *protocol, int protocol_interface_type, void *protocol_interface)¶: install protocol interface

Parameters

efi_handle_t *handle: handle on which the protocol shall be installed
const efi_guid_t *protocol: GUID of the protocol to be installed
int protocol_interface_type: type of the interface to be installed, always EFI_NATIVE_INTERFACE
void *protocol_interface: interface of the protocol implementation

Description

This function implements the InstallProtocolInterface service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_get_drivers(efi_handle_t handle, const efi_guid_t *protocol, efi_uintn_t *number_of_drivers, efi_handle_t **driver_handle_buffer)¶: get all drivers associated to a controller

Parameters

efi_handle_t handle: handle of the controller
const efi_guid_t *protocol: protocol GUID (optional)
efi_uintn_t *number_of_drivers: number of child controllers
efi_handle_t **driver_handle_buffer: handles of the the drivers

Description

The allocated buffer has to be freed with free().

Return

status code

efi_status_t efi_disconnect_all_drivers(efi_handle_t handle, const efi_guid_t *protocol, efi_handle_t child_handle)¶: disconnect all drivers from a controller

Parameters

efi_handle_t handle: handle of the controller
const efi_guid_t *protocol: protocol GUID (optional)
efi_handle_t child_handle: handle of the child to destroy

Description

This function implements the DisconnectController service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_uninstall_protocol(efi_handle_t handle, const efi_guid_t *protocol, void *protocol_interface)¶: uninstall protocol interface

Parameters

efi_handle_t handle: handle from which the protocol shall be removed
const efi_guid_t *protocol: GUID of the protocol to be removed
void *protocol_interface: interface to be removed

Description

This function DOES NOT delete a handle without installed protocol.

Return

status code

efi_status_t EFIAPI efi_uninstall_protocol_interface(efi_handle_t handle, const efi_guid_t *protocol, void *protocol_interface)¶: uninstall protocol interface

Parameters

efi_handle_t handle: handle from which the protocol shall be removed
const efi_guid_t *protocol: GUID of the protocol to be removed
void *protocol_interface: interface to be removed

Description

This function implements the UninstallProtocolInterface service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_register_protocol_notify(const efi_guid_t *protocol, struct efi_event *event, void **registration)¶: register an event for notification when a protocol is installed.

Parameters

const efi_guid_t *protocol: GUID of the protocol whose installation shall be notified
struct efi_event *event: event to be signaled upon installation of the protocol
void **registration: key for retrieving the registration information

Description

This function implements the RegisterProtocolNotify service. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

int efi_search(enum efi_locate_search_type search_type, const efi_guid_t *protocol, efi_handle_t handle)¶: determine if an EFI handle implements a protocol

Parameters

enum efi_locate_search_type search_type: selection criterion
const efi_guid_t *protocol: GUID of the protocol
efi_handle_t handle: handle

Description

See the documentation of the LocateHandle service in the UEFI specification.

Return

0 if the handle implements the protocol

struct efi_register_notify_event *efi_check_register_notify_event(void *key)¶: check if registration key is valid

Parameters

void *key: registration key

Description

Check that a pointer is a valid registration key as returned by RegisterProtocolNotify().

Return

valid registration key or NULL

efi_status_t efi_locate_handle(enum efi_locate_search_type search_type, const efi_guid_t *protocol, void *search_key, efi_uintn_t *buffer_size, efi_handle_t *buffer)¶: locate handles implementing a protocol

Parameters

enum efi_locate_search_type search_type: selection criterion
const efi_guid_t *protocol: GUID of the protocol
void *search_key: registration key
efi_uintn_t *buffer_size: size of the buffer to receive the handles in bytes
efi_handle_t *buffer: buffer to receive the relevant handles

Description

This function is meant for U-Boot internal calls. For the API implementation of the LocateHandle service see efi_locate_handle_ext.

Return

status code

efi_status_t EFIAPI efi_locate_handle_ext(enum efi_locate_search_type search_type, const efi_guid_t *protocol, void *search_key, efi_uintn_t *buffer_size, efi_handle_t *buffer)¶: locate handles implementing a protocol.

Parameters

enum efi_locate_search_type search_type: selection criterion
const efi_guid_t *protocol: GUID of the protocol
void *search_key: registration key
efi_uintn_t *buffer_size: size of the buffer to receive the handles in bytes
efi_handle_t *buffer: buffer to receive the relevant handles

Description

This function implements the LocateHandle service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

0 if the handle implements the protocol

void efi_remove_configuration_table(int i)¶: collapses configuration table entries, removing index i

Parameters

int i: index of the table entry to be removed

efi_status_t efi_install_configuration_table(const efi_guid_t *guid, void *table)¶: adds, updates, or removes a configuration table

Parameters

const efi_guid_t *guid: GUID of the installed table
void *table: table to be installed

Description

This function is used for internal calls. For the API implementation of the InstallConfigurationTable service see efi_install_configuration_table_ext.

Return

status code

efi_status_t EFIAPI efi_install_configuration_table_ext(const efi_guid_t *guid, void *table)¶: Adds, updates, or removes a configuration table.

Parameters

const efi_guid_t *guid: GUID of the installed table
void *table: table to be installed

Description

This function implements the InstallConfigurationTable service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_setup_loaded_image(struct efi_device_path *device_path, struct efi_device_path *file_path, struct efi_loaded_image_obj **handle_ptr, struct efi_loaded_image **info_ptr)¶: initialize a loaded image

Parameters

struct efi_device_path *device_path: device path of the loaded image
struct efi_device_path *file_path: file path of the loaded image
struct efi_loaded_image_obj **handle_ptr: handle of the loaded image
struct efi_loaded_image **info_ptr: loaded image protocol

Description

Initialize a loaded_image_info and loaded_image_info object with correct protocols, boot-device, etc.

In case of an error *handle_ptr and *info_ptr are set to NULL and an error code is returned.

Return

status code

efi_status_t EFIAPI efi_locate_device_path(const efi_guid_t *protocol, struct efi_device_path **device_path, efi_handle_t *device)¶: Get the device path and handle of an device implementing a protocol

Parameters

const efi_guid_t *protocol: GUID of the protocol
struct efi_device_path **device_path: device path
efi_handle_t *device: handle of the device

Description

This function implements the LocateDevicePath service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_load_image_from_file(struct efi_device_path *file_path, void **buffer, efi_uintn_t *size)¶: load an image from file system

Parameters

struct efi_device_path *file_path: the path of the image to load
void **buffer: buffer containing the loaded image
efi_uintn_t *size: size of the loaded image

Description

Read a file into a buffer allocated as EFI_BOOT_SERVICES_DATA. It is the callers obligation to update the memory type as needed.

Return

status code

efi_status_t efi_load_image_from_path(bool boot_policy, struct efi_device_path *file_path, void **buffer, efi_uintn_t *size)¶: load an image using a file path

Parameters

bool boot_policy: true for request originating from the boot manager
struct efi_device_path *file_path: the path of the image to load
void **buffer: buffer containing the loaded image
efi_uintn_t *size: size of the loaded image

Description

Read a file into a buffer allocated as EFI_BOOT_SERVICES_DATA. It is the callers obligation to update the memory type as needed.

Return

status code

efi_status_t EFIAPI efi_load_image(bool boot_policy, efi_handle_t parent_image, struct efi_device_path *file_path, void *source_buffer, efi_uintn_t source_size, efi_handle_t *image_handle)¶: load an EFI image into memory

Parameters

bool boot_policy: true for request originating from the boot manager
efi_handle_t parent_image: the caller’s image handle
struct efi_device_path *file_path: the path of the image to load
void *source_buffer: memory location from which the image is installed
efi_uintn_t source_size: size of the memory area from which the image is installed
efi_handle_t *image_handle: handle for the newly installed image

Description

This function implements the LoadImage service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

void efi_exit_caches(void)¶: fix up caches for EFI payloads if necessary

Parameters

void: no arguments

efi_status_t EFIAPI efi_exit_boot_services(efi_handle_t image_handle, efi_uintn_t map_key)¶: stop all boot services

Parameters

efi_handle_t image_handle: handle of the loaded image
efi_uintn_t map_key: key of the memory map

Description

This function implements the ExitBootServices service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

All timer events are disabled. For exit boot services events the notification function is called. The boot services are disabled in the system table.

Return

status code

efi_status_t EFIAPI efi_get_next_monotonic_count(uint64_t *count)¶: get next value of the counter

Parameters

uint64_t *count: returned value of the counter

Description

This function implements the NextMonotonicCount service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_stall(unsigned long microseconds)¶: sleep

Parameters

unsigned long microseconds: period to sleep in microseconds

Description

This function implements the Stall service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_set_watchdog_timer(unsigned long timeout, uint64_t watchdog_code, unsigned long data_size, uint16_t *watchdog_data)¶: reset the watchdog timer

Parameters

unsigned long timeout: seconds before reset by watchdog
uint64_t watchdog_code: code to be logged when resetting
unsigned long data_size: size of buffer in bytes
uint16_t *watchdog_data: buffer with data describing the reset reason

Description

This function implements the SetWatchdogTimer service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_close_protocol(efi_handle_t handle, const efi_guid_t *protocol, efi_handle_t agent_handle, efi_handle_t controller_handle)¶: close a protocol

Parameters

efi_handle_t handle: handle on which the protocol shall be closed
const efi_guid_t *protocol: GUID of the protocol to close
efi_handle_t agent_handle: handle of the driver
efi_handle_t controller_handle: handle of the controller

Description

This is the function implementing the CloseProtocol service is for internal usage in U-Boot. For API usage wrapper efi_close_protocol_ext() is provided.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_close_protocol_ext(efi_handle_t handle, const efi_guid_t *protocol, efi_handle_t agent_handle, efi_handle_t controller_handle)¶: close a protocol

Parameters

efi_handle_t handle: handle on which the protocol shall be closed
const efi_guid_t *protocol: GUID of the protocol to close
efi_handle_t agent_handle: handle of the driver
efi_handle_t controller_handle: handle of the controller

Description

This function implements the CloseProtocol service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_open_protocol_information(efi_handle_t handle, const efi_guid_t *protocol, struct efi_open_protocol_info_entry **entry_buffer, efi_uintn_t *entry_count)¶: provide information about then open status of a protocol on a handle

Parameters

efi_handle_t handle: handle for which the information shall be retrieved
const efi_guid_t *protocol: GUID of the protocol
struct efi_open_protocol_info_entry **entry_buffer: buffer to receive the open protocol information
efi_uintn_t *entry_count: number of entries available in the buffer

Description

This function implements the OpenProtocolInformation service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_protocols_per_handle(efi_handle_t handle, efi_guid_t ***protocol_buffer, efi_uintn_t *protocol_buffer_count)¶: get protocols installed on a handle

Parameters

efi_handle_t handle: handle for which the information is retrieved
efi_guid_t ***protocol_buffer: buffer with protocol GUIDs
efi_uintn_t *protocol_buffer_count: number of entries in the buffer

Description

This function implements the ProtocolsPerHandleService.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_locate_handle_buffer(enum efi_locate_search_type search_type, const efi_guid_t *protocol, void *search_key, efi_uintn_t *no_handles, efi_handle_t **buffer)¶: locate handles implementing a protocol

Parameters

enum efi_locate_search_type search_type: selection criterion
const efi_guid_t *protocol: GUID of the protocol
void *search_key: registration key
efi_uintn_t *no_handles: number of returned handles
efi_handle_t **buffer: buffer with the returned handles

Description

This function implements the LocateHandleBuffer service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_locate_protocol(const efi_guid_t *protocol, void *registration, void **protocol_interface)¶: find an interface implementing a protocol

Parameters

const efi_guid_t *protocol: GUID of the protocol
void *registration: registration key passed to the notification function
void **protocol_interface: interface implementing the protocol

Description

This function implements the LocateProtocol service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_install_multiple_protocol_interfaces_int(efi_handle_t *handle, efi_va_list argptr)¶: Install multiple protocol interfaces

Parameters

efi_handle_t *handle: handle on which the protocol interfaces shall be installed
efi_va_list argptr: va_list of args

Description

Core functionality of efi_install_multiple_protocol_interfaces Must not be called directly

Return

status code

efi_status_t EFIAPI efi_install_multiple_protocol_interfaces(efi_handle_t *handle, ...)¶: Install multiple protocol interfaces

Parameters

efi_handle_t *handle: handle on which the protocol interfaces shall be installed
...: NULL terminated argument list with pairs of protocol GUIDS and interfaces

Description

This is the function for internal usage in U-Boot. For the API function implementing the InstallMultipleProtocol service see efi_install_multiple_protocol_interfaces_ext()

Return

status code

efi_status_t EFIAPI efi_install_multiple_protocol_interfaces_ext(efi_handle_t *handle, ...)¶: Install multiple protocol interfaces

Parameters

efi_handle_t *handle: handle on which the protocol interfaces shall be installed
...: NULL terminated argument list with pairs of protocol GUIDS and interfaces

Description

This function implements the MultipleProtocolInterfaces service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_uninstall_multiple_protocol_interfaces_int(efi_handle_t handle, efi_va_list argptr)¶: wrapper for uninstall multiple protocol interfaces

Parameters

efi_handle_t handle: handle from which the protocol interfaces shall be removed
efi_va_list argptr: va_list of args

Description

Core functionality of efi_uninstall_multiple_protocol_interfaces Must not be called directly

Return

status code

efi_status_t EFIAPI efi_uninstall_multiple_protocol_interfaces(efi_handle_t handle, ...)¶: uninstall multiple protocol interfaces

Parameters

efi_handle_t handle: handle from which the protocol interfaces shall be removed
...: NULL terminated argument list with pairs of protocol GUIDS and interfaces

Description

This function implements the UninstallMultipleProtocolInterfaces service.

This is the function for internal usage in U-Boot. For the API function implementing the UninstallMultipleProtocolInterfaces service see efi_uninstall_multiple_protocol_interfaces_ext()

Return

status code

efi_status_t EFIAPI efi_uninstall_multiple_protocol_interfaces_ext(efi_handle_t handle, ...)¶: uninstall multiple protocol interfaces

Parameters

efi_handle_t handle: handle from which the protocol interfaces shall be removed
...: NULL terminated argument list with pairs of protocol GUIDS and interfaces

Description

This function implements the UninstallMultipleProtocolInterfaces service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_calculate_crc32(const void *data, efi_uintn_t data_size, u32 *crc32_p)¶: calculate cyclic redundancy code

Parameters

const void *data: buffer with data
efi_uintn_t data_size: size of buffer in bytes
u32 *crc32_p: cyclic redundancy code

Description

This function implements the CalculateCrc32 service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

void EFIAPI efi_copy_mem(void *destination, const void *source, size_t length)¶: copy memory

Parameters

void *destination: destination of the copy operation
const void *source: source of the copy operation
size_t length: number of bytes to copy

Description

This function implements the CopyMem service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

void EFIAPI efi_set_mem(void *buffer, size_t size, uint8_t value)¶: Fill memory with a byte value.

Parameters

void *buffer: buffer to fill
size_t size: size of buffer in bytes
uint8_t value: byte to copy to the buffer

Description

This function implements the SetMem service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t efi_protocol_open(struct efi_handler *handler, void **protocol_interface, void *agent_handle, void *controller_handle, uint32_t attributes)¶: open protocol interface on a handle

Parameters

struct efi_handler *handler: handler of a protocol
void **protocol_interface: interface implementing the protocol
void *agent_handle: handle of the driver
void *controller_handle: handle of the controller
uint32_t attributes: attributes indicating how to open the protocol

Return

status code

efi_status_t EFIAPI efi_open_protocol(efi_handle_t handle, const efi_guid_t *protocol, void **protocol_interface, efi_handle_t agent_handle, efi_handle_t controller_handle, uint32_t attributes)¶: open protocol interface on a handle

Parameters

efi_handle_t handle: handle on which the protocol shall be opened
const efi_guid_t *protocol: GUID of the protocol
void **protocol_interface: interface implementing the protocol
efi_handle_t agent_handle: handle of the driver
efi_handle_t controller_handle: handle of the controller
uint32_t attributes: attributes indicating how to open the protocol

Description

This function implements the OpenProtocol interface.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_start_image(efi_handle_t image_handle, efi_uintn_t *exit_data_size, u16 **exit_data)¶: call the entry point of an image

Parameters

efi_handle_t image_handle: handle of the image
efi_uintn_t *exit_data_size: size of the buffer
u16 **exit_data: buffer to receive the exit data of the called image

Description

This function implements the StartImage service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_delete_image(struct efi_loaded_image_obj *image_obj, struct efi_loaded_image *loaded_image_protocol)¶: delete loaded image from memory)

Parameters

struct efi_loaded_image_obj *image_obj: handle of the loaded image
struct efi_loaded_image *loaded_image_protocol: loaded image protocol

efi_status_t EFIAPI efi_unload_image(efi_handle_t image_handle)¶: unload an EFI image

Parameters

efi_handle_t image_handle: handle of the image to be unloaded

Description

This function implements the UnloadImage service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_update_exit_data(struct efi_loaded_image_obj *image_obj, efi_uintn_t exit_data_size, u16 *exit_data)¶: fill exit data parameters of StartImage()

Parameters

struct efi_loaded_image_obj *image_obj: image handle
efi_uintn_t exit_data_size: size of the exit data buffer
u16 *exit_data: buffer with data returned by UEFI payload

Return

status code

efi_status_t EFIAPI efi_exit(efi_handle_t image_handle, efi_status_t exit_status, efi_uintn_t exit_data_size, u16 *exit_data)¶: leave an EFI application or driver

Parameters

efi_handle_t image_handle: handle of the application or driver that is exiting
efi_status_t exit_status: status code
efi_uintn_t exit_data_size: size of the buffer in bytes
u16 *exit_data: buffer with data describing an error

Description

This function implements the Exit service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_handle_protocol(efi_handle_t handle, const efi_guid_t *protocol, void **protocol_interface)¶: get interface of a protocol on a handle

Parameters

efi_handle_t handle: handle on which the protocol shall be opened
const efi_guid_t *protocol: GUID of the protocol
void **protocol_interface: interface implementing the protocol

Description

This function implements the HandleProtocol service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_bind_controller(efi_handle_t controller_handle, efi_handle_t driver_image_handle, struct efi_device_path *remain_device_path)¶: bind a single driver to a controller

Parameters

efi_handle_t controller_handle: controller handle
efi_handle_t driver_image_handle: driver handle
struct efi_device_path *remain_device_path: remaining path

Return

status code

efi_status_t efi_connect_single_controller(efi_handle_t controller_handle, efi_handle_t *driver_image_handle, struct efi_device_path *remain_device_path)¶: connect a single driver to a controller

Parameters

efi_handle_t controller_handle: controller
efi_handle_t *driver_image_handle: driver
struct efi_device_path *remain_device_path: remaining path

Return

status code

efi_status_t EFIAPI efi_connect_controller(efi_handle_t controller_handle, efi_handle_t *driver_image_handle, struct efi_device_path *remain_device_path, bool recursive)¶: connect a controller to a driver

Parameters

efi_handle_t controller_handle: handle of the controller
efi_handle_t *driver_image_handle: handle of the driver
struct efi_device_path *remain_device_path: device path of a child controller
bool recursive: true to connect all child controllers

Description

This function implements the ConnectController service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

First all driver binding protocol handles are tried for binding drivers. Afterwards all handles that have opened a protocol of the controller with EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER are connected to drivers.

Return

status code

efi_status_t EFIAPI efi_reinstall_protocol_interface(efi_handle_t handle, const efi_guid_t *protocol, void *old_interface, void *new_interface)¶: reinstall protocol interface

Parameters

efi_handle_t handle: handle on which the protocol shall be reinstalled
const efi_guid_t *protocol: GUID of the protocol to be installed
void *old_interface: interface to be removed
void *new_interface: interface to be installed

Description

This function implements the ReinstallProtocolInterface service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

The old interface is uninstalled. The new interface is installed. Drivers are connected.

Return

status code

efi_status_t efi_get_child_controllers(struct efi_object *efiobj, efi_handle_t driver_handle, efi_uintn_t *number_of_children, efi_handle_t **child_handle_buffer)¶: get all child controllers associated to a driver

Parameters

struct efi_object *efiobj: handle of the controller
efi_handle_t driver_handle: handle of the driver
efi_uintn_t *number_of_children: number of child controllers
efi_handle_t **child_handle_buffer: handles of the the child controllers

Description

The allocated buffer has to be freed with free().

Return

status code

efi_status_t EFIAPI efi_disconnect_controller(efi_handle_t controller_handle, efi_handle_t driver_image_handle, efi_handle_t child_handle)¶: disconnect a controller from a driver

Parameters

efi_handle_t controller_handle: handle of the controller
efi_handle_t driver_image_handle: handle of the driver
efi_handle_t child_handle: handle of the child to destroy

Description

This function implements the DisconnectController service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_initialize_system_table(void)¶: Initialize system table

Parameters

void: no arguments

Return

status code

Image relocation¶

efi_status_t efi_print_image_info(struct efi_loaded_image_obj *obj, struct efi_loaded_image *image, void *pc)¶: print information about a loaded image

Parameters

struct efi_loaded_image_obj *obj: EFI object
struct efi_loaded_image *image: loaded image
void *pc: program counter (use NULL to suppress offset output)

Description

If the program counter is located within the image the offset to the base address is shown.

Return

status code

void efi_print_image_infos(void *pc)¶: print information about all loaded images

Parameters

void *pc: program counter (use NULL to suppress offset output)

efi_status_t efi_loader_relocate(const IMAGE_BASE_RELOCATION *rel, unsigned long rel_size, void *efi_reloc, unsigned long pref_address)¶: relocate UEFI binary

Parameters

const IMAGE_BASE_RELOCATION *rel: pointer to the relocation table
unsigned long rel_size: size of the relocation table in bytes
void *efi_reloc: actual load address of the image
unsigned long pref_address: preferred load address of the image

Return

status code

void efi_set_code_and_data_type(struct efi_loaded_image *loaded_image_info, uint16_t image_type)¶: determine the memory types to be used for code and data.

Parameters

struct efi_loaded_image *loaded_image_info: image descriptor
uint16_t image_type: field Subsystem of the optional header for Windows specific field

efi_status_t efi_image_region_add(struct efi_image_regions *regs, const void *start, const void *end, int nocheck)¶: add an entry of region

Parameters

struct efi_image_regions *regs: Pointer to array of regions
const void *start: Start address of region (included)
const void *end: End address of region (excluded)
int nocheck: flag against overlapped regions

Description

Take one entry of region [start, end[ and insert it into the list.

If nocheck is false, the list will be sorted ascending by address. Overlapping entries will not be allowed.
If nocheck is true, the list will be sorted ascending by sequence of adding the entries. Overlapping is allowed.

Return

status code

int cmp_pe_section(const void *arg1, const void *arg2)¶: compare virtual addresses of two PE image sections

Parameters

const void *arg1: pointer to pointer to first section header
const void *arg2: pointer to pointer to second section header

Description

Compare the virtual addresses of two sections of an portable executable. The arguments are defined as const void * to allow usage with qsort().

Return

-1 if the virtual address of arg1 is less than that of arg2,: 0 if the virtual addresses are equal, 1 if the virtual address of arg1 is greater than that of arg2.

void *efi_prepare_aligned_image(void *efi, u64 *efi_size)¶: prepare 8-byte aligned image

Parameters

void *efi: pointer to the EFI binary
u64 *efi_size: size of efi binary

Description

If efi is not 8-byte aligned, this function newly allocates the image buffer.

Return

valid pointer to a image, return NULL if allocation fails.

bool efi_image_parse(void *efi, size_t len, struct efi_image_regions **regp, WIN_CERTIFICATE **auth, size_t *auth_len)¶: parse a PE image

Parameters

void *efi: Pointer to image
size_t len: Size of efi
struct efi_image_regions **regp: Pointer to a list of regions
WIN_CERTIFICATE **auth: Pointer to a pointer to authentication data in PE
size_t *auth_len: Size of auth

Description

Parse image binary in PE32(+) format, assuming that sanity of PE image has been checked by a caller. On success, an address of authentication data in efi and its size will be returned in auth and auth_len, respectively.

Return

true on success, false on error

bool efi_image_verify_digest(struct efi_image_regions *regs, struct pkcs7_message *msg)¶: verify image’s message digest

Parameters

struct efi_image_regions *regs: Array of memory regions to digest
struct pkcs7_message *msg: Signature in pkcs7 structure

Description

regs contains all the data in a PE image to digest. Calculate a hash value based on regs and compare it with a messaged digest in the content (SpcPeImageData) of msg’s contentInfo.

Return

true if verified, false if not

bool efi_image_authenticate(void *efi, size_t efi_size)¶: verify a signature of signed image

Parameters

void *efi: Pointer to image
size_t efi_size: Size of efi

Description

A signed image should have its signature stored in a table of its PE header. So if an image is signed and only if if its signature is verified using signature databases, an image is authenticated. If an image is not signed, its validity is checked by using efi_image_unsigned_authenticated(). TODO: When AuditMode==0, if the image’s signature is not found in the authorized database, or is found in the forbidden database, the image will not be started and instead, information about it will be placed in this table. When AuditMode==1, an EFI_IMAGE_EXECUTION_INFO element is created in the EFI_IMAGE_EXECUTION_INFO_TABLE for every certificate found in the certificate table of every image that is validated.

Return

true if authenticated, false if not

efi_status_t efi_check_pe(void *buffer, size_t size, void **nt_header)¶: check if a memory buffer contains a PE-COFF image

Parameters

void *buffer: buffer to check
size_t size: size of buffer
void **nt_header: on return pointer to NT header of PE-COFF image

Return

EFI_SUCCESS if the buffer contains a PE-COFF image

u32 section_size(IMAGE_SECTION_HEADER *sec)¶: determine size of section

Parameters

IMAGE_SECTION_HEADER *sec: section header

Description

The size of a section in memory if normally given by VirtualSize. If VirtualSize is not provided, use SizeOfRawData.

Return

size of section in memory

efi_status_t efi_load_pe(struct efi_loaded_image_obj *handle, void *efi, size_t efi_size, struct efi_loaded_image *loaded_image_info)¶: relocate EFI binary

Parameters

struct efi_loaded_image_obj *handle: loaded image handle
void *efi: pointer to the EFI binary
size_t efi_size: size of efi binary
struct efi_loaded_image *loaded_image_info: loaded image protocol

Description

This function loads all sections from a PE binary into a newly reserved piece of memory. On success the entry point is returned as handle->entry.

Return

status code

Memory services¶

struct efi_pool_allocation¶: memory block allocated from pool

Definition

struct efi_pool_allocation {
  u64 num_pages;
  u64 checksum;
  char data[] ;
};

Members

num_pages: number of pages allocated
checksum: checksum
data: allocated pool memory

Description

U-Boot services each UEFI AllocatePool() request as a separate (multiple) page allocation. We have to track the number of pages to be able to free the correct amount later.

The checksum calculated in function checksum() is used in FreePool() to avoid freeing memory not allocated by AllocatePool() and duplicate freeing.

EFI requires 8 byte alignment for pool allocations, so we can prepend each allocation with these header fields.

u64 checksum(struct efi_pool_allocation *alloc)¶: calculate checksum for memory allocated from pool

Parameters

struct efi_pool_allocation *alloc: allocation header

Return

checksum, always non-zero

int efi_mem_cmp(void *priv, struct list_head *a, struct list_head *b)¶: comparator function for sorting memory map

Parameters

void *priv: unused
struct list_head *a: first memory area
struct list_head *b: second memory area

Description

Sorts the memory list from highest address to lowest address

When allocating memory we should always start from the highest address chunk, so sort the memory list such that the first list iterator gets the highest address and goes lower from there.

Return

1 if a is before b, -1 if b is before a, 0 if equal

uint64_t desc_get_end(struct efi_mem_desc *desc)¶: get end address of memory area

Parameters

struct efi_mem_desc *desc: memory descriptor

Return

end address + 1

void efi_mem_sort(void)¶: sort memory map

Parameters

void: no arguments

Description

Sort the memory map and then try to merge adjacent memory areas.

s64 efi_mem_carve_out(struct efi_mem_list *map, struct efi_mem_desc *carve_desc, bool overlap_only_ram)¶: unmap memory region

Parameters

struct efi_mem_list *map: memory map
struct efi_mem_desc *carve_desc: memory region to unmap
bool overlap_only_ram: the carved out region may only overlap RAM

Return

the number of overlapping pages which have been: removed from the map, EFI_CARVE_NO_OVERLAP, if the regions don’t overlap, EFI_CARVE_OVERLAPS_NONRAM, if the carve and map overlap, and the map contains anything but free ram (only when overlap_only_ram is true), EFI_CARVE_LOOP_AGAIN, if the mapping list should be traversed again, as it has been altered.

Description

Unmaps all memory occupied by the carve_desc region from the list entry pointed to by map.

In case of EFI_CARVE_OVERLAPS_NONRAM it is the callers responsibility to re-add the already carved out pages to the mapping.

efi_status_t efi_add_memory_map_pg(u64 start, u64 pages, int memory_type, bool overlap_only_ram)¶: add pages to the memory map

Parameters

u64 start: start address, must be a multiple of EFI_PAGE_SIZE
u64 pages: number of pages to add
int memory_type: type of memory added
bool overlap_only_ram: region may only overlap RAM

Return

status code

efi_status_t efi_add_memory_map(u64 start, u64 size, int memory_type)¶: add memory area to the memory map

Parameters

u64 start: start address of the memory area
u64 size: length in bytes of the memory area
int memory_type: type of memory added

Return

status code

Description

This function automatically aligns the start and size of the memory area to EFI_PAGE_SIZE.

efi_status_t efi_check_allocated(u64 addr, bool must_be_allocated)¶: validate address to be freed

Parameters

u64 addr: address of page to be freed
bool must_be_allocated: return success if the page is allocated

Description

Check that the address is within allocated memory:

The address must be in a range of the memory map.
The address may not point to EFI_CONVENTIONAL_MEMORY.

Page alignment is not checked as this is not a requirement of efi_free_pool().

Return

status code

uint64_t efi_find_free_memory(uint64_t len, uint64_t max_addr)¶: find free memory pages

Parameters

uint64_t len: size of memory area needed
uint64_t max_addr: highest address to allocate

Return

pointer to free memory area or 0

efi_status_t efi_allocate_pages(enum efi_allocate_type type, enum efi_memory_type memory_type, efi_uintn_t pages, uint64_t *memory)¶: allocate memory pages

Parameters

enum efi_allocate_type type: type of allocation to be performed
enum efi_memory_type memory_type: usage type of the allocated memory
efi_uintn_t pages: number of pages to be allocated
uint64_t *memory: allocated memory

Return

status code

efi_status_t efi_free_pages(uint64_t memory, efi_uintn_t pages)¶: free memory pages

Parameters

uint64_t memory: start of the memory area to be freed
efi_uintn_t pages: number of pages to be freed

Return

status code

void *efi_alloc_aligned_pages(u64 len, int memory_type, size_t align)¶: allocate aligned memory pages

Parameters

u64 len: len in bytes
int memory_type: usage type of the allocated memory
size_t align: alignment in bytes

Return

aligned memory or NULL

efi_status_t efi_allocate_pool(enum efi_memory_type pool_type, efi_uintn_t size, void **buffer)¶: allocate memory from pool

Parameters

enum efi_memory_type pool_type: type of the pool from which memory is to be allocated
efi_uintn_t size: number of bytes to be allocated
void **buffer: allocated memory

Return

status code

void *efi_alloc(size_t size)¶: allocate boot services data pool memory

Parameters

size_t size: number of bytes to allocate

Description

Allocate memory from pool and zero it out.

Return

pointer to allocated memory or NULL

efi_status_t efi_free_pool(void *buffer)¶: free memory from pool

Parameters

void *buffer: start of memory to be freed

Return

status code

efi_status_t efi_get_memory_map(efi_uintn_t *memory_map_size, struct efi_mem_desc *memory_map, efi_uintn_t *map_key, efi_uintn_t *descriptor_size, uint32_t *descriptor_version)¶: get map describing memory usage.

Parameters

efi_uintn_t *memory_map_size: on entry the size, in bytes, of the memory map buffer, on exit the size of the copied memory map
struct efi_mem_desc *memory_map: buffer to which the memory map is written
efi_uintn_t *map_key: key for the memory map
efi_uintn_t *descriptor_size: size of an individual memory descriptor
uint32_t *descriptor_version: version number of the memory descriptor structure

Return

status code

efi_status_t efi_get_memory_map_alloc(efi_uintn_t *map_size, struct efi_mem_desc **memory_map)¶: allocate map describing memory usage

Parameters

efi_uintn_t *map_size: size of the memory map
struct efi_mem_desc **memory_map: buffer to which the memory map is written

Description

The caller is responsible for calling FreePool() if the call succeeds.

Return

status code

efi_status_t efi_add_conventional_memory_map(u64 ram_start, u64 ram_end, u64 ram_top)¶: add a RAM memory area to the map

Parameters

u64 ram_start: start address of a RAM memory area
u64 ram_end: end address of a RAM memory area
u64 ram_top: max address to be used as conventional memory

Return

status code

void efi_add_known_memory(void)¶: add memory banks to map

Parameters

void: no arguments

Description

This function may be overridden for specific architectures.

void add_u_boot_and_runtime(void)¶: add U-Boot code to memory map

Parameters

void: no arguments

Description

Add memory regions for U-Boot’s memory and for the runtime services code.

SetWatchdogTimer service¶

void EFIAPI efi_watchdog_timer_notify(struct efi_event *event, void *context)¶: resets system upon watchdog event

Parameters

struct efi_event *event: the watchdog event
void *context: not used

Description

Reset the system when the watchdog event is notified.

efi_status_t efi_set_watchdog(unsigned long timeout)¶: resets the watchdog timer

Parameters

unsigned long timeout: seconds before reset by watchdog

Description

This function is used by the SetWatchdogTimer service.

Return

status code

efi_status_t efi_watchdog_register(void)¶: initializes the EFI watchdog

Parameters

void: no arguments

Description

This function is called by efi_init_obj_list().

Return

status code

Runtime services¶

efi_status_t efi_init_runtime_supported(void)¶: create runtime properties table

Parameters

void: no arguments

Description

Create a configuration table specifying which services are available at runtime.

Return

status code

void __efi_runtime efi_memcpy_runtime(void *dest, const void *src, size_t n)¶: copy memory area

Parameters

void *dest: destination buffer
const void *src: source buffer
size_t n: number of bytes to copy

Description

At runtime memcpy() is not available.

Overlapping memory areas can be copied safely if src >= dest.

Return

pointer to destination buffer

void __efi_runtime efi_update_table_header_crc32(struct efi_table_hdr *table)¶: Update crc32 in table header

Parameters

struct efi_table_hdr *table: EFI table

void EFIAPI efi_reset_system_boottime(enum efi_reset_type reset_type, efi_status_t reset_status, unsigned long data_size, void *reset_data)¶: reset system at boot time

Parameters

enum efi_reset_type reset_type: type of reset to perform
efi_status_t reset_status: status code for the reset
unsigned long data_size: size of reset_data
void *reset_data: information about the reset

Description

This function implements the ResetSystem() runtime service before SetVirtualAddressMap() is called.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_get_time_boottime(struct efi_time *time, struct efi_time_cap *capabilities)¶: get current time at boot time

Parameters

struct efi_time *time: pointer to structure to receive current time
struct efi_time_cap *capabilities: pointer to structure to receive RTC properties

Description

This function implements the GetTime runtime service before SetVirtualAddressMap() is called.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

int efi_validate_time(struct efi_time *time)¶: checks if timestamp is valid

Parameters

struct efi_time *time: timestamp to validate

Return

0 if timestamp is valid, 1 otherwise

efi_status_t EFIAPI efi_set_time_boottime(struct efi_time *time)¶: set current time

Parameters

struct efi_time *time: pointer to structure to with current time

Description

This function implements the SetTime() runtime service before SetVirtualAddressMap() is called.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

void __efi_runtime EFIAPI efi_reset_system(enum efi_reset_type reset_type, efi_status_t reset_status, unsigned long data_size, void *reset_data)¶: reset system

Parameters

enum efi_reset_type reset_type: type of reset to perform
efi_status_t reset_status: status code for the reset
unsigned long data_size: size of reset_data
void *reset_data: information about the reset

Description

This function implements the ResetSystem() runtime service after SetVirtualAddressMap() is called. As this placeholder cannot reset the system it simply return to the caller.

Boards may override the helpers below to implement reset functionality.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t efi_reset_system_init(void)¶: initialize the reset driver

Parameters

void: no arguments

Description

Boards may override this function to initialize the reset driver.

efi_status_t __efi_runtime EFIAPI efi_get_time(struct efi_time *time, struct efi_time_cap *capabilities)¶: get current time

Parameters

struct efi_time *time: pointer to structure to receive current time
struct efi_time_cap *capabilities: pointer to structure to receive RTC properties

Description

This function implements the GetTime runtime service after SetVirtualAddressMap() is called. As the U-Boot driver are not available anymore only an error code is returned.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t __efi_runtime EFIAPI efi_set_time(struct efi_time *time)¶: set current time

Parameters

struct efi_time *time: pointer to structure to with current time

Description

This function implements the SetTime runtime service after SetVirtualAddressMap() is called. As the U-Boot driver are not available anymore only an error code is returned.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t __efi_runtime EFIAPI efi_update_capsule_unsupported(struct efi_capsule_header **capsule_header_array, efi_uintn_t capsule_count, u64 scatter_gather_list)¶: process information from operating system

Parameters

struct efi_capsule_header **capsule_header_array: pointer to array of virtual pointers
efi_uintn_t capsule_count: number of pointers in capsule_header_array
u64 scatter_gather_list: pointer to array of physical pointers

Description

This function implements the UpdateCapsule() runtime service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t __efi_runtime EFIAPI efi_query_capsule_caps_unsupported(struct efi_capsule_header **capsule_header_array, efi_uintn_t capsule_count, u64 *maximum_capsule_size, u32 *reset_type)¶: check if capsule is supported

Parameters

struct efi_capsule_header **capsule_header_array: pointer to array of virtual pointers
efi_uintn_t capsule_count: number of pointers in capsule_header_array
u64 *maximum_capsule_size: maximum capsule size
u32 *reset_type: type of reset needed for capsule update

Description

This function implements the QueryCapsuleCapabilities() runtime service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

bool efi_is_runtime_service_pointer(void *p)¶: check if pointer points to runtime table

Parameters

void *p: pointer to check

Return

true if the pointer points to a service function pointer in the: runtime table

void efi_runtime_detach(void)¶: detach unimplemented runtime functions

Parameters

void: no arguments

__efi_runtime efi_status_t EFIAPI efi_set_virtual_address_map_runtime(efi_uintn_t memory_map_size, efi_uintn_t descriptor_size, uint32_t descriptor_version, struct efi_mem_desc *virtmap)¶: change from physical to virtual mapping

Parameters

efi_uintn_t memory_map_size: size of the virtual map
efi_uintn_t descriptor_size: size of an entry in the map
uint32_t descriptor_version: version of the map entries
struct efi_mem_desc *virtmap: virtual address mapping information

Description

This function implements the SetVirtualAddressMap() runtime service after it is first called.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code EFI_UNSUPPORTED

__efi_runtime efi_status_t EFIAPI efi_convert_pointer_runtime(efi_uintn_t debug_disposition, void **address)¶: convert from physical to virtual pointer

Parameters

efi_uintn_t debug_disposition: indicates if pointer may be converted to NULL
void **address: pointer to be converted

Description

This function implements the ConvertPointer() runtime service after the first call to SetVirtualAddressMap().

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code EFI_UNSUPPORTED

__efi_runtime efi_status_t EFIAPI efi_convert_pointer(efi_uintn_t debug_disposition, void **address)¶: convert from physical to virtual pointer

Parameters

efi_uintn_t debug_disposition: indicates if pointer may be converted to NULL
void **address: pointer to be converted

Description

This function implements the ConvertPointer() runtime service until the first call to SetVirtualAddressMap().

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_set_virtual_address_map(efi_uintn_t memory_map_size, efi_uintn_t descriptor_size, uint32_t descriptor_version, struct efi_mem_desc *virtmap)¶: change from physical to virtual mapping

Parameters

efi_uintn_t memory_map_size: size of the virtual map
efi_uintn_t descriptor_size: size of an entry in the map
uint32_t descriptor_version: version of the map entries
struct efi_mem_desc *virtmap: virtual address mapping information

Description

This function implements the SetVirtualAddressMap() runtime service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_add_runtime_mmio(void *mmio_ptr, u64 len)¶: add memory-mapped IO region

Parameters

void *mmio_ptr: pointer to a pointer to the start of the memory-mapped IO region
u64 len: size of the memory-mapped IO region

Description

This function adds a memory-mapped IO region to the memory map to make it available at runtime.

Return

status code

efi_status_t __efi_runtime EFIAPI efi_unimplemented(void)¶: replacement function, returns EFI_UNSUPPORTED

Parameters

void: no arguments

Description

This function is used after SetVirtualAddressMap() is called as replacement for services that are not available anymore due to constraints of the U-Boot implementation.

Return

EFI_UNSUPPORTED

Variable services¶

efi_status_t efi_get_variable_int(const u16 *variable_name, const efi_guid_t *vendor, u32 *attributes, efi_uintn_t *data_size, void *data, u64 *timep)¶: retrieve value of a UEFI variable

Parameters

const u16 *variable_name: name of the variable
const efi_guid_t *vendor: vendor GUID
u32 *attributes: attributes of the variable
efi_uintn_t *data_size: size of the buffer to which the variable value is copied
void *data: buffer to which the variable value is copied
u64 *timep: authentication time (seconds since start of epoch)

Return

status code

efi_status_t efi_set_variable_int(const u16 *variable_name, const efi_guid_t *vendor, u32 attributes, efi_uintn_t data_size, const void *data, bool ro_check)¶: set value of a UEFI variable

Parameters

const u16 *variable_name: name of the variable
const efi_guid_t *vendor: vendor GUID
u32 attributes: attributes of the variable
efi_uintn_t data_size: size of the buffer with the variable value
const void *data: buffer with the variable value
bool ro_check: check the read only read only bit in attributes

Return

status code

efi_status_t efi_get_next_variable_name_int(efi_uintn_t *variable_name_size, u16 *variable_name, efi_guid_t *vendor)¶: enumerate the current variable names

Parameters

efi_uintn_t *variable_name_size: size of variable_name buffer in byte
u16 *variable_name: name of uefi variable’s name in u16
efi_guid_t *vendor: vendor’s guid

Description

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t efi_query_variable_info_int(u32 attributes, u64 *maximum_variable_storage_size, u64 *remaining_variable_storage_size, u64 *maximum_variable_size)¶: get information about EFI variables

Parameters

u32 attributes: bitmask to select variables to be queried
u64 *maximum_variable_storage_size: maximum size of storage area for the selected variable types
u64 *remaining_variable_storage_size: remaining size of storage are for the selected variable types
u64 *maximum_variable_size: maximum size of a variable of the selected type

Description

This function implements the QueryVariableInfo() runtime service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

struct efi_var_entry¶: UEFI variable file entry

Definition

struct efi_var_entry {
  u32 length;
  u32 attr;
  u64 time;
  efi_guid_t guid;
  u16 name[];
};

Members

length: length of enty, multiple of 8
attr: variable attributes
time: authentication time (seconds since start of epoch)
guid: vendor GUID
name: UTF16 variable name

struct efi_var_file¶: file for storing UEFI variables

Definition

struct efi_var_file {
  u64 reserved;
  u64 magic;
  u32 length;
  u32 crc32;
  struct efi_var_entry var[];
};

Members

reserved: unused, may be overwritten by memory probing
magic: identifies file format, takes value EFI_VAR_FILE_MAGIC
length: length including header
crc32: CRC32 without header
var: variables

efi_status_t efi_var_to_file(void)¶: save non-volatile variables as file

Parameters

void: no arguments

Description

File ubootefi.var is created on the EFI system partion.

Return

status code

efi_status_t __maybe_unused efi_var_collect(struct efi_var_file **bufp, loff_t *lenp, u32 check_attr_mask)¶: collect variables in buffer

Parameters

struct efi_var_file **bufp: pointer to pointer of buffer with collected variables
loff_t *lenp: pointer to length of buffer
u32 check_attr_mask: bitmask with required attributes of variables to be collected. variables are only collected if all of the required attributes are set.

Description

A buffer is allocated and filled with variables in a format ready to be written to disk.

Return

status code

efi_status_t efi_var_restore(struct efi_var_file *buf, bool safe)¶: restore EFI variables from buffer

Parameters

struct efi_var_file *buf: buffer
bool safe: restoring from tamper-resistant storage

Description

Only if safe is set secure boot related variables will be restored.

Return

status code

efi_status_t efi_var_from_file(void)¶: read variables from file

Parameters

void: no arguments

Description

File ubootefi.var is read from the EFI system partitions and the variables stored in the file are created.

In case the file does not exist yet or a variable cannot be set EFI_SUCCESS is returned.

Return

status code

efi_status_t efi_var_mem_init(void)¶: set-up variable list

Parameters

void: no arguments

Return

status code

struct efi_var_entry *efi_var_mem_find(const efi_guid_t *guid, const u16 *name, struct efi_var_entry **next)¶: find a variable in the list

Parameters

const efi_guid_t *guid: GUID of the variable
const u16 *name: name of the variable
struct efi_var_entry **next: on exit pointer to the next variable after the found one

Return

found variable

void efi_var_mem_del(struct efi_var_entry *var)¶: delete a variable from the list of variables

Parameters

struct efi_var_entry *var: variable to delete

efi_status_t efi_var_mem_ins(const u16 *variable_name, const efi_guid_t *vendor, u32 attributes, const efi_uintn_t size1, const void *data1, const efi_uintn_t size2, const void *data2, const u64 time)¶: append a variable to the list of variables

Parameters

const u16 *variable_name: variable name
const efi_guid_t *vendor: GUID
u32 attributes: variable attributes
const efi_uintn_t size1: size of the first data buffer
const void *data1: first data buffer
const efi_uintn_t size2: size of the second data field
const void *data2: second data buffer
const u64 time: time of authentication (as seconds since start of epoch) Result: status code

Description

The variable is appended without checking if a variable of the same name already exists. The two data buffers are concatenated.

u64 efi_var_mem_free(void)¶: determine free memory for variables

Parameters

void: no arguments

Return

maximum data size plus variable name size

efi_status_t efi_init_secure_state(void)¶: initialize secure boot state

Parameters

void: no arguments

Return

status code

enum efi_auth_var_type efi_auth_var_get_type(const u16 *name, const efi_guid_t *guid)¶: convert variable name and guid to enum

Parameters

const u16 *name: name of UEFI variable
const efi_guid_t *guid: guid of UEFI variable

Return

identifier for authentication related variables

const efi_guid_t *efi_auth_var_get_guid(const u16 *name)¶: get the predefined GUID for a variable name

Parameters

const u16 *name: name of UEFI variable

Return

guid of UEFI variable

efi_status_t __efi_runtime efi_get_next_variable_name_mem(efi_uintn_t *variable_name_size, u16 *variable_name, efi_guid_t *vendor)¶: Runtime common code across efi variable implementations for GetNextVariable() from the cached memory copy

Parameters

efi_uintn_t *variable_name_size: size of variable_name buffer in bytes
u16 *variable_name: name of uefi variable’s name in u16
efi_guid_t *vendor: vendor’s guid

Return

status code

efi_status_t __efi_runtime efi_get_variable_mem(const u16 *variable_name, const efi_guid_t *vendor, u32 *attributes, efi_uintn_t *data_size, void *data, u64 *timep)¶: Runtime common code across efi variable implementations for GetVariable() from the cached memory copy

Parameters

const u16 *variable_name: name of the variable
const efi_guid_t *vendor: vendor GUID
u32 *attributes: attributes of the variable
efi_uintn_t *data_size: size of the buffer to which the variable value is copied
void *data: buffer to which the variable value is copied
u64 *timep: authentication time (seconds since start of epoch)

Return

status code

efi_status_t __efi_runtime EFIAPI efi_get_variable_runtime(u16 *variable_name, const efi_guid_t *guid, u32 *attributes, efi_uintn_t *data_size, void *data)¶: runtime implementation of GetVariable()

Parameters

u16 *variable_name: name of the variable
const efi_guid_t *guid: vendor GUID
u32 *attributes: attributes of the variable
efi_uintn_t *data_size: size of the buffer to which the variable value is copied
void *data: buffer to which the variable value is copied

Return

status code

efi_status_t __efi_runtime EFIAPI efi_get_next_variable_name_runtime(efi_uintn_t *variable_name_size, u16 *variable_name, efi_guid_t *guid)¶: runtime implementation of GetNextVariable()

Parameters

efi_uintn_t *variable_name_size: size of variable_name buffer in byte
u16 *variable_name: name of uefi variable’s name in u16
efi_guid_t *guid: vendor’s guid

Return

status code

void efi_var_buf_update(struct efi_var_file *var_buf)¶: udpate memory buffer for variables

Parameters

struct efi_var_file *var_buf: source buffer

Description

This function copies to the memory buffer for UEFI variables. Call this function in ExitBootServices() if memory backed variables are only used at runtime to fill the buffer.

efi_status_t efi_variable_authenticate(const u16 *variable, const efi_guid_t *vendor, efi_uintn_t *data_size, const void **data, u32 given_attr, u32 *env_attr, u64 *time)¶: authenticate a variable

Parameters

const u16 *variable: Variable name in u16
const efi_guid_t *vendor: Guid of variable
efi_uintn_t *data_size: Size of data
const void **data: Pointer to variable’s value
u32 given_attr: Attributes to be given at SetVariable()
u32 *env_attr: Attributes that an existing variable holds
u64 *time: signed time that an existing variable holds

Description

Called by efi_set_variable() to verify that the input is correct. Will replace the given data pointer with another that points to the actual data to store in the internal memory. On success, data and data_size will be replaced with variable’s actual data, excluding authentication data, and its size, and variable’s attributes and signed time will also be returned in env_attr and time, respectively.

Return

status code

efi_status_t __efi_runtime EFIAPI efi_query_variable_info_runtime(u32 attributes, u64 *maximum_variable_storage_size, u64 *remaining_variable_storage_size, u64 *maximum_variable_size)¶: runtime implementation of QueryVariableInfo()

Parameters

u32 attributes: bitmask to select variables to be queried
u64 *maximum_variable_storage_size: maximum size of storage area for the selected variable types
u64 *remaining_variable_storage_size: remaining size of storage are for the selected variable types
u64 *maximum_variable_size: maximum size of a variable of the selected type

Return

status code

efi_status_t __efi_runtime EFIAPI efi_set_variable_runtime(u16 *variable_name, const efi_guid_t *vendor, u32 attributes, efi_uintn_t data_size, const void *data)¶: runtime implementation of SetVariable()

Parameters

u16 *variable_name: name of the variable
const efi_guid_t *vendor: vendor GUID
u32 attributes: attributes of the variable
efi_uintn_t data_size: size of the buffer with the variable value
const void *data: buffer with the variable value

Return

status code

void efi_variables_boot_exit_notify(void)¶: notify ExitBootServices() is called

Parameters

void: no arguments

efi_status_t efi_init_variables(void)¶: initialize variable services

Parameters

void: no arguments

Return

status code

UEFI drivers¶

UEFI driver uclass¶

efi_status_t check_node_type(efi_handle_t handle)¶: check node type

Parameters

efi_handle_t handle: handle to be checked

Description

We do not support partitions as controller handles.

Return

status code

efi_status_t EFIAPI efi_uc_supported(struct efi_driver_binding_protocol *this, efi_handle_t controller_handle, struct efi_device_path *remaining_device_path)¶: check if the driver supports the controller

Parameters

struct efi_driver_binding_protocol *this: driver binding protocol
efi_handle_t controller_handle: handle of the controller
struct efi_device_path *remaining_device_path: path specifying the child controller

Return

status code

efi_status_t EFIAPI efi_uc_start(struct efi_driver_binding_protocol *this, efi_handle_t controller_handle, struct efi_device_path *remaining_device_path)¶: create child controllers and attach driver

Parameters

struct efi_driver_binding_protocol *this: driver binding protocol
efi_handle_t controller_handle: handle of the controller
struct efi_device_path *remaining_device_path: path specifying the child controller

Return

status code

efi_status_t disconnect_child(efi_handle_t controller_handle, efi_handle_t child_handle)¶: remove a single child controller from the parent controller

Parameters

efi_handle_t controller_handle: parent controller
efi_handle_t child_handle: child controller

Return

status code

efi_status_t EFIAPI efi_uc_stop(struct efi_driver_binding_protocol *this, efi_handle_t controller_handle, size_t number_of_children, efi_handle_t *child_handle_buffer)¶: Remove child controllers and disconnect the controller

Parameters

struct efi_driver_binding_protocol *this: driver binding protocol
efi_handle_t controller_handle: handle of the controller
size_t number_of_children: number of child controllers to remove
efi_handle_t *child_handle_buffer: handles of the child controllers to remove

Return

status code

efi_status_t efi_add_driver(struct driver *drv)¶: add driver

Parameters

struct driver *drv: driver to add

Return

status code

efi_status_t efi_driver_init(void)¶: initialize the EFI drivers

Parameters

void: no arguments

Description

Called by efi_init_obj_list().

Return

0 = success, any other value will stop further execution

int efi_uc_init(struct uclass *class)¶: initialize the EFI uclass

Parameters

struct uclass *class: the EFI uclass

Return

0 = success

int efi_uc_destroy(struct uclass *class)¶: destroy the EFI uclass

Parameters

struct uclass *class: the EFI uclass

Return

0 = success

Block device driver¶

struct efi_blk_plat¶: attributes of a block device

Definition

struct efi_blk_plat {
  efi_handle_t handle;
  struct efi_block_io     *io;
};

Members

handle: handle of the controller on which this driver is installed
io: block io protocol proxied by this driver

ulong efi_bl_read(struct udevice *dev, lbaint_t blknr, lbaint_t blkcnt, void *buffer)¶: read from block device

Parameters

struct udevice *dev: device
lbaint_t blknr: first block to be read
lbaint_t blkcnt: number of blocks to read
void *buffer: output buffer

Return

number of blocks transferred

ulong efi_bl_write(struct udevice *dev, lbaint_t blknr, lbaint_t blkcnt, const void *buffer)¶: write to block device

Parameters

struct udevice *dev: device
lbaint_t blknr: first block to be write
lbaint_t blkcnt: number of blocks to write
const void *buffer: input buffer

Return

number of blocks transferred

efi_status_t efi_bl_create_block_device(efi_handle_t handle, void *interface)¶: create a block device for a handle

Parameters

efi_handle_t handle: handle
void *interface: block io protocol

Return

status code

efi_status_t efi_bl_bind(struct efi_driver_binding_extended_protocol *this, efi_handle_t handle, void *interface)¶: bind to a block io protocol

Parameters

struct efi_driver_binding_extended_protocol *this: driver binding protocol
efi_handle_t handle: handle
void *interface: block io protocol

Return

status code

efi_status_t efi_bl_init(struct efi_driver_binding_extended_protocol *this)¶: initialize block device driver

Parameters

struct efi_driver_binding_extended_protocol *this: extended driver binding protocol

Protocols¶

Block IO protocol¶

struct efi_disk_obj¶: EFI disk object

Definition

struct efi_disk_obj {
  struct efi_object header;
  struct efi_block_io ops;
  int dev_index;
  struct efi_block_io_media media;
  struct efi_device_path *dp;
  unsigned int part;
  struct efi_simple_file_system_protocol *volume;
};

Members

header: EFI object header
ops: EFI disk I/O protocol interface
dev_index: device index of block device
media: block I/O media information
dp: device path to the block device
part: partition
volume: simple file system protocol of the partition

efi_status_t EFIAPI efi_disk_reset(struct efi_block_io *this, char extended_verification)¶: reset block device

Parameters

struct efi_block_io *this: pointer to the BLOCK_IO_PROTOCOL
char extended_verification: extended verification

Description

This function implements the Reset service of the EFI_BLOCK_IO_PROTOCOL.

As U-Boot’s block devices do not have a reset function simply return EFI_SUCCESS.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

bool efi_disk_is_removable(efi_handle_t handle)¶: check if the device is removable media

Parameters

efi_handle_t handle: efi object handle;

Description

Examine the device and determine if the device is a local block device and removable media.

Return

true if removable, false otherwise

efi_status_t EFIAPI efi_disk_read_blocks(struct efi_block_io *this, u32 media_id, u64 lba, efi_uintn_t buffer_size, void *buffer)¶: reads blocks from device

Parameters

struct efi_block_io *this: pointer to the BLOCK_IO_PROTOCOL
u32 media_id: id of the medium to be read from
u64 lba: starting logical block for reading
efi_uintn_t buffer_size: size of the read buffer
void *buffer: pointer to the destination buffer

Description

This function implements the ReadBlocks service of the EFI_BLOCK_IO_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_disk_write_blocks(struct efi_block_io *this, u32 media_id, u64 lba, efi_uintn_t buffer_size, void *buffer)¶: writes blocks to device

Parameters

struct efi_block_io *this: pointer to the BLOCK_IO_PROTOCOL
u32 media_id: id of the medium to be written to
u64 lba: starting logical block for writing
efi_uintn_t buffer_size: size of the write buffer
void *buffer: pointer to the source buffer

Description

This function implements the WriteBlocks service of the EFI_BLOCK_IO_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_disk_flush_blocks(struct efi_block_io *this)¶: flushes modified data to the device

Parameters

struct efi_block_io *this: pointer to the BLOCK_IO_PROTOCOL

Description

This function implements the FlushBlocks service of the EFI_BLOCK_IO_PROTOCOL.

As we always write synchronously nothing is done here.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

struct efi_simple_file_system_protocol *efi_fs_from_path(struct efi_device_path *full_path)¶: retrieve simple file system protocol

Parameters

struct efi_device_path *full_path: device path including device and file

Description

Gets the simple file system protocol for a file device path.

The full path provided is split into device part and into a file part. The device part is used to find the handle on which the simple file system protocol is installed.

Return

simple file system protocol

int efi_fs_exists(struct blk_desc *desc, int part)¶: check if a partition bears a file system

Parameters

struct blk_desc *desc: block device descriptor
int part: partition number

Return

1 if a file system exists on the partition: 0 otherwise

efi_status_t efi_disk_add_dev(efi_handle_t parent, struct efi_device_path *dp_parent, struct blk_desc *desc, int dev_index, struct disk_partition *part_info, unsigned int part, struct efi_disk_obj **disk, efi_handle_t agent_handle)¶: create a handle for a partition or disk

Parameters

efi_handle_t parent: parent handle
struct efi_device_path *dp_parent: parent device path
struct blk_desc *desc: internal block device
int dev_index: device index for block device
struct disk_partition *part_info: partition info
unsigned int part: partition
struct efi_disk_obj **disk: pointer to receive the created handle
efi_handle_t agent_handle: handle of the EFI block driver

Return

disk object

int efi_disk_create_raw(struct udevice *dev, efi_handle_t agent_handle)¶: create a handle for a whole raw disk

Parameters

struct udevice *dev: udevice (UCLASS_BLK)
efi_handle_t agent_handle: handle of the EFI block driver

Description

Create an efi_disk object which is associated with dev. The type of dev must be UCLASS_BLK.

Return

0 on success, -1 otherwise

int efi_disk_create_part(struct udevice *dev, efi_handle_t agent_handle)¶: create a handle for a disk partition

Parameters

struct udevice *dev: udevice (UCLASS_PARTITION)
efi_handle_t agent_handle: handle of the EFI block driver

Description

Create an efi_disk object which is associated with dev. The type of dev must be UCLASS_PARTITION.

Return

0 on success, -1 otherwise

int efi_disk_probe(void *ctx, struct event *event)¶: create efi_disk objects for a block device

Parameters

void *ctx: event context - driver binding protocol
struct event *event: EV_PM_POST_PROBE event

Description

Create efi_disk objects for partitions as well as a raw disk which is associated with dev. The type of dev must be UCLASS_BLK. This function is expected to be called at EV_PM_POST_PROBE.

Return

0 on success, -1 otherwise

efi_status_t efi_disk_get_device_name(const efi_handle_t handle, char *buf, int size)¶: get U-Boot device name associated with EFI handle

Parameters

const efi_handle_t handle: pointer to the EFI handle
char *buf: pointer to the buffer to store the string
int size: size of buffer

Return

status code

efi_status_t efi_disks_register(void)¶: ensure all block devices are available in UEFI

Parameters

void: no arguments

Description

The function probes all block devices. As we store UEFI variables on the EFI system partition this function has to be called before enabling variable services.

File protocol¶

int is_dir(struct file_handle *fh)¶: check if file handle points to directory

Parameters

struct file_handle *fh: file handle

Description

We assume that set_blk_dev(fh) has been called already.

Return

true if file handle points to a directory

int efi_create_file(struct file_handle *fh, u64 attributes)¶: create file or directory

Parameters

struct file_handle *fh: file handle
u64 attributes: attributes for newly created file

Return

0 for success

struct efi_file_handle *file_open(struct file_system *fs, struct file_handle *parent, u16 *file_name, u64 open_mode, u64 attributes)¶: open a file handle

Parameters

struct file_system *fs: file system
struct file_handle *parent: directory relative to which the file is to be opened
u16 *file_name: path of the file to be opened. ‘', ‘.’, or ‘..’ may be used as modifiers. A leading backslash indicates an absolute path.
u64 open_mode: bit mask indicating the access mode (read, write, create)
u64 attributes: attributes for newly created file

Return

handle to the opened file or NULL

efi_status_t EFIAPI efi_file_open(struct efi_file_handle *this, struct efi_file_handle **new_handle, u16 *file_name, u64 open_mode, u64 attributes)¶

Parameters

struct efi_file_handle *this: EFI_FILE_PROTOCOL instance
struct efi_file_handle **new_handle: on return pointer to file handle
u16 *file_name: file name
u64 open_mode: mode to open the file (read, read/write, create/read/write)
u64 attributes: attributes for newly created file

Description

This function implements the Open service of the File Protocol. See the UEFI spec for details.

efi_status_t EFIAPI efi_file_open_ex(struct efi_file_handle *this, struct efi_file_handle **new_handle, u16 *file_name, u64 open_mode, u64 attributes, struct efi_file_io_token *token)¶: open file asynchronously

Parameters

struct efi_file_handle *this: EFI_FILE_PROTOCOL instance
struct efi_file_handle **new_handle: on return pointer to file handle
u16 *file_name: file name
u64 open_mode: mode to open the file (read, read/write, create/read/write)
u64 attributes: attributes for newly created file
struct efi_file_io_token *token: transaction token

Description

This function implements the OpenEx service of the File Protocol. See the UEFI spec for details.

efi_status_t efi_get_file_size(struct file_handle *fh, loff_t *file_size)¶: determine the size of a file

Parameters

struct file_handle *fh: file handle
loff_t *file_size: pointer to receive file size

Return

status code

efi_status_t efi_file_size(struct efi_file_handle *fh, efi_uintn_t *size)¶: Get the size of a file using an EFI file handle

Parameters

struct efi_file_handle *fh: EFI file handle
efi_uintn_t *size: buffer to fill in the discovered size

Return

size of the file

efi_status_t EFIAPI efi_file_read(struct efi_file_handle *this, efi_uintn_t *buffer_size, void *buffer)¶: read file

Parameters

struct efi_file_handle *this: file protocol instance
efi_uintn_t *buffer_size: number of bytes to read
void *buffer: read buffer

Description

This function implements the Read() service of the EFI_FILE_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_file_read_ex(struct efi_file_handle *this, struct efi_file_io_token *token)¶: read file asynchonously

Parameters

struct efi_file_handle *this: file protocol instance
struct efi_file_io_token *token: transaction token

Description

This function implements the ReadEx() service of the EFI_FILE_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_file_write(struct efi_file_handle *this, efi_uintn_t *buffer_size, void *buffer)¶: write to file

Parameters

struct efi_file_handle *this: file protocol instance
efi_uintn_t *buffer_size: number of bytes to write
void *buffer: buffer with the bytes to write

Description

This function implements the Write() service of the EFI_FILE_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_file_write_ex(struct efi_file_handle *this, struct efi_file_io_token *token)¶: write to file

Parameters

struct efi_file_handle *this: file protocol instance
struct efi_file_io_token *token: transaction token

Description

This function implements the WriteEx() service of the EFI_FILE_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_file_getpos(struct efi_file_handle *file, u64 *pos)¶: get current position in file

Parameters

struct efi_file_handle *file: file handle
u64 *pos: pointer to file position

Description

This function implements the GetPosition service of the EFI file protocol. See the UEFI spec for details.

Return

status code

efi_status_t EFIAPI efi_file_setpos(struct efi_file_handle *file, u64 pos)¶: set current position in file

Parameters

struct efi_file_handle *file: file handle
u64 pos: new file position

Description

This function implements the SetPosition service of the EFI file protocol. See the UEFI spec for details.

Return

status code

efi_status_t efi_file_flush_int(struct efi_file_handle *this)¶: flush file

Parameters

struct efi_file_handle *this: file protocol instance

Description

This is the internal implementation of the Flush() and FlushEx() services of the EFI_FILE_PROTOCOL.

Return

status code

efi_status_t EFIAPI efi_file_flush(struct efi_file_handle *this)¶: flush file

Parameters

struct efi_file_handle *this: file protocol instance

Description

This function implements the Flush() service of the EFI_FILE_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_file_flush_ex(struct efi_file_handle *this, struct efi_file_io_token *token)¶: flush file

Parameters

struct efi_file_handle *this: file protocol instance
struct efi_file_io_token *token: transaction token

Description

This function implements the FlushEx() service of the EFI_FILE_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

struct efi_file_handle *efi_file_from_path(struct efi_device_path *fp)¶: open file via device path

Parameters

struct efi_device_path *fp: device path

Description

The device path fp consists of the device path of the handle with the simple file system protocol and one or more file path device path nodes. The concatenation of all file path names provides the total file path.

The code starts at the first file path node and tries to open that file or directory. If there is a succeding file path node, the code opens it relative to this directory and continues iterating until reaching the last file path node.

Return

EFI_FILE_PROTOCOL for the file or NULL

Graphical output protocol¶

struct efi_gop_obj¶: graphical output protocol object

Definition

struct efi_gop_obj {
  struct efi_object header;
  struct efi_gop ops;
  struct efi_gop_mode_info info;
  struct efi_gop_mode mode;
  u32 bpix;
  void *fb;
};

Members

header: EFI object header
ops: graphical output protocol interface
info: graphical output mode information
mode: graphical output mode
bpix: bits per pixel
fb: frame buffer

efi_status_t EFIAPI gop_set_mode(struct efi_gop *this, u32 mode_number)¶: set graphical output mode

Parameters

struct efi_gop *this: the graphical output protocol
u32 mode_number: the mode to be set

Description

This function implements the SetMode() service.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

Load file 2 protocol¶

The load file 2 protocol can be used by the Linux kernel to load the initial RAM disk. U-Boot can be configured to provide an implementation.

efi_status_t get_initrd_fp(struct efi_device_path **initrd_fp)¶: Get initrd device path from a FilePathList device path

Parameters

struct efi_device_path **initrd_fp: the final initrd filepath

Return

status code. Caller must free initrd_fp

efi_status_t EFIAPI efi_load_file2_initrd(struct efi_load_file_protocol *this, struct efi_device_path *file_path, bool boot_policy, efi_uintn_t *buffer_size, void *buffer)¶: load initial RAM disk

Parameters

struct efi_load_file_protocol *this: EFI_LOAD_FILE2_PROTOCOL instance
struct efi_device_path *file_path: media device path of the file, “” in this case
bool boot_policy: must be false
efi_uintn_t *buffer_size: size of allocated buffer
void *buffer: buffer to load the file

Description

This function implements the LoadFile service of the EFI_LOAD_FILE2_PROTOCOL in order to load an initial RAM disk requested by the Linux kernel stub.

See the UEFI spec for details.

Return

status code

efi_status_t check_initrd(void)¶: Determine if the file defined as an initrd in Boot#### load_options device path is present

Parameters

void: no arguments

Return

status code

efi_status_t efi_initrd_register(void)¶: create handle for loading initial RAM disk

Parameters

void: no arguments

Description

This function creates a new handle and installs a Linux specific vendor device path and an EFI_LOAD_FILE2_PROTOCOL. Linux uses the device path to identify the handle and then calls the LoadFile service of the EFI_LOAD_FILE2_PROTOCOL to read the initial RAM disk.

Return

status code

efi_status_t efi_initrd_deregister(void)¶: delete the handle for loading initial RAM disk

Parameters

void: no arguments

Description

This will delete the handle containing the Linux specific vendor device path and EFI_LOAD_FILE2_PROTOCOL for loading an initrd

Return

status code

Network protocols¶

struct efi_net_obj¶: EFI object representing a network interface

Definition

struct efi_net_obj {
  struct efi_object header;
  struct efi_simple_network net;
  struct efi_simple_network_mode net_mode;
  struct efi_pxe_base_code_protocol pxe;
  struct efi_pxe_mode pxe_mode;
};

Members

header: EFI object header
net: simple network protocol interface
net_mode: status of the network interface
pxe: PXE base code protocol interface
pxe_mode: status of the PXE base code protocol

efi_status_t EFIAPI efi_net_nvdata(struct efi_simple_network *this, int read_write, ulong offset, ulong buffer_size, char *buffer)¶: read or write NVRAM

Parameters

struct efi_simple_network *this: the instance of the Simple Network Protocol
int read_write: true for read, false for write
ulong offset: offset in NVRAM
ulong buffer_size: size of buffer
char *buffer: buffer

Description

This function implements the GetStatus service of the Simple Network Protocol. See the UEFI spec for details.

Return

status code

efi_status_t EFIAPI efi_net_get_status(struct efi_simple_network *this, u32 *int_status, void **txbuf)¶: get interrupt status

Parameters

struct efi_simple_network *this: the instance of the Simple Network Protocol
u32 *int_status: interface status
void **txbuf: transmission buffer

Description

This function implements the GetStatus service of the Simple Network Protocol. See the UEFI spec for details.

efi_status_t EFIAPI efi_net_transmit(struct efi_simple_network *this, size_t header_size, size_t buffer_size, void *buffer, struct efi_mac_address *src_addr, struct efi_mac_address *dest_addr, u16 *protocol)¶: transmit a packet

Parameters

struct efi_simple_network *this: the instance of the Simple Network Protocol
size_t header_size: size of the media header
size_t buffer_size: size of the buffer to receive the packet
void *buffer: buffer to receive the packet
struct efi_mac_address *src_addr: source hardware MAC address
struct efi_mac_address *dest_addr: destination hardware MAC address
u16 *protocol: type of header to build

Description

This function implements the Transmit service of the Simple Network Protocol. See the UEFI spec for details.

Return

status code

efi_status_t EFIAPI efi_net_receive(struct efi_simple_network *this, size_t *header_size, size_t *buffer_size, void *buffer, struct efi_mac_address *src_addr, struct efi_mac_address *dest_addr, u16 *protocol)¶: receive a packet from a network interface

Parameters

struct efi_simple_network *this: the instance of the Simple Network Protocol
size_t *header_size: size of the media header
size_t *buffer_size: size of the buffer to receive the packet
void *buffer: buffer to receive the packet
struct efi_mac_address *src_addr: source MAC address
struct efi_mac_address *dest_addr: destination MAC address
u16 *protocol: protocol

Description

This function implements the Receive service of the Simple Network Protocol. See the UEFI spec for details.

Return

status code

void efi_net_set_dhcp_ack(void *pkt, int len)¶: take note of a selected DHCP IP address

Parameters

void *pkt: packet received by dhcp_handler()
int len: length of the packet received

Description

This function is called by dhcp_handler().

void efi_net_push(void *pkt, int len)¶: callback for received network packet

Parameters

void *pkt: network packet
int len: length

Description

This function is called when a network packet is received by eth_rx().

void EFIAPI efi_network_timer_notify(struct efi_event *event, void *context)¶: check if a new network packet has been received

Parameters

struct efi_event *event: the event for which this notification function is registered
void *context: event context - not used in this function

Description

This notification function is called in every timer cycle.

efi_status_t efi_net_register(void)¶: register the simple network protocol

Parameters

void: no arguments

Description

This gets called from do_bootefi_exec().

Random number generator protocol¶

efi_status_t platform_get_rng_device(struct udevice **dev)¶: retrieve random number generator

Parameters

struct udevice **dev: udevice

Description

This function retrieves the udevice implementing a hardware random number generator.

This function may be overridden if special initialization is needed.

Return

status code

efi_status_t EFIAPI rng_getinfo(struct efi_rng_protocol *this, efi_uintn_t *rng_algorithm_list_size, efi_guid_t *rng_algorithm_list)¶: get information about random number generation

Parameters

struct efi_rng_protocol *this: random number generator protocol instance
efi_uintn_t *rng_algorithm_list_size: number of random number generation algorithms
efi_guid_t *rng_algorithm_list: descriptions of random number generation algorithms

Description

This function implement the GetInfo() service of the EFI random number generator protocol. See the UEFI spec for details.

Return

status code

efi_status_t EFIAPI getrng(struct efi_rng_protocol *this, efi_guid_t *rng_algorithm, efi_uintn_t rng_value_length, uint8_t *rng_value)¶: get random value

Parameters

struct efi_rng_protocol *this: random number generator protocol instance
efi_guid_t *rng_algorithm: random number generation algorithm
efi_uintn_t rng_value_length: number of random bytes to generate, buffer length
uint8_t *rng_value: buffer to receive random bytes

Description

This function implement the GetRng() service of the EFI random number generator protocol. See the UEFI spec for details.

Return

status code

efi_status_t efi_rng_register(void)¶: register EFI_RNG_PROTOCOL

Parameters

void: no arguments

Description

If a RNG device is available, the Random Number Generator Protocol is registered.

Return

An error status is only returned if adding the protocol fails.

Text IO protocols¶

int term_get_char(s32 *c)¶: read a character from the console

Parameters

s32 *c: pointer to the buffer to receive the character

Description

Wait for up to 100 ms to read a character from the console.

Return

0 on success, 1 otherwise

int term_read_reply(int *n, int num, char end_char)¶

Parameters

int *n: array of return values
int num: number of return values expected
char end_char: character indicating end of terminal message

Return

non-zero indicates error

efi_status_t EFIAPI efi_cout_output_string(struct efi_simple_text_output_protocol *this, const u16 *string)¶: write Unicode string to console

Parameters

struct efi_simple_text_output_protocol *this: simple text output protocol
const u16 *string: u16 string

Description

This function implements the OutputString service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_cout_test_string(struct efi_simple_text_output_protocol *this, const u16 *string)¶: test writing Unicode string to console

Parameters

struct efi_simple_text_output_protocol *this: simple text output protocol
const u16 *string: u16 string

Description

This function implements the TestString service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

As in OutputString we simply convert UTF-16 to UTF-8 there are no unsupported code points and we can always return EFI_SUCCESS.

Return

status code

bool cout_mode_matches(struct cout_mode *mode, int rows, int cols)¶: check if mode has given terminal size

Parameters

struct cout_mode *mode: text mode
int rows: number of rows
int cols: number of columns

Return

true if number of rows and columns matches the mode and: the mode is present

int query_console_serial(int *rows, int *cols)¶: query serial console size

Parameters

int *rows: pointer to return number of rows
int *cols: pointer to return number of columns

Description

When using a serial console or the net console we can only devise the terminal size by querying the terminal using ECMA-48 control sequences.

Return

0 on success

int __maybe_unused query_vidconsole(int *rows, int *cols)¶: query video console size

Parameters

int *rows: pointer to return number of rows
int *cols: pointer to return number of columns

Description

Return

0 on success

void efi_setup_console_size(void)¶: update the mode table.

Parameters

void: no arguments

Description

By default the only mode available is 80x25. If the console has at least 50 lines, enable mode 80x50. If we can query the console size and it is neither 80x25 nor 80x50, set it as an additional mode.

efi_status_t EFIAPI efi_cout_query_mode(struct efi_simple_text_output_protocol *this, unsigned long mode_number, unsigned long *columns, unsigned long *rows)¶: get terminal size for a text mode

Parameters

struct efi_simple_text_output_protocol *this: simple text output protocol
unsigned long mode_number: mode number to retrieve information on
unsigned long *columns: number of columns
unsigned long *rows: number of rows

Description

This function implements the QueryMode service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_cout_set_attribute(struct efi_simple_text_output_protocol *this, unsigned long attribute)¶: set fore- and background color

Parameters

struct efi_simple_text_output_protocol *this: simple text output protocol
unsigned long attribute: foreground color - bits 0-3, background color - bits 4-6

Description

This function implements the SetAttribute service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

void efi_clear_screen(void)¶: clear screen

Parameters

void: no arguments

efi_status_t EFIAPI efi_cout_clear_screen(struct efi_simple_text_output_protocol *this)¶: clear screen

Parameters

struct efi_simple_text_output_protocol *this: pointer to the protocol instance

Description

This function implements the ClearScreen service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_cout_set_mode(struct efi_simple_text_output_protocol *this, unsigned long mode_number)¶: set text model

Parameters

struct efi_simple_text_output_protocol *this: pointer to the protocol instance
unsigned long mode_number: number of the text mode to set

Description

This function implements the SetMode service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_cout_reset(struct efi_simple_text_output_protocol *this, char extended_verification)¶: reset the terminal

Parameters

struct efi_simple_text_output_protocol *this: pointer to the protocol instance
char extended_verification: if set an extended verification may be executed

Description

This function implements the Reset service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_cout_set_cursor_position(struct efi_simple_text_output_protocol *this, unsigned long column, unsigned long row)¶: reset the terminal

Parameters

struct efi_simple_text_output_protocol *this: pointer to the protocol instance
unsigned long column: column to move to
unsigned long row: row to move to

Description

This function implements the SetCursorPosition service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

efi_status_t EFIAPI efi_cout_enable_cursor(struct efi_simple_text_output_protocol *this, bool enable)¶: enable the cursor

Parameters

struct efi_simple_text_output_protocol *this: pointer to the protocol instance
bool enable: if true enable, if false disable the cursor

Description

This function implements the EnableCursor service of the simple text output protocol. See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

status code

struct efi_cin_notify_function¶: registered console input notify function

Definition

struct efi_cin_notify_function {
  struct list_head link;
  struct efi_key_data key;
  efi_status_t (EFIAPI *function) (struct efi_key_data *key_data);
};

Members

link: link to list
key: key to notify
function: function to call

void set_shift_mask(int mod, struct efi_key_state *key_state)¶: set shift mask

Parameters

int mod: Xterm shift mask
struct efi_key_state *key_state: receives the state of the shift, alt, control, and logo keys

int analyze_modifiers(struct efi_key_state *key_state)¶: analyze modifiers (shift, alt, ctrl) for function keys

Parameters

struct efi_key_state *key_state: receives the state of the shift, alt, control, and logo keys

Description

This gets called when we have already parsed CSI.

Return

the unmodified code

efi_status_t efi_cin_read_key(struct efi_key_data *key)¶: read a key from the console input

Parameters

struct efi_key_data *key

key received

Return

status code

void efi_cin_notify(void)¶: notify registered functions

Parameters

void: no arguments

void efi_cin_check(void)¶: check if keyboard input is available

Parameters

void: no arguments

void efi_cin_empty_buffer(void)¶: empty input buffer

Parameters

void: no arguments

efi_status_t EFIAPI efi_cin_reset_ex(struct efi_simple_text_input_ex_protocol *this, bool extended_verification)¶: reset console input

Parameters

struct efi_simple_text_input_ex_protocol *this

the extended simple text input protocol

bool extended_verification

extended verification

Description

This function implements the reset service of the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

old value of the task priority level

efi_status_t EFIAPI efi_cin_read_key_stroke_ex(struct efi_simple_text_input_ex_protocol *this, struct efi_key_data *key_data)¶: read key stroke

Parameters

struct efi_simple_text_input_ex_protocol *this: instance of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
struct efi_key_data *key_data: key read from console

Return

status code

Description

This function implements the ReadKeyStrokeEx service of the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_cin_set_state(struct efi_simple_text_input_ex_protocol *this, u8 *key_toggle_state)¶: set toggle key state

Parameters

struct efi_simple_text_input_ex_protocol *this: instance of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
u8 *key_toggle_state: pointer to key toggle state

Return

status code

Description

This function implements the SetState service of the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_cin_register_key_notify(struct efi_simple_text_input_ex_protocol *this, struct efi_key_data *key_data, efi_status_t (*key_notify_function)(struct efi_key_data *key_data), void **notify_handle, )¶: register key notification function

Parameters

struct efi_simple_text_input_ex_protocol *this: instance of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
struct efi_key_data *key_data: key to be notified
efi_status_t ( *key_notify_function)( struct efi_key_data *key_data): function to be called if the key is pressed
void **notify_handle: handle for unregistering the notification

Return

status code

Description

This function implements the SetState service of the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_cin_unregister_key_notify(struct efi_simple_text_input_ex_protocol *this, void *notification_handle)¶: unregister key notification function

Parameters

struct efi_simple_text_input_ex_protocol *this: instance of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
void *notification_handle: handle received when registering

Return

status code

Description

This function implements the SetState service of the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_cin_reset(struct efi_simple_text_input_protocol *this, bool extended_verification)¶: drain the input buffer

Parameters

struct efi_simple_text_input_protocol *this: instance of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
bool extended_verification: allow for exhaustive verification

Return

status code

Description

This function implements the Reset service of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

efi_status_t EFIAPI efi_cin_read_key_stroke(struct efi_simple_text_input_protocol *this, struct efi_input_key *key)¶: read key stroke

Parameters

struct efi_simple_text_input_protocol *this: instance of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
struct efi_input_key *key: key read from console

Return

status code

Description

This function implements the ReadKeyStroke service of the EFI_SIMPLE_TEXT_INPUT_PROTOCOL.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

void EFIAPI efi_key_notify(struct efi_event *event, void *context)¶: notify the wait for key event

Parameters

struct efi_event *event: wait for key event
void *context: not used

efi_status_t efi_console_register(void)¶: install the console protocols

Parameters

void: no arguments

Description

This function is called from do_bootefi_exec().

Return

status code

efi_status_t efi_console_get_u16_string(struct efi_simple_text_input_protocol *cin, u16 *buf, efi_uintn_t count, efi_console_filter_func filter_func, int row, int col)¶: get user input string

Parameters

struct efi_simple_text_input_protocol *cin: protocol interface to EFI_SIMPLE_TEXT_INPUT_PROTOCOL
u16 *buf: buffer to store user input string in UTF16
efi_uintn_t count: number of u16 string including NULL terminator that buf has
efi_console_filter_func filter_func: callback to filter user input
int row: row number to locate user input form
int col: column number to locate user input form

Return

status code

Unicode Collation protocol¶

efi_intn_t EFIAPI efi_stri_coll(struct efi_unicode_collation_protocol *this, u16 *s1, u16 *s2)¶: compare utf-16 strings case-insenitively

Parameters

struct efi_unicode_collation_protocol *this: unicode collation protocol instance
u16 *s1: first string
u16 *s2: second string

Description

This function implements the StriColl() service of the EFI_UNICODE_COLLATION_PROTOCOL2.

See the Unified Extensible Firmware Interface (UEFI) specification for details.

Return

0: s1 == s2, > 0: s1 > s2, < 0: s1 < s2

s32 next_lower(const u16 **string)¶: get next codepoint converted to lower case

Parameters

const u16 **string: pointer to u16 string, on return advanced by one codepoint

Return

first codepoint of string converted to lower case

bool metai_match(const u16 *string, const u16 *pattern)¶: compare utf-16 string with a pattern string case-insenitively

Parameters

const u16 *string: string to compare
const u16 *pattern: pattern string

Description

The pattern string may use these:

- matches >= 0 characters
? matches 1 character
[<char1><char2>…<charN>] match any character in the set
[<char1>-<char2>] matches any character in the range

This function is called my efi_metai_match().

For ‘*’ pattern searches this function calls itself recursively. Performance-wise this is suboptimal, especially for multiple ‘*’ wildcards. But it results in simple code.

Return

true if the string is matched.

bool EFIAPI efi_metai_match(struct efi_unicode_collation_protocol *this, const u16 *string, const u16 *pattern)¶: compare utf-16 string with a pattern string case-insenitively

Parameters

struct efi_unicode_collation_protocol *this: unicode collation protocol instance
const u16 *string: string to compare
const u16 *pattern: pattern string

Description

The pattern string may use these:

- matches >= 0 characters
? matches 1 character
[<char1><char2>…<charN>] match any character in the set
[<char1>-<char2>] matches any character in the range

This function implements the MetaMatch() service of the EFI_UNICODE_COLLATION_PROTOCOL2.

Return

true if the string is matched.

void EFIAPI efi_str_lwr(struct efi_unicode_collation_protocol *this, u16 *string)¶: convert to lower case

Parameters

struct efi_unicode_collation_protocol *this: unicode collation protocol instance
u16 *string: string to convert

Description

The conversion is done in place. As long as upper and lower letters use the same number of words this does not pose a problem.

This function implements the StrLwr() service of the EFI_UNICODE_COLLATION_PROTOCOL2.

void EFIAPI efi_str_upr(struct efi_unicode_collation_protocol *this, u16 *string)¶: convert to upper case

Parameters

struct efi_unicode_collation_protocol *this: unicode collation protocol instance
u16 *string: string to convert

Description

The conversion is done in place. As long as upper and lower letters use the same number of words this does not pose a problem.

This function implements the StrUpr() service of the EFI_UNICODE_COLLATION_PROTOCOL2.

void EFIAPI efi_fat_to_str(struct efi_unicode_collation_protocol *this, efi_uintn_t fat_size, char *fat, u16 *string)¶: convert an 8.3 file name from an OEM codepage to Unicode

Parameters

struct efi_unicode_collation_protocol *this: unicode collation protocol instance
efi_uintn_t fat_size: size of the string to convert
char *fat: string to convert
u16 *string: converted string

Description

This function implements the FatToStr() service of the EFI_UNICODE_COLLATION_PROTOCOL2.

bool EFIAPI efi_str_to_fat(struct efi_unicode_collation_protocol *this, const u16 *string, efi_uintn_t fat_size, char *fat)¶: convert a utf-16 string to legal characters for a FAT file name in an OEM code page

Parameters

struct efi_unicode_collation_protocol *this: unicode collation protocol instance
const u16 *string: Unicode string to convert
efi_uintn_t fat_size: size of the target buffer
char *fat: converted string

Description

This function implements the StrToFat() service of the EFI_UNICODE_COLLATION_PROTOCOL2.

Return

true if an illegal character was substituted by ‘_’.

Firmware management protocol¶

struct fmp_payload_header¶: EDK2 header for the FMP payload

Definition

struct fmp_payload_header {
  u32 signature;
  u32 header_size;
  u32 fw_version;
  u32 lowest_supported_version;
};

Members

signature: Header signature used to identify the header
header_size: Size of the structure
fw_version: Firmware versions used
lowest_supported_version: Lowest supported version

Description

This structure describes the header which is preprended to the FMP payload by the edk2 capsule generation scripts.

efi_status_t efi_fill_image_desc_array(efi_uintn_t *image_info_size, struct efi_firmware_image_descriptor *image_info, u32 *descriptor_version, u8 *descriptor_count, efi_uintn_t *descriptor_size, u32 *package_version, u16 **package_version_name)¶: populate image descriptor array

Parameters

efi_uintn_t *image_info_size: Size of image_info
struct efi_firmware_image_descriptor *image_info: Image information
u32 *descriptor_version: Pointer to version number
u8 *descriptor_count: Image count
efi_uintn_t *descriptor_size: Pointer to descriptor size
u32 *package_version: Package version
u16 **package_version_name: Package version’s name

Description

Return information about the current firmware image in image_info. image_info will consist of a number of descriptors. Each descriptor will be created based on efi_fw_image array.

Return status code

efi_status_t efi_firmware_capsule_authenticate(const void **p_image, efi_uintn_t *p_image_size)¶: authenticate the capsule if enabled

Parameters

const void **p_image: Pointer to new image
efi_uintn_t *p_image_size: Pointer to size of new image

Description

Authenticate the capsule if authentication is enabled. The image pointer and the image size are updated in case of success.

Return

status code

efi_status_t EFIAPI efi_firmware_get_image_info(struct efi_firmware_management_protocol *this, efi_uintn_t *image_info_size, struct efi_firmware_image_descriptor *image_info, u32 *descriptor_version, u8 *descriptor_count, efi_uintn_t *descriptor_size, u32 *package_version, u16 **package_version_name)¶: return information about the current firmware image

Parameters

struct efi_firmware_management_protocol *this: Protocol instance
efi_uintn_t *image_info_size: Size of image_info
struct efi_firmware_image_descriptor *image_info: Image information
u32 *descriptor_version: Pointer to version number
u8 *descriptor_count: Pointer to number of descriptors
efi_uintn_t *descriptor_size: Pointer to descriptor size
u32 *package_version: Package version
u16 **package_version_name: Package version’s name

Description

Return information bout the current firmware image in image_info. image_info will consist of a number of descriptors. Each descriptor will be created based on “dfu_alt_info” variable.

Return status code

efi_status_t EFIAPI efi_firmware_fit_set_image(struct efi_firmware_management_protocol *this, u8 image_index, const void *image, efi_uintn_t image_size, const void *vendor_code, efi_status_t (*progress)(efi_uintn_t completion), u16 **abort_reason, )¶: update the firmware image

Parameters

struct efi_firmware_management_protocol *this: Protocol instance
u8 image_index: Image index number
const void *image: New image
efi_uintn_t image_size: Size of new image
const void *vendor_code: Vendor-specific update policy
efi_status_t (*progress)(efi_uintn_t completion): Function to report the progress of update
u16 **abort_reason: Pointer to string of abort reason

Description

Update the firmware to new image, using dfu. The new image should have FIT image format commonly used in U-Boot. vendor_code, progress and abort_reason are not supported.

Return

status code

efi_status_t EFIAPI efi_firmware_raw_set_image(struct efi_firmware_management_protocol *this, u8 image_index, const void *image, efi_uintn_t image_size, const void *vendor_code, efi_status_t (*progress)(efi_uintn_t completion), u16 **abort_reason, )¶: update the firmware image

Parameters

struct efi_firmware_management_protocol *this: Protocol instance
u8 image_index: Image index number
const void *image: New image
efi_uintn_t image_size: Size of new image
const void *vendor_code: Vendor-specific update policy
efi_status_t (*progress)(efi_uintn_t completion): Function to report the progress of update
u16 **abort_reason: Pointer to string of abort reason

Description

Update the firmware to new image, using dfu. The new image should be a single raw image. vendor_code, progress and abort_reason are not supported.

Return

status code

Driver binding protocol¶

struct efi_driver_binding_extended_protocol¶: extended driver binding protocol

Definition

struct efi_driver_binding_extended_protocol {
  struct efi_driver_binding_protocol bp;
  const struct efi_driver_ops *ops;
};

Members

bp: driver binding protocol
ops: operations supported by the driver

Description

This structure adds internal fields to the driver binding protocol.

struct efi_driver_ops¶: operations support by an EFI driver

Definition

struct efi_driver_ops {
  const efi_guid_t *protocol;
  const efi_guid_t *child_protocol;
  efi_status_t (*init)(struct efi_driver_binding_extended_protocol *this);
  efi_status_t (*bind)(struct efi_driver_binding_extended_protocol *this, efi_handle_t handle, void *interface);
};

Members

protocol: The GUID of the protocol which is consumed by the driver. This GUID is used by the EFI uclass in the supports() and start() methods of the EFI_DRIVER_BINDING_PROTOCOL.
child_protocol: Protocol supported by the child handles generated by the EFI driver.
init: Function called by the EFI uclass after installing the driver binding protocol.
bind: Function called by the EFI uclass to attach the driver to EFI driver to a handle.

Unit testing¶

The following library functions are provided to support writing UEFI unit tests. The should not be used elsewhere.

efi_st_printf¶

efi_st_printf (...)

print a message

Parameters

...: format string followed by fields to print

efi_st_error¶

efi_st_error (...)

prints an error message

Parameters

...: format string followed by fields to print

efi_st_todo¶

efi_st_todo (...)

prints a TODO message

Parameters

...: format string followed by fields to print

enum efi_test_phase¶: phase when test will be executed

Constants

EFI_EXECUTE_BEFORE_BOOTTIME_EXIT: Setup, execute, and teardown are executed before ExitBootServices().
EFI_SETUP_BEFORE_BOOTTIME_EXIT: Setup is executed before ExitBootServices() while execute, and teardown are executed after ExitBootServices().
EFI_SETTING_VIRTUAL_ADDRESS_MAP: Execute calls SetVirtualAddressMap(). Setup is executed before ExitBootServices() while execute is executed after ExitBootServices(), and after the execute of tests marked as EFI_SETUP_BEFORE_BOOTTIME_EXIT. Teardown is executed thereafter.

Description

A test may be setup and executed at boottime, it may be setup at boottime and executed at runtime, or it may be setup and executed at runtime.

void efi_st_exit_boot_services(void)¶: exit the boot services

Parameters

void: no arguments

Description

The size of the memory map is determined.
Pool memory is allocated to copy the memory map.
The memory map is copied and the map key is obtained.
The map key is used to exit the boot services.

void efi_st_printc(int color, const char *fmt, ...)¶: print a colored message

Parameters

int color: color, see constants in efi_api.h, use -1 for no color
const char *fmt: printf style format string
...: arguments to be printed

u16 *efi_st_translate_char(u16 code)¶: translate a Unicode character to a string

Parameters

u16 code: Unicode character

Return

string

u16 *efi_st_translate_code(u16 code)¶: translate a scan code to a human readable string

Parameters

u16 code: scan code

Description

This function translates the scan code returned by the simple text input protocol to a human readable string, e.g. 0x04 is translated to u”Left”.

Return

Unicode string

int efi_st_strcmp_16_8(const u16 *buf1, const unsigned char *buf2)¶: compare an u16 string to a char string

Parameters

const u16 *buf1: u16 string
const unsigned char *buf2: char string

Description

This function compares each u16 value to the char value at the same position. This function is only useful for ANSI strings.

Return

0 if both buffers contain equivalent strings

void *efi_st_get_config_table(const efi_guid_t *guid)¶: get configuration table

Parameters

const efi_guid_t *guid: GUID of the configuration table

Return

pointer to configuration table or NULL

u16 efi_st_get_key(void)¶: reads an Unicode character from the input device

Parameters

void: no arguments

Return

Unicode character

struct efi_unit_test¶: EFI unit test

Definition

struct efi_unit_test {
  const char *name;
  const enum efi_test_phase phase;
  int (*setup)(const efi_handle_t handle, const struct efi_system_table *systable);
  int (*execute)(void);
  int (*teardown)(void);
  bool on_request;
};

Members

name: name of the unit test used in the user interface
phase: specifies when setup and execute are executed
setup: set up function of the unit test
execute: execute function of the unit test
teardown: tear down function of the unit test
on_request: flag indicating that the test shall only be executed on request

Description

The struct efi_unit_test structure provides a interface to an EFI unit test.

EFI_UNIT_TEST¶

EFI_UNIT_TEST (__name)

macro to declare a new EFI unit test

Parameters

__name: string identifying the unit test in the linker generated list

Description

The macro EFI_UNIT_TEST() declares an EFI unit test using the struct efi_unit_test structure. The test is added to a linker generated list which is evaluated by the ‘bootefi selftest’ command.