diff options
Diffstat (limited to 'include/linker_lists.h')
| -rw-r--r-- | include/linker_lists.h | 164 |
1 files changed, 53 insertions, 111 deletions
diff --git a/include/linker_lists.h b/include/linker_lists.h index e0759d446f4..d775d041e04 100644 --- a/include/linker_lists.h +++ b/include/linker_lists.h @@ -20,87 +20,6 @@ #if !defined(__ASSEMBLY__) /** - * A linker list is constructed by grouping together linker input - * sections, each containing one entry of the list. Each input section - * contains a constant initialized variable which holds the entry's - * content. Linker list input sections are constructed from the list - * and entry names, plus a prefix which allows grouping all lists - * together. Assuming _list and _entry are the list and entry names, - * then the corresponding input section name is - * - * .u_boot_list_ + 2_ + @_list + _2_ + @_entry - * - * and the C variable name is - * - * _u_boot_list + _2_ + @_list + _2_ + @_entry - * - * This ensures uniqueness for both input section and C variable name. - * - * Note that the names differ only in the first character, "." for the - * section and "_" for the variable, so that the linker cannot confuse - * section and symbol names. From now on, both names will be referred - * to as - * - * %u_boot_list_ + 2_ + @_list + _2_ + @_entry - * - * Entry variables need never be referred to directly. - * - * The naming scheme for input sections allows grouping all linker lists - * into a single linker output section and grouping all entries for a - * single list. - * - * Note the two '_2_' constant components in the names: their presence - * allows putting a start and end symbols around a list, by mapping - * these symbols to sections names with components "1" (before) and - * "3" (after) instead of "2" (within). - * Start and end symbols for a list can generally be defined as - * - * %u_boot_list_2_ + @_list + _1_... - * %u_boot_list_2_ + @_list + _3_... - * - * Start and end symbols for the whole of the linker lists area can be - * defined as - * - * %u_boot_list_1_... - * %u_boot_list_3_... - * - * Here is an example of the sorted sections which result from a list - * "array" made up of three entries : "first", "second" and "third", - * iterated at least once. - * - * .u_boot_list_2_array_1 - * .u_boot_list_2_array_2_first - * .u_boot_list_2_array_2_second - * .u_boot_list_2_array_2_third - * .u_boot_list_2_array_3 - * - * If lists must be divided into sublists (e.g. for iterating only on - * part of a list), one can simply give the list a name of the form - * 'outer_2_inner', where 'outer' is the global list name and 'inner' - * is the sub-list name. Iterators for the whole list should use the - * global list name ("outer"); iterators for only a sub-list should use - * the full sub-list name ("outer_2_inner"). - * - * Here is an example of the sections generated from a global list - * named "drivers", two sub-lists named "i2c" and "pci", and iterators - * defined for the whole list and each sub-list: - * - * %u_boot_list_2_drivers_1 - * %u_boot_list_2_drivers_2_i2c_1 - * %u_boot_list_2_drivers_2_i2c_2_first - * %u_boot_list_2_drivers_2_i2c_2_first - * %u_boot_list_2_drivers_2_i2c_2_second - * %u_boot_list_2_drivers_2_i2c_2_third - * %u_boot_list_2_drivers_2_i2c_3 - * %u_boot_list_2_drivers_2_pci_1 - * %u_boot_list_2_drivers_2_pci_2_first - * %u_boot_list_2_drivers_2_pci_2_second - * %u_boot_list_2_drivers_2_pci_2_third - * %u_boot_list_2_drivers_2_pci_3 - * %u_boot_list_2_drivers_3 - */ - -/** * llsym() - Access a linker-generated array entry * @_type: Data type of the entry * @_name: Name of the entry @@ -134,16 +53,19 @@ * a subsection of this section is declared and contains some elements, * it is imperative that the elements are of the same type. * - * 4) In case an outer section is declared that contains some array elements + * 3) In case an outer section is declared that contains some array elements * AND an inner subsection of this section is declared and contains some * elements, then when traversing the outer section, even the elements of * the inner sections are present in the array. * * Example: - * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { - * .x = 3, - * .y = 4, - * }; + * + * :: + * + * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { + * .x = 3, + * .y = 4, + * }; */ #define ll_entry_declare(_type, _name, _list) \ _type _u_boot_list_2_##_list##_2_##_name __aligned(4) \ @@ -160,18 +82,20 @@ * This is like ll_entry_declare() but creates multiple entries. It should * be assigned to an array. * - * ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { - * { .x = 3, .y = 4 }, - * { .x = 8, .y = 2 }, - * { .x = 1, .y = 7 } - * }; + * :: + * + * ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { + * { .x = 3, .y = 4 }, + * { .x = 8, .y = 2 }, + * { .x = 1, .y = 7 } + * }; */ #define ll_entry_declare_list(_type, _name, _list) \ _type _u_boot_list_2_##_list##_2_##_name[] __aligned(4) \ __attribute__((unused, \ section(".u_boot_list_2_"#_list"_2_"#_name))) -/** +/* * We need a 0-byte-size type for iterator symbols, and the compiler * does not allow defining objects of C type 'void'. Using an empty * struct is allowed by the compiler, but causes gcc versions 4.4 and @@ -185,7 +109,7 @@ * @_type: Data type of the entry * @_list: Name of the list in which this entry is placed * - * This function returns (_type *) pointer to the very first entry of a + * This function returns ``(_type *)`` pointer to the very first entry of a * linker-generated array placed into subsection of .u_boot_list section * specified by _list argument. * @@ -193,7 +117,10 @@ * must be 2 and its rightmost index must be 1. * * Example: - * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); + * + * :: + * + * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); */ #define ll_entry_start(_type, _list) \ ({ \ @@ -208,7 +135,7 @@ * @_list: Name of the list in which this entry is placed * (with underscores instead of dots) * - * This function returns (_type *) pointer after the very last entry of + * This function returns ``(_type *)`` pointer after the very last entry of * a linker-generated array placed into subsection of .u_boot_list * section specified by _list argument. * @@ -216,7 +143,10 @@ * must be 2 and its rightmost index must be 3. * * Example: - * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub); + * + * :: + * + * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub); */ #define ll_entry_end(_type, _list) \ ({ \ @@ -234,11 +164,14 @@ * argument. The result is of an unsigned int type. * * Example: - * int i; - * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub); - * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); - * for (i = 0; i < count; i++, msc++) - * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y); + * + * :: + * + * int i; + * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub); + * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); + * for (i = 0; i < count; i++, msc++) + * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y); */ #define ll_entry_count(_type, _list) \ ({ \ @@ -259,12 +192,15 @@ * and it's name. * * Example: - * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { - * .x = 3, - * .y = 4, - * }; - * ... - * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub); + * + * :: + * + * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = { + * .x = 3, + * .y = 4, + * }; + * ... + * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub); */ #define ll_entry_get(_type, _name, _list) \ ({ \ @@ -278,14 +214,17 @@ * ll_start() - Point to first entry of first linker-generated array * @_type: Data type of the entry * - * This function returns (_type *) pointer to the very first entry of + * This function returns ``(_type *)`` pointer to the very first entry of * the very first linker-generated array. * * Since this macro defines the start of the linker-generated arrays, * its leftmost index must be 1. * * Example: - * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd); + * + * :: + * + * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd); */ #define ll_start(_type) \ ({ \ @@ -298,14 +237,17 @@ * ll_end() - Point after last entry of last linker-generated array * @_type: Data type of the entry * - * This function returns (_type *) pointer after the very last entry of + * This function returns ``(_type *)`` pointer after the very last entry of * the very last linker-generated array. * * Since this macro defines the end of the linker-generated arrays, * its leftmost index must be 3. * * Example: - * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd); + * + * :: + * + * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd); */ #define ll_end(_type) \ ({ \ |