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.
-
efi_status_t
set_load_options
(efi_handle_t handle, const char * env_var, u16 ** load_options)¶
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
efi_carve_out_dt_rsv
(void * fdt)¶ Carve out DT reserved memory ranges
Parameters
void * fdt
- Pointer to device tree
Description
The mem_rsv entries of the FDT are added to the memory map. Any failures are ignored because this is not critical and we would rather continue to try to boot.
-
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)¶ execute EFI binary
Parameters
efi_handle_t handle
- handle of loaded image
Return
status code
Load the EFI binary into a newly assigned memory unwinding the relocation information, install the loaded image protocol, and call the binary.
-
int
do_efibootmgr
(void)¶ execute EFI boot manager
Parameters
void
- no arguments
Return
status code
-
int
do_bootefi_image
(const char * image_opt)¶ execute EFI binary
Parameters
const char * image_opt
- string of image start address
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
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ execute bootefi command
Parameters
cmd_tbl_t * 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
-
void
efi_set_bootdev
(const char * dev, const char * devnr, const char * path)¶ 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
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.
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
-
void
efi_deserialize_load_option
(struct efi_load_option * lo, u8 * data)¶ parse serialized data
Parameters
struct efi_load_option * lo
- pointer to target
u8 * data
- serialized data
Description
Parse serialized data describing a load option and transform it to the efi_load_option structure.
-
unsigned long
efi_serialize_load_option
(struct efi_load_option * lo, u8 ** data)¶ serialize load option
Parameters
struct efi_load_option * lo
- load option
u8 ** data
- buffer for serialized data
Description
Serialize efi_load_option structure into byte stream for BootXXXX.
Return
size of allocated buffer
-
void *
get_var
(u16 * name, const efi_guid_t * vendor, efi_uintn_t * size)¶ get UEFI variable
Parameters
u16 * name
- name of variable
const efi_guid_t * vendor
- vendor GUID of variable
efi_uintn_t * size
- size of allocated buffer
Description
It is the caller’s duty to free the returned buffer.
Return
buffer with variable data or NULL
-
efi_status_t
try_load_entry
(u16 n, efi_handle_t * handle)¶ 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
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)¶ try to load from BootNext or BootOrder
Parameters
efi_handle_t * handle
- on return handle for the newly installed image
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
efi_get_device_handle_info
(efi_handle_t handle, u16 ** dev_path_text)¶ get information of UEFI device
Parameters
efi_handle_t handle
- Handle of UEFI device
u16 ** dev_path_text
- Pointer to text of device path
Return
0 on success, -1 on failure
Currently return a formatted text of device path.
-
int
do_efi_show_devices
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ show UEFI devices
Parameters
cmd_tbl_t * 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
Implement efidebug “devices” sub-command. Show all UEFI devices and their information.
-
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
Currently return no useful information as all UEFI drivers are built-in..
-
int
do_efi_show_drivers
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ show UEFI drivers
Parameters
cmd_tbl_t * 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
Implement efidebug “drivers” sub-command. Show all UEFI drivers and their information.
-
const char *
get_guid_text
(const void * guid)¶ get string of GUID
Parameters
const void * guid
- GUID
Description
Return description of GUID.
Return
description of GUID or NULL
-
int
do_efi_show_handles
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ show UEFI handles
Parameters
cmd_tbl_t * 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
Implement efidebug “dh” sub-command. Show all UEFI handles and their information, currently all protocols added to handle.
-
int
do_efi_show_images
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ show UEFI images
Parameters
cmd_tbl_t * 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
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
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ show UEFI memory map
Parameters
cmd_tbl_t * 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
Implement efidebug “memmap” sub-command. Show UEFI memory map.
-
int
do_efi_show_tables
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ show UEFI configuration tables
Parameters
cmd_tbl_t * 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
Implement efidebug “tables” sub-command. Show UEFI configuration tables.
-
int
do_efi_boot_add
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ set UEFI load option
Parameters
cmd_tbl_t * 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
Implement efidebug “boot add” sub-command. Create or change UEFI load option.
efidebug boot add <id> <label> <interface> <devnum>[:<part>] <file> <options>
-
int
do_efi_boot_rm
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ delete UEFI load options
Parameters
cmd_tbl_t * 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
Implement efidebug “boot rm” sub-command. Delete UEFI load options.
efidebug boot rm <id> …
-
void
show_efi_boot_opt_data
(int id, void * data, size_t size)¶ dump UEFI load option
Parameters
int id
- load option number
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
(int id)¶ dump UEFI load option
Parameters
int id
- Load option number
Description
Dump information defined by UEFI load option.
-
int
do_efi_boot_dump
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ dump all UEFI load options
Parameters
cmd_tbl_t * 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
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
Show order of UEFI load options defined by BootOrder variable.
-
int
do_efi_boot_next
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ manage UEFI BootNext variable
Parameters
cmd_tbl_t * 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
Implement efidebug “boot next” sub-command. Set BootNext variable.
efidebug boot next <id>
-
int
do_efi_boot_order
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ manage UEFI BootOrder variable
Parameters
cmd_tbl_t * 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
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
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ manage UEFI load options
Parameters
cmd_tbl_t * 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
Implement efidebug “boot” sub-command.
-
int
do_efidebug
(cmd_tbl_t * cmdtp, int flag, int argc, char *const argv)¶ display and configure UEFI environment
Parameters
cmd_tbl_t * 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
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_obj_list
(void)¶ Initialize and populate EFI object list
Parameters
void
- no arguments
Return
status code
Boot services¶
-
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 (EFIAPI *notify_function) ( struct efi_event *event, void *context) notify_function, 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 (EFIAPI *notify_function) ( struct efi_event *event, void *context) notify_function
- 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 (EFIAPI *notify_function) ( struct efi_event *event, void *context) notify_function, 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 (EFIAPI *notify_function) ( struct efi_event *event, void *context) notify_function
- 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
(efi_guid_t * guid, void * table)¶ Adds, updates, or removes a configuration table.
Parameters
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
efi_load_image_from_path
(struct efi_device_path * file_path, void ** buffer, efi_uintn_t * size)¶ load an image using a file path
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 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 EFIAPI
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 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_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 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 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
(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_load_pe
(struct efi_loaded_image_obj * handle, void * efi, 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
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
-
efi_status_t
efi_add_memory_map
(uint64_t start, uint64_t pages, int memory_type, bool overlap_only_ram)¶ add memory area to the memory map
Parameters
uint64_t start
- start address, must be a multiple of EFI_PAGE_SIZE
uint64_t pages
- number of pages to add
int memory_type
- type of memory added
bool overlap_only_ram
- the memory area must overlap existing
Return
status code
-
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
-
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
-
efi_status_t
efi_allocate_pool
(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
Return
status code
-
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_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
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_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. It only executes an endless loop.
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
-
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
-
efi_status_t __efi_runtime EFIAPI
efi_update_capsule
(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 arry 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
(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
Variable services¶
-
efi_status_t
efi_to_native
(char ** native, const u16 * variable_name, const efi_guid_t * vendor)¶ convert the UEFI variable name and vendor GUID to U-Boot variable name
Parameters
char ** native
- pointer to pointer to U-Boot variable name
const u16 * variable_name
- UEFI variable name
const efi_guid_t * vendor
- vendor GUID
Description
The U-Boot variable name is a concatenation of prefix ‘efi’, the hexstring encoded vendor GUID, and the UTF-8 encoded UEFI variable name separated by underscores, e.g. ‘efi_8be4df61-93ca-11d2-aa0d-00e098032b8c_BootOrder’.
Return
status code
-
const char *
prefix
(const char * str, const char * prefix)¶ skip over prefix
Parameters
const char * str
- string with prefix
const char * prefix
- prefix string
Description
Skip over a prefix string.
Return
string without prefix, or NULL if prefix not found
-
const char *
parse_attr
(const char * str, u32 * attrp)¶ decode attributes part of variable value
Parameters
const char * str
- value of U-Boot variable
u32 * attrp
- pointer to UEFI attributes
Description
Convert the string encoded attributes of a UEFI variable to a bit mask. TODO: Several attributes are not supported.
Return
pointer to remainder of U-Boot variable value
-
efi_status_t EFIAPI
efi_get_variable
(u16 * variable_name, const efi_guid_t * vendor, u32 * attributes, efi_uintn_t * data_size, void * data)¶ retrieve value of a UEFI variable
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 to which the variable value is copied
void * data
- buffer to which the variable value is copied
Description
This function implements the GetVariable runtime service.
See the Unified Extensible Firmware Interface (UEFI) specification for details.
Return
status code
-
efi_status_t
parse_uboot_variable
(char * variable, efi_uintn_t * variable_name_size, u16 * variable_name, const efi_guid_t * vendor, u32 * attributes)¶ parse a u-boot variable and get uefi-related information
Parameters
char * variable
- whole data of u-boot variable (ie. name=value)
efi_uintn_t * variable_name_size
- size of variable_name buffer in byte
u16 * variable_name
- name of uefi variable in u16, null-terminated
const efi_guid_t * vendor
- vendor’s guid
u32 * attributes
- attributes
Description
A uefi variable is encoded into a u-boot variable as described above. This function parses such a u-boot variable and retrieve uefi-related information into respective parameters. In return, variable_name_size is the size of variable name including NULL.
Return
- EFI_SUCCESS if parsing is OK, EFI_NOT_FOUND when
- the entire variable list has been returned, otherwise non-zero status code
-
efi_status_t EFIAPI
efi_get_next_variable_name
(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
This function implements the GetNextVariableName service.
See the Unified Extensible Firmware Interface (UEFI) specification for details.
Return
status code
-
efi_status_t EFIAPI
efi_set_variable
(u16 * variable_name, const efi_guid_t * vendor, u32 attributes, efi_uintn_t data_size, const void * data)¶ set value of a UEFI variable
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
Description
This function implements the SetVariable runtime service.
See the Unified Extensible Firmware Interface (UEFI) specification for details.
Return
status code
-
efi_status_t __efi_runtime EFIAPI
efi_query_variable_info
(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
-
efi_status_t __efi_runtime EFIAPI
efi_get_variable_runtime
(u16 * variable_name, const efi_guid_t * vendor, 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 * 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
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 * vendor)¶ 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 * vendor
- vendor’s guid
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¶
-
ulong
efi_bl_read
(struct udevice * dev, lbaint_t blknr, lbaint_t blkcnt, void * buffer)¶
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)¶
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
-
int
efi_bl_bind_partitions
(efi_handle_t handle, struct udevice * dev)¶
Parameters
efi_handle_t handle
- EFI handle of the block device
struct udevice * dev
- udevice of the block device
Return
number of partitions created
-
int
efi_bl_bind
(efi_handle_t handle, void * interface)¶
Parameters
efi_handle_t handle
- handle
void * interface
- block io protocol
Return
0 = success
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;
const char *ifname;
int dev_index;
struct efi_block_io_media media;
struct efi_device_path *dp;
unsigned int part;
struct efi_simple_file_system_protocol *volume;
lbaint_t offset;
struct blk_desc *desc;
};
Members
header
- EFI object header
ops
- EFI disk I/O protocol interface
ifname
- interface name for block device
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
offset
- offset into disk for simple partition
desc
- internal block device descriptor
-
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
-
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
-
int
efi_disk_create_partitions
(efi_handle_t parent, struct blk_desc * desc, const char * if_typename, int diskid, const char * pdevname)¶ create handles and protocols for partitions
Parameters
efi_handle_t parent
- handle of the parent disk
struct blk_desc * desc
- undescribed
const char * if_typename
- interface type
int diskid
- device number
const char * pdevname
- device name
Description
Create handles and protocols for the partitions of a block device.
Return
number of partitions created
-
efi_status_t
efi_disk_register
(void)¶ register block devices
Parameters
void
- no arguments
Description
U-Boot doesn’t have a list of all online disk devices. So when running our EFI payload, we scan through all of the potentially available ones and store them in our object pool.
This function is called in efi_init_obj_list()
.
TODO(sjg**chromium.org**): Actually with CONFIG_BLK, U-Boot does have this. Consider converting the code to look up devices as needed. The EFI device could be a child of the UCLASS_BLK block device, perhaps.
Return
status code
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
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 EFIAPI
efi_file_write
(struct efi_file_handle * file, efi_uintn_t * buffer_size, void * buffer)¶ write to file
Parameters
struct efi_file_handle * file
- file handle
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_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
-
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
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.
-
loff_t
get_file_size
(const char * dev, const char * part, const char * file, efi_status_t * status)¶ retrieve the size of initramfs, set efi status on error
Parameters
const char * dev
- device to read from. i.e “mmc”
const char * part
- device partition. i.e “0:1”
const char * file
- name fo file
efi_status_t * status
- EFI exit code in case of failure
Return
size of file
-
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)¶ get information about random number generation
Parameters
struct efi_load_file_protocol * this
- loadfile2 protocol instance
struct efi_device_path * file_path
- relative path of the file. “” in this case
bool boot_policy
- must be false for Loadfile2
efi_uintn_t * buffer_size
- size of allocated buffer
void * buffer
- buffer to load the file
Description
This function implement the LoadFile2()
service in order to load an initram
disk requested by the Linux kernel stub.
See the UEFI spec for details.
Return
status code
-
efi_status_t
efi_initrd_register
(void)¶ Register a handle and loadfile2 protocol
Parameters
void
- no arguments
Description
This function creates a new handle and installs a linux specific GUID to handle initram disk loading during boot. See the UEFI spec for details.
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
Text IO protocols¶
-
int
query_console_serial
(int * rows, int * cols)¶ query console size
Parameters
int * rows
- pointer to return number of rows
int * cols
- pointer to return number of columns
Return
0 on success
-
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 EFI_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
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
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 (EFIAPI *key_notify_function)( struct efi_key_data *key_data) key_notify_function, 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 (EFIAPI *key_notify_function)( struct efi_key_data *key_data) key_notify_function
- function to be called if the key is pressed
void ** notify_handle
- handle for unregistering the notification
Return
status code
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
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
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
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