michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: llext: split existing text into separate files

Browse source 
The existing index.rst file contains a mix of information about the
llext subsystem and the LLEXT Extension Development Kit (EDK). This
commit splits the existing text into two separate files, index.rst and
build.rst, as a first step on improving the documentation.

No change in text is done in this commit.

Signed-off-by: Luca Burelli <l.burelli@arduino.cc>
This commit is contained in:
Luca Burelli 2024-06-26 16:17:24 +02:00 • committed by Alberto Escolar
commit c444fdb581
4 changed files with 84 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc/services/llext/api.rst Normal file
View file

@ -0,0 +1,10 @@
API Reference
*************
.. doxygengroup:: llext
.. doxygengroup:: llext_symbols
.. doxygengroup:: llext_loader
.. doxygengroup:: llext_buf_loader

61
doc/services/llext/build.rst Normal file
View file

@ -0,0 +1,61 @@
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_kconf_edk:
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.

85
doc/services/llext/index.rst
View file

@ -3,6 +3,13 @@
Linkable Loadable Extensions (LLEXT)
####################################
.. toctree::
:maxdepth: 1
build
load
api
The llext subsystem provides a toolbox for extending the functionality of an
application at runtime with linkable loadable code.
@ -10,81 +17,3 @@ Extensions can be loaded from precompiled ELF formatted data which is
verified, loaded, and linked with other extensions. Extensions can be
manipulated and introspected to some degree, as well as unloaded when no longer
needed.
An extension may be loaded using any implementation of a :c:struct:`llext_loader`
which has a set of function pointers that provide the necessary functionality
to read the ELF data. A loader also provides some minimal context (memory)
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
*************
.. doxygengroup:: llext
.. doxygengroup:: llext_symbols
.. doxygengroup:: llext_loader
.. doxygengroup:: llext_buf_loader

6
doc/services/llext/load.rst Normal file
View file

@ -0,0 +1,6 @@
An extension may be loaded using any implementation of a :c:struct:`llext_loader`
which has a set of function pointers that provide the necessary functionality
to read the ELF data. A loader also provides some minimal context (memory)
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`.