llext.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023 Intel Corporation
 * Copyright (c) 2024 Schneider Electric
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_LLEXT_H
#define ZEPHYR_LLEXT_H
 
#include <zephyr/sys/slist.h>
#include <zephyr/llext/elf.h>
#include <zephyr/llext/symbol.h>
#include <zephyr/kernel.h>
#include <sys/types.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif


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,         
#ifdef CONFIG_LLEXT_RODATA_NO_RELOC
        LLEXT_MEM_RODATA_NO_RELOC,  
#endif
 
        LLEXT_MEM_COUNT,        
};

 
/* Number of memory partitions used by LLEXT */
#define LLEXT_MEM_PARTITIONS (LLEXT_MEM_BSS+1)
 
#ifdef CONFIG_LLEXT_RODATA_NO_RELOC
/* Section name for read-only data kept in flash */
#define LLEXT_SECT_RODATA_NO_RELOC llext.rodata.noreloc
 
/* Full section name as string for comparisons */
#define LLEXT_SECTION_RODATA_NO_RELOC ("." STRINGIFY(LLEXT_SECT_RODATA_NO_RELOC))

#define LLEXT_RODATA_NO_RELOC Z_GENERIC_DOT_SECTION(LLEXT_SECT_RODATA_NO_RELOC)
#else
#define LLEXT_RODATA_NO_RELOC
#endif
 
struct llext_loader;

#define LLEXT_MAX_NAME_LEN 15

#define LLEXT_MAX_DEPENDENCIES 8
 
#ifdef CONFIG_LLEXT_HEAP_MEMBLK
struct llext_alloc {
        int num_blocks;
        void *memblk_ptr;
};
struct llext_alloc_map {
        int idx;
        struct llext_alloc map[LLEXT_MEM_COUNT];
};
#endif

struct llext {
        sys_snode_t llext_list;
 
#ifdef CONFIG_USERSPACE
        struct k_mem_partition mem_parts[LLEXT_MEM_PARTITIONS];
#endif


        char name[LLEXT_MAX_NAME_LEN + 1];

        void *mem[LLEXT_MEM_COUNT];

        bool mem_on_heap[LLEXT_MEM_COUNT];
 
#ifdef CONFIG_LLEXT_HEAP_MEMBLK
        struct llext_alloc_map mem_alloc_map;
#endif

        size_t mem_size[LLEXT_MEM_COUNT];

        size_t alloc_size;

        struct llext_symtable sym_tab;

        struct llext_symtable exp_tab;

        unsigned int use_count;

        struct llext *dependency[LLEXT_MAX_DEPENDENCIES];

        unsigned int sect_cnt;
        elf_shdr_t *sect_hdrs;
        bool sect_hdrs_on_heap;
        bool mmu_permissions_set;
};
 
static inline const elf_shdr_t *llext_section_headers(const struct llext *ext)
{
        return ext->sect_hdrs;
}
 
static inline unsigned int llext_section_count(const struct llext *ext)
{
        return ext->sect_cnt;
}

struct llext_load_param {
        bool relocate_local;

        bool pre_located;

        bool (*section_detached)(const elf_shdr_t *shdr);

        bool keep_section_info;
};

#define LLEXT_LOAD_PARAM_DEFAULT { .relocate_local = true, }

struct llext *llext_by_name(const char *name);

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

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

int llext_unload(struct llext **ext);

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

typedef void (*llext_entry_fn_t)(void *user_data);

int llext_bringup(struct llext *ext);

int llext_teardown(struct llext *ext);

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

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

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

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

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

int arch_elf_relocate(struct llext_loader *ldr, struct llext *ext, elf_rela_t *rel,
                      const elf_shdr_t *shdr);

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

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

int llext_heap_init(void *mem, size_t bytes);

int llext_heap_init_harvard(void *instr_mem, size_t instr_bytes, void *data_mem, size_t data_bytes);

int llext_heap_uninit(void);

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

int llext_restore(struct llext **ext, struct llext_loader **ldr, unsigned int n_ext);
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/llext.h>
 
#endif /* ZEPHYR_LLEXT_H */