1 /*
2 * Copyright (c) 2008 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 */
16 package xdc.bld;
17
18 /*!
19 * ======== ITarget ========
20 * The interface between code generation tool-chains and the XDC Build
21 * Engine.
22 *
23 * This interface defines an abstract interface that must be supported by
24 * a compiler tool-chain in order to be used in an XDC build environment.
25 * This interface allows the XDC Build engine to treat all compiler tool
26 * chains uniformly; thus, it is possible to add support for a new compiler
27 * without making *any* changes to the build engine.
28 */
29 metaonlyinterface ITarget {
30
31 /*!
32 * ======== Model ========
33 * Target runtime model.
34 *
35 * @field(`endian`) this string specifies the endianess of the
36 * generated code. Valid values include:
37 * @p(dlist) 38 * - `"big"`
39 * big endian
40 * - `"little"`
41 * little endian
42 * - `null`
43 * unspecified
44 * @p 45 *
46 * @field(`codeModel`) this string specifies a target-specific code size
47 * model. Valid values include:
48 * @p(dlist) 49 * - `"near"`
50 * C54 near mode
51 * - `"far"`
52 * C54 far mode
53 * - `undefined`
54 * unspecified
55 * @p 56 *
57 * @field(`dataModel`) this string specifies a target-specific data size
58 * model. Valid values include:
59 * @p(dlist) 60 * - `"large"`
61 * C55, C28 large model
62 * - `undefined`
63 * unspecified
64 * @p 65 * @see #model
66 */
67 struct Model {
68 String endian; /*! endian-ness of this target */
69 String codeModel; /*! target-specific code model */
70 String dataModel; /*! target-specific data model */
71 }
72
73 /*!
74 * ======== name ========
75 * Nickname for this target.
76 *
77 * This name is typically the name of the module without the package
78 * name prefix. Thus, it is not necessarily globally unique.
79 *
80 * Use the `$name` property of the module to get a globally unique name
81 * for the target.
82 */
83 readonlyconfig String name;
84
85 /*!
86 * ======== suffix ========
87 * Suffix appended to all objs, libraries, and executable.
88 *
89 * All files generated by this target (object files, archives,
90 * executables, etc.) have file names whose extensions end with
91 * suffix. In particular, targets create files with the following
92 * extensions:
93 * @p(dlist) 94 * - `".a<suffix>"`
95 * archive files (i.e., libraries)
96 * - `".o<suffix>"`
97 * object files
98 * - `".s<suffix>"`
99 * assembly language source (see `{@link #scompile()}`)
100 * - `".x<suffix>"`
101 * executable files
102 *
103 * This suffix should be chosen to globally and uniquely identify the
104 * EABI (Embedded Application Binary Interface) of the objects produced
105 * by this target. Targets with the same suffix should
106 * should produce 100% EABI compatible objects and, targets with different
107 * suffixes should produce objects with incompatible EABIs.
108 *
109 * @see #scompile()
110 */
111 readonlyconfig String suffix;
112
113 /*!
114 * ======== compatibleSuffixes ========
115 * Array of suffixes used by targets compatible with this target
116 *
117 * This array is used to identify a set of targets that produce
118 * code that can be linked with code produced by this target, where the
119 * order of suffixes defines the order of preferrence. This
120 * parameter is used by `findSuffixes()`.
121 *
122 * For example, an Arm target which builds for v6 architecture might have
123 * the following values in its `compatibleSuffix`: ["v5T", "MV470"].
124 * This means that code produced by targets with suffixes "v5T' and
125 * "MV470" can be linked with code produced by that target, and that "v5T"
126 * code is more preferred than "MV470" code.
127 */
128 config String compatibleSuffixes[];
129
130 /*!
131 * ======== isa ========
132 * CPU Instruction Set Architecture (ISA)
133 *
134 * This parameter is used to identify a set of targets that produce
135 * code for a common ISA. This is used by build scripts that need to
136 * build for all targets that support a particular device.
137 *
138 * For example, the build script for a package that is designed for
139 * the TMS32064xx (and no other CPU) can easily specify that it
140 * should be built for all targets that generate code for the
141 * TMS320C64xx without having to specify a specific target. This
142 * allows the user to add new targets (big endian, little endian,
143 * different compilers, etc.) that build for the TMS320C64xx without
144 * having to modify the package's build script.
145 *
146 * Note that this field should not be confused with platform ISA
147 * names; this field is defined by target tool-chains and may differ
148 * from the names given by a CPU device.
149 *
150 * @see xdc.platform.ICpuDataSheet
151 */
152 readonlyconfig String isa;
153
154 /*!
155 * ======== model ========
156 * Run-time model
157 *
158 * This structure identifies a particular run-time model
159 * used by the compiler to generate instructions.
160 */
161 readonlyconfig Model model;
162
163 /*!
164 * ======== os ========
165 * Name of OS required to run programs built for this target.
166 *
167 * Native executables are run by the host OS. This OS often
168 * defines runtime interfaces that all executables (implicitly or
169 * explicitly) use.
170 *
171 * If os is undefined, then no OS is required.
172 */
173 readonlyconfig String os;
174
175 /*!
176 * ======== rts ========
177 * Name of a run-time support package to include
178 *
179 * Development environments often provide a set of common run-time
180 * support functions that all other code can easily utilize; e.g.,
181 * some means for performing a "printf", normal program termination
182 * with "exit status", etc. If the `rts` parameter is non-`null`, it is
183 * the name of a package that is implicitly imported when building
184 * any executable that is built using this target. If `rts` is
185 * undefined, no rts package is imported.
186 *
187 * This parameter makes it possible for the target producer to name
188 * a package that provides a target-specific implementation of a runtime
189 * support interface. Clients of a target do not need to explicitly
190 * name a target specific rts implementation; thus, it is not
191 * possible for the client to inadvertently name the wrong (or an
192 * incompatible) rts implementation.
193 *
194 * Note: this package is *NOT* included if the executable's
195 * `{@link xdc.bld.Executable#attrs}.rtsName` attribute is set to `null`;
196 * see {@link xdc.bld.Executable#Attrs}. It is also not included if the
197 * executable is a legacy DSP/BIOS program.
198 */
199 readonlyconfig String rts;
200
201 /*!
202 * ======== base ========
203 * A target that this target is based upon.
204 *
205 * If non-`null`, this target shares the same tool-chain of the specified
206 * base target. This parameter is used to determine various default
207 * values for target configuration parameters. For example, the default
208 * setting of `{@link #rootDir}` is the value of the base's
209 * `{@link #rootDir}` setting.
210 */
211 readonlyconfig ITarget.Module base;
212
213 /*!
214 * ======== dllExt ========
215 * @_nodoc dlls are not yet fully supported
216 */
217 config String dllExt;
218
219 /*!
220 * ======== execExt ========
221 * Extension for executables.
222 *
223 * Operating systems and tools often have a strong preference for a
224 * specific extension for executables; e.g., Windows expects executables
225 * to have the extension "`.exe`". If this parameter is set, executables
226 * will be given the specified extension instead of the default
227 * "`.x<suffix>`", where `<suffix>` is the target's suffix parameter.
228 *
229 * The `execExt` is an expression that is expanded prior to use.
230 * Expressions of the form "`$(name)`" within the
231 * pattern string are expanded if "`name`" is one of the built-in
232 * variables listed below.
233 *
234 * Built-in variables for `execExt`:
235 * @p(dlist) 236 * - `trgName`
237 * the target's `name` property
238 * - `trgSuffix`
239 * the target's `suffix` property
240 * - `platPName`
241 * the executable's platform package name
242 * - `platIName`
243 * the executable's platform instance name
244 * @p 245 *
246 * @a(Example) If you want to build a portable executable for multiple
247 * targets side-by-side and you want (or need) to use a fixed extension
248 * such as ".out" for all executables, setting `execExt` to
249 * `"_$(trgSuffix).out"` for all targets ensures that all generated
250 * executables will have unique names and yet share a common extension
251 * of `".out"`.
252 */
253 config String execExt;
254
255 /*!
256 * ======== platform ========
257 * The default platform name for this target
258 *
259 * Build scripts often build for just one platform per target. This
260 * parameter allows one to establish a default platform for each
261 * target in a build.
262 *
263 * If this parameter is `null` or `undefined` and `{@link #platforms}`
264 * array is non-empty, it is initialized to be the first element of the
265 * platforms array (i.e., `{@link #platforms[0]}`).
266 */
267 config String platform;
268
269 /*!
270 * ======== platforms ========
271 * A set of platforms that can support this target
272 *
273 * Some build scripts build executables for "all" platforms; e.g.,
274 * regression test suites. This parameter allows one to establish
275 * a set of platforms that build scripts can legitimately use to
276 * create executables, for example.
277 *
278 * If this array is empty (i.e., has length 0) and `{@link #platform}`
279 * is non-`null`, platforms is initialized to an array of one element
280 * equal to `{@link #platform}`.
281 */
282 config String platforms[] = [];
283
284 /*!
285 * ======== binaryParser ========
286 * The name of a object file parser
287 *
288 * The value of this configuration parameter is the name of a
289 * module or Java class that implements the ?? interface. This
290 * interface is used to extract information from the object files
291 * produced by this target.
292 *
293 * @_nodoc object file readers are not yet fully supported
294 */
295 config String binaryParser;
296
297 /*!
298 * ======== version ========
299 * The Compatibility Key associated with this target.
300 *
301 * @a(Readonly) This value is automatically computed by the XDC Build
302 * Engine by executing the `{@link #getVersion()}` function after
303 * `package.bld` completes but prior to generating `package.mak`.
304 */
305 config String version;
306
307 /*!
308 * ======== versionRaw ========
309 * The unmodified version string associated with this target.
310 *
311 * @a(Readonly) This value is automatically computed by the XDC Build
312 * Engine by executing the `{@link #getVersion()}` function after
313 * `package.bld` completes but prior to generating `package.mak`.
314 *
315 * @_nodoc 316 */
317 config String versionRaw;
318
319 /*!
320 * ======== DebugGen ========
321 * Debugger integration support.
322 *
323 * This structure specifies additional files that are generated
324 * in order to support integration with a debugger. For example, the
325 * default setting for TI targets specifies the generation of CCS
326 * project files that allow one to easily debug executables that have
327 * been constructed from multiple packages.
328 *
329 * There are two "types" of debug support files that are generated;
330 * one for the package as a whole, and one for each executable.
331 * Since packages may contain portable sources that are built for more
332 * than one target, a "package-level" file is generated for each target
333 * used in the package. A separate file is generated for each
334 * executable built within the package.
335 *
336 * The `execTemplate` and `packageTemplate` fields name a template that
337 * is expanded in the context of the config model and the build
338 * model, respectively. These fields should be set to a file name
339 * string which is relative to the package path; e.g., the string
340 * "`ti/targets/cc_exec.xdt`" refers to the file "`cc_exec.xdt`" in the
341 * `ti.targets` package located along the package path.
342 *
343 * Preconditions for the `execTemplate`:
344 * @p(dlist) 345 * - `this`
346 * the configured program object (`xdc.cfg.Program`);
347 * i.e., the program object *after* the program's
348 * configuration script completes.
349 * - `$args`
350 * array of arguments passed to the template
351 *
352 * - `$args[1]`
353 * the name of the executable being produced for this
354 * configuration.
355 *
356 * - `environment`
357 * hash table of XDC global parameters; e.g., `"xdc.path"`,
358 * `"xdc.root"`, ...
359 * @p 360 * Preconditions for the `packageTemplate`:
361 * @p(dlist) 362 * - `this`
363 * the "package contents" object (i.e.,
364 * `xdc.bld.PackageContents`) *after* the package's
365 * build script (`package.bld`) completes.
366 * - `$args`
367 * array of arguments passed to the template
368 *
369 * - `$args[0]`
370 * the target (a module implementing the
371 * `{@link xdc.bld.ITarget}` interface)
372 *
373 * - `$args[1]`
374 * hash-table of all package sources
375 *
376 * - `environment`
377 * hash table of XDC global parameters; e.g., `"xdc.path"`,
378 * `"xdc.root"`, ...
379 * @p 380 * The `execPattern` and `packagePattern` fields are expressions that
381 * are expanded prior to template expansion to determine the name of
382 * the output file. Expressions of the form "`$(name)`" within the
383 * pattern string are expanded if "`name`" is one of the built-in
384 * variables listed below.
385 *
386 * Built-in variables for `execPattern`:
387 * @p(dlist) 388 * - `cfgName`
389 * the name of the generated configuration file (without
390 * any directory prefix);
391 * - `cfgDir`
392 * the name of the directory containing the config file;
393 * - `exeName`
394 * the name of the executable file (without any
395 * directory prefix);
396 * - `exeDir`
397 * the directory containing the executable file.
398 * @p 399 * Both the `exeDir` and `cfgDir` are relative to the directory
400 * containing the `package.bld` script.
401 *
402 * Built-in variables for `packagePattern`:
403 * @p(dlist) 404 * - `pkgName`
405 * the package's name (e.g., `"ti.targets"`);
406 * - `trgName`
407 * the target's `name` property;
408 * - `trgSuffix`
409 * the target's `suffix` property.
410 *
411 * @see #debugGen
412 */
413 struct DebugGen {
414 String execTemplate; /*! debugger template for executable */
415 String execPattern; /*! exec file name pattern */
416 String packageTemplate; /*! debugger template for package */
417 String packagePattern; /*! package file name pattern */
418 }
419
420 /*!
421 * ======== debugGen ========
422 * Debugger/IDE file generation support.
423 *
424 * This parameter allows one to automatically generate files that
425 * can be used by an IDE to more easily debug (and possibly rebuild)
426 * specified goals.
427 *
428 * To avoid unnecessary build time overhead, these files are not always
429 * generated; by default, they are only generated for "debug" profiles.
430 * The generation of these files is controlled by the
431 * `{@link xdc.cfg.Program#gen}` configuration parameter. To force these
432 * files to be generated for a particular executable, add the following
433 * line to the executable's program configuration script:
434 * @p(code) 435 * Program.gen.debuggerFiles = true;
436 * @p 437 *
438 * It is also possible to disable the generation of selected files by
439 * setting the appropriate fields of `{@link #DebugGen}` to `null` in
440 * your `config.bld` script.
441 */
442 config DebugGen debugGen;
443
444 /*!
445 * ======== Extension ========
446 * File extension to file type association.
447 *
448 * This structure is used by the Build Engine to determine whether a
449 * file should be treated as C++, C, or assembly language source.
450 *
451 * @field(suf) the file extension including any '.' characters
452 *
453 * @field(typ) the type of the file having this extension.
454 * Allowable file type identifiers include:
455 * @p(dlist) 456 * - `"c"`
457 * C language source file
458 * - `"asm"`
459 * assembly language source file
460 * - `"cpp"`
461 * C++ language source file
462 *
463 * @see #extensions
464 */
465 struct Extension {
466 String suf; /*! file extension (including any '.') */
467 String typ; /*! type of this file; e.g., `"c"`, `"asm"`, ... */
468 };
469
470 /*!
471 * ======== extensions ========
472 * File extensions recognized by this target.
473 *
474 * This is a user modifiable table used to customize file extensions
475 * recognized by each target.
476 *
477 * For example, to add a new assembly language extension, say "`.s64`",
478 * to the target `ti.targets.C64P`, add the following lines to the
479 * build model startup script:
480 * @p(code) 481 * var C64P = xdc.module('ti.targets.C64P');
482 * C64P.extensions[".s64"] = {
483 * suf: ".s64", typ: "asm"
484 * };
485 *
486 * Note that individual targets may add additional language types.
487 *
488 * It is also possible to remove default extensions. For example, to
489 * remove the "`.asm`" extension from the target `ti.targets.C64P`, add
490 * the following lines to the build model startup script:
491 * @p(code) 492 * var C64P = xdc.module('ti.targets.C64P');
493 * delete C64P.extensions[".asm"];
494 * @p 495 */
496 config Extension extensions[string] = [
497 [".asm", {suf: ".asm", typ: "asm"}],
498 [".c", {suf: ".c", typ: "c" }],
499 [".cpp", {suf: ".cpp", typ: "cpp"}],
500 [".cxx", {suf: ".cxx", typ: "cpp"}],
501 [".C", {suf: ".C", typ: "cpp"}],
502 [".cc", {suf: ".cc", typ: "cpp"}],
503 ];
504
505 /*!
506 * ======== versionMap ========
507 * Map of compiler version numbers to compatibility keys.
508 *
509 * `versionMap` is a user modifiable table used to map tool-chain
510 * version numbers to Compatibility Keys.
511 *
512 * Each target defines the format of the tool-chain version obtained
513 * from the tool-chain. The user can then map new tool-chain version
514 * strings to an appropriate compatibility key.
515 *
516 * Each target must respect the mapping defined by this table; i.e.,
517 * if the user supplies a compatibility key in this map, it must be
518 * returned when `{@link #getVersion()}` is called.
519 *
520 * Thus, it is possible for the user to assert that any two compiler
521 * tool chains should be treated as equivalent (or incompatible) by
522 * mapping their version numbers to identical (incompatible)
523 * compatibility keys.
524 *
525 * @see ti.targets.ITarget#versionMap
526 */
527 config String versionMap[string] = [
528 ];
529
530 /*!
531 * ======== alignDirectiveSupported ========
532 * The compiler supports an align directive.
533 */
534 readonlyconfig Bool alignDirectiveSupported = false;
535
536 /*!
537 * ======== rootDir ========
538 * Installation directory for this target's code generation tools.
539 *
540 * Since each target potentially "wraps" a different compiler tool-chain
541 * and each tool-chain will, in general, assume a different physical
542 * design for the installation of the compiler and its associated
543 * libraries and headers, one must consult each specific target to know
544 * how to set this parameter.
545 *
546 * If the `{@link #base}` parameter is `null`, this parameter *must* be
547 * set by the user; otherwise, `rootDir` defaults to the value
548 * `base.rootDir`.
549 */
550 config String rootDir;
551
552 /*!
553 * ======== CompileOptions ========
554 * Options passed to the compiler/assembler.
555 *
556 * @field(aopts) a string of target-specific assembler options
557 * @field(copts) a string of target-specific C/C++ compiler options
558 * @field(defs) a string of macro definitions each of the form
559 * "`-Dname=value`" separated by white space
560 * @field(incs) a string of include directories each of the form
561 * "`-Idir`" separated by white space
562 *
563 * @a(Predefined Macros) 564 * The XDC Build Engine automatically adds several predefined macros via
565 * `-D` definitions that enable conditional compilation of source files
566 * based on build-specific attributes.
567 * @p(dlist) 568 * - `xdc_bld__profile_`{profile_name}
569 * this symbol is always defined and {profile_name} is the
570 * compile goal's (see `{@link #CompileGoal}`) profile name.
571 * @p 572 *
573 * In addition, each target defines a set of macros that enable clients
574 * to portably support big/little endian targets, for example. These
575 * macros are indirectly included by sources that include `xdc/std.h`;
576 * see `{@link xdc}`.
577 *
578 * @see #OptionSet
579 * @see #CompileGoal
580 * @see xdc
581 */
582 struct CompileOptions {
583 String aopts; /*! goal specific ASM options */
584 String copts; /*! goal specific C compiler options */
585 String defs; /*! goal specific C/ASM definition options */
586 String incs; /*! goal specific C/ASM include options */
587 };
588
589 /*!
590 * ======== OptionSet ========
591 * Collection of tool-chain options.
592 *
593 * This structure is used to define a collection of tool-chain
594 * options that are used as a group to achieve some effect supported
595 * by the tool-chain. For example, some compilers require that
596 * specific options be passed to the compiler *and* linker in order
597 * to generate execution profile information or code coverage
598 * statistics.
599 *
600 * @field(compilerOptions) a set of compiler/assembler options
601 * @field(linkOpts) a string of target-specific linker options
602 * @field(archiveOpts) a string of target-specific archiver options
603 * @field(filters) an array of filters applied (in order) to
604 * tool-chain commands
605 *
606 * @see #profiles
607 */
608 struct OptionSet {
609 CompileOptions compileOpts; /*! profile-specific compiler opts */
610 String linkOpts; /*! profile-specific linker opts */
611 String archiveOpts; /*! profile-specific archiver opts */
612
613 ITargetFilter.InstDesc filters[]; /*! ITargetFilter instance descs */
614 };
615
616 /*!
617 * ======== profiles ========
618 * Profiles supported by this target.
619 *
620 * A profile is a collection of tool options used to create a
621 * library or executable that supports a certain "flavor" of library
622 * or executable; e.g., "debug" or "release".
623 *
624 * Some profile names are supported by all targets even though the
625 * targets use different compilers (and therefore different options).
626 * These profile names makes it possible for a package to build
627 * libraries or executables in a "debug" (or "release") profile
628 * independent of the target, for example.
629 *
630 * All targets are required to support "debug" and "release" profile
631 * names.
632 *
633 * Profile options are added to beginning of any goal specific options
634 * specified by the user before being passed to the target.
635 */
636 config OptionSet profiles[string] = [
637 ["release", {}],
638 ["debug", {}],
639 ];
640
641 /*!
642 * ======== CompileGoal ========
643 * The goal specification passed to the `{@link #compile}`
644 * function.
645 *
646 * @see #compile
647 * @see #scompile
648 */
649 struct CompileGoal {
650 String base; /*! base name of the source and destination */
651 String dstPrefix; /*! directory prefix of destination file */
652 String dstSuffix; /*! suffix of destination file; e.g., ".o62" */
653 String srcSuffix; /*! optional suffix of source file; e.g., ".c" */
654 String srcPrefix; /*! optional directory prefix of source file */
655 String profile; /*! index into profiles map */
656 CompileOptions opts;/*! goal specific compiler options */
657 Bool configOpts; /*! true if compiling the generated C config file */
658 };
659
660 /*!
661 * ======== LinkGoal ========
662 * The goal specification passed to the `{@link #link}` function.
663 *
664 * @see #link
665 */
666 struct LinkGoal {
667 String base; /*! base name of the source and destination */
668 String dstPrefix; /*! directory prefix of destination file */
669 String dstSuffix; /*! suffix of destination file; e.g., ".x62" */
670 String files; /*! string of files to link with */
671 String profile; /*! index into profiles map */
672 String opts; /*! goal specific linker options */
673 Bool dllMode; /*! true if we're linking an assembly */
674 Bool isRom; /*! reflects the `isRom` attribute */
675 };
676
677 /*!
678 * ======== ArchiveGoal ========
679 * The goal specification passed to the `{@link #archive}`
680 * function.
681 *
682 * @see #archive
683 */
684 struct ArchiveGoal {
685 String base; /*! base name of the source and destination */
686 String dstPrefix; /*! directory prefix of destination file */
687 String dstSuffix; /*! suffix of destination file; e.g., ".a62" */
688 String files; /*! String of files to archive */
689 String profile; /*! index into profiles map */
690 String opts; /*! goal specific archiver options */
691 };
692
693 /*!
694 * ======== CommandSet ========
695 * The commands necessary to create a specified goal.
696 *
697 * This structure is the return value of the `{@link #compile}`,
698 * `{@link #link}` and `{@link #archive}` functions. This value is then
699 * used to generate a makefile or any other files necessary to generate
700 * a specified goal.
701 *
702 * @field(msg) a brief synopsis of the commands specified by `cmds`;
703 * this string is output in lieu of `cmds` when building
704 * in "non-verbose" mode.
705 *
706 * @field(cmds) a single string of commands that must be executed
707 * to complete the specified operation. Multiple
708 * commands may be specified by separating each command
709 * with the '\n' character.
710 *
711 * To facilitate the creation of "portable" makefiles and
712 * to simplify the implementation of targets, certain
713 * distinguished "macros" may be embedded in this string.
714 * The build engine replaces these macros with the
715 * values described below.
716 * @p(dlist) 717 * - `$(rootDir)`
718 * the target's `{@link #rootDir}` configuration
719 * parameter
720 * - `$(packageBase)`
721 * the target package's
722 * `{@link xdc.IPackage#packageBase}` property
723 * - `$(XDCINCS)`
724 * a set of "-I" options that names each
725 * repository in the package path
726 * @p 727 *
728 * @field(envs) an array of "name=value" strings that represent
729 * environment variables that are defined prior to the
730 * execution of the commands specified by `cmds`
731 *
732 * @field(path) an array of directory names that are used to compose
733 * the PATH environment variable that is in effect when
734 * the commands specified by `cmds` are run.
735 *
736 * @see #archive
737 * @see #compile
738 * @see #scompile
739 * @see #link
740 */
741 struct CommandSet {
742 String msg; /*! brief message describing subsequent commands */
743 String cmds; /*! commands necessary to generate goal */
744 String path[]; /*! host-independent representation of PATH */
745 String envs[]; /*! environment variable settings for the cmds */
746 };
747
748 /*!
749 * ======== archive ========
750 * Create an archive.
751 *
752 * This function is called during makefile generation to convert build
753 * goals into specific commands that generate the specified goal.
754 *
755 * @param(goal) the `{@link #ArchiveGoal}` defining the archive to build.
756 *
757 * @a(returns) 758 * This function returns a `{@link #CommandSet}`. If non-`null`, this
759 * object defines the commands that must be executed to create the
760 * specified object file. If `null`, then goal can not be achieved.
761 *
762 * @a(throws) `Error` exceptions are thrown for fatal errors.
763 */
764 CommandSet* archive(ArchiveGoal *goal);
765
766 /*!
767 * ======== compile ========
768 * Compile a source file into an object file.
769 *
770 * This function is called during makefile generation to convert build
771 * goals into specific commands that generate the specified object
772 * file goal.
773 *
774 * @param(goal) a `{@link #CompileGoal}` that specifies what file to
775 * compile, the output file name, and any goal-specific
776 * options to use
777 *
778 * @a(returns) 779 * This function retuns a `{@link #CommandSet}`. If non-`null`,
780 * this object defines the commands that must be executed to create the
781 * specified object file. If `null`, then goal can not be achieved.
782 *
783 * @a(throws) `Error` exceptions are thrown for fatal errors.
784 */
785 CommandSet* compile(CompileGoal *goal);
786
787 /*!
788 * ======== scompile ========
789 * Compile a source file into an assembly language file.
790 *
791 * This function is called during makefile generation to convert build
792 * goals into specific commands that generate the specified assembly
793 * language source goal.
794 *
795 * @param(goal) a `{@link #CompileGoal}` that specifies what file to
796 * compile, the output file name, and any goal-specific
797 * options to use
798 *
799 * @a(returns) 800 * This function returns a `{@link #CommandSet}`. If non-`null`, this
801 * object defines the commands that must be executed to create the
802 * specified assembly language file. If `null`, then goal
803 * can not be achieved or is unnecessary (e.g., because
804 * the source file is already an asm file).
805 *
806 * @a(throws) `Error` exceptions are thrown for fatal errors.
807 */
808 CommandSet* scompile(CompileGoal *goal);
809
810 /*!
811 * ======== link ========
812 * Link object files to produce an executable.
813 *
814 * This function is called during makefile generation to convert build
815 * goals into specific commands that generate the specified goal.
816 *
817 * @param(goal) a `{@link #LinkGoal}` that specifies the output file
818 * name, a list of files to link with, and any goal-specific
819 * options to use
820 *
821 * @a(returns) 822 * This function returns a `{@link #CommandSet}`. If non-`null`, this
823 * object defines the commands that must be executed to create the
824 * specified object file. If `null`, then goal can not be
825 * achieved.
826 *
827 * @a(throws) `Error` exceptions are thrown for fatal errors.
828 */
829 CommandSet* link(LinkGoal *goal);
830
831 /*!
832 * ======== getVersion ========
833 * Get a target-specific Compatibility Key string
834 *
835 * This function is called during makefile generation to obtain a
836 * target-specific Compatibility Key string. This string is of the
837 * form:
838 * @p(code) 839 * "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>"
840 * @p 841 * where, `<pkg>.<mod>` is the name of the target, and `<d0>`, `<d1>`,
842 * etc. forms a Compatibility Key.
843 *
844 * @a(returns) 845 * This function returns a string that encodes the name of the target
846 * and its Compatibility Key.
847 *
848 * @a(throws) `Error` exceptions are thrown for fatal errors.
849 */
850 String getVersion();
851
852 typedef String StringArray[];
853
854 /*!
855 * ======== getISAChain ========
856 * Get this target's ISA "is compatible with" relation.
857 *
858 * Returns an array of ISA names (including this target's ISA) that
859 * represents the "is a" relation between ISA's. The array starts with
860 * the most general ISA and ends with this target's ISA or with the
861 * optionally specified argument. This relation is used to:
862 * @p(nlist) 863 * - pre-define macro definitions that enable code to be
864 * conditionally compiled based on compatible versions of a
865 * target's ISA.
866 *
867 * - locate appropriate source files during makefile generation;
868 * each ISA named in a chain causes the extensions ".s"isa to be
869 * added to the ITarget.extensions table (in the reverse order
870 * that they appear in the chain). For example, if a target's
871 * ISA is "64P" and the returned chain is ["62", "64", "64P"],
872 * the following assembly language suffixes are added to
873 * the target's extensions table: ".s64P", ".s64", ".s62".
874 *
875 * - determine the assembly language suffix used during legacy BIOS
876 * configuration; the first element of the target's ISA chain
877 * defines the suffix. For example, if a target's ISA is "64P"
878 * and the returned chain is ["62", "64", "64P"], the assembly
879 * suffix is ".s62".
880 * @p 881 *
882 * This relation may also be used in the future to help validate
883 * combinations of targets and platforms; a target's CPU ISA must
884 * appear on the chain specified by the platform's CPU ISA.
885 *
886 * @param(isa) the ISA identifier string for the ISA to lookup; if null
887 * then the target's ISA is used (ITarget.isa).
888 *
889 * @a(returns) 890 * This function returns an array of ISA strings where the last string
891 * is the optionally specified ISA string or this target's ISA,
892 * and the first string is the "base" ISA in the
893 * is source compatible" relationship.
894 * If the specified ISA string is not in this target's chain
895 * of compatible targets, `null` is returned.
896 *
897 * @a(throws) `Error` exceptions are thrown for fatal errors.
898 *
899 */
900 function getISAChain(isa);
901
902 /*!
903 * ======== findSuffix ========
904 * Find the suffix that is compatible with this target.
905 *
906 * This function determines the list of targets supported by the
907 * package given as the argument. From that list, this function
908 * returns the suffix of a target that is compatible with this target.
909 * Compatibility in this case means that object files created by a
910 * target having the suffix returned by this function can be linked
911 * into an executable produced using this target. In the case where more
912 * than one suffix is compatible, this function returns a suffix in the
913 * following order of preference:
914 * @p(nlist) 915 * - if this target's suffix is in the list, that suffix is returned.
916 *
917 * - suffixes from `compatibleSuffixes` are matched against the list
918 * from the first to the last, and the first one with the match is
919 * returned.
920 * @p 921 *
922 * @param(pkg) a package object or an array of target suffix strings
923 * (see `{@link #suffix}`).
924 *
925 * @a(returns) 926 * This function returns the suffix string of a target compatible with
927 * this target or `null` if `pkg` does not support any target compatible
928 * with this target.
929 *
930 */
931 function findSuffix(pkg);
932
933 /*!
934 * ======== selectSuffix ========
935 * Select the suffix that is compatible with this target.
936 *
937 * From a list of suffixes supplied as an argument, this function
938 * returns the suffix compatible with this target. Compatibility in
939 * this case means that object files created by a target having the
940 * suffix returned by this function can be linked into an executable
941 * produced using this target. In the case where more than one suffix
942 * is compatible, this function returns a suffix in the following order
943 * of preference:
944 * @p(nlist) 945 * - if this target's suffix is in the list, that suffix is returned.
946 *
947 * - suffixes from `compatibleSuffixes` are matched against the list
948 * from the first to the last, and the first one with the match is
949 * returned.
950 * @p 951 *
952 * @param(suffixList) an array of target suffix strings
953 * (see `{@link #suffix}`).
954 *
955 * @a(returns) 956 * This function returns the suffix string of a target compatible with
957 * this target or `null` if no such suffix is found in the list of
958 * suffixes specified by the first argument.
959 *
960 */
961 String selectSuffix(StringArray suffixList);
962
963 /*!
964 * ======== sectMap ========
965 * Output section name to segment type mapping
966 *
967 * This hash table is used to determine whether a particular object file
968 * output section (".text", ".stack", etc.) requires 'data', 'code' or
969 * 'stack' memory segment.
970 *
971 * This `sectMap` is referenced by linker command file templates during
972 * generation to create linker command files. The Platform defines the
973 * default memory segments for code and data, and based on this map and
974 * the default segments, the linker command file template places an
975 * output section into a physical memory segment.
976 *
977 * Note that the `{@link xdc.cfg.Program}` object and the
978 * `{@link xdc.platform.IPlatform}` instance have a
979 * `sectMap` parameter. Both the `Program`'s and `IPlatform`'s `sectMap`
980 * can augment and/or override the placement for a section, but
981 * `{@link xdc.cfg.Program#sectMap}` takes precedence. Therefore, this
982 * `sectMap` and the default segments from the platform define an
983 * initial section map which is then augmented by the `Program`'s and
984 * `IPlatform`'s section map.
985 */
986 readonlyconfig String sectMap[string];
987
988 /*!
989 * ======== TypeInfo ========
990 * @_nodoc 991 *
992 * @see #StdTypes
993 */
994 struct TypeInfo {
995 int size;
996 int align;
997 }
998
999 /*!
1000 * ======== StdTypes ========
1001 * Standard base types supported by all targets
1002 *
1003 * @see #stdTypes
1004 */
1005 struct StdTypes {
1006 TypeInfo t_IArg;
1007 TypeInfo t_Char;
1008 TypeInfo t_Double;
1009 TypeInfo t_Float;
1010 TypeInfo t_Fxn;
1011 TypeInfo t_Int;
1012 TypeInfo t_Int8;
1013 TypeInfo t_Int16;
1014 TypeInfo t_Int32;
1015 TypeInfo t_Int40;
1016 TypeInfo t_Int64;
1017 TypeInfo t_Long;
1018 TypeInfo t_LDouble;
1019 TypeInfo t_LLong;
1020 TypeInfo t_Ptr;
1021 TypeInfo t_Short;
1022 }
1023
1024 /*!
1025 * ======== stdInclude ========
1026 * Standard C/C++ types header
1027 *
1028 * This string identifies a header containing the C/C++ definitions
1029 * required to enable use of `xdc/std.h` in C/C++ sources; see
1030 * `{@link xdc}`.
1031 *
1032 * The value of this string is used by `xdc/std.h` to include
1033 * target-specific definitions of the types `Int8`, `Int16`, etc. In
1034 * addition, this header supplies target-specific definitions of the
1035 * predefined `xdc_target__*` macros required by `{@link xdc xdc/std.h}`.
1036 *
1037 * Since this header must supply target-specific values for
1038 * target-independent names the structure of this header is usually of
1039 * the form:
1040 * @p(code) 1041 * // if target macros are not already defined,
1042 * #if !defined(xdc_target_macros_include__)
1043 * // include target-specific definitions
1044 * #if defined(TARGET1)
1045 * #include "target1.h"
1046 * #elif defined(TARGET2)
1047 * #include "target2.h"
1048 * #elif ...
1049 * :
1050 * #else
1051 * #error unsupported target
1052 * #endif
1053 * #endif
1054 * // include common definitions
1055 * :
1056 * @p 1057 * The check of the symbol `xdc_target_macros_include__` exists to
1058 * allow others that define new targets to include this header to
1059 * get common definitions for a family of related targets.
1060 *
1061 * To simplify the creation of the target-specific header files, the
1062 * template file `stddefs.xdt` in this package can be used to
1063 * automatically generate the required definitions from each target's
1064 * `.xdc` specification.
1065 */
1066 readonlyconfig String stdInclude;
1067
1068 /*!
1069 * ======== stdTypes ========
1070 * Size and alignment for standard base types
1071 *
1072 * The values of size are the values returned by the
1073 * target-specific `sizeof()` operator applied to the specified
1074 * type (as defined by the C language). The align value is the number
1075 * of chars used in the alignment of the specified type.
1076 */
1077 readonlyconfig StdTypes stdTypes = {
1078 t_IArg : { size: 0, align: 0 },
1079 t_Char : { size: 0, align: 0 },
1080 t_Double : { size: 0, align: 0 },
1081 t_Float : { size: 0, align: 0 },
1082 t_Fxn : { size: 0, align: 0 },
1083 t_Int : { size: 0, align: 0 },
1084 t_Int8 : { size: 0, align: 0 },
1085 t_Int16 : { size: 0, align: 0 },
1086 t_Int32 : { size: 0, align: 0 },
1087 t_Int40 : { size: 0, align: 0 },
1088 t_Int64 : { size: 0, align: 0 },
1089 t_Long : { size: 0, align: 0 },
1090 t_LDouble : { size: 0, align: 0 },
1091 t_LLong : { size: 0, align: 0 },
1092 t_Ptr : { size: 0, align: 0 },
1093 t_Short : { size: 0, align: 0 },
1094 };
1095
1096 /*!
1097 * ======== bitsPerChar ========
1098 * The number of bits in a variable of type `char`
1099 *
1100 * This constant allows one to determine the precise number of bits in
1101 * each of the types specified in the stdTypes map. For example, the
1102 * number of bits in the target t's `int` type is
1103 * @p(code) 1104 * t.stdTypes.t_Int.size * t.bitsPerChar
1105 * @p 1106 */
1107 readonlyconfig Int bitsPerChar = 8;
1108 }
1109 /*
1110 * @(#) xdc.bld; 1, 0, 2,208; 6-9-2009 20:08:43; /db/ztree/library/trees/xdc-t50x/src/packages/
1111 */
1112