From fca654c5a7a1dfe3b2b74062e4b0483c8d1a0a09 Mon Sep 17 00:00:00 2001 From: Luca Burelli Date: Tue, 27 Aug 2024 15:04:47 +0200 Subject: [PATCH] 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 --- doc/services/llext/load.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/services/llext/load.rst b/doc/services/llext/load.rst index 0898cb3a40e..78fc897b87d 100644 --- a/doc/services/llext/load.rst +++ b/doc/services/llext/load.rst @@ -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 :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 `, 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 =======================