Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Intel Corporation
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_LLEXT_SYMBOL_H
8 : #define ZEPHYR_LLEXT_SYMBOL_H
9 :
10 : #include <zephyr/sys/iterable_sections.h>
11 : #include <zephyr/toolchain.h>
12 : #include <stddef.h>
13 : #include <stdint.h>
14 :
15 : #ifdef __cplusplus
16 : extern "C" {
17 : #endif
18 :
19 : /**
20 : * @file
21 : * @brief Linkable loadable extension symbol definitions
22 : *
23 : * This file provides a set of macros and structures for defining and exporting
24 : * symbols from the base image to extensions and vice versa, so that proper
25 : * linking can be done between the two entities.
26 : *
27 : * @defgroup llext_symbols Exported symbol definitions
28 : * @ingroup llext_apis
29 : * @{
30 : */
31 :
32 : /**
33 : * @brief Constant symbols are unchangeable named memory addresses
34 : *
35 : * Symbols may be named function or global objects that have been exported
36 : * for linking. These constant symbols are useful in the base image
37 : * as they may be placed in ROM.
38 : *
39 : * @note When updating this structure, make sure to also update the
40 : * 'scripts/build/llext_prepare_exptab.py' build script.
41 : */
42 1 : struct llext_const_symbol {
43 : /** At build time, we always write to 'name'.
44 : * At runtime, which field is used depends
45 : * on CONFIG_LLEXT_EXPORT_BUILTINS_BY_SLID.
46 : */
47 : union {
48 : /** Name of symbol */
49 1 : const char *const name;
50 :
51 : /** Symbol Link Identifier */
52 1 : const uintptr_t slid;
53 1 : };
54 :
55 : /** Address of symbol */
56 1 : const void *const addr;
57 : };
58 : BUILD_ASSERT(sizeof(struct llext_const_symbol) == 2 * sizeof(uintptr_t));
59 :
60 : /**
61 : * @brief Symbols are named memory addresses
62 : *
63 : * Symbols may be named function or global objects that have been exported
64 : * for linking. These are mutable and should come from extensions where
65 : * the location may need updating depending on where memory is placed.
66 : */
67 1 : struct llext_symbol {
68 : /** Name of symbol */
69 1 : const char *name;
70 :
71 : /** Address of symbol */
72 1 : void *addr;
73 : };
74 :
75 :
76 : /**
77 : * @brief A symbol table
78 : *
79 : * An array of symbols
80 : */
81 1 : struct llext_symtable {
82 : /** Number of symbols in the table */
83 1 : size_t sym_cnt;
84 :
85 : /** Array of symbols */
86 1 : struct llext_symbol *syms;
87 : };
88 :
89 :
90 : /** @cond ignore */
91 : #ifdef LL_EXTENSION_BUILD
92 : /* Extension build: add exported symbols to llext table */
93 : #define Z_LL_EXTENSION_SYMBOL_NAMED(sym_ident, sym_name) \
94 : static const struct llext_const_symbol \
95 : Z_GENERIC_SECTION(.exported_sym) __used \
96 : __llext_sym_ ## sym_name = { \
97 : .name = STRINGIFY(sym_name), .addr = (const void *)&sym_ident, \
98 : }
99 : #else
100 : /* No-op when not building an extension */
101 : #define Z_LL_EXTENSION_SYMBOL_NAMED(sym_ident, sym_name)
102 : #endif
103 : /** @endcond */
104 :
105 : /**
106 : * @brief Exports a symbol from an extension to the base image with a custom name
107 : *
108 : * Version of @ref LL_EXTENSION_SYMBOL that allows the user to specify a custom
109 : * name for the exported symbol.
110 : *
111 : * @param sym_ident Extension symbol to export to the base image
112 : * @param sym_name Name associated with the symbol
113 : */
114 1 : #define LL_EXTENSION_SYMBOL_NAMED(sym_ident, sym_name) \
115 : Z_LL_EXTENSION_SYMBOL_NAMED(sym_ident, sym_name)
116 :
117 : /**
118 : * @brief Exports a symbol from an extension to the base image
119 : *
120 : * This macro can be used in extensions to add a symbol (function or object)
121 : * to the extension's exported symbol table, so that it may be referenced by
122 : * the base image.
123 : *
124 : * When not building an extension, this macro is a no-op.
125 : *
126 : * @param x Extension symbol to export to the base image
127 : */
128 1 : #define LL_EXTENSION_SYMBOL(x) Z_LL_EXTENSION_SYMBOL_NAMED(x, x)
129 :
130 : /** @cond ignore */
131 : #if defined(LL_EXTENSION_BUILD)
132 : /* Extension build: EXPORT_SYMBOL maps to LL_EXTENSION_SYMBOL */
133 : #define Z_EXPORT_SYMBOL_NAMED(sym_ident, sym_name) \
134 : Z_LL_EXTENSION_SYMBOL_NAMED(sym_ident, sym_name)
135 : #elif defined(CONFIG_LLEXT_EXPORT_BUILTINS_BY_SLID)
136 : /* SLID-enabled LLEXT application: export symbols, names in separate section */
137 : #define Z_EXPORT_SYMBOL_NAMED(sym_ident, sym_name) \
138 : static const char Z_GENERIC_SECTION(llext_exports_strtab) __used \
139 : __llext_sym_name_ ## sym_name[] = STRINGIFY(sym_name); \
140 : static const STRUCT_SECTION_ITERABLE(llext_const_symbol, \
141 : __llext_sym_ ## sym_name) = { \
142 : .name = __llext_sym_name_ ## sym_name, \
143 : .addr = (const void *)&sym_ident, \
144 : }
145 : #elif defined(CONFIG_LLEXT)
146 : /* LLEXT application: export symbols */
147 : #define Z_EXPORT_SYMBOL_NAMED(sym_ident, sym_name) \
148 : static const STRUCT_SECTION_ITERABLE(llext_const_symbol, \
149 : __llext_sym_ ## sym_name) = { \
150 : .name = STRINGIFY(sym_name), .addr = (const void *)&sym_ident, \
151 : }
152 : #else
153 : /* No extension support in this build */
154 : #define Z_EXPORT_SYMBOL_NAMED(sym_ident, sym_name)
155 : #endif
156 : /** @endcond */
157 :
158 : /**
159 : * @brief Export a constant symbol from the current build with a custom name
160 : *
161 : * Version of @ref EXPORT_SYMBOL that allows the user to specify a custom name
162 : * for the exported symbol.
163 : *
164 : * When @c CONFIG_LLEXT is not enabled, this macro is a no-op.
165 : *
166 : * @param sym_ident Symbol to export
167 : * @param sym_name Name associated with the symbol
168 : */
169 1 : #define EXPORT_SYMBOL_NAMED(sym_ident, sym_name) \
170 : Z_EXPORT_SYMBOL_NAMED(sym_ident, sym_name)
171 :
172 : /**
173 : * @brief Export a constant symbol from the current build
174 : *
175 : * Takes a symbol (function or object) by symbolic name and adds the name
176 : * and address of the symbol to a table of symbols that may be referenced
177 : * by extensions or by the base image, depending on the current build type.
178 : *
179 : * When @c CONFIG_LLEXT is not enabled, this macro is a no-op.
180 : *
181 : * @param x Symbol to export
182 : */
183 1 : #define EXPORT_SYMBOL(x) EXPORT_SYMBOL_NAMED(x, x)
184 :
185 : /**
186 : * @}
187 : */
188 :
189 : #ifdef __cplusplus
190 : }
191 : #endif
192 :
193 :
194 : #endif /* ZEPHYR_LLEXT_SYMBOL_H */
|
