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