Topics
	ELF constants and data types


	ELF loader context


	Exported symbol definitions

Data Structures
struct	llext
	Structure describing a linkable loadable extension. More...

struct	llext_load_param
	Advanced llext_load parameters. More...

Macros
#define	LLEXT_MAX_DEPENDENCIES 8

#define	LLEXT_LOAD_PARAM_DEFAULT { .relocate_local = true, }
	Default initializer for llext_load_param.

Typedefs
typedef void(*	llext_entry_fn_t) (void *user_data)
	Entry point function signature for an extension.

Enumerations
enum	llext_mem { LLEXT_MEM_TEXT , LLEXT_MEM_DATA , LLEXT_MEM_RODATA , LLEXT_MEM_BSS , LLEXT_MEM_EXPORT , LLEXT_MEM_SYMTAB , LLEXT_MEM_STRTAB , LLEXT_MEM_SHSTRTAB , LLEXT_MEM_PREINIT , LLEXT_MEM_INIT , LLEXT_MEM_FINI , LLEXT_MEM_COUNT }
	List of memory regions stored or referenced in the LLEXT subsystem. More...

Functions
static const elf_shdr_t *	llext_section_headers (const struct llext *ext)

static unsigned int	llext_section_count (const struct llext *ext)

struct llext *	llext_by_name (const char *name)
	Find an llext by name.

int	llext_iterate (int(fn)(struct llext ext, void arg), void arg)
	Iterate over all loaded extensions.

int	llext_load (struct llext_loader loader, const char name, struct llext *ext, const struct llext_load_param ldr_parm)
	Load and link an extension.

int	llext_unload (struct llext **ext)
	Unload an extension.

int	llext_bringup (struct llext *ext)
	Calls bringup functions for an extension.

int	llext_teardown (struct llext *ext)
	Calls teardown functions for an extension.

void	llext_bootstrap (struct llext ext, llext_entry_fn_t entry_fn, void user_data)
	Bring up, execute, and teardown an extension.

ssize_t	llext_get_fn_table (struct llext ext, bool is_init, void buf, size_t size)
	Get pointers to setup or cleanup functions for an extension.

const void *	llext_find_sym (const struct llext_symtable sym_table, const char sym_name)
	Find the address for an arbitrary symbol.

int	llext_call_fn (struct llext ext, const char sym_name)
	Call a function by name.

int	llext_add_domain (struct llext ext, struct k_mem_domain domain)
	Add an extension to a memory domain.

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.

ssize_t	llext_find_section (struct llext_loader loader, const char search_name)
	Locates an ELF section in the file.

int	llext_get_section_header (struct llext_loader loader, struct llext ext, const char search_name, elf_shdr_t shdr)
	Extract ELF section header by name.

void	arch_elf_relocate_local (struct llext_loader loader, struct llext ext, const elf_rela_t rel, const elf_sym_t sym, uint8_t rel_addr, const struct llext_load_param ldr_parm)
	Architecture specific function for local binding relocations.

void	arch_elf_relocate_global (struct llext_loader loader, struct llext ext, const elf_rela_t rel, const elf_sym_t sym, uint8_t rel_addr, const void link_addr)
	Architecture specific function for global binding relocations.

Detailed Description

Since: 3.5

Version: 0.1.0

Macro Definition Documentation

◆ LLEXT_LOAD_PARAM_DEFAULT

#define LLEXT_LOAD_PARAM_DEFAULT { .relocate_local = true, }

#include <zephyr/llext/llext.h>

Default initializer for llext_load_param.

◆ LLEXT_MAX_DEPENDENCIES

#define LLEXT_MAX_DEPENDENCIES 8

#include <zephyr/llext/llext.h>

Typedef Documentation

◆ llext_entry_fn_t

typedef void(* llext_entry_fn_t) (void *user_data)

#include <zephyr/llext/llext.h>

Entry point function signature for an extension.

Enumeration Type Documentation

◆ llext_mem

enum llext_mem

#include <zephyr/llext/llext.h>

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.

Enumerator
LLEXT_MEM_TEXT	Executable code.
LLEXT_MEM_DATA	Initialized data.
LLEXT_MEM_RODATA	Read-only data.
LLEXT_MEM_BSS	Uninitialized data.
LLEXT_MEM_EXPORT	Exported symbol table.
LLEXT_MEM_SYMTAB	Symbol table.
LLEXT_MEM_STRTAB	Symbol name strings.
LLEXT_MEM_SHSTRTAB	Section name strings.
LLEXT_MEM_PREINIT	Array of early setup functions.
LLEXT_MEM_INIT	Array of setup functions.
LLEXT_MEM_FINI	Array of cleanup functions.
LLEXT_MEM_COUNT	Number of regions managed by LLEXT.

Function Documentation

◆ arch_elf_relocate()

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

#include <zephyr/llext/llext.h>

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

[in]	rel	Relocation data provided by ELF
[in]	loc	Address of opcode to rewrite
[in]	sym_base_addr	Address of symbol referenced by relocation
[in]	sym_name	Name of symbol referenced by relocation
[in]	load_bias	`.text` load address

Return values

0	Success
-ENOTSUP	Unsupported relocation
-ENOEXEC	Invalid relocation

◆ arch_elf_relocate_global()

void arch_elf_relocate_global	(	struct llext_loader *	loader,
		struct llext *	ext,
		const elf_rela_t *	rel,
		const elf_sym_t *	sym,
		uint8_t *	rel_addr,
		const void *	link_addr )

#include <zephyr/llext/llext.h>

Architecture specific function for global binding relocations.

Parameters

[in]	loader	Extension loader data and context
[in]	ext	Extension to call function in
[in]	rel	Relocation data provided by elf
[in]	sym	Corresponding symbol table entry
[in]	rel_addr	Address where relocation should be performed
[in]	link_addr	target address for table-based relocations

◆ arch_elf_relocate_local()

void arch_elf_relocate_local	(	struct llext_loader *	loader,
		struct llext *	ext,
		const elf_rela_t *	rel,
		const elf_sym_t *	sym,
		uint8_t *	rel_addr,
		const struct llext_load_param *	ldr_parm )

#include <zephyr/llext/llext.h>

Architecture specific function for local binding relocations.

Parameters

[in]	loader	Extension loader data and context
[in]	ext	Extension to call function in
[in]	rel	Relocation data provided by elf
[in]	sym	Corresponding symbol table entry
[in]	rel_addr	Address where relocation should be performed
[in]	ldr_parm	Loader parameters

◆ llext_add_domain()

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

#include <zephyr/llext/llext.h>

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

[in]	ext	Extension to add to a domain
[in]	domain	Memory domain to add partitions to

Returns: 0 on success, or a negative error code.

Return values

-ENOSYS Option CONFIG_USERSPACE is not enabled or supported

◆ llext_bootstrap()

void llext_bootstrap	(	struct llext *	ext,
		llext_entry_fn_t	entry_fn,
		void *	user_data )

#include <zephyr/llext/llext.h>

Bring up, execute, and teardown an extension.

Calls the extension's own setup functions, an additional entry point and the extension's cleanup functions in the current thread context.

This is a convenient wrapper around llext_bringup and llext_teardown that matches the k_thread_entry_t signature, so it can be directly started as a new user or kernel thread via k_thread_create.

Parameters

[in]	ext	Extension to execute. Passed as `p1` in k_thread_create.
[in]	entry_fn	Main entry point of the thread after performing extension setup. Passed as `p2` in k_thread_create.
[in]	user_data	Argument passed to entry_fn. Passed as `p3` in k_thread_create.

◆ llext_bringup()

int llext_bringup ( struct llext * ext )

#include <zephyr/llext/llext.h>

Calls bringup functions for an extension.

Must be called before accessing any symbol in the extension. Will execute the extension's own setup functions in the caller context.

See also: llext_bootstrap

Parameters

[in] ext Extension to initialize.

Returns: 0 on success, or a negative error code.

Return values

-EFAULT A relocation issue was detected

◆ llext_by_name()

struct llext * llext_by_name ( const char * name )

#include <zephyr/llext/llext.h>

Find an llext by name.

Parameters

[in] name String name of the llext

Returns: a pointer to the llext, or NULL if not found

◆ llext_call_fn()

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

#include <zephyr/llext/llext.h>

Call a function by name.

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

Parameters

[in]	ext	Extension to call function in
[in]	sym_name	Function name (exported symbol) in the extension

Return values

0	Success
-ENOENT	Symbol name not found

◆ llext_find_section()

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

#include <zephyr/llext/llext.h>

Locates an ELF section in the file.

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

Parameters

[in]	loader	Extension loader data and context
[in]	search_name	Section name to search for

Returns: the section offset or a negative error code

◆ llext_find_sym()

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

#include <zephyr/llext/llext.h>

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

[in]	sym_table	Symbol table to lookup symbol in, or `NULL` to search in the main Zephyr symbol table
[in]	sym_name	Symbol name to find

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

◆ llext_get_fn_table()

ssize_t llext_get_fn_table	(	struct llext *	ext,
		bool	is_init,
		void *	buf,
		size_t	size )

#include <zephyr/llext/llext.h>

Get pointers to setup or cleanup functions for an extension.

This syscall can be used to get the addresses of all the functions that have to be called for full extension setup or cleanup.

See also: llext_bootstrap

Parameters

[in]	ext	Extension to initialize.
[in]	is_init	`true` to get functions to be called at setup time, `false` to get the cleanup ones.
[in,out]	buf	Buffer to store the function pointers in. Can be `NULL` to only get the minimum required size.
[in]	size	Allocated size of the buffer in bytes.

Returns: the size used by the array in bytes, or a negative error code.

Return values

-EFAULT	A relocation issue was detected
-ENOMEM	Array does not fit in the allocated buffer

◆ llext_get_section_header()

int llext_get_section_header	(	struct llext_loader *	loader,
		struct llext *	ext,
		const char *	search_name,
		elf_shdr_t *	shdr )

#include <zephyr/llext/llext.h>

Extract ELF section header by name.

Searches for a section by name in the ELF file and retrieves its full header.

Parameters

[in]	loader	Extension loader data and context
[in]	ext	Extension to be searched
[in]	search_name	Section name to search for
[out]	shdr	Buffer for the section header

Return values

0	Success
-ENOTSUP	"peek" method not supported
-ENOENT	section not found

◆ llext_iterate()

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

#include <zephyr/llext/llext.h>

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

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

Returns: the value returned by the last callback invocation

Return values

0	if no extensions are registered

◆ llext_load()

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

#include <zephyr/llext/llext.h>

Load and link an extension.

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

Parameters

[in]	loader	An extension loader that provides input data and context
[in]	name	A string identifier for the extension
[out]	ext	Pointer to the newly allocated llext structure
[in]	ldr_parm	Optional advanced load parameters (may be `NULL`)

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

Return values

-ENOMEM	Not enough memory
-ENOEXEC	Invalid ELF stream
-ENOTSUP	Unsupported ELF features

◆ llext_section_count()

static unsigned int llext_section_count ( const struct llext * ext )

inlinestatic

#include <zephyr/llext/llext.h>

◆ llext_section_headers()

static const elf_shdr_t * llext_section_headers ( const struct llext * ext )

inlinestatic

#include <zephyr/llext/llext.h>

◆ llext_teardown()

int llext_teardown ( struct llext * ext )

#include <zephyr/llext/llext.h>

Calls teardown functions for an extension.

Will execute the extension's own cleanup functions in the caller context. After this function completes, the extension is no longer usable and must be fully unloaded with llext_unload.

See also: llext_bootstrap

Parameters

[in] ext Extension to de-initialize.

Returns: 0 on success, or a negative error code.

Return values

-EFAULT A relocation issue was detected

◆ llext_unload()

int llext_unload ( struct llext ** ext )

#include <zephyr/llext/llext.h>

Unload an extension.

Parameters

[in] ext Extension to unload

Topics

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LLEXT_LOAD_PARAM_DEFAULT

◆ LLEXT_MAX_DEPENDENCIES

Typedef Documentation

◆ llext_entry_fn_t

Enumeration Type Documentation

◆ llext_mem

Function Documentation

◆ arch_elf_relocate()

◆ arch_elf_relocate_global()

◆ arch_elf_relocate_local()

◆ llext_add_domain()

◆ llext_bootstrap()

◆ llext_bringup()

◆ llext_by_name()

◆ llext_call_fn()

◆ llext_find_section()

◆ llext_find_sym()

◆ llext_get_fn_table()

◆ llext_get_section_header()

◆ llext_iterate()

◆ llext_load()

◆ llext_section_count()

◆ llext_section_headers()

◆ llext_teardown()

◆ llext_unload()