doc/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 first character, "." 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 .. kernel-doc:: include/linker_lists.h
 100    :internal: