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