Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
|
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 | |
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. | |
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. | |
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. | |
#define LLEXT_LOAD_PARAM_DEFAULT { .relocate_local = true, } |
#include <zephyr/llext/llext.h>
Default initializer for llext_load_param.
#define LLEXT_MAX_DEPENDENCIES 8 |
#include <zephyr/llext/llext.h>
typedef void(* llext_entry_fn_t) (void *user_data) |
#include <zephyr/llext/llext.h>
Entry point function signature for an extension.
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.
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.
[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 |
0 | Success |
-ENOTSUP | Unsupported relocation |
-ENOEXEC | Invalid relocation |
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.
[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 |
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.
[in] | ext | Extension to add to a domain |
[in] | domain | Memory domain to add partitions to |
-ENOSYS | CONFIG_USERSPACE is not enabled or supported |
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.
[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. |
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.
[in] | ext | Extension to initialize. |
-EFAULT | A relocation issue was detected |
struct llext * llext_by_name | ( | const char * | name | ) |
#include <zephyr/llext/llext.h>
Find an llext by name.
[in] | name | String name of the llext |
NULL
if not found 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.
[in] | ext | Extension to call function in |
[in] | sym_name | Function name (exported symbol) in the extension |
0 | Success |
-ENOENT | Symbol name not found |
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.
[in] | loader | Extension loader data and context |
[in] | search_name | Section name to search for |
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.
[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 |
NULL
if not found #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.
[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. |
-EFAULT | A relocation issue was detected |
-ENOMEM | Array does not fit in the allocated buffer |
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.
[in] | fn | callback function |
[in] | arg | a private argument to be provided to the callback function |
0 | if no extensions are registered |
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.
[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 ) |
-ENOMEM | Not enough memory |
-ENOEXEC | Invalid ELF stream |
-ENOTSUP | Unsupported ELF features |
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.
[in] | ext | Extension to de-initialize. |
-EFAULT | A relocation issue was detected |
int llext_unload | ( | struct llext ** | ext | ) |