Documentation/index.rst

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