Linkable loadable extensions

Topics
	ELF constants and data types
	ELF inspection APIs
	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_NAME_LEN   15
	Maximum length of an extension name.
#define	LLEXT_MAX_DEPENDENCIES   8
	Maximum number of dependency LLEXTs.
#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_free_inspection_data (struct llext_loader *ldr, struct llext *ext)
	Free any inspection-related memory for the specified loader and 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 (struct llext_loader *ldr, struct llext *ext, elf_rela_t *rel, const elf_shdr_t *shdr)
	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.
int	llext_heap_init (void *mem, size_t bytes)
	Initialize LLEXT heap dynamically.
int	llext_heap_uninit (void)
	Mark LLEXT heap as uninitialized.
int	llext_relink_dependency (struct llext *ext, unsigned int n_ext)
	Relink dependencies to prepare for suspend.
int	llext_restore (struct llext **ext, struct llext_loader **ldr, unsigned int n_ext)
	Restore LLEXT context from saved data.

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>

Maximum number of dependency LLEXTs.

LLEXT_MAX_NAME_LEN

#define LLEXT_MAX_NAME_LEN   15

#include <zephyr/llext/llext.h>

Maximum length of an extension name.

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	(	struct llext_loader *	ldr,
		struct llext *	ext,
		elf_rela_t *	rel,
		const elf_shdr_t *	shdr )

#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. Arguments sym_base_addr, sym_name can be computed from the sym parameter, but these parameters are provided redundantly to increase efficiency.

Parameters

[in]	ldr	Extension loader
[in]	ext	Extension being relocated refers to
[in]	rel	Relocation data provided by ELF
[in]	shdr	Header of the ELF section currently being located

Return values

0	Success
-ENOTSUP	Unsupported relocation
-ENOEXEC	Invalid relocation

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_free_inspection_data()

int llext_free_inspection_data	(	struct llext_loader *	ldr,
		struct llext *	ext )

#include <zephyr/llext/llext.h>

Free any inspection-related memory for the specified loader and extension.

This is only required if inspection data was requested at load time by setting llext_load_param::keep_section_info; otherwise, this call will be a no-op.

Parameters

[in]	ldr	Extension loader
[in]	ext	Extension

Returns

0 on success, or a negative error code.

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_heap_init()

int llext_heap_init	(	void *	mem,
		size_t	bytes )

#include <zephyr/llext/llext.h>

Initialize LLEXT heap dynamically.

Use the provided memory block as the LLEXT heap at runtime.

Parameters

mem	Pointer to memory.
bytes	Size of memory region, in bytes

Returns

0 on success, or a negative error code.

Return values

-ENOSYS

Option CONFIG_LLEXT_HEAP_DYNAMIC is not enabled or supported

llext_heap_uninit()

int llext_heap_uninit

(

void

)

#include <zephyr/llext/llext.h>

Mark LLEXT heap as uninitialized.

Returns

0 on success, or a negative error code.

Return values

-ENOSYS	Option CONFIG_LLEXT_HEAP_DYNAMIC is not enabled or supported
-EBUSY	On heap not empty

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_relink_dependency()

int llext_relink_dependency	(	struct llext *	ext,
		unsigned int	n_ext )

#include <zephyr/llext/llext.h>

Relink dependencies to prepare for suspend.

For suspend-resume use-cases, when LLEXT context should be saved in a non-volatile buffer, the user can save most LLEXT support data, but they have to use llext_restore() to re-allocate objects, which will also have to restore dependency pointers. To make sure dependency saving and restoring is done consistently, we provide a helper function for the former too.

Warning

this is a part of an experimental API, it WILL change in the future! Its availability depends on CONFIG_LLEXT_EXPERIMENTAL, which is disabled by default.

Parameters

[in]	ext	Extension array
[in]	n_ext	Number of extensions

Return values

0	Success
-ENOENT	Some dependencies not found

llext_restore()

int llext_restore	(	struct llext **	ext,
		struct llext_loader **	ldr,
		unsigned int	n_ext )

#include <zephyr/llext/llext.h>

Restore LLEXT context from saved data.

During suspend the user has saved all the extension and loader descriptors and related objects and called llext_relink_dependency() to prepare dependency pointers. When resuming llext_alloc() has to be used to re-allocate all the objects, therefore the user needs support from LLEXT core to accomplish that. This function takes arrays of pointers to saved copies of extensions and loaders as arguments and re-allocates all the objects, while also adding them to the global extension list. At the same time it relinks dependency pointers to newly allocated extensions.

Warning

this is a part of an experimental API, it WILL change in the future! Its availability depends on CONFIG_LLEXT_EXPERIMENTAL, which is disabled by default.

Parameters

[in,out]	ext	Extension pointer array - replaced with re-allocated copies
[in,out]	ldr	Array of loader pointers to restore section maps
[in]	n_ext	Number of extensions

Return values

0	Success
-ENOMEM	No memory
-EINVAL	Stored dependency out of range
-EFAULT	Internal algorithmic error

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