blob: 76898ab70262dc8e033c0c74d6ce63708d236902 [file] [log] [blame]
Marek Vasut42ebaae2012-10-12 10:27:02 +00001/*
2 * include/linker_lists.h
3 *
4 * Implementation of linker-generated arrays
5 *
6 * Copyright (C) 2012 Marek Vasut <marex@denx.de>
7 *
Wolfgang Denk1a459662013-07-08 09:37:19 +02008 * SPDX-License-Identifier: GPL-2.0+
Marek Vasut42ebaae2012-10-12 10:27:02 +00009 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +000010
Masahiro Yamadababb4442014-02-05 10:52:52 +090011#ifndef __LINKER_LISTS_H__
12#define __LINKER_LISTS_H__
13
Masahiro Yamadadc7cb462014-10-07 14:48:22 +090014#include <linux/compiler.h>
15
Albert ARIBAUDef123c52013-02-25 00:59:00 +000016/*
17 * There is no use in including this from ASM files, but that happens
18 * anyway, e.g. PPC kgdb.S includes command.h which incluse us.
19 * So just don't define anything when included from ASM.
20 */
21
22#if !defined(__ASSEMBLY__)
23
24/**
25 * A linker list is constructed by grouping together linker input
Guilherme Maciel Ferreira44f145f2015-01-15 02:39:59 -020026 * sections, each containing one entry of the list. Each input section
Albert ARIBAUDef123c52013-02-25 00:59:00 +000027 * contains a constant initialized variable which holds the entry's
28 * content. Linker list input sections are constructed from the list
29 * and entry names, plus a prefix which allows grouping all lists
30 * together. Assuming _list and _entry are the list and entry names,
31 * then the corresponding input section name is
32 *
Masahiro Yamada97d5e9d2014-09-16 20:21:15 +090033 * .u_boot_list_ + 2_ + @_list + _2_ + @_entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +000034 *
35 * and the C variable name is
36 *
Masahiro Yamada97d5e9d2014-09-16 20:21:15 +090037 * _u_boot_list + _2_ + @_list + _2_ + @_entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +000038 *
39 * This ensures uniqueness for both input section and C variable name.
40 *
41 * Note that the names differ only in the first character, "." for the
Guilherme Maciel Ferreira44f145f2015-01-15 02:39:59 -020042 * section and "_" for the variable, so that the linker cannot confuse
Albert ARIBAUDef123c52013-02-25 00:59:00 +000043 * section and symbol names. From now on, both names will be referred
44 * to as
45 *
46 * %u_boot_list_ + 2_ + @_list + _2_ + @_entry
47 *
48 * Entry variables need never be referred to directly.
49 *
50 * The naming scheme for input sections allows grouping all linker lists
51 * into a single linker output section and grouping all entries for a
52 * single list.
53 *
54 * Note the two '_2_' constant components in the names: their presence
55 * allows putting a start and end symbols around a list, by mapping
56 * these symbols to sections names with components "1" (before) and
57 * "3" (after) instead of "2" (within).
58 * Start and end symbols for a list can generally be defined as
59 *
60 * %u_boot_list_2_ + @_list + _1_...
61 * %u_boot_list_2_ + @_list + _3_...
62 *
63 * Start and end symbols for the whole of the linker lists area can be
64 * defined as
65 *
66 * %u_boot_list_1_...
67 * %u_boot_list_3_...
68 *
69 * Here is an example of the sorted sections which result from a list
70 * "array" made up of three entries : "first", "second" and "third",
71 * iterated at least once.
72 *
73 * .u_boot_list_2_array_1
74 * .u_boot_list_2_array_2_first
75 * .u_boot_list_2_array_2_second
76 * .u_boot_list_2_array_2_third
77 * .u_boot_list_2_array_3
78 *
79 * If lists must be divided into sublists (e.g. for iterating only on
80 * part of a list), one can simply give the list a name of the form
81 * 'outer_2_inner', where 'outer' is the global list name and 'inner'
82 * is the sub-list name. Iterators for the whole list should use the
83 * global list name ("outer"); iterators for only a sub-list should use
84 * the full sub-list name ("outer_2_inner").
85 *
Bin Meng7e378b82015-07-19 00:20:02 +080086 * Here is an example of the sections generated from a global list
Albert ARIBAUDef123c52013-02-25 00:59:00 +000087 * named "drivers", two sub-lists named "i2c" and "pci", and iterators
88 * defined for the whole list and each sub-list:
89 *
90 * %u_boot_list_2_drivers_1
91 * %u_boot_list_2_drivers_2_i2c_1
92 * %u_boot_list_2_drivers_2_i2c_2_first
93 * %u_boot_list_2_drivers_2_i2c_2_first
94 * %u_boot_list_2_drivers_2_i2c_2_second
95 * %u_boot_list_2_drivers_2_i2c_2_third
96 * %u_boot_list_2_drivers_2_i2c_3
97 * %u_boot_list_2_drivers_2_pci_1
98 * %u_boot_list_2_drivers_2_pci_2_first
99 * %u_boot_list_2_drivers_2_pci_2_second
100 * %u_boot_list_2_drivers_2_pci_2_third
101 * %u_boot_list_2_drivers_2_pci_3
102 * %u_boot_list_2_drivers_3
103 */
104
Marek Vasut42ebaae2012-10-12 10:27:02 +0000105/**
Bin Meng7e378b82015-07-19 00:20:02 +0800106 * llsym() - Access a linker-generated array entry
Simon Glass72538f42015-03-25 12:21:49 -0600107 * @_type: Data type of the entry
108 * @_name: Name of the entry
109 * @_list: name of the list. Should contain only characters allowed
110 * in a C variable name!
111 */
112#define llsym(_type, _name, _list) \
113 ((_type *)&_u_boot_list_2_##_list##_2_##_name)
114
115/**
Marek Vasut42ebaae2012-10-12 10:27:02 +0000116 * ll_entry_declare() - Declare linker-generated array entry
117 * @_type: Data type of the entry
118 * @_name: Name of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000119 * @_list: name of the list. Should contain only characters allowed
120 * in a C variable name!
Marek Vasut42ebaae2012-10-12 10:27:02 +0000121 *
122 * This macro declares a variable that is placed into a linker-generated
123 * array. This is a basic building block for more advanced use of linker-
124 * generated arrays. The user is expected to build their own macro wrapper
125 * around this one.
126 *
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000127 * A variable declared using this macro must be compile-time initialized.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000128 *
129 * Special precaution must be made when using this macro:
Marek Vasut42ebaae2012-10-12 10:27:02 +0000130 *
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000131 * 1) The _type must not contain the "static" keyword, otherwise the
132 * entry is generated and can be iterated but is listed in the map
133 * file and cannot be retrieved by name.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000134 *
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000135 * 2) In case a section is declared that contains some array elements AND
136 * a subsection of this section is declared and contains some elements,
137 * it is imperative that the elements are of the same type.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000138 *
139 * 4) In case an outer section is declared that contains some array elements
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000140 * AND an inner subsection of this section is declared and contains some
Marek Vasut42ebaae2012-10-12 10:27:02 +0000141 * elements, then when traversing the outer section, even the elements of
142 * the inner sections are present in the array.
143 *
144 * Example:
Bin Meng7e378b82015-07-19 00:20:02 +0800145 * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
Marek Vasut42ebaae2012-10-12 10:27:02 +0000146 * .x = 3,
147 * .y = 4,
148 * };
149 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000150#define ll_entry_declare(_type, _name, _list) \
151 _type _u_boot_list_2_##_list##_2_##_name __aligned(4) \
152 __attribute__((unused, \
153 section(".u_boot_list_2_"#_list"_2_"#_name)))
154
155/**
Simon Glass3fcc3af2014-10-01 19:57:20 -0600156 * ll_entry_declare_list() - Declare a list of link-generated array entries
157 * @_type: Data type of each entry
158 * @_name: Name of the entry
159 * @_list: name of the list. Should contain only characters allowed
160 * in a C variable name!
161 *
162 * This is like ll_entry_declare() but creates multiple entries. It should
163 * be assigned to an array.
164 *
Bin Meng7e378b82015-07-19 00:20:02 +0800165 * ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
Simon Glass3fcc3af2014-10-01 19:57:20 -0600166 * { .x = 3, .y = 4 },
167 * { .x = 8, .y = 2 },
168 * { .x = 1, .y = 7 }
169 * };
170 */
171#define ll_entry_declare_list(_type, _name, _list) \
172 _type _u_boot_list_2_##_list##_2_##_name[] __aligned(4) \
173 __attribute__((unused, \
174 section(".u_boot_list_2_"#_list"_2_"#_name)))
175
176/**
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000177 * We need a 0-byte-size type for iterator symbols, and the compiler
178 * does not allow defining objects of C type 'void'. Using an empty
179 * struct is allowed by the compiler, but causes gcc versions 4.4 and
180 * below to complain about aliasing. Therefore we use the next best
181 * thing: zero-sized arrays, which are both 0-byte-size and exempt from
182 * aliasing warnings.
183 */
Marek Vasut42ebaae2012-10-12 10:27:02 +0000184
185/**
186 * ll_entry_start() - Point to first entry of linker-generated array
187 * @_type: Data type of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000188 * @_list: Name of the list in which this entry is placed
Marek Vasut42ebaae2012-10-12 10:27:02 +0000189 *
190 * This function returns (_type *) pointer to the very first entry of a
191 * linker-generated array placed into subsection of .u_boot_list section
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000192 * specified by _list argument.
193 *
194 * Since this macro defines an array start symbol, its leftmost index
195 * must be 2 and its rightmost index must be 1.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000196 *
197 * Example:
198 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
199 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000200#define ll_entry_start(_type, _list) \
201({ \
202 static char start[0] __aligned(4) __attribute__((unused, \
203 section(".u_boot_list_2_"#_list"_1"))); \
204 (_type *)&start; \
205})
Marek Vasut42ebaae2012-10-12 10:27:02 +0000206
207/**
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000208 * ll_entry_end() - Point after last entry of linker-generated array
209 * @_type: Data type of the entry
210 * @_list: Name of the list in which this entry is placed
211 * (with underscores instead of dots)
212 *
213 * This function returns (_type *) pointer after the very last entry of
214 * a linker-generated array placed into subsection of .u_boot_list
215 * section specified by _list argument.
216 *
217 * Since this macro defines an array end symbol, its leftmost index
218 * must be 2 and its rightmost index must be 3.
219 *
220 * Example:
221 * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
222 */
223#define ll_entry_end(_type, _list) \
224({ \
Bin Meng7e378b82015-07-19 00:20:02 +0800225 static char end[0] __aligned(4) __attribute__((unused, \
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000226 section(".u_boot_list_2_"#_list"_3"))); \
227 (_type *)&end; \
228})
229/**
Marek Vasut42ebaae2012-10-12 10:27:02 +0000230 * ll_entry_count() - Return the number of elements in linker-generated array
231 * @_type: Data type of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000232 * @_list: Name of the list of which the number of elements is computed
Marek Vasut42ebaae2012-10-12 10:27:02 +0000233 *
234 * This function returns the number of elements of a linker-generated array
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000235 * placed into subsection of .u_boot_list section specified by _list
Marek Vasut42ebaae2012-10-12 10:27:02 +0000236 * argument. The result is of an unsigned int type.
237 *
238 * Example:
239 * int i;
240 * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
241 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
242 * for (i = 0; i < count; i++, msc++)
243 * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
244 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000245#define ll_entry_count(_type, _list) \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000246 ({ \
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000247 _type *start = ll_entry_start(_type, _list); \
248 _type *end = ll_entry_end(_type, _list); \
249 unsigned int _ll_result = end - start; \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000250 _ll_result; \
251 })
252
Marek Vasut42ebaae2012-10-12 10:27:02 +0000253/**
254 * ll_entry_get() - Retrieve entry from linker-generated array by name
255 * @_type: Data type of the entry
256 * @_name: Name of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000257 * @_list: Name of the list in which this entry is placed
Marek Vasut42ebaae2012-10-12 10:27:02 +0000258 *
Bin Meng7e378b82015-07-19 00:20:02 +0800259 * This function returns a pointer to a particular entry in linker-generated
260 * array identified by the subsection of u_boot_list where the entry resides
Marek Vasut42ebaae2012-10-12 10:27:02 +0000261 * and it's name.
262 *
263 * Example:
Mateusz Zalegaaf41d6b2014-04-29 20:14:22 +0200264 * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
Marek Vasut42ebaae2012-10-12 10:27:02 +0000265 * .x = 3,
266 * .y = 4,
267 * };
268 * ...
269 * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
270 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000271#define ll_entry_get(_type, _name, _list) \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000272 ({ \
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000273 extern _type _u_boot_list_2_##_list##_2_##_name; \
274 _type *_ll_result = \
Bin Meng7e378b82015-07-19 00:20:02 +0800275 &_u_boot_list_2_##_list##_2_##_name; \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000276 _ll_result; \
277 })
278
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000279/**
280 * ll_start() - Point to first entry of first linker-generated array
281 * @_type: Data type of the entry
282 *
283 * This function returns (_type *) pointer to the very first entry of
284 * the very first linker-generated array.
285 *
286 * Since this macro defines the start of the linker-generated arrays,
287 * its leftmost index must be 1.
288 *
289 * Example:
290 * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
291 */
292#define ll_start(_type) \
293({ \
294 static char start[0] __aligned(4) __attribute__((unused, \
295 section(".u_boot_list_1"))); \
296 (_type *)&start; \
297})
298
299/**
Bin Meng7e378b82015-07-19 00:20:02 +0800300 * ll_end() - Point after last entry of last linker-generated array
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000301 * @_type: Data type of the entry
302 *
303 * This function returns (_type *) pointer after the very last entry of
304 * the very last linker-generated array.
305 *
306 * Since this macro defines the end of the linker-generated arrays,
307 * its leftmost index must be 3.
308 *
309 * Example:
310 * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
311 */
312#define ll_end(_type) \
313({ \
Bin Meng7e378b82015-07-19 00:20:02 +0800314 static char end[0] __aligned(4) __attribute__((unused, \
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000315 section(".u_boot_list_3"))); \
316 (_type *)&end; \
317})
318
319#endif /* __ASSEMBLY__ */
320
Marek Vasut42ebaae2012-10-12 10:27:02 +0000321#endif /* __LINKER_LISTS_H__ */