API Reference

group llext_apis

Since

3.5

Version

0.1.0

Defines

LLEXT_LOAD_PARAM_DEFAULT

Default initializer for llext_load_param.

Enums

enum llext_mem

List of memory regions stored or referenced in the LLEXT subsystem.

This enum lists the different types of memory regions that are used by the LLEXT subsystem. The names match common ELF file section names; but note that at load time multiple ELF sections with similar flags may be merged together into a single memory region.

Values:

enumerator LLEXT_MEM_TEXT

Executable code.

enumerator LLEXT_MEM_DATA

Initialized data.

enumerator LLEXT_MEM_RODATA

Read-only data.

enumerator LLEXT_MEM_BSS

Uninitialized data.

enumerator LLEXT_MEM_EXPORT

Exported symbol table.

enumerator LLEXT_MEM_SYMTAB

Symbol table.

enumerator LLEXT_MEM_STRTAB

Symbol name strings.

enumerator LLEXT_MEM_SHSTRTAB

Section name strings.

enumerator LLEXT_MEM_COUNT

Number of regions managed by LLEXT.

Functions

struct llext *llext_by_name(const char *name)

Find an llext by name.

Parameters:

• name – [in] String name of the llext

Returns:

a pointer to the llext, or NULL if not found

int llext_iterate(int (*fn)(struct llext *ext, void *arg), void *arg)

Iterate over all loaded extensions.

Calls a provided callback function for each registered extension or until the callback function returns a non-0 value.

Parameters:

• fn – [in] callback function

• arg – [in] a private argument to be provided to the callback function

Return values:

0 – if no extensions are registered

Returns:

the value returned by the last callback invocation

int llext_load(struct llext_loader *loader, const char *name, struct llext **ext, struct llext_load_param *ldr_parm)

Load and link an extension.

Loads relevant ELF data into memory and provides a structure to work with it.

Parameters:

• loader – [in] An extension loader that provides input data and context

• name – [in] A string identifier for the extension

• ext – [out] Pointer to the newly allocated llext structure

• ldr_parm – [in] Optional advanced load parameters (may be NULL)

Return values:

• -ENOMEM – Not enough memory

• -ENOEXEC – Invalid ELF stream

• -ENOTSUP – Unsupported ELF features

Returns:

the previous extension use count on success, or a negative error code.

int llext_unload(struct llext **ext)

Unload an extension.

Parameters:

• ext – [in] Extension to unload

const void *llext_find_sym(const struct llext_symtable *sym_table, const char *sym_name)

Find the address for an arbitrary symbol.

Searches for a symbol address, either in the list of symbols exported by the main Zephyr binary or in an extension’s symbol table.

Parameters:

• sym_table – [in] Symbol table to lookup symbol in, or NULL to search in the main Zephyr symbol table

• sym_name – [in] Symbol name to find

Returns:

the address of symbol in memory, or NULL if not found

int llext_call_fn(struct llext *ext, const char *sym_name)

Call a function by name.

Expects a symbol representing a void fn(void) style function exists and may be called.

Parameters:

• ext – [in] Extension to call function in

• sym_name – [in] Function name (exported symbol) in the extension

Return values:

• 0 – Success

• -ENOENT – Symbol name not found

int llext_add_domain(struct llext *ext, struct k_mem_domain *domain)

Add an extension to a memory domain.

Allows an extension to be executed in user mode threads when memory protection hardware is enabled by adding memory partitions covering the extension’s memory regions to a memory domain.

Parameters:

• ext – [in] Extension to add to a domain

• domain – [in] Memory domain to add partitions to

Return values:

-ENOSYS – CONFIG_USERSPACE is not enabled or supported

Returns:

0 on success, or a negative error code.

int arch_elf_relocate(elf_rela_t *rel, uintptr_t loc, uintptr_t sym_base_addr, const char *sym_name, uintptr_t load_bias)

Architecture specific opcode update function.

ELF files include sections describing a series of relocations, which are instructions on how to rewrite opcodes given the actual placement of some symbolic data such as a section, function, or object. These relocations are architecture specific and each architecture supporting LLEXT must implement this.

Parameters:

• rel – [in] Relocation data provided by ELF

• loc – [in] Address of opcode to rewrite

• sym_base_addr – [in] Address of symbol referenced by relocation

• sym_name – [in] Name of symbol referenced by relocation

• load_bias – [in] .text load address

Return values:

• 0 – Success

• -ENOTSUP – Unsupported relocation

• -ENOEXEC – Invalid relocation

ssize_t llext_find_section(struct llext_loader *loader, const char *search_name)

Locates an ELF section in the file.

Searches for a section by name in the ELF file and returns its offset.

Parameters:

• loader – Extension loader data and context

• search_name – Section name to search for

Returns:

the section offset or a negative error code

void arch_elf_relocate_local(struct llext_loader *loader, struct llext *ext, const elf_rela_t *rel, const elf_sym_t *sym, size_t got_offset)

Architecture specific function for updating addresses via relocation table.

Parameters:

• loader – [in] Extension loader data and context

• ext – [in] Extension to call function in

• rel – [in] Relocation data provided by elf

• sym – [in] Corresponding symbol table entry

• got_offset – [in] Offset within a relocation table

struct llext

#include <llext.h>

Structure describing a linkable loadable extension.

This structure holds the data for a loaded extension. It is created by the llext_load function and destroyed by the llext_unload function.

Public Members

char name[16]

Name of the llext.

void *mem[LLEXT_MEM_COUNT]

Lookup table of memory regions.

bool mem_on_heap[LLEXT_MEM_COUNT]

Is the memory for this region allocated on heap?

size_t mem_size[LLEXT_MEM_COUNT]

Size of each stored region.

size_t alloc_size

Total llext allocation size.

struct llext_symtable sym_tab

Table of all global symbols in the extension; used internally as part of the linking process.

E.g. if the extension is built out of several files, if any symbols are referenced between files, this table will be used to link them.

struct llext_symtable exp_tab

Table of symbols exported by the llext via LL_EXTENSION_SYMBOL.

This can be used in the main Zephyr binary to find symbols in the extension.

unsigned int use_count

Extension use counter, prevents unloading while in use.

struct llext_load_param

#include <llext.h>

Advanced llext_load parameters.

This structure contains advanced parameters for llext_load.

Public Members

bool relocate_local

Perform local relocation.

bool pre_located

Use the virtual symbol addresses from the ELF, not addresses within the memory buffer, when calculating relocation targets.

group llext_symbols

Defines

EXPORT_SYMBOL(x)

Export a constant symbol to extensions.

Takes a symbol (function or object) by symbolic name and adds the name and address of the symbol to a table of symbols that may be referenced by extensions.

Parameters:

• x – Symbol to export to extensions

LL_EXTENSION_SYMBOL(x)

Exports a symbol from an extension to the base image.

This macro can be used in extensions to add a symbol (function or object) to the extension’s exported symbol table, so that it may be referenced by the base image.

Parameters:

• x – Extension symbol to export to the base image

struct llext_const_symbol

#include <symbol.h>

Constant symbols are unchangeable named memory addresses.

Symbols may be named function or global objects that have been exported for linking. These constant symbols are useful in the base image as they may be placed in ROM.

Note

When updating this structure, make sure to also update the ‘scripts/build/llext_prepare_exptab.py’ build script.

Public Members

const char *const name

Name of symbol.

const uintptr_t slid

Symbol Link Identifier.

union llext_const_symbol

At build time, we always write to ‘name’.

At runtime, which field is used depends on CONFIG_LLEXT_EXPORT_BUILTINS_BY_SLID.

const void *const addr

Address of symbol.

struct llext_symbol

#include <symbol.h>

Symbols are named memory addresses.

Symbols may be named function or global objects that have been exported for linking. These are mutable and should come from extensions where the location may need updating depending on where memory is placed.

Public Members

const char *name

Name of symbol.

void *addr

Address of symbol.

struct llext_symtable

#include <symbol.h>

A symbol table.

An array of symbols

Public Members

size_t sym_cnt

Number of symbols in the table.

struct llext_symbol *syms

Array of symbols.

group llext_loader_apis

Defines

LLEXT_BUF_LOADER(_buf, _buf_len)

Initializer for an llext_buf_loader structure.

Parameters:

• _buf – Buffer containing the ELF binary

• _buf_len – Buffer length in bytes

struct llext_buf_loader

#include <buf_loader.h>

Implementation of llext_loader that reads from a memory buffer.

Public Members

struct llext_loader loader

Extension loader.

struct llext_loader

#include <loader.h>

Linkable loadable extension loader context.

This object is used to access the ELF file data and cache its contents while an extension is being loaded by the LLEXT subsystem. Once the extension is loaded, this object is no longer needed.

Public Members

int (*read)(struct llext_loader *ldr, void *out, size_t len)

Function to read (copy) from the loader.

Copies len bytes into buf from the current position of the loader.

Param ldr:

[in] Loader

Param out:

[in] Output location

Param len:

[in] Length to copy into the output location

Return:

0 on success, or a negative error code.

int (*seek)(struct llext_loader *ldr, size_t pos)

Function to seek to a new absolute location in the stream.

Changes the location of the loader position to a new absolute given position.

Param ldr:

[in] Loader

Param pos:

[in] Position in stream to move loader

Return:

0 on success, or a negative error code.

void *(*peek)(struct llext_loader *ldr, size_t pos)

Optional function to peek at an absolute location in the ELF.

Return a pointer to the buffer at specified offset.

Param ldr:

[in] Loader

Param pos:

[in] Position to obtain a pointer to

Return:

a pointer into the buffer or NULL if not supported