1Loading extensions
2##################
3
4Once an extension is built and the ELF file is available, it can be loaded into
5the Zephyr application using the LLEXT API, which provides a way to load the
6extension into memory, access its symbols and call its functions.
7
8Loading an extension
9====================
10
11An extension may be loaded using any implementation of a :c:struct:`llext_loader`
12which has a set of function pointers that provide the necessary functionality
13to read the ELF data. A loader also provides some minimal context (memory)
14needed by the :c:func:`llext_load` function. An implementation over a buffer
15containing an ELF in addressable memory in memory is available as
16:c:struct:`llext_buf_loader`.
17
18The extensions are loaded with a call to the :c:func:`llext_load` function,
19passing in the extension name and the configured loader. Once that completes
20successfully, the extension is loaded into memory and is ready to be used.
21
22.. note::
23   When :ref:`User Mode <usermode_api>` is enabled, the extension will not be
24   included in any user memory domain. To allow access from user mode, the
25   :c:func:`llext_add_domain` function must be called.
26
27Initializing and cleaning up the extension
28==========================================
29
30The extension may define a number of initialization functions that must be
31called after loading but before any function in it can be used; this is typical
32in languages such as C++ that provide the concept of object constructors. The
33same is true for cleanup functions that must be called before unloading the
34extension.
35
36LLEXT supports calling the functions listed in the ``.preinit_array`` and
37``.init_array`` sections of the ELF file with the :c:func:`llext_bringup`
38function, and the functions listed in the ``.fini_array`` section with the
39:c:func:`llext_teardown` function. These APIs are compatible with
40:ref:`User Mode <usermode_api>`, and thus can be called from either kernel or
41user context.
42
43.. important::
44   The code run by these functions is fully determined by the contents of the
45   ELF file. This may have security implications if its origin is untrusted.
46
47If the extension requires a dedicated thread, the :c:func:`llext_bootstrap`
48function can be used to minimize boilerplate code. This function has a
49signature that is compatible with the :c:func:`k_thread_create` API, and will
50call :c:func:`llext_bringup`, then a user-specified function in the same
51context, and finally :c:func:`llext_teardown` before returning.
52
53Accessing code and data
54=======================
55
56To interact with the newly loaded extension, the host application must use the
57:c:func:`llext_find_sym` function to get the address of the exported symbol.
58The returned ``void *`` can then be cast to the appropriate type and used.
59
60A wrapper for calling a function with no arguments is provided in
61:c:func:`llext_call_fn`.
62
63Cleaning up after use
64=====================
65
66The :c:func:`llext_unload` function must be called to free the memory used by
67the extension once it is no longer required. After this call completes, all
68pointers to symbols in the extension that were obtained will be invalid.
69
70Troubleshooting
71###############
72
73This feature is being actively developed and as such it is possible that some
74issues may arise. Since linking does modify the binary code, in case of errors
75the results are difficult to predict. Some common issues may be:
76
77* Results from :c:func:`llext_find_sym` point to an invalid address;
78
79* Constants and variables defined in the extension do not have the expected
80  values;
81
82* Calling a function defined in an extension results in a hard fault, or memory
83  in the main application is corrupted after returning from it.
84
85If any of this happens, the following tips may help understand the issue:
86
87* Make sure :kconfig:option:`CONFIG_LLEXT_LOG_LEVEL` is set to ``DEBUG``, then
88  obtain a log of the :c:func:`llext_load` invocation.
89
90* If possible, disable memory protection (MMU/MPU) and see if this results in
91  different behavior.
92
93* Try to simplify the extension to the minimum possible code that reproduces
94  the issue.
95
96* Use a debugger to inspect the memory and registers to try to understand what
97  is happening.
98
99  .. note::
100     When using GDB, the ``add_symbol_file`` command may be used to load the
101     debugging information and symbols from the ELF file. Make sure to specify
102     the proper offset (usually the start of the ``.text`` section, reported
103     as ``region 0`` in the debug logs.)
104
105If the issue persists, please open an issue in the GitHub repository, including
106all the above information.
107