doc/api/linker_lists.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Linker-Generated Arrays
   4 =======================
   5
   6 A linker list is constructed by grouping together linker input
   7 sections, each containing one entry of the list. Each input section
   8 contains a constant initialized variable which holds the entry's
   9 content. Linker list input sections are constructed from the list
  10 and entry names, plus a prefix which allows grouping all lists
  11 together. Assuming _list and _entry are the list and entry names,
  12 then the corresponding input section name is
  13
  14 ::
  15
  16   __u_boot_list_ + 2_ + @_list + _2_ + @_entry
  17
  18 and the C variable name is
  19
  20 ::
  21
  22   _u_boot_list + _2_ + @_list + _2_ + @_entry
  23
  24 This ensures uniqueness for both input section and C variable name.
  25
  26 Note that the names differ only in the characters, "__" for the
  27 section and "_" for the variable, so that the linker cannot confuse
  28 section and symbol names. From now on, both names will be referred
  29 to as
  30
  31 ::
  32
  33   %u_boot_list_ + 2_ + @_list + _2_ + @_entry
  34
  35 Entry variables need never be referred to directly.
  36
  37 The naming scheme for input sections allows grouping all linker lists
  38 into a single linker output section and grouping all entries for a
  39 single list.
  40
  41 Note the two '_2_' constant components in the names: their presence
  42 allows putting a start and end symbols around a list, by mapping
  43 these symbols to sections names with components "1" (before) and
  44 "3" (after) instead of "2" (within).
  45 Start 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
  52 Start and end symbols for the whole of the linker lists area can be
  53 defined as
  54
  55 ::
  56
  57   %u_boot_list_1_...
  58   %u_boot_list_3_...
  59
  60 Here is an example of the sorted sections which result from a list
  61 "array" made up of three entries : "first", "second" and "third",
  62 iterated 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
  72 If lists must be divided into sublists (e.g. for iterating only on
  73 part 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'
  75 is the sub-list name. Iterators for the whole list should use the
  76 global list name ("outer"); iterators for only a sub-list should use
  77 the full sub-list name ("outer_2_inner").
  78
  79 Here is an example of the sections generated from a global list
  80 named "drivers", two sub-lists named "i2c" and "pci", and iterators
  81 defined 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 Alignment issues
 100 ----------------
 101
 102 The linker script uses alphabetic sorting to group the different linker
 103 lists together. Each group has its own struct and potentially its own
 104 alignment. But when the linker packs the structs together it cannot ensure
 105 that a linker list starts on the expected alignment boundary.
 106
 107 For example, if the first list has a struct size of 8 and we place 3 of
 108 them in the image, that means that the next struct will start at offset
 109 0x18 from the start of the linker_list section. If the next struct has
 110 a size of 16 then it will start at an 8-byte aligned offset, but not a
 111 16-byte aligned offset.
 112
 113 With sandbox on x86_64, a reference to a linker list item using
 114 ll_entry_get() can force alignment of that particular linker_list item,
 115 if it is in the same file as the linker_list item is declared.
 116
 117 Consider 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
 125 If these two lines of code are in the same file, then the entry is forced
 126 to be aligned at the 'struct driver' alignment, which is 16 bytes. If the
 127 second line of code is in a different file, then no action is taken, since
 128 the compiler cannot update the alignment of the linker_list item.
 129
 130 In 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
 146 With this, the linker_list no-longer works since items after testfdt1_drv
 147 are not at the expected address.
 148
 149 Ideally we would have a way to tell gcc not to align structs in this way.
 150 It is not clear how we could do this, and in any case it would require us
 151 to adjust every struct used by the linker_list feature.
 152
 153 The simplest fix seems to be to force each separate linker_list to start
 154 on the largest possible boundary that can be required by the compiler. This
 155 is the purpose of CONFIG_LINKER_LIST_ALIGN
 156
 157
 158 .. kernel-doc:: include/linker_lists.h
 159    :internal: