Skip to content

Commit fca654c

Browse files
pillo79nashif
authored andcommitted
doc: llext: add extension bringup and teardown documentation
Add documentation for the new LLEXT APIs that allow to call the initialization and cleanup functions of an extension. Signed-off-by: Luca Burelli <[email protected]>
1 parent af302cd commit fca654c

File tree

1 file changed

+26
-0
lines changed

1 file changed

+26
-0
lines changed

doc/services/llext/load.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,32 @@ successfully, the extension is loaded into memory and is ready to be used.
2424
included in any user memory domain. To allow access from user mode, the
2525
:c:func:`llext_add_domain` function must be called.
2626

27+
Initializing and cleaning up the extension
28+
==========================================
29+
30+
The extension may define a number of initialization functions that must be
31+
called after loading but before any function in it can be used; this is typical
32+
in languages such as C++ that provide the concept of object constructors. The
33+
same is true for cleanup functions that must be called before unloading the
34+
extension.
35+
36+
LLEXT supports calling the functions listed in the ``.preinit_array`` and
37+
``.init_array`` sections of the ELF file with the :c:func:`llext_bringup`
38+
function, 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
41+
user 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+
47+
If the extension requires a dedicated thread, the :c:func:`llext_bootstrap`
48+
function can be used to minimize boilerplate code. This function has a
49+
signature that is compatible with the :c:func:`k_thread_create` API, and will
50+
call :c:func:`llext_bringup`, then a user-specified function in the same
51+
context, and finally :c:func:`llext_teardown` before returning.
52+
2753
Accessing code and data
2854
=======================
2955

0 commit comments

Comments
 (0)