From 2654fdc6bacb74225098bf5e565b719e1978c020 Mon Sep 17 00:00:00 2001 From: Ederson de Souza Date: Wed, 22 May 2024 13:18:35 -0700 Subject: [PATCH] doc/services/llext: Mention the LLEXT EDK Mention the EDK existence, the build target and discuss some features. Signed-off-by: Ederson de Souza --- doc/services/llext/index.rst | 60 ++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/doc/services/llext/index.rst b/doc/services/llext/index.rst index d742f198530..899936cda61 100644 --- a/doc/services/llext/index.rst +++ b/doc/services/llext/index.rst @@ -18,6 +18,66 @@ needed by the :c:func:`llext_load` function. An implementation over a buffer containing an ELF in addressable memory in memory is available as :c:struct:`llext_buf_loader`. +LLEXT Extension Development Kit +******************************* + +To build the extensions to be loaded by the llext subsystem, it's necessary to +have access to the headers and compiler flags used by the main Zephyr +application. While building an extension as part of the Zephyr application +is straightforward, it can be more complex as a standalone project. + +The LLEXT Extension Development Kit (EDK) provides a set of headers and compile +flags that can be used to build extensions as standalone projects. The EDK +can be generated by the Zephyr build system by running the following command +which uses the ``llext-edk`` target to generate the EDK: + +.. code-block:: shell + + west build -t llext-edk + +The generated EDK can be found in the build directory under the ``zephyr`` +directory. It's a tarball that contains the headers and compile flags needed +to build extensions. The extension developer can then include the headers +and use the compile flags in their build system to build the extension. + +Compile flags +------------- + +Convenience files ``cmake.cflags`` (for CMake based projects) and +``Makefile.cflags`` are provided by the EDK containing the needed compile flags. +The main flag is ``LLEXT_CFLAGS`` which contains the flags needed to build an +extension. Also provided is a granular set of flags that can be used in support +of different use cases, such as when building mocks for unit tests. The provided +flags are: + +- ``LLEXT_CFLAGS``: Flags needed to build an extension. +- ``LLEXT_ALL_INCLUDE_CFLAGS``: Include flags needed to include all headers. +- ``LLEXT_INCLUDE_CFLAGS``: Include flags for non build generated headers. +- ``LLEXT_GENERATED_INCLUDE_CFLAGS``: Include flags for build generated headers. +- ``LLEXT_BASE_CFLAGS``: All other flags needed to build an extension, + excluding the include flags. +- ``LLEXT_GENERATED_IMACROS_CFLAGS``: Include only ``-imacros`` flags for build + generated headers. + +LLEXT EDK Kconfig options +------------------------- + +The LLEXT EDK can be configured using the following Kconfig options: + +:kconfig:option:`CONFIG_LLEXT_EDK_NAME` + The name of the generated EDK tarball. + +:kconfig:option:`CONFIG_LLEXT_EDK_USERSPACE_ONLY` + If set, the EDK will include headers that do not contain code to route + syscalls to the kernel. This is useful when building extensions that will + run exclusively in user mode. + +EDK Sample +---------- + +Refer to :zephyr:code-sample:`llext-edk` for an example of how to use the +LLEXT EDK. + API Reference *************