diff options
Diffstat (limited to 'roms/u-boot/doc/api/linker_lists.rst')
| -rw-r--r-- | roms/u-boot/doc/api/linker_lists.rst | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/roms/u-boot/doc/api/linker_lists.rst b/roms/u-boot/doc/api/linker_lists.rst new file mode 100644 index 000000000..7063fdc83 --- /dev/null +++ b/roms/u-boot/doc/api/linker_lists.rst @@ -0,0 +1,159 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Linker-Generated Arrays +======================= + +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 + +Alignment issues +---------------- + +The linker script uses alphabetic sorting to group the different linker +lists together. Each group has its own struct and potentially its own +alignment. But when the linker packs the structs together it cannot ensure +that a linker list starts on the expected alignment boundary. + +For example, if the first list has a struct size of 8 and we place 3 of +them in the image, that means that the next struct will start at offset +0x18 from the start of the linker_list section. If the next struct has +a size of 16 then it will start at an 8-byte aligned offset, but not a +16-byte aligned offset. + +With sandbox on x86_64, a reference to a linker list item using +ll_entry_get() can force alignment of that particular linker_list item, +if it is in the same file as the linker_list item is declared. + +Consider this example, where struct driver is 0x80 bytes:: + + ll_entry_declare(struct driver, fred, driver) + + ... + + void *p = ll_entry_get(struct driver, fred, driver) + +If these two lines of code are in the same file, then the entry is forced +to be aligned at the 'struct driver' alignment, which is 16 bytes. If the +second line of code is in a different file, then no action is taken, since +the compiler cannot update the alignment of the linker_list item. + +In the first case, an 8-byte 'fill' region is added:: + + .u_boot_list_2_driver_2_testbus_drv + 0x0000000000270018 0x80 test/built-in.o + 0x0000000000270018 _u_boot_list_2_driver_2_testbus_drv + .u_boot_list_2_driver_2_testfdt1_drv + 0x0000000000270098 0x80 test/built-in.o + 0x0000000000270098 _u_boot_list_2_driver_2_testfdt1_drv + *fill* 0x0000000000270118 0x8 + .u_boot_list_2_driver_2_testfdt_drv + 0x0000000000270120 0x80 test/built-in.o + 0x0000000000270120 _u_boot_list_2_driver_2_testfdt_drv + .u_boot_list_2_driver_2_testprobe_drv + 0x00000000002701a0 0x80 test/built-in.o + 0x00000000002701a0 _u_boot_list_2_driver_2_testprobe_drv + +With this, the linker_list no-longer works since items after testfdt1_drv +are not at the expected address. + +Ideally we would have a way to tell gcc not to align structs in this way. +It is not clear how we could do this, and in any case it would require us +to adjust every struct used by the linker_list feature. + +The simplest fix seems to be to force each separate linker_list to start +on the largest possible boundary that can be required by the compiler. This +is the purpose of CONFIG_LINKER_LIST_ALIGN + + +.. kernel-doc:: include/linker_lists.h + :internal: |