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 * 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 */ 16 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 106 #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 113 * @_list: name of the list. Should contain only characters allowed 114 * in a C variable name! 115 * 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 * 121 * A variable declared using this macro must be compile-time initialized. 122 * 123 * Special precaution must be made when using this macro: 124 * 125 * 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. 128 * 129 * 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. 132 * 133 * 4) In case an outer section is declared that contains some array elements 134 * AND an inner subsection of this section is declared and contains some 135 * 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 */ 144 #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 */ 157 158 /** 159 * ll_entry_start() - Point to first entry of linker-generated array 160 * @_type: Data type of the entry 161 * @_list: Name of the list in which this entry is placed 162 * 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 165 * 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. 169 * 170 * Example: 171 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); 172 */ 173 #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 }) 179 180 /** 181 * 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 /** 203 * ll_entry_count() - Return the number of elements in linker-generated array 204 * @_type: Data type of the entry 205 * @_list: Name of the list of which the number of elements is computed 206 * 207 * This function returns the number of elements of a linker-generated array 208 * placed into subsection of .u_boot_list section specified by _list 209 * 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 */ 218 #define ll_entry_count(_type, _list) \ 219 ({ \ 220 _type *start = ll_entry_start(_type, _list); \ 221 _type *end = ll_entry_end(_type, _list); \ 222 unsigned int _ll_result = end - start; \ 223 _ll_result; \ 224 }) 225 226 /** 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 230 * @_list: Name of the list in which this entry is placed 231 * 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 */ 244 #define ll_entry_get(_type, _name, _list) \ 245 ({ \ 246 extern _type _u_boot_list_2_##_list##_2_##_name; \ 247 _type *_ll_result = \ 248 &_u_boot_list_2_##_list##_2_##_name; \ 249 _ll_result; \ 250 }) 251 252 /** 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 294 #endif /* __LINKER_LISTS_H__ */ 295