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