README.rst
1.. zephyr:code-sample:: llext-modules
2 :name: Linkable loadable extensions "module" sample
3 :relevant-api: llext_apis
4
5 Call a function in a loadable extension module,
6 either built-in or loaded at runtime.
7
8Overview
9********
10
11This sample demonstrates the use of the :ref:`llext` subsystem in Zephyr. The
12llext subsystem allows for the loading of relocatable ELF files at runtime;
13their symbols can be accessed and functions called.
14
15Specifically, this shows how to call a simple "hello world" function,
16implemented in :zephyr_file:`samples/subsys/llext/modules/src/hello_world_ext.c`.
17This is achieved in two different ways, depending on the value of the Kconfig
18symbol ``CONFIG_HELLO_WORLD_MODE``:
19
20- if it is ``y``, the function is directly compiled and called by the Zephyr
21 application. The caller code used in this case is in
22 :zephyr_file:`samples/subsys/llext/modules/src/main_builtin.c`.
23
24- if it is ``m``, the function is compiled as an llext and it is included in
25 the application as a binary blob. At runtime, the llext subsystem is used to
26 load the extension and call the function. The caller code is in
27 :zephyr_file:`samples/subsys/llext/modules/src/main_module.c`.
28
29Requirements
30************
31
32A board with a supported llext architecture and console. This can also be
33executed in QEMU emulation on the :zephyr:board:`qemu_xtensa <qemu_xtensa>` or
34:zephyr:board:`qemu_cortex_r5 <qemu_cortex_r5>` virtual boards.
35
36Building and running
37********************
38
39- By default, the sample will compile the function along with the rest of
40 Zephyr in the same binary. This can be verified via the following commands:
41
42 .. zephyr-app-commands::
43 :zephyr-app: samples/subsys/llext/modules
44 :board: qemu_xtensa/dc233c
45 :goals: build run
46 :compact:
47
48- The following commands build and run the sample so that the extension code is
49 compiled separately and included in the Zephyr image as a binary blob:
50
51 .. zephyr-app-commands::
52 :zephyr-app: samples/subsys/llext/modules
53 :board: qemu_xtensa/dc233c
54 :goals: build run
55 :west-args: -T sample.llext.modules.module_build
56 :compact:
57
58 .. important::
59 Take a look at :zephyr_file:`samples/subsys/llext/modules/sample.yaml` for
60 the additional architecture-specific configurations required in this case.
61
62To build for a different board, replace ``qemu_xtensa`` in the commands above
63with the desired board name.
64
