include/linker_lists.h

   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
  10 #ifndef __LINKER_LISTS_H__
  11 #define __LINKER_LISTS_H__
  12
  13 #include <linux/compiler.h>
  14
  15 /*
  16  * There is no use in including this from ASM files.
  17  * So just don't define anything when included from ASM.
  18  */
  19
  20 #if !defined(__ASSEMBLY__)
  21
  22 /**
  23  * llsym() - Access a linker-generated array entry
  24  * @_type:      Data type of the entry
  25  * @_name:      Name of the entry
  26  * @_list:      name of the list. Should contain only characters allowed
  27  *              in a C variable name!
  28  */
  29 #define llsym(_type, _name, _list) \
  30                 ((_type *)&_u_boot_list_2_##_list##_2_##_name)
  31
  32 /**
  33  * ll_entry_declare() - Declare linker-generated array entry
  34  * @_type:      Data type of the entry
  35  * @_name:      Name of the entry
  36  * @_list:      name of the list. Should contain only characters allowed
  37  *              in a C variable name!
  38  *
  39  * This macro declares a variable that is placed into a linker-generated
  40  * array. This is a basic building block for more advanced use of linker-
  41  * generated arrays. The user is expected to build their own macro wrapper
  42  * around this one.
  43  *
  44  * A variable declared using this macro must be compile-time initialized.
  45  *
  46  * Special precaution must be made when using this macro:
  47  *
  48  * 1) The _type must not contain the "static" keyword, otherwise the
  49  *    entry is generated and can be iterated but is listed in the map
  50  *    file and cannot be retrieved by name.
  51  *
  52  * 2) In case a section is declared that contains some array elements AND
  53  *    a subsection of this section is declared and contains some elements,
  54  *    it is imperative that the elements are of the same type.
  55  *
  56  * 3) In case an outer section is declared that contains some array elements
  57  *    AND an inner subsection of this section is declared and contains some
  58  *    elements, then when traversing the outer section, even the elements of
  59  *    the inner sections are present in the array.
  60  *
  61  * Example:
  62  *
  63  * ::
  64  *
  65  *   ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
  66  *           .x = 3,
  67  *           .y = 4,
  68  *   };
  69  */
  70 #define ll_entry_declare(_type, _name, _list)                           \
  71         _type _u_boot_list_2_##_list##_2_##_name __aligned(4)           \
  72                         __attribute__((unused))                         \
  73                         __section("__u_boot_list_2_"#_list"_2_"#_name)
  74
  75 /**
  76  * ll_entry_declare_list() - Declare a list of link-generated array entries
  77  * @_type:      Data type of each entry
  78  * @_name:      Name of the entry
  79  * @_list:      name of the list. Should contain only characters allowed
  80  *              in a C variable name!
  81  *
  82  * This is like ll_entry_declare() but creates multiple entries. It should
  83  * be assigned to an array.
  84  *
  85  * ::
  86  *
  87  *   ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
  88  *        { .x = 3, .y = 4 },
  89  *        { .x = 8, .y = 2 },
  90  *        { .x = 1, .y = 7 }
  91  *   };
  92  */
  93 #define ll_entry_declare_list(_type, _name, _list)                      \
  94         _type _u_boot_list_2_##_list##_2_##_name[] __aligned(4)         \
  95                         __attribute__((unused))                         \
  96                         __section("__u_boot_list_2_"#_list"_2_"#_name)
  97
  98 /*
  99  * We need a 0-byte-size type for iterator symbols, and the compiler
 100  * does not allow defining objects of C type 'void'. Using an empty
 101  * struct is allowed by the compiler, but causes gcc versions 4.4 and
 102  * below to complain about aliasing. Therefore we use the next best
 103  * thing: zero-sized arrays, which are both 0-byte-size and exempt from
 104  * aliasing warnings.
 105  */
 106
 107 /**
 108  * ll_entry_start() - Point to first entry of linker-generated array
 109  * @_type:      Data type of the entry
 110  * @_list:      Name of the list in which this entry is placed
 111  *
 112  * This function returns ``(_type *)`` pointer to the very first entry of a
 113  * linker-generated array placed into subsection of __u_boot_list section
 114  * specified by _list argument.
 115  *
 116  * Since this macro defines an array start symbol, its leftmost index
 117  * must be 2 and its rightmost index must be 1.
 118  *
 119  * Example:
 120  *
 121  * ::
 122  *
 123  *   struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
 124  */
 125 #define ll_entry_start(_type, _list)                                    \
 126 ({                                                                      \
 127         static char start[0] __aligned(CONFIG_LINKER_LIST_ALIGN)        \
 128                 __attribute__((unused))                                 \
 129                 __section("__u_boot_list_2_"#_list"_1");                        \
 130         _type * tmp = (_type *)&start;                                  \
 131         asm("":"+r"(tmp));                                              \
 132         tmp;                                                            \
 133 })
 134
 135 /**
 136  * ll_entry_end() - Point after last entry of linker-generated array
 137  * @_type:      Data type of the entry
 138  * @_list:      Name of the list in which this entry is placed
 139  *              (with underscores instead of dots)
 140  *
 141  * This function returns ``(_type *)`` pointer after the very last entry of
 142  * a linker-generated array placed into subsection of __u_boot_list
 143  * section specified by _list argument.
 144  *
 145  * Since this macro defines an array end symbol, its leftmost index
 146  * must be 2 and its rightmost index must be 3.
 147  *
 148  * Example:
 149  *
 150  * ::
 151  *
 152  *   struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
 153  */
 154 #define ll_entry_end(_type, _list)                                      \
 155 ({                                                                      \
 156         static char end[0] __aligned(4) __attribute__((unused))         \
 157                 __section("__u_boot_list_2_"#_list"_3");                        \
 158         _type * tmp = (_type *)&end;                                    \
 159         asm("":"+r"(tmp));                                              \
 160         tmp;                                                            \
 161 })
 162 /**
 163  * ll_entry_count() - Return the number of elements in linker-generated array
 164  * @_type:      Data type of the entry
 165  * @_list:      Name of the list of which the number of elements is computed
 166  *
 167  * This function returns the number of elements of a linker-generated array
 168  * placed into subsection of __u_boot_list section specified by _list
 169  * argument. The result is of an unsigned int type.
 170  *
 171  * Example:
 172  *
 173  * ::
 174  *
 175  *   int i;
 176  *   const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
 177  *   struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
 178  *   for (i = 0; i < count; i++, msc++)
 179  *           printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
 180  */
 181 #define ll_entry_count(_type, _list)                                    \
 182         ({                                                              \
 183                 _type *start = ll_entry_start(_type, _list);            \
 184                 _type *end = ll_entry_end(_type, _list);                \
 185                 unsigned int _ll_result = end - start;                  \
 186                 _ll_result;                                             \
 187         })
 188
 189 /**
 190  * ll_entry_get() - Retrieve entry from linker-generated array by name
 191  * @_type:      Data type of the entry
 192  * @_name:      Name of the entry
 193  * @_list:      Name of the list in which this entry is placed
 194  *
 195  * This function returns a pointer to a particular entry in linker-generated
 196  * array identified by the subsection of u_boot_list where the entry resides
 197  * and it's name.
 198  *
 199  * Example:
 200  *
 201  * ::
 202  *
 203  *   ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
 204  *           .x = 3,
 205  *           .y = 4,
 206  *   };
 207  *   ...
 208  *   struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
 209  */
 210 #define ll_entry_get(_type, _name, _list)                               \
 211         ({                                                              \
 212                 extern _type _u_boot_list_2_##_list##_2_##_name;        \
 213                 _type *_ll_result =                                     \
 214                         &_u_boot_list_2_##_list##_2_##_name;            \
 215                 _ll_result;                                             \
 216         })
 217
 218 /**
 219  * ll_entry_ref() - Get a reference to a linker-generated array entry
 220  *
 221  * Once an extern ll_entry_declare() has been used to declare the reference,
 222  * this macro allows the entry to be accessed.
 223  *
 224  * This is like ll_entry_get(), but without the extra code, so it is suitable
 225  * for putting into data structures.
 226  *
 227  * @_type: C type of the list entry, e.g. 'struct foo'
 228  * @_name: name of the entry
 229  * @_list: name of the list
 230  */
 231 #define ll_entry_ref(_type, _name, _list)                               \
 232         ((_type *)&_u_boot_list_2_##_list##_2_##_name)
 233
 234 /**
 235  * ll_start() - Point to first entry of first linker-generated array
 236  * @_type:      Data type of the entry
 237  *
 238  * This function returns ``(_type *)`` pointer to the very first entry of
 239  * the very first linker-generated array.
 240  *
 241  * Since this macro defines the start of the linker-generated arrays,
 242  * its leftmost index must be 1.
 243  *
 244  * Example:
 245  *
 246  * ::
 247  *
 248  *   struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
 249  */
 250 #define ll_start(_type)                                                 \
 251 ({                                                                      \
 252         static char start[0] __aligned(4) __attribute__((unused))       \
 253                 __section("__u_boot_list_1");                           \
 254         _type * tmp = (_type *)&start;                                  \
 255         asm("":"+r"(tmp));                                              \
 256         tmp;                                                            \
 257 })
 258
 259 /**
 260  * ll_end() - Point after last entry of last linker-generated array
 261  * @_type:      Data type of the entry
 262  *
 263  * This function returns ``(_type *)`` pointer after the very last entry of
 264  * the very last linker-generated array.
 265  *
 266  * Since this macro defines the end of the linker-generated arrays,
 267  * its leftmost index must be 3.
 268  *
 269  * Example:
 270  *
 271  * ::
 272  *
 273  *   struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
 274  */
 275 #define ll_end(_type)                                                   \
 276 ({                                                                      \
 277         static char end[0] __aligned(4) __attribute__((unused))         \
 278                 __section("__u_boot_list_3");                           \
 279         _type * tmp = (_type *)&end;                                    \
 280         asm("":"+r"(tmp));                                              \
 281         tmp;                                                            \
 282 })
 283
 284 #endif /* __ASSEMBLY__ */
 285
 286 #endif  /* __LINKER_LISTS_H__ */