1 2 3 4 5 6 7 8 9 10 11
12 13 14
15 package xdc.bld;
16
17 /*!
18 * ======== ITarget2 ========
19 * Extension of the interface {@link xdc.bld.ITarget}.
20 *
21 * This interface contains some common structures and config parameters
22 * shared by several packages that contain targets.
23 */
24 metaonly interface ITarget2 inherits ITarget {
25
26 /*!
27 * ======== Command ========
28 * Required command and options.
29 *
30 * The compile, link, and archive functions in this interface are
31 * implemented by expanding the strings specified in this structure
32 * and inserting strings from the Options structure to form a single
33 * command. The strings in this structure can not be changed by
34 * the user (they are fixed by the target), but the string in the
35 * Options structure may be changed by the user.
36 *
37 * The final command is:
38 * Command.cmd Options.prefix Command.opts Options.suffix
39 *
40 * @field(cmd) name of a tool-chain executable without any path
41 * information. The location of this executable is
42 * specified by the binDir (or pathPrefix)
43 * configuration parameter.
44 *
45 * @field(opts) required options passed to the command; these options
46 * can not be changed or eliminated by user's
47 * configuration script.
48 */
49 struct Command {
50 string cmd; /*! the command to run */
51 string opts; /*! required options for the command */
52 }
53
54 /*!
55 * ======== Options ========
56 * User configurable command options.
57 *
58 * The option strings allow the user to pass additional parameters to the
59 * executable that is responsible for compiling, linker, or archiving.
60 * See `{@link #Command xdc.bld.ITarget2.Command}`.
61 */
62 struct Options {
63 string prefix; /*! options that appear before Command.opts */
64 string suffix; /*! options that appear after Command.opts */
65 }
66
67 /*!
68 * ======== ar ========
69 * The command used to create an archive
70 */
71 readonly config Command ar;
72
73 /*!
74 * ======== arOpts ========
75 * User configurable archiver options.
76 */
77 config Options arOpts = {
78 prefix: "",
79 suffix: ""
80 };
81
82 /*!
83 * ======== lnk ========
84 * The command used to link executables.
85 */
86 readonly config Command lnk;
87
88 /*!
89 * ======== lnkOpts ========
90 * User configurable linker options.
91 */
92 config Options lnkOpts = {
93 prefix: "",
94 suffix: ""
95 };
96
97 /*!
98 * ======== cc ========
99 * The command used to compile C/C++ source files into object files
100 */
101 readonly config Command cc;
102
103 /*!
104 * ======== ccOpts ========
105 * User configurable compiler options.
106 */
107 config Options ccOpts = {
108 prefix: "",
109 suffix: ""
110 };
111
112 /*!
113 * ======== ccConfigOpts ========
114 * User configurable compiler options for the generated config C file.
115 *
116 * By default, this parameter inherits values specified in
117 * `{@link #ccOpts ccOpts}`. The strings `"$(ccOpts.prefix)"` and
118 * `"$(ccOpts.suffix)"` are expanded into the values specified by
119 * `{@link #ccOpts ccOpts}` for this target.
120 */
121 config Options ccConfigOpts = {
122 prefix: "$(ccOpts.prefix)",
123 suffix: "$(ccOpts.suffix)"
124 };
125
126 /*!
127 * ======== asm ========
128 * The command used to assembles assembly source files into object files
129 */
130 readonly config Command asm;
131
132 /*!
133 * ======== asmOpts ========
134 * User configurable assembler options.
135 */
136 config Options asmOpts = {
137 prefix: "",
138 suffix: ""
139 };
140
141 /*!
142 * ======== includeOpts ========
143 * Additional user configurable target-specific include path options
144 */
145 config string includeOpts;
146
147 /*!
148 * ======== genConstCustom ========
149 * Return any custom generated code related to generated constants
150 *
151 * This function is invoked for each constant in the generated config C
152 * file. This includes module-level config parameter, as well as the
153 * internal data structures that define modules, interfaces and instances.
154 * A target is given a chance to add any target-specific pragmas or
155 * attributes for the generated constants. The set of the data supplied to
156 * this function overlaps with the data supplied to
157 * `{@link genVisibleData genVisibleData}`, so their output must be
158 * coordinated to avoid duplicate or inconsistent definitions or
159 * directives.
160 *
161 * @params(names) array of constant names generated in the
162 * config C file
163 *
164 * @params(types) array of types; each type corresponds to the element
165 * of `names` with the same index
166 *
167 * @a(returns)
168 * This function returns custom C code that will be embedded into the
169 * generated config C file. If there is nothing to be added, this function
170 * returns `null`. If a target never generates any such code, it can rely
171 * on the default implementation that always returns `null`.
172 */
173 String genConstCustom(StringArray names, StringArray types);
174
175 /*!
176 * ======== genVisibleData ========
177 * Return any custom generated code related to data generated in the
178 * config C file
179 *
180 * This function is invoked for each module-level configuration parameter
181 * in the configuration. Such parameters are represented by constants in the
182 * generated config C file.
183
184 * A target is given a chance to add any target-specific pragmas or
185 * attributes for the generated constants. The set of the data supplied to
186 * this function overlaps with the data supplied to
187 * `{@link genConstCustom genConstCustom}`, so their output must be
188 * coordinated to avoid duplicate or inconsistent definitions or
189 * directives.
190 *
191 * @params(quals) array of declaration qualifiers for the
192 * generated data
193 *
194 * @params(types) array of types for the generated data
195 *
196 * @params(names) array of variable names; each name corresponds
197 * to the elements of `quals` and `types` with the
198 * same index
199 *
200 * @a(returns)
201 * This function returns custom C code that will be embedded into the
202 * generated config C file. The purpose of the function is to allow
203 * targets to add pragmas or attributes to prevent elimination of data
204 * in case of partially linker objects.
205 * If there is nothing to be added, this function returns `null`. If a
206 * target never generates any such code, it can rely on the default
207 * implementation that always returns `null`.
208 */
209 String genVisibleData(StringArray quals, StringArray types,
210 StringArray names);
211 /*!
212 * ======== genVisibleFxns ========
213 * Return any custom generated code related to functions generated in
214 * the config C file
215 *
216 * @params(types) array of types of functions' return values
217 *
218 * @params(names) array of functions' names; each name corresponds
219 * to the elements of `types` and `args` with the
220 * same index
221 *
222 * @params(args) array of functions' argument lists, including
223 * qualifiers
224
225 * @a(returns)
226 * This function returns custom C code that will be embedded into the
227 * generated config C file. The purpose of the function is to allow
228 * targets to add pragmas or attributes to prevent elimination of functions
229 * in case of partially linker objects.
230 */
231 String genVisibleFxns(StringArray types, StringArray names,
232 StringArray args);
233
234 /*!
235 * ======== genVisibleLibFxns ========
236 * Return any custom generated code related to functions that are included
237 * in the configuration, but are not generated in the config C file
238 *
239 * @params(types) array of types of functions' return values
240 *
241 * @params(names) array of functions' names; each name corresponds
242 * to the elements of `types` and `args` with the
243 * same index
244 *
245 * @params(args) array of functions' argument lists, including
246 * qualifiers
247
248 * @a(returns)
249 * This function returns custom C code that will be embedded into the
250 * generated config C file. The purpose of the function is to allow
251 * targets to add pragmas or attributes to prevent elimination of functions
252 * in case of partially linker objects. These functions are managed
253 * separately from the functions that are generated in the config C file
254 * because some pragmas and attributes can be used only for functions
255 * defined in the same compilation unit where the paragmas and attributes
256 * are generated. For functions that are not generated in the config C
257 * file, and the mentioned restrictions exist, targets may have to create
258 * references that will prevent elimination of functions defined outside
259 * of the config C file.
260 */
261 String genVisibleLibFxns(StringArray types, StringArray names,
262 StringArray args);
263 }
264 265 266
267