1 /*
2 * Copyright (c) 2009 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * */
12 /*
13 * ======== ITarget2.xdc ========
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 metaonlyinterface 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 readonlyconfig 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 readonlyconfig 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 readonlyconfig 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 readonlyconfig 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 * @params(names) array of constant names generated in the
152 * config C file
153 *
154 * @params(types) array of types; each type corresponds to the element
155 * of `names` with the same index
156 *
157 * @a(returns) 158 * This function returns custom C code that will be embedded into the
159 * generated config C file. If there is nothing to be added, this function
160 * returns 'null'. If a target never generates any such code, it can rely
161 * on the default implementation that always returns 'null'.
162 */
163 String genConstCustom(StringArray names, StringArray types);
164
165 /*!
166 * ======== genVisibleData ========
167 * Return any custom generated code related to data generated in the
168 * config C file
169 *
170 * @params(quals) array of declaration qualifiers for the
171 * generated data
172 *
173 * @params(types) array of types for the generated data
174 *
175 * @params(names) array of variable names; each name corresponds
176 * to the elements of `quals` and 'types` with the
177 * same index
178 *
179 * @a(returns) 180 * This function returns custom C code that will be embedded into the
181 * generated config C file. The purpose of the function is to allow
182 * targets to add pragmas or attributes to prevent elimination of data
183 * in case of partially linker objects.
184 * If there is nothing to be added, this function returns 'null'. If a
185 * target never generates any such code, it can rely on the default
186 * implementation that always returns 'null'.
187 */
188 String genVisibleData(StringArray quals, StringArray types,
189 StringArray names);
190 /*!
191 * ======== genVisibleFxns ========
192 * Return any custom generated code related to functions generated in
193 * the config C file
194 *
195 * @params(types) array of types of functions' return values
196 *
197 * @params(names) array of functions' names; each name corresponds
198 * to the elements of `types` and 'args` with the
199 * same index
200 *
201 * @params(args) array of functions' argument lists, including
202 * qualifiers
203 204 * @a(returns) 205 * This function returns custom C code that will be embedded into the
206 * generated config C file. The purpose of the function is to allow
207 * targets to add pragmas or attributes to prevent elimination of functions
208 * in case of partially linker objects.
209 */
210 String genVisibleFxns(StringArray types, StringArray names,
211 StringArray args);
212
213 /*!
214 * ======== genVisibleLibFxns ========
215 * Return any custom generated code related to functions that are included
216 * in the configuration, but are not generated in the config C file
217 *
218 * @params(types) array of types of functions' return values
219 *
220 * @params(names) array of functions' names; each name corresponds
221 * to the elements of `types` and 'args` with the
222 * same index
223 *
224 * @params(args) array of functions' argument lists, including
225 * qualifiers
226 227 * @a(returns) 228 * This function returns custom C code that will be embedded into the
229 * generated config C file. The purpose of the function is to allow
230 * targets to add pragmas or attributes to prevent elimination of functions
231 * in case of partially linker objects. These functions are managed
232 * separately from the functions that are generated in the config C file
233 * because some pragmas and attributes can be used only for functions
234 * defined in the same compilation unit where the paragmas and attributes
235 * are generated. For functions that are not generated in the config C
236 * file, and the mentioned restrictions exist, targets may have to create
237 * references that will prevent elimination of functions defined outside
238 * of the config C file.
239 */
240 String genVisibleLibFxns(StringArray types, StringArray names,
241 StringArray args);
242 }
243 /*
244 * @(#) xdc.bld; 1, 0, 2,384; 6-27-2012 10:24:45; /db/ztree/library/trees/xdc/xdc-y30x/src/packages/
245 */
246