blob: 6c28bf961b0b96dc5d067a84d5c315dc0ef4bef0 [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 *
8 * See file CREDITS for list of people who contributed to this
9 * project.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License as
13 * published by the Free Software Foundation; either version 2 of
14 * the License, or (at your option) any later version.
15 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +000016
17/*
18 * There is no use in including this from ASM files, but that happens
19 * anyway, e.g. PPC kgdb.S includes command.h which incluse us.
20 * So just don't define anything when included from ASM.
21 */
22
23#if !defined(__ASSEMBLY__)
24
25/**
26 * A linker list is constructed by grouping together linker input
27 * sections, each containning one entry of the list. Each input section
28 * contains a constant initialized variable which holds the entry's
29 * content. Linker list input sections are constructed from the list
30 * and entry names, plus a prefix which allows grouping all lists
31 * together. Assuming _list and _entry are the list and entry names,
32 * then the corresponding input section name is
33 *
34 * _u_boot_list + _2_ + @_list + _2_ + @_entry
35 *
36 * and the C variable name is
37 *
38 * .u_boot_list_ + 2_ + @_list + _2_ + @_entry
39 *
40 * This ensures uniqueness for both input section and C variable name.
41 *
42 * Note that the names differ only in the first character, "." for the
43 * setion and "_" for the variable, so that the linker cannot confuse
44 * section and symbol names. From now on, both names will be referred
45 * to as
46 *
47 * %u_boot_list_ + 2_ + @_list + _2_ + @_entry
48 *
49 * Entry variables need never be referred to directly.
50 *
51 * The naming scheme for input sections allows grouping all linker lists
52 * into a single linker output section and grouping all entries for a
53 * single list.
54 *
55 * Note the two '_2_' constant components in the names: their presence
56 * allows putting a start and end symbols around a list, by mapping
57 * these symbols to sections names with components "1" (before) and
58 * "3" (after) instead of "2" (within).
59 * Start and end symbols for a list can generally be defined as
60 *
61 * %u_boot_list_2_ + @_list + _1_...
62 * %u_boot_list_2_ + @_list + _3_...
63 *
64 * Start and end symbols for the whole of the linker lists area can be
65 * defined as
66 *
67 * %u_boot_list_1_...
68 * %u_boot_list_3_...
69 *
70 * Here is an example of the sorted sections which result from a list
71 * "array" made up of three entries : "first", "second" and "third",
72 * iterated at least once.
73 *
74 * .u_boot_list_2_array_1
75 * .u_boot_list_2_array_2_first
76 * .u_boot_list_2_array_2_second
77 * .u_boot_list_2_array_2_third
78 * .u_boot_list_2_array_3
79 *
80 * If lists must be divided into sublists (e.g. for iterating only on
81 * part of a list), one can simply give the list a name of the form
82 * 'outer_2_inner', where 'outer' is the global list name and 'inner'
83 * is the sub-list name. Iterators for the whole list should use the
84 * global list name ("outer"); iterators for only a sub-list should use
85 * the full sub-list name ("outer_2_inner").
86 *
87 * Here is an example of the sections generated from a global list
88 * named "drivers", two sub-lists named "i2c" and "pci", and iterators
89 * defined for the whole list and each sub-list:
90 *
91 * %u_boot_list_2_drivers_1
92 * %u_boot_list_2_drivers_2_i2c_1
93 * %u_boot_list_2_drivers_2_i2c_2_first
94 * %u_boot_list_2_drivers_2_i2c_2_first
95 * %u_boot_list_2_drivers_2_i2c_2_second
96 * %u_boot_list_2_drivers_2_i2c_2_third
97 * %u_boot_list_2_drivers_2_i2c_3
98 * %u_boot_list_2_drivers_2_pci_1
99 * %u_boot_list_2_drivers_2_pci_2_first
100 * %u_boot_list_2_drivers_2_pci_2_second
101 * %u_boot_list_2_drivers_2_pci_2_third
102 * %u_boot_list_2_drivers_2_pci_3
103 * %u_boot_list_2_drivers_3
104 */
105
Marek Vasut42ebaae2012-10-12 10:27:02 +0000106#ifndef __LINKER_LISTS_H__
107#define __LINKER_LISTS_H__
108
109/**
110 * ll_entry_declare() - Declare linker-generated array entry
111 * @_type: Data type of the entry
112 * @_name: Name of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000113 * @_list: name of the list. Should contain only characters allowed
114 * in a C variable name!
Marek Vasut42ebaae2012-10-12 10:27:02 +0000115 *
116 * This macro declares a variable that is placed into a linker-generated
117 * array. This is a basic building block for more advanced use of linker-
118 * generated arrays. The user is expected to build their own macro wrapper
119 * around this one.
120 *
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000121 * A variable declared using this macro must be compile-time initialized.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000122 *
123 * Special precaution must be made when using this macro:
Marek Vasut42ebaae2012-10-12 10:27:02 +0000124 *
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000125 * 1) The _type must not contain the "static" keyword, otherwise the
126 * entry is generated and can be iterated but is listed in the map
127 * file and cannot be retrieved by name.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000128 *
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000129 * 2) In case a section is declared that contains some array elements AND
130 * a subsection of this section is declared and contains some elements,
131 * it is imperative that the elements are of the same type.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000132 *
133 * 4) In case an outer section is declared that contains some array elements
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000134 * AND an inner subsection of this section is declared and contains some
Marek Vasut42ebaae2012-10-12 10:27:02 +0000135 * elements, then when traversing the outer section, even the elements of
136 * the inner sections are present in the array.
137 *
138 * Example:
139 * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub, cmd.sub) = {
140 * .x = 3,
141 * .y = 4,
142 * };
143 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000144#define ll_entry_declare(_type, _name, _list) \
145 _type _u_boot_list_2_##_list##_2_##_name __aligned(4) \
146 __attribute__((unused, \
147 section(".u_boot_list_2_"#_list"_2_"#_name)))
148
149/**
150 * We need a 0-byte-size type for iterator symbols, and the compiler
151 * does not allow defining objects of C type 'void'. Using an empty
152 * struct is allowed by the compiler, but causes gcc versions 4.4 and
153 * below to complain about aliasing. Therefore we use the next best
154 * thing: zero-sized arrays, which are both 0-byte-size and exempt from
155 * aliasing warnings.
156 */
Marek Vasut42ebaae2012-10-12 10:27:02 +0000157
158/**
159 * ll_entry_start() - Point to first entry of linker-generated array
160 * @_type: Data type of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000161 * @_list: Name of the list in which this entry is placed
Marek Vasut42ebaae2012-10-12 10:27:02 +0000162 *
163 * This function returns (_type *) pointer to the very first entry of a
164 * linker-generated array placed into subsection of .u_boot_list section
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000165 * specified by _list argument.
166 *
167 * Since this macro defines an array start symbol, its leftmost index
168 * must be 2 and its rightmost index must be 1.
Marek Vasut42ebaae2012-10-12 10:27:02 +0000169 *
170 * Example:
171 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
172 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000173#define ll_entry_start(_type, _list) \
174({ \
175 static char start[0] __aligned(4) __attribute__((unused, \
176 section(".u_boot_list_2_"#_list"_1"))); \
177 (_type *)&start; \
178})
Marek Vasut42ebaae2012-10-12 10:27:02 +0000179
180/**
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000181 * ll_entry_end() - Point after last entry of linker-generated array
182 * @_type: Data type of the entry
183 * @_list: Name of the list in which this entry is placed
184 * (with underscores instead of dots)
185 *
186 * This function returns (_type *) pointer after the very last entry of
187 * a linker-generated array placed into subsection of .u_boot_list
188 * section specified by _list argument.
189 *
190 * Since this macro defines an array end symbol, its leftmost index
191 * must be 2 and its rightmost index must be 3.
192 *
193 * Example:
194 * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
195 */
196#define ll_entry_end(_type, _list) \
197({ \
198 static char end[0] __aligned(4) __attribute__((unused, \
199 section(".u_boot_list_2_"#_list"_3"))); \
200 (_type *)&end; \
201})
202/**
Marek Vasut42ebaae2012-10-12 10:27:02 +0000203 * ll_entry_count() - Return the number of elements in linker-generated array
204 * @_type: Data type of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000205 * @_list: Name of the list of which the number of elements is computed
Marek Vasut42ebaae2012-10-12 10:27:02 +0000206 *
207 * This function returns the number of elements of a linker-generated array
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000208 * placed into subsection of .u_boot_list section specified by _list
Marek Vasut42ebaae2012-10-12 10:27:02 +0000209 * argument. The result is of an unsigned int type.
210 *
211 * Example:
212 * int i;
213 * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
214 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
215 * for (i = 0; i < count; i++, msc++)
216 * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
217 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000218#define ll_entry_count(_type, _list) \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000219 ({ \
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000220 _type *start = ll_entry_start(_type, _list); \
221 _type *end = ll_entry_end(_type, _list); \
222 unsigned int _ll_result = end - start; \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000223 _ll_result; \
224 })
225
Marek Vasut42ebaae2012-10-12 10:27:02 +0000226/**
227 * ll_entry_get() - Retrieve entry from linker-generated array by name
228 * @_type: Data type of the entry
229 * @_name: Name of the entry
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000230 * @_list: Name of the list in which this entry is placed
Marek Vasut42ebaae2012-10-12 10:27:02 +0000231 *
232 * This function returns a pointer to a particular entry in LG-array
233 * identified by the subsection of u_boot_list where the entry resides
234 * and it's name.
235 *
236 * Example:
237 * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub, cmd.sub) = {
238 * .x = 3,
239 * .y = 4,
240 * };
241 * ...
242 * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
243 */
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000244#define ll_entry_get(_type, _name, _list) \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000245 ({ \
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000246 extern _type _u_boot_list_2_##_list##_2_##_name; \
247 _type *_ll_result = \
248 &_u_boot_list_2_##_list##_2_##_name; \
Marek Vasut42ebaae2012-10-12 10:27:02 +0000249 _ll_result; \
250 })
251
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000252/**
253 * ll_start() - Point to first entry of first linker-generated array
254 * @_type: Data type of the entry
255 *
256 * This function returns (_type *) pointer to the very first entry of
257 * the very first linker-generated array.
258 *
259 * Since this macro defines the start of the linker-generated arrays,
260 * its leftmost index must be 1.
261 *
262 * Example:
263 * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
264 */
265#define ll_start(_type) \
266({ \
267 static char start[0] __aligned(4) __attribute__((unused, \
268 section(".u_boot_list_1"))); \
269 (_type *)&start; \
270})
271
272/**
273 * ll_entry_end() - Point after last entry of last linker-generated array
274 * @_type: Data type of the entry
275 *
276 * This function returns (_type *) pointer after the very last entry of
277 * the very last linker-generated array.
278 *
279 * Since this macro defines the end of the linker-generated arrays,
280 * its leftmost index must be 3.
281 *
282 * Example:
283 * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
284 */
285#define ll_end(_type) \
286({ \
287 static char end[0] __aligned(4) __attribute__((unused, \
288 section(".u_boot_list_3"))); \
289 (_type *)&end; \
290})
291
292#endif /* __ASSEMBLY__ */
293
Marek Vasut42ebaae2012-10-12 10:27:02 +0000294#endif /* __LINKER_LISTS_H__ */