linker_lists.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * include/linker_lists.h
  4. *
  5. * Implementation of linker-generated arrays
  6. *
  7. * Copyright (C) 2012 Marek Vasut <marex@denx.de>
  8. */
  9. #ifndef __LINKER_LISTS_H__
  10. #define __LINKER_LISTS_H__
  11. #include <linux/compiler.h>
  12. /*
  13. * There is no use in including this from ASM files.
  14. * So just don't define anything when included from ASM.
  15. */
  16. #if !defined(__ASSEMBLY__)
  17. /**
  18. * A linker list is constructed by grouping together linker input
  19. * sections, each containing one entry of the list. Each input section
  20. * contains a constant initialized variable which holds the entry's
  21. * content. Linker list input sections are constructed from the list
  22. * and entry names, plus a prefix which allows grouping all lists
  23. * together. Assuming _list and _entry are the list and entry names,
  24. * then the corresponding input section name is
  25. *
  26. * .u_boot_list_ + 2_ + @_list + _2_ + @_entry
  27. *
  28. * and the C variable name is
  29. *
  30. * _u_boot_list + _2_ + @_list + _2_ + @_entry
  31. *
  32. * This ensures uniqueness for both input section and C variable name.
  33. *
  34. * Note that the names differ only in the first character, "." for the
  35. * section and "_" for the variable, so that the linker cannot confuse
  36. * section and symbol names. From now on, both names will be referred
  37. * to as
  38. *
  39. * %u_boot_list_ + 2_ + @_list + _2_ + @_entry
  40. *
  41. * Entry variables need never be referred to directly.
  42. *
  43. * The naming scheme for input sections allows grouping all linker lists
  44. * into a single linker output section and grouping all entries for a
  45. * single list.
  46. *
  47. * Note the two '_2_' constant components in the names: their presence
  48. * allows putting a start and end symbols around a list, by mapping
  49. * these symbols to sections names with components "1" (before) and
  50. * "3" (after) instead of "2" (within).
  51. * Start and end symbols for a list can generally be defined as
  52. *
  53. * %u_boot_list_2_ + @_list + _1_...
  54. * %u_boot_list_2_ + @_list + _3_...
  55. *
  56. * Start and end symbols for the whole of the linker lists area can be
  57. * defined as
  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. * .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. * %u_boot_list_2_drivers_1
  84. * %u_boot_list_2_drivers_2_i2c_1
  85. * %u_boot_list_2_drivers_2_i2c_2_first
  86. * %u_boot_list_2_drivers_2_i2c_2_first
  87. * %u_boot_list_2_drivers_2_i2c_2_second
  88. * %u_boot_list_2_drivers_2_i2c_2_third
  89. * %u_boot_list_2_drivers_2_i2c_3
  90. * %u_boot_list_2_drivers_2_pci_1
  91. * %u_boot_list_2_drivers_2_pci_2_first
  92. * %u_boot_list_2_drivers_2_pci_2_second
  93. * %u_boot_list_2_drivers_2_pci_2_third
  94. * %u_boot_list_2_drivers_2_pci_3
  95. * %u_boot_list_2_drivers_3
  96. */
  97. /**
  98. * llsym() - Access a linker-generated array entry
  99. * @_type: Data type of the entry
  100. * @_name: Name of the entry
  101. * @_list: name of the list. Should contain only characters allowed
  102. * in a C variable name!
  103. */
  104. #define llsym(_type, _name, _list) \
  105. ((_type *)&_u_boot_list_2_##_list##_2_##_name)
  106. /**
  107. * ll_entry_declare() - Declare linker-generated array entry
  108. * @_type: Data type of the entry
  109. * @_name: Name of the entry
  110. * @_list: name of the list. Should contain only characters allowed
  111. * in a C variable name!
  112. *
  113. * This macro declares a variable that is placed into a linker-generated
  114. * array. This is a basic building block for more advanced use of linker-
  115. * generated arrays. The user is expected to build their own macro wrapper
  116. * around this one.
  117. *
  118. * A variable declared using this macro must be compile-time initialized.
  119. *
  120. * Special precaution must be made when using this macro:
  121. *
  122. * 1) The _type must not contain the "static" keyword, otherwise the
  123. * entry is generated and can be iterated but is listed in the map
  124. * file and cannot be retrieved by name.
  125. *
  126. * 2) In case a section is declared that contains some array elements AND
  127. * a subsection of this section is declared and contains some elements,
  128. * it is imperative that the elements are of the same type.
  129. *
  130. * 4) In case an outer section is declared that contains some array elements
  131. * AND an inner subsection of this section is declared and contains some
  132. * elements, then when traversing the outer section, even the elements of
  133. * the inner sections are present in the array.
  134. *
  135. * Example:
  136. * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
  137. * .x = 3,
  138. * .y = 4,
  139. * };
  140. */
  141. #define ll_entry_declare(_type, _name, _list) \
  142. _type _u_boot_list_2_##_list##_2_##_name __aligned(4) \
  143. __attribute__((unused, \
  144. section(".u_boot_list_2_"#_list"_2_"#_name)))
  145. /**
  146. * ll_entry_declare_list() - Declare a list of link-generated array entries
  147. * @_type: Data type of each entry
  148. * @_name: Name of the entry
  149. * @_list: name of the list. Should contain only characters allowed
  150. * in a C variable name!
  151. *
  152. * This is like ll_entry_declare() but creates multiple entries. It should
  153. * be assigned to an array.
  154. *
  155. * ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
  156. * { .x = 3, .y = 4 },
  157. * { .x = 8, .y = 2 },
  158. * { .x = 1, .y = 7 }
  159. * };
  160. */
  161. #define ll_entry_declare_list(_type, _name, _list) \
  162. _type _u_boot_list_2_##_list##_2_##_name[] __aligned(4) \
  163. __attribute__((unused, \
  164. section(".u_boot_list_2_"#_list"_2_"#_name)))
  165. /**
  166. * We need a 0-byte-size type for iterator symbols, and the compiler
  167. * does not allow defining objects of C type 'void'. Using an empty
  168. * struct is allowed by the compiler, but causes gcc versions 4.4 and
  169. * below to complain about aliasing. Therefore we use the next best
  170. * thing: zero-sized arrays, which are both 0-byte-size and exempt from
  171. * aliasing warnings.
  172. */
  173. /**
  174. * ll_entry_start() - Point to first entry of linker-generated array
  175. * @_type: Data type of the entry
  176. * @_list: Name of the list in which this entry is placed
  177. *
  178. * This function returns (_type *) pointer to the very first entry of a
  179. * linker-generated array placed into subsection of .u_boot_list section
  180. * specified by _list argument.
  181. *
  182. * Since this macro defines an array start symbol, its leftmost index
  183. * must be 2 and its rightmost index must be 1.
  184. *
  185. * Example:
  186. * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
  187. */
  188. #define ll_entry_start(_type, _list) \
  189. ({ \
  190. static char start[0] __aligned(4) __attribute__((unused, \
  191. section(".u_boot_list_2_"#_list"_1"))); \
  192. (_type *)&start; \
  193. })
  194. /**
  195. * ll_entry_end() - Point after last entry of linker-generated array
  196. * @_type: Data type of the entry
  197. * @_list: Name of the list in which this entry is placed
  198. * (with underscores instead of dots)
  199. *
  200. * This function returns (_type *) pointer after the very last entry of
  201. * a linker-generated array placed into subsection of .u_boot_list
  202. * section specified by _list argument.
  203. *
  204. * Since this macro defines an array end symbol, its leftmost index
  205. * must be 2 and its rightmost index must be 3.
  206. *
  207. * Example:
  208. * struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
  209. */
  210. #define ll_entry_end(_type, _list) \
  211. ({ \
  212. static char end[0] __aligned(4) __attribute__((unused, \
  213. section(".u_boot_list_2_"#_list"_3"))); \
  214. (_type *)&end; \
  215. })
  216. /**
  217. * ll_entry_count() - Return the number of elements in linker-generated array
  218. * @_type: Data type of the entry
  219. * @_list: Name of the list of which the number of elements is computed
  220. *
  221. * This function returns the number of elements of a linker-generated array
  222. * placed into subsection of .u_boot_list section specified by _list
  223. * argument. The result is of an unsigned int type.
  224. *
  225. * Example:
  226. * int i;
  227. * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
  228. * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
  229. * for (i = 0; i < count; i++, msc++)
  230. * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
  231. */
  232. #define ll_entry_count(_type, _list) \
  233. ({ \
  234. _type *start = ll_entry_start(_type, _list); \
  235. _type *end = ll_entry_end(_type, _list); \
  236. unsigned int _ll_result = end - start; \
  237. _ll_result; \
  238. })
  239. /**
  240. * ll_entry_get() - Retrieve entry from linker-generated array by name
  241. * @_type: Data type of the entry
  242. * @_name: Name of the entry
  243. * @_list: Name of the list in which this entry is placed
  244. *
  245. * This function returns a pointer to a particular entry in linker-generated
  246. * array identified by the subsection of u_boot_list where the entry resides
  247. * and it's name.
  248. *
  249. * Example:
  250. * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
  251. * .x = 3,
  252. * .y = 4,
  253. * };
  254. * ...
  255. * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
  256. */
  257. #define ll_entry_get(_type, _name, _list) \
  258. ({ \
  259. extern _type _u_boot_list_2_##_list##_2_##_name; \
  260. _type *_ll_result = \
  261. &_u_boot_list_2_##_list##_2_##_name; \
  262. _ll_result; \
  263. })
  264. /**
  265. * ll_start() - Point to first entry of first linker-generated array
  266. * @_type: Data type of the entry
  267. *
  268. * This function returns (_type *) pointer to the very first entry of
  269. * the very first linker-generated array.
  270. *
  271. * Since this macro defines the start of the linker-generated arrays,
  272. * its leftmost index must be 1.
  273. *
  274. * Example:
  275. * struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
  276. */
  277. #define ll_start(_type) \
  278. ({ \
  279. static char start[0] __aligned(4) __attribute__((unused, \
  280. section(".u_boot_list_1"))); \
  281. (_type *)&start; \
  282. })
  283. /**
  284. * ll_end() - Point after last entry of last linker-generated array
  285. * @_type: Data type of the entry
  286. *
  287. * This function returns (_type *) pointer after the very last entry of
  288. * the very last linker-generated array.
  289. *
  290. * Since this macro defines the end of the linker-generated arrays,
  291. * its leftmost index must be 3.
  292. *
  293. * Example:
  294. * struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
  295. */
  296. #define ll_end(_type) \
  297. ({ \
  298. static char end[0] __aligned(4) __attribute__((unused, \
  299. section(".u_boot_list_3"))); \
  300. (_type *)&end; \
  301. })
  302. #endif /* __ASSEMBLY__ */
  303. #endif /* __LINKER_LISTS_H__ */