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
99Alignment issues
100----------------
101
102The linker script uses alphabetic sorting to group the different linker
103lists together. Each group has its own struct and potentially its own
104alignment. But when the linker packs the structs together it cannot ensure
105that a linker list starts on the expected alignment boundary.
106
107For example, if the first list has a struct size of 8 and we place 3 of
108them in the image, that means that the next struct will start at offset
1090x18 from the start of the linker_list section. If the next struct has
110a size of 16 then it will start at an 8-byte aligned offset, but not a
11116-byte aligned offset.
112
113With sandbox on x86_64, a reference to a linker list item using
114ll_entry_get() can force alignment of that particular linker_list item,
115if it is in the same file as the linker_list item is declared.
116
117Consider this example, where struct driver is 0x80 bytes::
118
119    ll_entry_declare(struct driver, fred, driver)
120
121    ...
122
123    void *p = ll_entry_get(struct driver, fred, driver)
124
125If these two lines of code are in the same file, then the entry is forced
126to be aligned at the 'struct driver' alignment, which is 16 bytes. If the
127second line of code is in a different file, then no action is taken, since
128the compiler cannot update the alignment of the linker_list item.
129
130In the first case, an 8-byte 'fill' region is added::
131
132   .u_boot_list_2_driver_2_testbus_drv
133               0x0000000000270018       0x80 test/built-in.o
134               0x0000000000270018                _u_boot_list_2_driver_2_testbus_drv
135   .u_boot_list_2_driver_2_testfdt1_drv
136               0x0000000000270098       0x80 test/built-in.o
137               0x0000000000270098                _u_boot_list_2_driver_2_testfdt1_drv
138   *fill*         0x0000000000270118        0x8
139   .u_boot_list_2_driver_2_testfdt_drv
140               0x0000000000270120       0x80 test/built-in.o
141               0x0000000000270120                _u_boot_list_2_driver_2_testfdt_drv
142   .u_boot_list_2_driver_2_testprobe_drv
143               0x00000000002701a0       0x80 test/built-in.o
144               0x00000000002701a0                _u_boot_list_2_driver_2_testprobe_drv
145
146With this, the linker_list no-longer works since items after testfdt1_drv
147are not at the expected address.
148
149Ideally we would have a way to tell gcc not to align structs in this way.
150It is not clear how we could do this, and in any case it would require us
151to adjust every struct used by the linker_list feature.
152
153The simplest fix seems to be to force each separate linker_list to start
154on the largest possible boundary that can be required by the compiler. This
155is the purpose of CONFIG_LINKER_LIST_ALIGN
156
157
158.. kernel-doc:: include/linker_lists.h
159   :internal:
160