1.. SPDX-License-Identifier: GPL-2.0+
2
3Linker-Generated Arrays
4=======================
5
6A linker list is constructed by grouping together linker input
7sections, each containing one entry of the list. Each input section
8contains a constant initialized variable which holds the entry's
9content. Linker list input sections are constructed from the list
10and entry names, plus a prefix which allows grouping all lists
11together. Assuming _list and _entry are the list and entry names,
12then the corresponding input section name is
13
14::
15
16  .u_boot_list_ + 2_ + @_list + _2_ + @_entry
17
18and the C variable name is
19
20::
21
22  _u_boot_list + _2_ + @_list + _2_ + @_entry
23
24This ensures uniqueness for both input section and C variable name.
25
26Note that the names differ only in the first character, "." for the
27section and "_" for the variable, so that the linker cannot confuse
28section and symbol names. From now on, both names will be referred
29to as
30
31::
32
33  %u_boot_list_ + 2_ + @_list + _2_ + @_entry
34
35Entry variables need never be referred to directly.
36
37The naming scheme for input sections allows grouping all linker lists
38into a single linker output section and grouping all entries for a
39single list.
40
41Note the two '_2_' constant components in the names: their presence
42allows putting a start and end symbols around a list, by mapping
43these symbols to sections names with components "1" (before) and
44"3" (after) instead of "2" (within).
45Start and end symbols for a list can generally be defined as
46
47::
48
49  %u_boot_list_2_ + @_list + _1_...
50  %u_boot_list_2_ + @_list + _3_...
51
52Start and end symbols for the whole of the linker lists area can be
53defined as
54
55::
56
57  %u_boot_list_1_...
58  %u_boot_list_3_...
59
60Here is an example of the sorted sections which result from a list
61"array" made up of three entries : "first", "second" and "third",
62iterated at least once.
63
64::
65
66  .u_boot_list_2_array_1
67  .u_boot_list_2_array_2_first
68  .u_boot_list_2_array_2_second
69  .u_boot_list_2_array_2_third
70  .u_boot_list_2_array_3
71
72If lists must be divided into sublists (e.g. for iterating only on
73part of a list), one can simply give the list a name of the form
74'outer_2_inner', where 'outer' is the global list name and 'inner'
75is the sub-list name. Iterators for the whole list should use the
76global list name ("outer"); iterators for only a sub-list should use
77the full sub-list name ("outer_2_inner").
78
79Here is an example of the sections generated from a global list
80named "drivers", two sub-lists named "i2c" and "pci", and iterators
81defined for the whole list and each sub-list:
82
83::
84
85  %u_boot_list_2_drivers_1
86  %u_boot_list_2_drivers_2_i2c_1
87  %u_boot_list_2_drivers_2_i2c_2_first
88  %u_boot_list_2_drivers_2_i2c_2_first
89  %u_boot_list_2_drivers_2_i2c_2_second
90  %u_boot_list_2_drivers_2_i2c_2_third
91  %u_boot_list_2_drivers_2_i2c_3
92  %u_boot_list_2_drivers_2_pci_1
93  %u_boot_list_2_drivers_2_pci_2_first
94  %u_boot_list_2_drivers_2_pci_2_second
95  %u_boot_list_2_drivers_2_pci_2_third
96  %u_boot_list_2_drivers_2_pci_3
97  %u_boot_list_2_drivers_3
98
99.. kernel-doc:: include/linker_lists.h
100   :internal:
101