Linkable loadable extensions

Modules
	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_LOAD_PARAM_DEFAULT   { .relocate_local = true, }
	Default initializer for llext_load_param.

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_COUNT }
	List of memory regions stored or referenced in the LLEXT subsystem. More...

Functions
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, struct llext_load_param *ldr_parm)
	Load and link an extension.
int	llext_unload (struct llext **ext)
	Unload 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.
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.

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 <include/zephyr/llext/llext.h>

Default initializer for llext_load_param.

Enumeration Type Documentation

llext_mem

enum llext_mem

#include <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_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 <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_local()

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
	)

#include <include/zephyr/llext/llext.h>

Architecture specific function for updating addresses via relocation table.

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]	got_offset	Offset within a relocation table

llext_add_domain()

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

#include <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

CONFIG_USERSPACE is not enabled or supported

llext_by_name()

struct llext * llext_by_name

(

const char *

name

)

#include <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 <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 <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

loader	Extension loader data and context
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 <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_iterate()

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

#include <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,
		struct llext_load_param *	ldr_parm
	)

#include <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_unload()

int llext_unload

(

struct llext **

ext

)

#include <include/zephyr/llext/llext.h>

Unload an extension.

Parameters

[in]

ext

Extension to unload