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 * ======== ITarget.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(constants) array of constant names generated in the
152 * config C file
153 *
154 * @a(returns) 155 * This function returns custom C code that will be embedded into the
156 * generated config C file. If there is nothing to be added, this function
157 * returns 'null'. If a target never generates any such code, it can rely
158 * on the default implementation that always returns 'null'.
159 */
160 String genConstCustom(StringArray constants);
161
162 /*!
163 * ======== genVisibleData ========
164 * Return any custom generated code related to data generated in the
165 * config C file
166 *
167 * @params(quals) array of declaration qualifiers for the
168 * generated data
169 *
170 * @params(types) array of types for the generated data
171 *
172 * @params(names) array of variable names; each name corresponds
173 * to the elements of `quals` and 'types` with the
174 * same index
175 *
176 * @a(returns) 177 * This function returns custom C code that will be embedded into the
178 * generated config C file. The purpose of the function is to allow
179 * targets to add pragmas or attributes to prevent elimination of data
180 * in case of partially linker objects.
181 * If there is nothing to be added, this function returns 'null'. If a
182 * target never generates any such code, it can rely on the default
183 * implementation that always returns 'null'.
184 */
185 String genVisibleData(StringArray quals, StringArray types,
186 StringArray names);
187 /*!
188 * ======== genVisibleFxns ========
189 * Return any custom generated code related to functions generated in
190 * the config C file
191 *
192 * @params(types) array of types of functions' return values
193 *
194 * @params(names) array of functions' names; each name corresponds
195 * to the elements of `types` and 'args` with the
196 * same index
197 *
198 * @params(args) array of functions' argument lists, including
199 * qualifiers
200 201 * @a(returns) 202 * This function returns custom C code that will be embedded into the
203 * generated config C file. The purpose of the function is to allow
204 * targets to add pragmas or attributes to prevent elimination of functions
205 * in case of partially linker objects.
206 */
207 String genVisibleFxns(StringArray types, StringArray names,
208 StringArray args);
209
210 /*!
211 * ======== genVisibleLibFxns ========
212 * Return any custom generated code related to functions that are included
213 * in the configuration, but are not generated in the config C file
214 *
215 * @params(types) array of types of functions' return values
216 *
217 * @params(names) array of functions' names; each name corresponds
218 * to the elements of `types` and 'args` with the
219 * same index
220 *
221 * @params(args) array of functions' argument lists, including
222 * qualifiers
223 224 * @a(returns) 225 * This function returns custom C code that will be embedded into the
226 * generated config C file. The purpose of the function is to allow
227 * targets to add pragmas or attributes to prevent elimination of functions
228 * in case of partially linker objects. These functions are managed
229 * separately from the functions that are generated in the config C file
230 * because some pragmas and attributes can be used only for functions
231 * defined in the same compilation unit where the paragmas and attributes
232 * are generated. For functions that are not generated in the config C
233 * file, and the mentioned restrictions exist, targets may have to create
234 * references that will prevent elimination of functions defined outside
235 * of the config C file.
236 */
237 String genVisibleLibFxns(StringArray types, StringArray names,
238 StringArray args);
239 }
240 /*
241 * @(#) xdc.bld; 1, 0, 2,340; 6-14-2011 11:49:19; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
242 */
243