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 <l.burelli@arduino.cc>
This commit is contained in:
Luca Burelli 2024-08-27 15:04:47 +02:00 committed by Anas Nashif
commit fca654c5a7

View file

@ -24,6 +24,32 @@ successfully, the extension is loaded into memory and is ready to be used.
included in any user memory domain. To allow access from user mode, the included in any user memory domain. To allow access from user mode, the
:c:func:`llext_add_domain` function must be called. :c:func:`llext_add_domain` function must be called.
Initializing and cleaning up the extension
==========================================
The extension may define a number of initialization functions that must be
called after loading but before any function in it can be used; this is typical
in languages such as C++ that provide the concept of object constructors. The
same is true for cleanup functions that must be called before unloading the
extension.
LLEXT supports calling the functions listed in the ``.preinit_array`` and
``.init_array`` sections of the ELF file with the :c:func:`llext_bringup`
function, and the functions listed in the ``.fini_array`` section with the
:c:func:`llext_teardown` function. These APIs are compatible with
:ref:`User Mode <usermode_api>`, and thus can be called from either kernel or
user context.
.. important::
The code run by these functions is fully determined by the contents of the
ELF file. This may have security implications if its origin is untrusted.
If the extension requires a dedicated thread, the :c:func:`llext_bootstrap`
function can be used to minimize boilerplate code. This function has a
signature that is compatible with the :c:func:`k_thread_create` API, and will
call :c:func:`llext_bringup`, then a user-specified function in the same
context, and finally :c:func:`llext_teardown` before returning.
Accessing code and data Accessing code and data
======================= =======================