linker_lists: include <linux/compiler.h>
[karo-tx-uboot.git] / include / linker_lists.h
1 /*
2  * include/linker_lists.h
3  *
4  * Implementation of linker-generated arrays
5  *
6  * Copyright (C) 2012 Marek Vasut <marex@denx.de>
7  *
8  * SPDX-License-Identifier:     GPL-2.0+
9  */
10
11 #ifndef __LINKER_LISTS_H__
12 #define __LINKER_LISTS_H__
13
14 #include <linux/compiler.h>
15
16 /*
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
26  * sections, each containning one entry of the list. Each input section
27  * 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  *
33  *   .u_boot_list_ + 2_ + @_list + _2_ + @_entry
34  *
35  * and the C variable name is
36  *
37  *   _u_boot_list + _2_ + @_list + _2_ + @_entry
38  *
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
42  * setion and "_" for the variable, so that the linker cannot confuse
43  * 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  *
86  *  Here is an example of the sections generated from a global list
87  * 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
105 /**
106  * ll_entry_declare() - Declare linker-generated array entry
107  * @_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  * This macro declares a variable that is placed into a linker-generated
113  * array. This is a basic building block for more advanced use of linker-
114  * generated arrays. The user is expected to build their own macro wrapper
115  * around this one.
116  *
117  * A variable declared using this macro must be compile-time initialized.
118  *
119  * Special precaution must be made when using this macro:
120  *
121  * 1) The _type must not contain the "static" keyword, otherwise the
122  *    entry is generated and can be iterated but is listed in the map
123  *    file and cannot be retrieved by name.
124  *
125  * 2) In case a section is declared that contains some array elements AND
126  *    a subsection of this section is declared and contains some elements,
127  *    it is imperative that the elements are of the same type.
128  *
129  * 4) In case an outer section is declared that contains some array elements
130  *    AND an inner subsection of this section is declared and contains some
131  *    elements, then when traversing the outer section, even the elements of
132  *    the inner sections are present in the array.
133  *
134  * Example:
135  * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub, cmd.sub) = {
136  *         .x = 3,
137  *         .y = 4,
138  * };
139  */
140 #define ll_entry_declare(_type, _name, _list)                           \
141         _type _u_boot_list_2_##_list##_2_##_name __aligned(4)           \
142                         __attribute__((unused,                          \
143                         section(".u_boot_list_2_"#_list"_2_"#_name)))
144
145 /**
146  * We need a 0-byte-size type for iterator symbols, and the compiler
147  * does not allow defining objects of C type 'void'. Using an empty
148  * struct is allowed by the compiler, but causes gcc versions 4.4 and
149  * below to complain about aliasing. Therefore we use the next best
150  * thing: zero-sized arrays, which are both 0-byte-size and exempt from
151  * aliasing warnings.
152  */
153
154 /**
155  * ll_entry_start() - Point to first entry of linker-generated array
156  * @_type:      Data type of the entry
157  * @_list:      Name of the list in which this entry is placed
158  *
159  * This function returns (_type *) pointer to the very first entry of a
160  * linker-generated array placed into subsection of .u_boot_list section
161  * specified by _list argument.
162  *
163  * Since this macro defines an array start symbol, its leftmost index
164  * must be 2 and its rightmost index must be 1.
165  *
166  * Example:
167  * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
168  */
169 #define ll_entry_start(_type, _list)                                    \
170 ({                                                                      \
171         static char start[0] __aligned(4) __attribute__((unused,        \
172                 section(".u_boot_list_2_"#_list"_1")));                 \
173         (_type *)&start;                                                \
174 })
175
176 /**
177  * ll_entry_end() - Point after last entry of linker-generated array
178  * @_type:      Data type of the entry
179  * @_list:      Name of the list in which this entry is placed
180  *              (with underscores instead of dots)
181  *
182  * This function returns (_type *) pointer after the very last entry of
183  * a linker-generated array placed into subsection of .u_boot_list
184  * section specified by _list argument.
185  *
186  * Since this macro defines an array end symbol, its leftmost index
187  * must be 2 and its rightmost index must be 3.
188  *
189  * Example:
190  * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
191  */
192 #define ll_entry_end(_type, _list)                                      \
193 ({                                                                      \
194         static char end[0] __aligned(4) __attribute__((unused,  \
195                 section(".u_boot_list_2_"#_list"_3")));                 \
196         (_type *)&end;                                                  \
197 })
198 /**
199  * ll_entry_count() - Return the number of elements in linker-generated array
200  * @_type:      Data type of the entry
201  * @_list:      Name of the list of which the number of elements is computed
202  *
203  * This function returns the number of elements of a linker-generated array
204  * placed into subsection of .u_boot_list section specified by _list
205  * argument. The result is of an unsigned int type.
206  *
207  * Example:
208  * int i;
209  * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
210  * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
211  * for (i = 0; i < count; i++, msc++)
212  *         printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
213  */
214 #define ll_entry_count(_type, _list)                                    \
215         ({                                                              \
216                 _type *start = ll_entry_start(_type, _list);            \
217                 _type *end = ll_entry_end(_type, _list);                \
218                 unsigned int _ll_result = end - start;                  \
219                 _ll_result;                                             \
220         })
221
222 /**
223  * ll_entry_get() - Retrieve entry from linker-generated array by name
224  * @_type:      Data type of the entry
225  * @_name:      Name of the entry
226  * @_list:      Name of the list in which this entry is placed
227  *
228  * This function returns a pointer to a particular entry in LG-array
229  * identified by the subsection of u_boot_list where the entry resides
230  * and it's name.
231  *
232  * Example:
233  * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
234  *         .x = 3,
235  *         .y = 4,
236  * };
237  * ...
238  * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
239  */
240 #define ll_entry_get(_type, _name, _list)                               \
241         ({                                                              \
242                 extern _type _u_boot_list_2_##_list##_2_##_name;        \
243                 _type *_ll_result =                                     \
244                         &_u_boot_list_2_##_list##_2_##_name;    \
245                 _ll_result;                                             \
246         })
247
248 /**
249  * ll_start() - Point to first entry of first linker-generated array
250  * @_type:      Data type of the entry
251  *
252  * This function returns (_type *) pointer to the very first entry of
253  * the very first linker-generated array.
254  *
255  * Since this macro defines the start of the linker-generated arrays,
256  * its leftmost index must be 1.
257  *
258  * Example:
259  * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
260  */
261 #define ll_start(_type)                                                 \
262 ({                                                                      \
263         static char start[0] __aligned(4) __attribute__((unused,        \
264                 section(".u_boot_list_1")));                            \
265         (_type *)&start;                                                \
266 })
267
268 /**
269  * ll_entry_end() - Point after last entry of last linker-generated array
270  * @_type:      Data type of the entry
271  *
272  * This function returns (_type *) pointer after the very last entry of
273  * the very last linker-generated array.
274  *
275  * Since this macro defines the end of the linker-generated arrays,
276  * its leftmost index must be 3.
277  *
278  * Example:
279  * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
280  */
281 #define ll_end(_type)                                                   \
282 ({                                                                      \
283         static char end[0] __aligned(4) __attribute__((unused,  \
284                 section(".u_boot_list_3")));                            \
285         (_type *)&end;                                                  \
286 })
287
288 #endif /* __ASSEMBLY__ */
289
290 #endif  /* __LINKER_LISTS_H__ */