1Configuration
2#############
3
4The following Kconfig options are available for the LLEXT subsystem:
5
6.. _llext_kconfig_heap:
7
8Heap size
9----------
10
11The LLEXT subsystem needs a heap to be allocated for extension related data.
12The following option controls this allocation, when allocating a static heap.
13
14:kconfig:option:`CONFIG_LLEXT_HEAP_SIZE`
15
16        Size of the LLEXT heap in kilobytes.
17
18For boards using the Harvard architecture, the LLEXT heap is split into two:
19one heap in instruction memory and another in data memory. The following options
20control these allocations.
21
22:kconfig:option:`CONFIG_LLEXT_INSTR_HEAP_SIZE`
23
24        Size of the LLEXT heap in instruction memory in kilobytes.
25
26:kconfig:option:`CONFIG_LLEXT_DATA_HEAP_SIZE`
27
28        Size of the LLEXT heap in data memory in kilobytes.
29
30.. note::
31   The LLEXT instruction heap is grouped with Zephyr .rodata, which the linker
32   typically places after .text in instruction memory.
33
34.. warning::
35   LLEXT will be unable to link and execute extensions if instruction memory
36   (i.e., memory the processor can fetch instructions from) is not writable.
37
38Alternatively the application can configure a dynamic heap using the following
39option.
40
41:kconfig:option:`CONFIG_LLEXT_HEAP_DYNAMIC`
42
43        Some applications require loading extensions into the memory which does
44        not exist during the boot time and cannot be allocated statically. Make
45        the application responsible for LLEXT heap allocation. Do not allocate
46        LLEXT heap statically.
47
48        Application must call :c:func:`llext_heap_init` in order to assign a
49        buffer to be used as the LLEXT heap, otherwise LLEXT modules will not
50        load. When the application does not need LLEXT functionality any more,
51        it should call :c:func:`llext_heap_uninit` which releases control of
52        the buffer back to the application.
53
54.. note::
55
56   When :ref:`user mode <usermode_api>` is enabled, the heap size must be
57   large enough to allow the extension sections to be allocated with the
58   alignment required by the architecture.
59
60.. note::
61   On Harvard architectures, applications must call
62   :c:func:`llext_heap_init_harvard`.
63
64.. _llext_kconfig_type:
65
66ELF object type
67---------------
68
69The LLEXT subsystem supports loading different types of extensions; the type
70can be set by choosing among the following Kconfig options:
71
72:kconfig:option:`CONFIG_LLEXT_TYPE_ELF_OBJECT`
73
74        Build and expect relocatable files as binary object type for the LLEXT
75        subsystem. A single compiler invocation is used to generate the object
76        file.
77
78:kconfig:option:`CONFIG_LLEXT_TYPE_ELF_RELOCATABLE`
79
80        Build and expect relocatable (partially linked) files as the binary
81        object type for the LLEXT subsystem. These object files are generated
82        by the linker by combining multiple object files into a single one.
83
84:kconfig:option:`CONFIG_LLEXT_TYPE_ELF_SHAREDLIB`
85
86        Build and expect shared libraries as binary object type for the LLEXT
87        subsystem. The standard linking process is used to generate the shared
88        library from multiple object files.
89
90        .. note::
91
92           This is not currently supported on ARM architectures.
93
94.. _llext_kconfig_storage:
95
96Minimize allocations
97--------------------
98
99The LLEXT subsystem loading mechanism, by default, uses a seek/read abstraction
100and copies all data into allocated memory; this is done to allow the extension
101to be loaded from any storage medium. Sometimes, however, data is already in a
102buffer in RAM and copying it is not necessary. The following option allows the
103LLEXT subsystem to optimize memory footprint in this case.
104
105:kconfig:option:`CONFIG_LLEXT_STORAGE_WRITABLE`
106
107        Allow the extension to be loaded by directly referencing section data
108        into the ELF buffer. To be effective, this requires the use of an ELF
109        loader that supports the ``peek`` functionality, such as the
110        :c:struct:`llext_buf_loader`.
111
112        .. warning::
113
114           The application must ensure that the buffer used to load the
115           extension remains allocated until the extension is unloaded.
116
117        .. note::
118
119           This will directly modify the contents of the buffer during the link
120           phase. Once the extension is unloaded, the buffer must be reloaded
121           before it can be used again in a call to :c:func:`llext_load`.
122
123        .. note::
124
125           This is currently required by the Xtensa architecture. Further
126           information on this topic is available on GitHub issue `#75341
127           <https://github.com/zephyrproject-rtos/zephyr/issues/75341>`_.
128
129.. _llext_kconfig_slid:
130
131Using SLID for symbol lookups
132-----------------------------
133
134When an extension is loaded, the LLEXT subsystem must find the address of all
135the symbols residing in the main application that the extension references.
136To this end, the main binary contains a LLEXT-dedicated symbol table, filled
137with one symbol-name-to-address mapping entry for each symbol exported by the
138main application to extensions. This table can then be searched into by the
139LLEXT linker at extension load time. This process is pretty slow due to the
140nature of string comparisons, and the size consumed by the table can become
141significant as the number of exported symbols increases.
142
143:kconfig:option:`CONFIG_LLEXT_EXPORT_BUILTINS_BY_SLID`
144
145        Perform an extra processing step on the Zephyr binary and on all
146        extensions being built, converting every string in the symbol tables to
147        a pointer-sized hash called Symbol Link Identifier (SLID), which is
148        stored in the binary.
149
150        This speeds up the symbol lookup process by allowing usage of
151        integer-based comparisons rather than string-based ones. Another
152        benefit of SLID-based linking is that storing symbol names in the
153        binary is no longer necessary, which provides a significant decrease in
154        symbol table size.
155
156        .. note::
157
158           This option is not currently compatible with the :ref:`LLEXT EDK
159           <llext_build_edk>`.
160
161        .. note::
162
163           Using a different value for this option in the main binary and in
164           extensions is not supported. For example, if the main application
165           is built with ``CONFIG_LLEXT_EXPORT_BUILTINS_BY_SLID=y``, it is
166           forbidden to load an extension that was compiled with
167           ``CONFIG_LLEXT_EXPORT_BUILTINS_BY_SLID=n``.
168
169EDK configuration
170-----------------
171
172Options influencing the generation and behavior of the LLEXT EDK are described
173in :ref:`llext_kconfig_edk`.
174