blob: 0b405d78ea34df1c528fbc4e24ed2aad756ac4a2 [file] [log] [blame]
Marek Vasut42ebaae2012-10-12 10:27:02 +00001/*
2 * include/linker_lists.h
3 *
4 * Implementation of linker-generated arrays
5 *
6 * Copyright (C) 2012 Marek Vasut <marex@denx.de>
7 *
8 * See file CREDITS for list of people who contributed to this
9 * project.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License as
13 * published by the Free Software Foundation; either version 2 of
14 * the License, or (at your option) any later version.
15 */
16#ifndef __LINKER_LISTS_H__
17#define __LINKER_LISTS_H__
18
19/**
20 * ll_entry_declare() - Declare linker-generated array entry
21 * @_type: Data type of the entry
22 * @_name: Name of the entry
23 * @_section_u: Subsection of u_boot_list in which this entry is placed
24 * (with underscores instead of dots, for name concatenation)
25 * @_section_d: Subsection of u_boot_list in which this entry is placed
26 * (with dots, for section concatenation)
27 *
28 * This macro declares a variable that is placed into a linker-generated
29 * array. This is a basic building block for more advanced use of linker-
30 * generated arrays. The user is expected to build their own macro wrapper
31 * around this one.
32 *
33 * A variable declared using this macro must be compile-time initialized
34 * and is as such placed into subsection of special section, .u_boot_list.
35 * The subsection is specified by the _section_[u,d] parameter, see below.
36 * The base name of the variable is _name, yet the actual variable is
37 * declared as concatenation of
38 *
39 * %_u_boot_list_ + @_section_u + _ + @_name
40 *
41 * which ensures name uniqueness. This variable shall never be refered
42 * directly though.
43 *
44 * Special precaution must be made when using this macro:
45 * 1) The _type must not contain the "static" keyword, otherwise the entry
46 * is not generated.
47 *
48 * 2) The @_section_u and @_section_d variables must match, the only difference
49 * is that in @_section_u is every dot "." character present in @_section_d
50 * replaced by a single underscore "_" character in @_section_u. The actual
51 * purpose of these parameters is to select proper subsection in the global
52 * .u_boot_list section.
53 *
54 * 3) In case a section is declared that contains some array elements AND a
55 * subsection of this section is declared and contains some elements, it is
56 * imperative that the elements are of the same type.
57 *
58 * 4) In case an outer section is declared that contains some array elements
59 * AND am inner subsection of this section is declared and contains some
60 * elements, then when traversing the outer section, even the elements of
61 * the inner sections are present in the array.
62 *
63 * Example:
64 * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub, cmd.sub) = {
65 * .x = 3,
66 * .y = 4,
67 * };
68 */
69#define ll_entry_declare(_type, _name, _section_u, _section_d) \
70 _type _u_boot_list_##_section_u##_##_name __attribute__(( \
71 unused, aligned(4), \
72 section(".u_boot_list."#_section_d"."#_name)))
73
74/**
75 * ll_entry_start() - Point to first entry of linker-generated array
76 * @_type: Data type of the entry
77 * @_section_u: Subsection of u_boot_list in which this entry is placed
78 * (with underscores instead of dots)
79 *
80 * This function returns (_type *) pointer to the very first entry of a
81 * linker-generated array placed into subsection of .u_boot_list section
82 * specified by _section_u argument.
83 *
84 * Example:
85 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
86 */
87#define ll_entry_start(_type, _section_u) \
88 ({ \
89 extern _type _u_boot_list_##_section_u##__start; \
90 _type *_ll_result = &_u_boot_list_##_section_u##__start;\
91 _ll_result; \
92 })
93
94/**
95 * ll_entry_count() - Return the number of elements in linker-generated array
96 * @_type: Data type of the entry
97 * @_section_u: Subsection of u_boot_list in which this entry is placed
98 * (with underscores instead of dots)
99 *
100 * This function returns the number of elements of a linker-generated array
101 * placed into subsection of .u_boot_list section specified by _section_u
102 * argument. The result is of an unsigned int type.
103 *
104 * Example:
105 * int i;
106 * const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
107 * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
108 * for (i = 0; i < count; i++, msc++)
109 * printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
110 */
111#define ll_entry_count(_type, _section_u) \
112 ({ \
113 extern _type _u_boot_list_##_section_u##__start; \
114 extern _type _u_boot_list_##_section_u##__end; \
115 unsigned int _ll_result = \
116 &_u_boot_list_##_section_u##__end - \
117 &_u_boot_list_##_section_u##__start; \
118 _ll_result; \
119 })
120
121
122/**
123 * ll_entry_get() - Retrieve entry from linker-generated array by name
124 * @_type: Data type of the entry
125 * @_name: Name of the entry
126 * @_section_u: Subsection of u_boot_list in which this entry is placed
127 * (with underscores instead of dots)
128 *
129 * This function returns a pointer to a particular entry in LG-array
130 * identified by the subsection of u_boot_list where the entry resides
131 * and it's name.
132 *
133 * Example:
134 * ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub, cmd.sub) = {
135 * .x = 3,
136 * .y = 4,
137 * };
138 * ...
139 * struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
140 */
141#define ll_entry_get(_type, _name, _section_u) \
142 ({ \
143 extern _type _u_boot_list_##_section_u##_##_name; \
144 _type *_ll_result = &_u_boot_list_##_section_u##_##_name;\
145 _ll_result; \
146 })
147
148#endif /* __LINKER_LISTS_H__ */