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