linker_lists.rst 3.0 KB

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