Blame view
include/linker_lists.h
10.7 KB
42ebaae3a common: Implement... |
1 2 3 4 5 6 7 |
/* * include/linker_lists.h * * Implementation of linker-generated arrays * * Copyright (C) 2012 Marek Vasut <marex@denx.de> * |
1a4596601 Add GPL-2.0+ SPDX... |
8 |
* SPDX-License-Identifier: GPL-2.0+ |
42ebaae3a common: Implement... |
9 |
*/ |
ef123c525 Refactor linker-g... |
10 |
|
babb4440c kernel-doc: fix s... |
11 12 |
#ifndef __LINKER_LISTS_H__ #define __LINKER_LISTS_H__ |
dc7cb46f9 linker_lists: inc... |
13 |
#include <linux/compiler.h> |
ef123c525 Refactor linker-g... |
14 |
/* |
d72fd7b34 linker_lists: rem... |
15 |
* There is no use in including this from ASM files. |
ef123c525 Refactor linker-g... |
16 17 18 19 20 21 22 |
* So just don't define anything when included from ASM. */ #if !defined(__ASSEMBLY__) /** * A linker list is constructed by grouping together linker input |
44f145fd8 linker_lists: fix... |
23 |
* sections, each containing one entry of the list. Each input section |
ef123c525 Refactor linker-g... |
24 25 26 27 28 29 |
* contains a constant initialized variable which holds the entry's * content. Linker list input sections are constructed from the list * and entry names, plus a prefix which allows grouping all lists * together. Assuming _list and _entry are the list and entry names, * then the corresponding input section name is * |
97d5e9d14 linker_lists: fix... |
30 |
* .u_boot_list_ + 2_ + @_list + _2_ + @_entry |
ef123c525 Refactor linker-g... |
31 32 33 |
* * and the C variable name is * |
97d5e9d14 linker_lists: fix... |
34 |
* _u_boot_list + _2_ + @_list + _2_ + @_entry |
ef123c525 Refactor linker-g... |
35 36 37 38 |
* * This ensures uniqueness for both input section and C variable name. * * Note that the names differ only in the first character, "." for the |
44f145fd8 linker_lists: fix... |
39 |
* section and "_" for the variable, so that the linker cannot confuse |
ef123c525 Refactor linker-g... |
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
* section and symbol names. From now on, both names will be referred * to as * * %u_boot_list_ + 2_ + @_list + _2_ + @_entry * * Entry variables need never be referred to directly. * * The naming scheme for input sections allows grouping all linker lists * into a single linker output section and grouping all entries for a * single list. * * Note the two '_2_' constant components in the names: their presence * allows putting a start and end symbols around a list, by mapping * these symbols to sections names with components "1" (before) and * "3" (after) instead of "2" (within). * Start and end symbols for a list can generally be defined as * * %u_boot_list_2_ + @_list + _1_... * %u_boot_list_2_ + @_list + _3_... * * Start and end symbols for the whole of the linker lists area can be * defined as * * %u_boot_list_1_... * %u_boot_list_3_... * * Here is an example of the sorted sections which result from a list * "array" made up of three entries : "first", "second" and "third", * iterated at least once. * * .u_boot_list_2_array_1 * .u_boot_list_2_array_2_first * .u_boot_list_2_array_2_second * .u_boot_list_2_array_2_third * .u_boot_list_2_array_3 * * If lists must be divided into sublists (e.g. for iterating only on * part of a list), one can simply give the list a name of the form * 'outer_2_inner', where 'outer' is the global list name and 'inner' * is the sub-list name. Iterators for the whole list should use the * global list name ("outer"); iterators for only a sub-list should use * the full sub-list name ("outer_2_inner"). * |
7e378b8bf Fix incorrect com... |
83 |
* Here is an example of the sections generated from a global list |
ef123c525 Refactor linker-g... |
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 |
* named "drivers", two sub-lists named "i2c" and "pci", and iterators * defined for the whole list and each sub-list: * * %u_boot_list_2_drivers_1 * %u_boot_list_2_drivers_2_i2c_1 * %u_boot_list_2_drivers_2_i2c_2_first * %u_boot_list_2_drivers_2_i2c_2_first * %u_boot_list_2_drivers_2_i2c_2_second * %u_boot_list_2_drivers_2_i2c_2_third * %u_boot_list_2_drivers_2_i2c_3 * %u_boot_list_2_drivers_2_pci_1 * %u_boot_list_2_drivers_2_pci_2_first * %u_boot_list_2_drivers_2_pci_2_second * %u_boot_list_2_drivers_2_pci_2_third * %u_boot_list_2_drivers_2_pci_3 * %u_boot_list_2_drivers_3 */ |
42ebaae3a common: Implement... |
101 |
/** |
7e378b8bf Fix incorrect com... |
102 |
* llsym() - Access a linker-generated array entry |
72538f4c3 linker_lists: Add... |
103 104 105 106 107 108 109 110 111 |
* @_type: Data type of the entry * @_name: Name of the entry * @_list: name of the list. Should contain only characters allowed * in a C variable name! */ #define llsym(_type, _name, _list) \ ((_type *)&_u_boot_list_2_##_list##_2_##_name) /** |
42ebaae3a common: Implement... |
112 113 114 |
* ll_entry_declare() - Declare linker-generated array entry * @_type: Data type of the entry * @_name: Name of the entry |
ef123c525 Refactor linker-g... |
115 116 |
* @_list: name of the list. Should contain only characters allowed * in a C variable name! |
42ebaae3a common: Implement... |
117 118 119 120 121 122 |
* * This macro declares a variable that is placed into a linker-generated * array. This is a basic building block for more advanced use of linker- * generated arrays. The user is expected to build their own macro wrapper * around this one. * |
ef123c525 Refactor linker-g... |
123 |
* A variable declared using this macro must be compile-time initialized. |
42ebaae3a common: Implement... |
124 125 |
* * Special precaution must be made when using this macro: |
42ebaae3a common: Implement... |
126 |
* |
ef123c525 Refactor linker-g... |
127 128 129 |
* 1) The _type must not contain the "static" keyword, otherwise the * entry is generated and can be iterated but is listed in the map * file and cannot be retrieved by name. |
42ebaae3a common: Implement... |
130 |
* |
ef123c525 Refactor linker-g... |
131 132 133 |
* 2) In case a section is declared that contains some array elements AND * a subsection of this section is declared and contains some elements, * it is imperative that the elements are of the same type. |
42ebaae3a common: Implement... |
134 135 |
* * 4) In case an outer section is declared that contains some array elements |
ef123c525 Refactor linker-g... |
136 |
* AND an inner subsection of this section is declared and contains some |
42ebaae3a common: Implement... |
137 138 139 140 |
* elements, then when traversing the outer section, even the elements of * the inner sections are present in the array. * * Example: |
7e378b8bf Fix incorrect com... |
141 |
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { |
42ebaae3a common: Implement... |
142 143 144 145 |
* .x = 3, * .y = 4, * }; */ |
ef123c525 Refactor linker-g... |
146 147 148 149 150 151 |
#define ll_entry_declare(_type, _name, _list) \ _type _u_boot_list_2_##_list##_2_##_name __aligned(4) \ __attribute__((unused, \ section(".u_boot_list_2_"#_list"_2_"#_name))) /** |
3fcc3af4d dm: linker_lists:... |
152 153 154 155 156 157 158 159 160 |
* ll_entry_declare_list() - Declare a list of link-generated array entries * @_type: Data type of each entry * @_name: Name of the entry * @_list: name of the list. Should contain only characters allowed * in a C variable name! * * This is like ll_entry_declare() but creates multiple entries. It should * be assigned to an array. * |
7e378b8bf Fix incorrect com... |
161 |
* ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { |
3fcc3af4d dm: linker_lists:... |
162 163 164 165 166 167 168 169 170 171 172 |
* { .x = 3, .y = 4 }, * { .x = 8, .y = 2 }, * { .x = 1, .y = 7 } * }; */ #define ll_entry_declare_list(_type, _name, _list) \ _type _u_boot_list_2_##_list##_2_##_name[] __aligned(4) \ __attribute__((unused, \ section(".u_boot_list_2_"#_list"_2_"#_name))) /** |
ef123c525 Refactor linker-g... |
173 174 175 176 177 178 179 |
* We need a 0-byte-size type for iterator symbols, and the compiler * does not allow defining objects of C type 'void'. Using an empty * struct is allowed by the compiler, but causes gcc versions 4.4 and * below to complain about aliasing. Therefore we use the next best * thing: zero-sized arrays, which are both 0-byte-size and exempt from * aliasing warnings. */ |
42ebaae3a common: Implement... |
180 181 182 183 |
/** * ll_entry_start() - Point to first entry of linker-generated array * @_type: Data type of the entry |
ef123c525 Refactor linker-g... |
184 |
* @_list: Name of the list in which this entry is placed |
42ebaae3a common: Implement... |
185 186 187 |
* * This function returns (_type *) pointer to the very first entry of a * linker-generated array placed into subsection of .u_boot_list section |
ef123c525 Refactor linker-g... |
188 189 190 191 |
* specified by _list argument. * * Since this macro defines an array start symbol, its leftmost index * must be 2 and its rightmost index must be 1. |
42ebaae3a common: Implement... |
192 193 194 195 |
* * Example: * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); */ |
ef123c525 Refactor linker-g... |
196 197 198 199 200 201 |
#define ll_entry_start(_type, _list) \ ({ \ static char start[0] __aligned(4) __attribute__((unused, \ section(".u_boot_list_2_"#_list"_1"))); \ (_type *)&start; \ }) |
42ebaae3a common: Implement... |
202 203 |
/** |
ef123c525 Refactor linker-g... |
204 |
* ll_entry_end() - Point after last entry of linker-generated array |
42ebaae3a common: Implement... |
205 |
* @_type: Data type of the entry |
ef123c525 Refactor linker-g... |
206 |
* @_list: Name of the list in which this entry is placed |
42ebaae3a common: Implement... |
207 208 |
* (with underscores instead of dots) * |
ef123c525 Refactor linker-g... |
209 210 211 212 213 214 215 216 217 218 219 220 |
* This function returns (_type *) pointer after the very last entry of * a linker-generated array placed into subsection of .u_boot_list * section specified by _list argument. * * Since this macro defines an array end symbol, its leftmost index * must be 2 and its rightmost index must be 3. * * Example: * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub); */ #define ll_entry_end(_type, _list) \ ({ \ |
7e378b8bf Fix incorrect com... |
221 |
static char end[0] __aligned(4) __attribute__((unused, \ |
ef123c525 Refactor linker-g... |
222 223 224 225 226 227 228 229 |
section(".u_boot_list_2_"#_list"_3"))); \ (_type *)&end; \ }) /** * ll_entry_count() - Return the number of elements in linker-generated array * @_type: Data type of the entry * @_list: Name of the list of which the number of elements is computed * |
42ebaae3a common: Implement... |
230 |
* This function returns the number of elements of a linker-generated array |
ef123c525 Refactor linker-g... |
231 |
* placed into subsection of .u_boot_list section specified by _list |
42ebaae3a common: Implement... |
232 233 234 235 236 237 238 239 240 241 |
* argument. The result is of an unsigned int type. * * Example: * int i; * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub); * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); * for (i = 0; i < count; i++, msc++) * printf("Entry %i, x=%i y=%i ", i, msc->x, msc->y); */ |
ef123c525 Refactor linker-g... |
242 |
#define ll_entry_count(_type, _list) \ |
42ebaae3a common: Implement... |
243 |
({ \ |
ef123c525 Refactor linker-g... |
244 245 246 |
_type *start = ll_entry_start(_type, _list); \ _type *end = ll_entry_end(_type, _list); \ unsigned int _ll_result = end - start; \ |
42ebaae3a common: Implement... |
247 248 |
_ll_result; \ }) |
42ebaae3a common: Implement... |
249 250 251 252 |
/** * ll_entry_get() - Retrieve entry from linker-generated array by name * @_type: Data type of the entry * @_name: Name of the entry |
ef123c525 Refactor linker-g... |
253 |
* @_list: Name of the list in which this entry is placed |
42ebaae3a common: Implement... |
254 |
* |
7e378b8bf Fix incorrect com... |
255 256 |
* This function returns a pointer to a particular entry in linker-generated * array identified by the subsection of u_boot_list where the entry resides |
42ebaae3a common: Implement... |
257 258 259 |
* and it's name. * * Example: |
af41d6b4c common: fixed lin... |
260 |
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { |
42ebaae3a common: Implement... |
261 262 263 264 265 266 |
* .x = 3, * .y = 4, * }; * ... * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub); */ |
ef123c525 Refactor linker-g... |
267 |
#define ll_entry_get(_type, _name, _list) \ |
42ebaae3a common: Implement... |
268 |
({ \ |
ef123c525 Refactor linker-g... |
269 270 |
extern _type _u_boot_list_2_##_list##_2_##_name; \ _type *_ll_result = \ |
7e378b8bf Fix incorrect com... |
271 |
&_u_boot_list_2_##_list##_2_##_name; \ |
42ebaae3a common: Implement... |
272 273 |
_ll_result; \ }) |
ef123c525 Refactor linker-g... |
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 |
/** * ll_start() - Point to first entry of first linker-generated array * @_type: Data type of the entry * * This function returns (_type *) pointer to the very first entry of * the very first linker-generated array. * * Since this macro defines the start of the linker-generated arrays, * its leftmost index must be 1. * * Example: * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd); */ #define ll_start(_type) \ ({ \ static char start[0] __aligned(4) __attribute__((unused, \ section(".u_boot_list_1"))); \ (_type *)&start; \ }) /** |
7e378b8bf Fix incorrect com... |
295 |
* ll_end() - Point after last entry of last linker-generated array |
ef123c525 Refactor linker-g... |
296 297 298 299 300 301 302 303 304 305 306 307 308 |
* @_type: Data type of the entry * * This function returns (_type *) pointer after the very last entry of * the very last linker-generated array. * * Since this macro defines the end of the linker-generated arrays, * its leftmost index must be 3. * * Example: * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd); */ #define ll_end(_type) \ ({ \ |
7e378b8bf Fix incorrect com... |
309 |
static char end[0] __aligned(4) __attribute__((unused, \ |
ef123c525 Refactor linker-g... |
310 311 312 313 314 |
section(".u_boot_list_3"))); \ (_type *)&end; \ }) #endif /* __ASSEMBLY__ */ |
42ebaae3a common: Implement... |
315 |
#endif /* __LINKER_LISTS_H__ */ |