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