Linkable loadable extensions

Linkable loadable extensions. More...

Modules
	ELF data types and defines
	ELF types and parsing.
	LLEXT symbols
	Linkable loadable extension symbol.
	Linkable loadable extensions buffer loader
	LLEXT buffer loader.
	Loader context for llext
	Loader context for llext.

Data Structures
struct	llext
	Linkable loadable extension. More...
struct	llext_load_param
	llext loader parameters More...

Macros
#define	LLEXT_MEM_PARTITIONS   (LLEXT_MEM_BSS+1)
#define	LLEXT_LOAD_PARAM_DEFAULT   {.relocate_local = true,}

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 ELF regions that are stored or referenced in the llext. 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 overall registered llext instances.
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 name.
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 the known memory partitions of the 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 function for updating op codes given a relocation.
ssize_t	llext_find_section (struct llext_loader *loader, const char *search_name)
	Find an ELF section.
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

Linkable loadable extensions.

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>

LLEXT_MEM_PARTITIONS

#define LLEXT_MEM_PARTITIONS   (LLEXT_MEM_BSS+1)

#include <zephyr/llext/llext.h>

Enumeration Type Documentation

llext_mem

enum llext_mem

#include <zephyr/llext/llext.h>

List of ELF regions that are stored or referenced in the llext.

Enumerator
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

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 function for updating op codes given a relocation.

Elf files contain a series of relocations described in a section. These relocation instructions are architecture specific and each architecture supporting extensions must implement this. They are instructions on how to rewrite opcodes given the actual placement of some symbolic data such as a section, function, or object.

Parameters

[in]	rel	Relocation data provided by elf
[in]	loc	Address of operation to rewrite with relocation
[in]	sym_base_addr	Symbol address
[in]	sym_name	Symbol name
[in]	load_bias	.text load address

Return values

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

Add the known memory partitions of the extension to a memory domain.

Allows an extension to be executed in supervisor or user mode threads when memory protection hardware is enabled.

Parameters

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

Return values

0	success
-errno	error

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

Return values

NULL	if no llext not found
llext	if llext 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
-EINVAL	invalid symbol name

llext_find_section()

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

#include <zephyr/llext/llext.h>

Find an ELF section.

Parameters

loader	Extension loader data and context
search_name	Section name to search for

Return values

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 name.

Parameters

[in]	sym_table	Symbol table to lookup symbol in, if NULL uses base table
[in]	sym_name	Symbol name to find

Return values

NULL	if no symbol found
addr	Address of symbol in memory if found

llext_iterate()

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

#include <zephyr/llext/llext.h>

Iterate overall registered llext instances.

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

Return values

0	if no extensions are registered
value	returned by the most recent callback invocation

llext_load()

int llext_load	(	struct llext_loader *	loader,
		const char *	name,
		struct llext **	ext,
		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.

Only relocatable ELF files are currently supported (partially linked).

Parameters

[in]	loader	An extension loader that provides input data and context
[in]	name	A string identifier for the extension
[out]	ext	This will hold the pointer to the llext struct
[in]	ldr_parm	Loader parameters

Return values

0	Success
>	0 extension use count
-ENOMEM	Not enough memory
-EINVAL	Invalid ELF stream

llext_unload()

int llext_unload

(

struct llext **

ext

)

#include <zephyr/llext/llext.h>

Unload an extension.

Parameters

[in]

ext

Extension to unload