142ebaae3SMarek Vasut /* 242ebaae3SMarek Vasut * include/linker_lists.h 342ebaae3SMarek Vasut * 442ebaae3SMarek Vasut * Implementation of linker-generated arrays 542ebaae3SMarek Vasut * 642ebaae3SMarek Vasut * Copyright (C) 2012 Marek Vasut <marex@denx.de> 742ebaae3SMarek Vasut * 81a459660SWolfgang Denk * SPDX-License-Identifier: GPL-2.0+ 942ebaae3SMarek Vasut */ 10ef123c52SAlbert ARIBAUD 11babb4440SMasahiro Yamada #ifndef __LINKER_LISTS_H__ 12babb4440SMasahiro Yamada #define __LINKER_LISTS_H__ 13babb4440SMasahiro Yamada 14ef123c52SAlbert ARIBAUD /* 15ef123c52SAlbert ARIBAUD * There is no use in including this from ASM files, but that happens 16ef123c52SAlbert ARIBAUD * anyway, e.g. PPC kgdb.S includes command.h which incluse us. 17ef123c52SAlbert ARIBAUD * So just don't define anything when included from ASM. 18ef123c52SAlbert ARIBAUD */ 19ef123c52SAlbert ARIBAUD 20ef123c52SAlbert ARIBAUD #if !defined(__ASSEMBLY__) 21ef123c52SAlbert ARIBAUD 22ef123c52SAlbert ARIBAUD /** 23ef123c52SAlbert ARIBAUD * A linker list is constructed by grouping together linker input 24ef123c52SAlbert ARIBAUD * sections, each containning one entry of the list. Each input section 25ef123c52SAlbert ARIBAUD * contains a constant initialized variable which holds the entry's 26ef123c52SAlbert ARIBAUD * content. Linker list input sections are constructed from the list 27ef123c52SAlbert ARIBAUD * and entry names, plus a prefix which allows grouping all lists 28ef123c52SAlbert ARIBAUD * together. Assuming _list and _entry are the list and entry names, 29ef123c52SAlbert ARIBAUD * then the corresponding input section name is 30ef123c52SAlbert ARIBAUD * 31ef123c52SAlbert ARIBAUD * _u_boot_list + _2_ + @_list + _2_ + @_entry 32ef123c52SAlbert ARIBAUD * 33ef123c52SAlbert ARIBAUD * and the C variable name is 34ef123c52SAlbert ARIBAUD * 35ef123c52SAlbert ARIBAUD * .u_boot_list_ + 2_ + @_list + _2_ + @_entry 36ef123c52SAlbert ARIBAUD * 37ef123c52SAlbert ARIBAUD * This ensures uniqueness for both input section and C variable name. 38ef123c52SAlbert ARIBAUD * 39ef123c52SAlbert ARIBAUD * Note that the names differ only in the first character, "." for the 40ef123c52SAlbert ARIBAUD * setion and "_" for the variable, so that the linker cannot confuse 41ef123c52SAlbert ARIBAUD * section and symbol names. From now on, both names will be referred 42ef123c52SAlbert ARIBAUD * to as 43ef123c52SAlbert ARIBAUD * 44ef123c52SAlbert ARIBAUD * %u_boot_list_ + 2_ + @_list + _2_ + @_entry 45ef123c52SAlbert ARIBAUD * 46ef123c52SAlbert ARIBAUD * Entry variables need never be referred to directly. 47ef123c52SAlbert ARIBAUD * 48ef123c52SAlbert ARIBAUD * The naming scheme for input sections allows grouping all linker lists 49ef123c52SAlbert ARIBAUD * into a single linker output section and grouping all entries for a 50ef123c52SAlbert ARIBAUD * single list. 51ef123c52SAlbert ARIBAUD * 52ef123c52SAlbert ARIBAUD * Note the two '_2_' constant components in the names: their presence 53ef123c52SAlbert ARIBAUD * allows putting a start and end symbols around a list, by mapping 54ef123c52SAlbert ARIBAUD * these symbols to sections names with components "1" (before) and 55ef123c52SAlbert ARIBAUD * "3" (after) instead of "2" (within). 56ef123c52SAlbert ARIBAUD * Start and end symbols for a list can generally be defined as 57ef123c52SAlbert ARIBAUD * 58ef123c52SAlbert ARIBAUD * %u_boot_list_2_ + @_list + _1_... 59ef123c52SAlbert ARIBAUD * %u_boot_list_2_ + @_list + _3_... 60ef123c52SAlbert ARIBAUD * 61ef123c52SAlbert ARIBAUD * Start and end symbols for the whole of the linker lists area can be 62ef123c52SAlbert ARIBAUD * defined as 63ef123c52SAlbert ARIBAUD * 64ef123c52SAlbert ARIBAUD * %u_boot_list_1_... 65ef123c52SAlbert ARIBAUD * %u_boot_list_3_... 66ef123c52SAlbert ARIBAUD * 67ef123c52SAlbert ARIBAUD * Here is an example of the sorted sections which result from a list 68ef123c52SAlbert ARIBAUD * "array" made up of three entries : "first", "second" and "third", 69ef123c52SAlbert ARIBAUD * iterated at least once. 70ef123c52SAlbert ARIBAUD * 71ef123c52SAlbert ARIBAUD * .u_boot_list_2_array_1 72ef123c52SAlbert ARIBAUD * .u_boot_list_2_array_2_first 73ef123c52SAlbert ARIBAUD * .u_boot_list_2_array_2_second 74ef123c52SAlbert ARIBAUD * .u_boot_list_2_array_2_third 75ef123c52SAlbert ARIBAUD * .u_boot_list_2_array_3 76ef123c52SAlbert ARIBAUD * 77ef123c52SAlbert ARIBAUD * If lists must be divided into sublists (e.g. for iterating only on 78ef123c52SAlbert ARIBAUD * part of a list), one can simply give the list a name of the form 79ef123c52SAlbert ARIBAUD * 'outer_2_inner', where 'outer' is the global list name and 'inner' 80ef123c52SAlbert ARIBAUD * is the sub-list name. Iterators for the whole list should use the 81ef123c52SAlbert ARIBAUD * global list name ("outer"); iterators for only a sub-list should use 82ef123c52SAlbert ARIBAUD * the full sub-list name ("outer_2_inner"). 83ef123c52SAlbert ARIBAUD * 84ef123c52SAlbert ARIBAUD * Here is an example of the sections generated from a global list 85ef123c52SAlbert ARIBAUD * named "drivers", two sub-lists named "i2c" and "pci", and iterators 86ef123c52SAlbert ARIBAUD * defined for the whole list and each sub-list: 87ef123c52SAlbert ARIBAUD * 88ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_1 89ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_i2c_1 90ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_i2c_2_first 91ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_i2c_2_first 92ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_i2c_2_second 93ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_i2c_2_third 94ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_i2c_3 95ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_pci_1 96ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_pci_2_first 97ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_pci_2_second 98ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_pci_2_third 99ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_2_pci_3 100ef123c52SAlbert ARIBAUD * %u_boot_list_2_drivers_3 101ef123c52SAlbert ARIBAUD */ 102ef123c52SAlbert ARIBAUD 10342ebaae3SMarek Vasut /** 10442ebaae3SMarek Vasut * ll_entry_declare() - Declare linker-generated array entry 10542ebaae3SMarek Vasut * @_type: Data type of the entry 10642ebaae3SMarek Vasut * @_name: Name of the entry 107ef123c52SAlbert ARIBAUD * @_list: name of the list. Should contain only characters allowed 108ef123c52SAlbert ARIBAUD * in a C variable name! 10942ebaae3SMarek Vasut * 11042ebaae3SMarek Vasut * This macro declares a variable that is placed into a linker-generated 11142ebaae3SMarek Vasut * array. This is a basic building block for more advanced use of linker- 11242ebaae3SMarek Vasut * generated arrays. The user is expected to build their own macro wrapper 11342ebaae3SMarek Vasut * around this one. 11442ebaae3SMarek Vasut * 115ef123c52SAlbert ARIBAUD * A variable declared using this macro must be compile-time initialized. 11642ebaae3SMarek Vasut * 11742ebaae3SMarek Vasut * Special precaution must be made when using this macro: 11842ebaae3SMarek Vasut * 119ef123c52SAlbert ARIBAUD * 1) The _type must not contain the "static" keyword, otherwise the 120ef123c52SAlbert ARIBAUD * entry is generated and can be iterated but is listed in the map 121ef123c52SAlbert ARIBAUD * file and cannot be retrieved by name. 12242ebaae3SMarek Vasut * 123ef123c52SAlbert ARIBAUD * 2) In case a section is declared that contains some array elements AND 124ef123c52SAlbert ARIBAUD * a subsection of this section is declared and contains some elements, 125ef123c52SAlbert ARIBAUD * it is imperative that the elements are of the same type. 12642ebaae3SMarek Vasut * 12742ebaae3SMarek Vasut * 4) In case an outer section is declared that contains some array elements 128ef123c52SAlbert ARIBAUD * AND an inner subsection of this section is declared and contains some 12942ebaae3SMarek Vasut * elements, then when traversing the outer section, even the elements of 13042ebaae3SMarek Vasut * the inner sections are present in the array. 13142ebaae3SMarek Vasut * 13242ebaae3SMarek Vasut * Example: 13342ebaae3SMarek Vasut * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub, cmd.sub) = { 13442ebaae3SMarek Vasut * .x = 3, 13542ebaae3SMarek Vasut * .y = 4, 13642ebaae3SMarek Vasut * }; 13742ebaae3SMarek Vasut */ 138ef123c52SAlbert ARIBAUD #define ll_entry_declare(_type, _name, _list) \ 139ef123c52SAlbert ARIBAUD _type _u_boot_list_2_##_list##_2_##_name __aligned(4) \ 140ef123c52SAlbert ARIBAUD __attribute__((unused, \ 141ef123c52SAlbert ARIBAUD section(".u_boot_list_2_"#_list"_2_"#_name))) 142ef123c52SAlbert ARIBAUD 143ef123c52SAlbert ARIBAUD /** 144ef123c52SAlbert ARIBAUD * We need a 0-byte-size type for iterator symbols, and the compiler 145ef123c52SAlbert ARIBAUD * does not allow defining objects of C type 'void'. Using an empty 146ef123c52SAlbert ARIBAUD * struct is allowed by the compiler, but causes gcc versions 4.4 and 147ef123c52SAlbert ARIBAUD * below to complain about aliasing. Therefore we use the next best 148ef123c52SAlbert ARIBAUD * thing: zero-sized arrays, which are both 0-byte-size and exempt from 149ef123c52SAlbert ARIBAUD * aliasing warnings. 150ef123c52SAlbert ARIBAUD */ 15142ebaae3SMarek Vasut 15242ebaae3SMarek Vasut /** 15342ebaae3SMarek Vasut * ll_entry_start() - Point to first entry of linker-generated array 15442ebaae3SMarek Vasut * @_type: Data type of the entry 155ef123c52SAlbert ARIBAUD * @_list: Name of the list in which this entry is placed 15642ebaae3SMarek Vasut * 15742ebaae3SMarek Vasut * This function returns (_type *) pointer to the very first entry of a 15842ebaae3SMarek Vasut * linker-generated array placed into subsection of .u_boot_list section 159ef123c52SAlbert ARIBAUD * specified by _list argument. 160ef123c52SAlbert ARIBAUD * 161ef123c52SAlbert ARIBAUD * Since this macro defines an array start symbol, its leftmost index 162ef123c52SAlbert ARIBAUD * must be 2 and its rightmost index must be 1. 16342ebaae3SMarek Vasut * 16442ebaae3SMarek Vasut * Example: 16542ebaae3SMarek Vasut * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); 16642ebaae3SMarek Vasut */ 167ef123c52SAlbert ARIBAUD #define ll_entry_start(_type, _list) \ 16842ebaae3SMarek Vasut ({ \ 169ef123c52SAlbert ARIBAUD static char start[0] __aligned(4) __attribute__((unused, \ 170ef123c52SAlbert ARIBAUD section(".u_boot_list_2_"#_list"_1"))); \ 171ef123c52SAlbert ARIBAUD (_type *)&start; \ 17242ebaae3SMarek Vasut }) 17342ebaae3SMarek Vasut 17442ebaae3SMarek Vasut /** 175ef123c52SAlbert ARIBAUD * ll_entry_end() - Point after last entry of linker-generated array 17642ebaae3SMarek Vasut * @_type: Data type of the entry 177ef123c52SAlbert ARIBAUD * @_list: Name of the list in which this entry is placed 17842ebaae3SMarek Vasut * (with underscores instead of dots) 17942ebaae3SMarek Vasut * 180ef123c52SAlbert ARIBAUD * This function returns (_type *) pointer after the very last entry of 181ef123c52SAlbert ARIBAUD * a linker-generated array placed into subsection of .u_boot_list 182ef123c52SAlbert ARIBAUD * section specified by _list argument. 183ef123c52SAlbert ARIBAUD * 184ef123c52SAlbert ARIBAUD * Since this macro defines an array end symbol, its leftmost index 185ef123c52SAlbert ARIBAUD * must be 2 and its rightmost index must be 3. 186ef123c52SAlbert ARIBAUD * 187ef123c52SAlbert ARIBAUD * Example: 188ef123c52SAlbert ARIBAUD * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub); 189ef123c52SAlbert ARIBAUD */ 190ef123c52SAlbert ARIBAUD #define ll_entry_end(_type, _list) \ 191ef123c52SAlbert ARIBAUD ({ \ 192ef123c52SAlbert ARIBAUD static char end[0] __aligned(4) __attribute__((unused, \ 193ef123c52SAlbert ARIBAUD section(".u_boot_list_2_"#_list"_3"))); \ 194ef123c52SAlbert ARIBAUD (_type *)&end; \ 195ef123c52SAlbert ARIBAUD }) 196ef123c52SAlbert ARIBAUD /** 197ef123c52SAlbert ARIBAUD * ll_entry_count() - Return the number of elements in linker-generated array 198ef123c52SAlbert ARIBAUD * @_type: Data type of the entry 199ef123c52SAlbert ARIBAUD * @_list: Name of the list of which the number of elements is computed 200ef123c52SAlbert ARIBAUD * 20142ebaae3SMarek Vasut * This function returns the number of elements of a linker-generated array 202ef123c52SAlbert ARIBAUD * placed into subsection of .u_boot_list section specified by _list 20342ebaae3SMarek Vasut * argument. The result is of an unsigned int type. 20442ebaae3SMarek Vasut * 20542ebaae3SMarek Vasut * Example: 20642ebaae3SMarek Vasut * int i; 20742ebaae3SMarek Vasut * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub); 20842ebaae3SMarek Vasut * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); 20942ebaae3SMarek Vasut * for (i = 0; i < count; i++, msc++) 21042ebaae3SMarek Vasut * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y); 21142ebaae3SMarek Vasut */ 212ef123c52SAlbert ARIBAUD #define ll_entry_count(_type, _list) \ 21342ebaae3SMarek Vasut ({ \ 214ef123c52SAlbert ARIBAUD _type *start = ll_entry_start(_type, _list); \ 215ef123c52SAlbert ARIBAUD _type *end = ll_entry_end(_type, _list); \ 216ef123c52SAlbert ARIBAUD unsigned int _ll_result = end - start; \ 21742ebaae3SMarek Vasut _ll_result; \ 21842ebaae3SMarek Vasut }) 21942ebaae3SMarek Vasut 22042ebaae3SMarek Vasut /** 22142ebaae3SMarek Vasut * ll_entry_get() - Retrieve entry from linker-generated array by name 22242ebaae3SMarek Vasut * @_type: Data type of the entry 22342ebaae3SMarek Vasut * @_name: Name of the entry 224ef123c52SAlbert ARIBAUD * @_list: Name of the list in which this entry is placed 22542ebaae3SMarek Vasut * 22642ebaae3SMarek Vasut * This function returns a pointer to a particular entry in LG-array 22742ebaae3SMarek Vasut * identified by the subsection of u_boot_list where the entry resides 22842ebaae3SMarek Vasut * and it's name. 22942ebaae3SMarek Vasut * 23042ebaae3SMarek Vasut * Example: 231*af41d6b4SMateusz Zalega * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { 23242ebaae3SMarek Vasut * .x = 3, 23342ebaae3SMarek Vasut * .y = 4, 23442ebaae3SMarek Vasut * }; 23542ebaae3SMarek Vasut * ... 23642ebaae3SMarek Vasut * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub); 23742ebaae3SMarek Vasut */ 238ef123c52SAlbert ARIBAUD #define ll_entry_get(_type, _name, _list) \ 23942ebaae3SMarek Vasut ({ \ 240ef123c52SAlbert ARIBAUD extern _type _u_boot_list_2_##_list##_2_##_name; \ 241ef123c52SAlbert ARIBAUD _type *_ll_result = \ 242ef123c52SAlbert ARIBAUD &_u_boot_list_2_##_list##_2_##_name; \ 24342ebaae3SMarek Vasut _ll_result; \ 24442ebaae3SMarek Vasut }) 24542ebaae3SMarek Vasut 246ef123c52SAlbert ARIBAUD /** 247ef123c52SAlbert ARIBAUD * ll_start() - Point to first entry of first linker-generated array 248ef123c52SAlbert ARIBAUD * @_type: Data type of the entry 249ef123c52SAlbert ARIBAUD * 250ef123c52SAlbert ARIBAUD * This function returns (_type *) pointer to the very first entry of 251ef123c52SAlbert ARIBAUD * the very first linker-generated array. 252ef123c52SAlbert ARIBAUD * 253ef123c52SAlbert ARIBAUD * Since this macro defines the start of the linker-generated arrays, 254ef123c52SAlbert ARIBAUD * its leftmost index must be 1. 255ef123c52SAlbert ARIBAUD * 256ef123c52SAlbert ARIBAUD * Example: 257ef123c52SAlbert ARIBAUD * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd); 258ef123c52SAlbert ARIBAUD */ 259ef123c52SAlbert ARIBAUD #define ll_start(_type) \ 260ef123c52SAlbert ARIBAUD ({ \ 261ef123c52SAlbert ARIBAUD static char start[0] __aligned(4) __attribute__((unused, \ 262ef123c52SAlbert ARIBAUD section(".u_boot_list_1"))); \ 263ef123c52SAlbert ARIBAUD (_type *)&start; \ 264ef123c52SAlbert ARIBAUD }) 265ef123c52SAlbert ARIBAUD 266ef123c52SAlbert ARIBAUD /** 267ef123c52SAlbert ARIBAUD * ll_entry_end() - Point after last entry of last linker-generated array 268ef123c52SAlbert ARIBAUD * @_type: Data type of the entry 269ef123c52SAlbert ARIBAUD * 270ef123c52SAlbert ARIBAUD * This function returns (_type *) pointer after the very last entry of 271ef123c52SAlbert ARIBAUD * the very last linker-generated array. 272ef123c52SAlbert ARIBAUD * 273ef123c52SAlbert ARIBAUD * Since this macro defines the end of the linker-generated arrays, 274ef123c52SAlbert ARIBAUD * its leftmost index must be 3. 275ef123c52SAlbert ARIBAUD * 276ef123c52SAlbert ARIBAUD * Example: 277ef123c52SAlbert ARIBAUD * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd); 278ef123c52SAlbert ARIBAUD */ 279ef123c52SAlbert ARIBAUD #define ll_end(_type) \ 280ef123c52SAlbert ARIBAUD ({ \ 281ef123c52SAlbert ARIBAUD static char end[0] __aligned(4) __attribute__((unused, \ 282ef123c52SAlbert ARIBAUD section(".u_boot_list_3"))); \ 283ef123c52SAlbert ARIBAUD (_type *)&end; \ 284ef123c52SAlbert ARIBAUD }) 285ef123c52SAlbert ARIBAUD 286ef123c52SAlbert ARIBAUD #endif /* __ASSEMBLY__ */ 287ef123c52SAlbert ARIBAUD 28842ebaae3SMarek Vasut #endif /* __LINKER_LISTS_H__ */ 289