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 *
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
113 * should produce 100% EABI compatible objects and, targets with different
114 * suffixes should produce 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 ?? interface. This
296 * 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 *
417 * @see #debugGen
418 */
419 struct DebugGen {
420 String execTemplate; /*! debugger template for executable */
421 String execPattern; /*! exec file name pattern */
422 String packageTemplate; /*! debugger template for package */
423 String packagePattern; /*! package file name pattern */
424 }
425
426 /*!
427 * ======== debugGen ========
428 * Debugger/IDE file generation support.
429 *
430 * This parameter allows one to automatically generate files that
431 * can be used by an IDE to more easily debug (and possibly rebuild)
432 * specified goals.
433 *
434 * To avoid unnecessary build time overhead, these files are not always
435 * generated; by default, they are only generated for "debug" profiles.
436 * The generation of these files is controlled by the
437 * `{@link xdc.cfg.Program#gen}` configuration parameter. To force these
438 * files to be generated for a particular executable, add the following
439 * line to the executable's program configuration script:
440 * @p(code)
441 * Program.gen.debuggerFiles = true;
442 * @p
443 *
444 * It is also possible to disable the generation of selected files by
445 * setting the appropriate fields of `{@link #DebugGen}` to `null` in
446 * your `config.bld` script.
447 */
448 config DebugGen debugGen;
449
450 /*!
451 * ======== Extension ========
452 * File extension to file type association.
453 *
454 * This structure is used by the Build Engine to determine whether a
455 * file should be treated as C++, C, or assembly language source.
456 *
457 * @field(suf) the file extension including any '.' characters
458 *
459 * @field(typ) the type of the file having this extension.
460 * Allowable file type identifiers include:
461 * @p(dlist)
462 * - `"c"`
463 * C language source file
464 * - `"asm"`
465 * assembly language source file
466 * - `"cpp"`
467 * C++ language source file
468 *
469 * @see #extensions
470 */
471 struct Extension {
472 String suf; /*! file extension (including any '.') */
473 String typ; /*! type of this file; e.g., `"c"`, `"asm"`, ... */
474 };
475
476 /*!
477 * ======== extensions ========
478 * File extensions recognized by this target.
479 *
480 * This is a user modifiable table used to customize file extensions
481 * recognized by each target.
482 *
483 * For example, to add a new assembly language extension, say "`.s64`",
484 * to the target `ti.targets.C64P`, add the following lines to the
485 * build model startup script:
486 * @p(code)
487 * var C64P = xdc.module('ti.targets.C64P');
488 * C64P.extensions[".s64"] = {
489 * suf: ".s64", typ: "asm"
490 * };
491 * @p
492 * Note that individual targets may add additional language types.
493 *
494 * It is also possible to remove default extensions. For example, to
495 * remove the "`.asm`" extension from the target `ti.targets.C64P`, add
496 * the following lines to the build model startup script:
497 * @p(code)
498 * var C64P = xdc.module('ti.targets.C64P');
499 * delete C64P.extensions[".asm"];
500 * @p
501 */
502 config Extension extensions[string] = [
503 [".asm", {suf: ".asm", typ: "asm"}],
504 [".c", {suf: ".c", typ: "c" }],
505 [".cpp", {suf: ".cpp", typ: "cpp"}],
506 [".cxx", {suf: ".cxx", typ: "cpp"}],
507 [".C", {suf: ".C", typ: "cpp"}],
508 [".cc", {suf: ".cc", typ: "cpp"}],
509 ];
510
511 /*!
512 * ======== versionMap ========
513 * Map of compiler version numbers to compatibility keys.
514 *
515 * `versionMap` is a user modifiable table used to map tool-chain
516 * version numbers to Compatibility Keys.
517 *
518 * Each target defines the format of the tool-chain version obtained
519 * from the tool-chain. The user can then map new tool-chain version
520 * strings to an appropriate compatibility key.
521 *
522 * Each target must respect the mapping defined by this table; i.e.,
523 * if the user supplies a compatibility key in this map, it must be
524 * returned when `{@link #getVersion()}` is called.
525 *
526 * Thus, it is possible for the user to assert that any two compiler
527 * tool chains should be treated as equivalent (or incompatible) by
528 * mapping their version numbers to identical (incompatible)
529 * compatibility keys.
530 *
531 * @see ti.targets.ITarget#versionMap
532 */
533 config String versionMap[string] = [
534 ];
535
536 /*!
537 * ======== alignDirectiveSupported ========
538 * The compiler supports an align directive.
539 */
540 readonly config Bool alignDirectiveSupported = false;
541
542 /*!
543 * ======== rootDir ========
544 * Installation directory for this target's code generation tools.
545 *
546 * Since each target potentially "wraps" a different compiler tool-chain
547 * and each tool-chain will, in general, assume a different physical
548 * design for the installation of the compiler and its associated
549 * libraries and headers, one must consult each specific target to know
550 * how to set this parameter.
551 *
552 * If the `{@link #base}` parameter is `null`, this parameter *must* be
553 * set by the user; otherwise, `rootDir` defaults to the value
554 * `base.rootDir`.
555 */
556 config String rootDir;
557
558 /*!
559 * ======== CompileOptions ========
560 * Options passed to the compiler/assembler.
561 *
562 * @field(aopts) a string of target-specific assembler options
563 * @field(copts) a string of target-specific C/C++ compiler options
564 * @field(cfgcopts) a string of C/C++ compiler options for C config file,
565 * includes 'copts' in addition to the value passed
566 * @field(defs) a string of macro definitions each of the form
567 * "`-Dname=value`" separated by white space
568 * @field(incs) a string of include directories each of the form
569 * "`-Idir`" separated by white space
570 *
571 * @a(Predefined Macros)
572 * The XDC Build Engine automatically adds several predefined macros via
573 * `-D` definitions that enable conditional compilation of source files
574 * based on build-specific attributes.
575 * @p(dlist)
576 * - `xdc_bld__profile_`{profile_name}
577 * this symbol is always defined and {profile_name} is the
578 * compile goal's (see `{@link #CompileGoal}`) profile name.
579 * @p
580 *
581 * In addition, each target defines a set of macros that enable clients
582 * to portably support big/little endian targets, for example. These
583 * macros are indirectly included by sources that include `xdc/std.h`;
584 * see `{@link xdc}`.
585 *
586 * @see #OptionSet
587 * @see #CompileGoal
588 * @see xdc
589 */
590 struct CompileOptions {
591 String aopts; /*! goal specific ASM options */
592 String copts; /*! goal specific C compiler options */
593 String cfgcopts; /*! goal specific C config file options */
594 String defs; /*! goal specific C/ASM definition options */
595 String incs; /*! goal specific C/ASM include options */
596 };
597
598 /*!
599 * ======== OptionSet ========
600 * Collection of tool-chain options.
601 *
602 * This structure is used to define a collection of tool-chain
603 * options that are used as a group to achieve some effect supported
604 * by the tool-chain. For example, some compilers require that
605 * specific options be passed to the compiler *and* linker in order
606 * to generate execution profile information or code coverage
607 * statistics.
608 *
609 * @field(compilerOptions) a set of compiler/assembler options
610 * @field(linkOpts) a string of target-specific linker options
611 * @field(archiveOpts) a string of target-specific archiver options
612 * @field(filters) an array of filters applied (in order) to
613 * tool-chain commands
614 *
615 * @see #profiles
616 */
617 struct OptionSet {
618 CompileOptions compileOpts; /*! profile-specific compiler opts */
619 String linkOpts; /*! profile-specific linker opts */
620 String archiveOpts; /*! profile-specific archiver opts */
621
622 ITargetFilter.InstDesc filters[]; /*! ITargetFilter instance descs */
623 };
624
625 /*!
626 * ======== profiles ========
627 * Profiles supported by this target.
628 *
629 * A profile is a collection of tool options used to create a
630 * library or executable that supports a certain "flavor" of library
631 * or executable; e.g., "debug" or "release".
632 *
633 * Some profile names are supported by all targets even though the
634 * targets use different compilers (and therefore different options).
635 * These profile names makes it possible for a package to build
636 * libraries or executables in a "debug" (or "release") profile
637 * independent of the target, for example.
638 *
639 * All targets are required to support "debug" and "release" profile
640 * names.
641 *
642 * Profile options are added to beginning of any goal specific options
643 * specified by the user before being passed to the target.
644 */
645 config OptionSet profiles[string] = [
646 ["release", {}],
647 ["debug", {}],
648 ];
649
650 /*!
651 * ======== CompileGoal ========
652 * The goal specification passed to the `{@link #compile}`
653 * function.
654 *
655 * @see #compile
656 * @see #scompile
657 */
658 struct CompileGoal {
659 String base; /*! base name of the source and destination */
660 String dstPrefix; /*! directory prefix of destination file */
661 String dstSuffix; /*! suffix of destination file; e.g., ".o62" */
662 String srcSuffix; /*! optional suffix of source file; e.g., ".c" */
663 String srcPrefix; /*! optional directory prefix of source file */
664 String profile; /*! index into profiles map */
665 CompileOptions opts;/*! goal specific compiler options */
666 Bool configOpts; /*! true if compiling the generated C config file */
667 };
668
669 /*!
670 * ======== LinkGoal ========
671 * The goal specification passed to the `{@link #link}` function.
672 *
673 * @see #link
674 */
675 struct LinkGoal {
676 String base; /*! base name of the source and destination */
677 String dstPrefix; /*! directory prefix of destination file */
678 String dstSuffix; /*! suffix of destination file; e.g., ".x62" */
679 String files; /*! string of files to link with */
680 String profile; /*! index into profiles map */
681 String opts; /*! goal specific linker options */
682 Bool dllMode; /*! true if we're linking an assembly */
683 Bool isRom; /*! reflects the `isRom` attribute */
684 };
685
686 /*!
687 * ======== ArchiveGoal ========
688 * The goal specification passed to the `{@link #archive}`
689 * function.
690 *
691 * @see #archive
692 */
693 struct ArchiveGoal {
694 String base; /*! base name of the source and destination */
695 String dstPrefix; /*! directory prefix of destination file */
696 String dstSuffix; /*! suffix of destination file; e.g., ".a62" */
697 String files; /*! String of files to archive */
698 String profile; /*! index into profiles map */
699 String opts; /*! goal specific archiver options */
700 };
701
702 /*!
703 * ======== CommandSet ========
704 * The commands necessary to create a specified goal.
705 *
706 * This structure is the return value of the `{@link #compile}`,
707 * `{@link #link}` and `{@link #archive}` functions. This value is then
708 * used to generate a makefile or any other files necessary to generate
709 * a specified goal.
710 *
711 * @field(msg) a brief synopsis of the commands specified by `cmds`;
712 * this string is output in lieu of `cmds` when building
713 * in "non-verbose" mode.
714 *
715 * @field(cmds) a single string of commands that must be executed
716 * to complete the specified operation. Multiple
717 * commands may be specified by separating each command
718 * with the '\n' character.
719 *
720 * To facilitate the creation of "portable" makefiles and
721 * to simplify the implementation of targets, certain
722 * distinguished "macros" may be embedded in this string.
723 * The build engine replaces these macros with the
724 * values described below.
725 * @p(dlist)
726 * - `$(rootDir)`
727 * the target's `{@link #rootDir}` configuration
728 * parameter
729 * - `$(packageBase)`
730 * the target package's
731 * `{@link xdc.IPackage#packageBase}` property
732 * - `$(XDCINCS)`
733 * a set of "-I" options that names each
734 * repository in the package path
735 * @p
736 *
737 * @field(envs) an array of "name=value" strings that represent
738 * environment variables that are defined prior to the
739 * execution of the commands specified by `cmds`
740 *
741 * @field(path) an array of directory names that are used to compose
742 * the PATH environment variable that is in effect when
743 * the commands specified by `cmds` are run.
744 *
745 * @see #archive
746 * @see #compile
747 * @see #scompile
748 * @see #link
749 */
750 struct CommandSet {
751 String msg; /*! brief message describing subsequent commands */
752 String cmds; /*! commands necessary to generate goal */
753 String path[]; /*! host-independent representation of PATH */
754 String envs[]; /*! environment variable settings for the cmds */
755 };
756
757 /*!
758 * ======== archive ========
759 * Create an archive.
760 *
761 * This function is called during makefile generation to convert build
762 * goals into specific commands that generate the specified goal.
763 *
764 * @param(goal) the `{@link #ArchiveGoal}` defining the archive to build.
765 *
766 * @a(returns)
767 * This function returns a `{@link #CommandSet}`. If non-`null`, this
768 * object defines the commands that must be executed to create the
769 * specified object file. If `null`, then goal can not be achieved.
770 *
771 * @a(throws) `Error` exceptions are thrown for fatal errors.
772 */
773 CommandSet* archive(ArchiveGoal *goal);
774
775 /*!
776 * ======== compile ========
777 * Compile a source file into an object file.
778 *
779 * This function is called during makefile generation to convert build
780 * goals into specific commands that generate the specified object
781 * file goal.
782 *
783 * @param(goal) a `{@link #CompileGoal}` that specifies what file to
784 * compile, the output file name, and any goal-specific
785 * options to use
786 *
787 * @a(returns)
788 * This function retuns a `{@link #CommandSet}`. If non-`null`,
789 * this object defines the commands that must be executed to create the
790 * specified object file. If `null`, then goal can not be achieved.
791 *
792 * @a(throws) `Error` exceptions are thrown for fatal errors.
793 */
794 CommandSet* compile(CompileGoal *goal);
795
796 /*!
797 * ======== scompile ========
798 * Compile a source file into an assembly language file.
799 *
800 * This function is called during makefile generation to convert build
801 * goals into specific commands that generate the specified assembly
802 * language source goal.
803 *
804 * @param(goal) a `{@link #CompileGoal}` that specifies what file to
805 * compile, the output file name, and any goal-specific
806 * options to use
807 *
808 * @a(returns)
809 * This function returns a `{@link #CommandSet}`. If non-`null`, this
810 * object defines the commands that must be executed to create the
811 * specified assembly language file. If `null`, then goal
812 * can not be achieved or is unnecessary (e.g., because
813 * the source file is already an asm file).
814 *
815 * @a(throws) `Error` exceptions are thrown for fatal errors.
816 */
817 CommandSet* scompile(CompileGoal *goal);
818
819 /*!
820 * ======== link ========
821 * Link object files to produce an executable.
822 *
823 * This function is called during makefile generation to convert build
824 * goals into specific commands that generate the specified goal.
825 *
826 * @param(goal) a `{@link #LinkGoal}` that specifies the output file
827 * name, a list of files to link with, and any goal-specific
828 * options to use
829 *
830 * @a(returns)
831 * This function returns a `{@link #CommandSet}`. If non-`null`, this
832 * object defines the commands that must be executed to create the
833 * specified object file. If `null`, then goal can not be
834 * achieved.
835 *
836 * @a(throws) `Error` exceptions are thrown for fatal errors.
837 */
838 CommandSet* link(LinkGoal *goal);
839
840 /*!
841 * ======== getVersion ========
842 * Get a target-specific Compatibility Key string
843 *
844 * This function is called during makefile generation to obtain a
845 * target-specific Compatibility Key string. This string is of the
846 * form:
847 * @p(code)
848 * "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>"
849 * @p
850 * where, `<pkg>.<mod>` is the name of the target, and `<d0>`, `<d1>`,
851 * etc. forms a Compatibility Key.
852 *
853 * @a(returns)
854 * This function returns a string that encodes the name of the target
855 * and its Compatibility Key.
856 *
857 * @a(throws) `Error` exceptions are thrown for fatal errors.
858 */
859 String getVersion();
860
861 typedef String StringArray[];
862
863 /*!
864 * ======== getISAChain ========
865 * Get this target's ISA "is compatible with" relation.
866 *
867 * Returns an array of ISA names (including this target's ISA) that
868 * represents the "is a" relation between ISA's. The array starts with
869 * the most general ISA and ends with this target's ISA or with the
870 * optionally specified argument. This relation is used to:
871 * @p(nlist)
872 * - pre-define macro definitions that enable code to be
873 * conditionally compiled based on compatible versions of a
874 * target's ISA.
875 *
876 * - locate appropriate source files during makefile generation;
877 * each ISA named in a chain causes the extensions ".s"isa to be
878 * added to the ITarget.extensions table (in the reverse order
879 * that they appear in the chain). For example, if a target's
880 * ISA is "64P" and the returned chain is ["62", "64", "64P"],
881 * the following assembly language suffixes are added to
882 * the target's extensions table: ".s64P", ".s64", ".s62".
883 * @p
884 *
885 * This relation may also be used in the future to help validate
886 * combinations of targets and platforms; a target's CPU ISA must
887 * appear on the chain specified by the platform's CPU ISA.
888 *
889 * @param(isa) the ISA identifier string for the ISA to lookup; if null
890 * then the target's ISA is used (ITarget.isa).
891 *
892 * @a(returns)
893 * This function returns an array of ISA strings where the last string
894 * is the optionally specified ISA string or this target's ISA,
895 * and the first string is the "base" ISA in the
896 * is source compatible" relationship.
897 * If the specified ISA string is not in this target's chain
898 * of compatible targets, `null` is returned.
899 *
900 * @a(throws) `Error` exceptions are thrown for fatal errors.
901 *
902 */
903 function getISAChain(isa);
904
905 /*!
906 * ======== findSuffix ========
907 * Find the suffix that is compatible with this target.
908 *
909 * This function determines the list of targets supported by the
910 * package given as the argument. From that list, this function
911 * returns the suffix of a target that is compatible with this target.
912 * Compatibility in this case means that object files created by a
913 * target having the suffix returned by this function can be linked
914 * into an executable produced using this target. In the case where more
915 * than one suffix is compatible, this function returns a suffix in the
916 * following order of preference:
917 * @p(nlist)
918 * - if this target's suffix is in the list, that suffix is returned.
919 *
920 * - suffixes from `compatibleSuffixes` are matched against the list
921 * in the order they appear in `compatibleSuffixes`, and the first one
922 * found in the list is returned.
923 * @p
924 *
925 * @param(pkg) a package object or an array of target suffix strings
926 * (see `{@link #suffix}`).
927 *
928 * @a(returns)
929 * This function returns the suffix string of a target compatible with
930 * this target or `null` if `pkg` does not support any target compatible
931 * with this target.
932 *
933 */
934 function findSuffix(pkg);
935
936 /*!
937 * ======== selectSuffix ========
938 * Select the suffix that is compatible with this target.
939 *
940 * From a list of suffixes supplied as an argument, this function
941 * returns the suffix compatible with this target. Compatibility in
942 * this case means that object files created by a target having the
943 * suffix returned by this function can be linked into an executable
944 * produced using this target. In the case where more than one suffix
945 * is compatible, this function returns a suffix in the following order
946 * of preference:
947 * @p(nlist)
948 * - if this target's suffix is in the list, that suffix is returned.
949 *
950 * - suffixes from `compatibleSuffixes` are matched against the list
951 * in the order they appear in `compatibleSuffixes`, and the first one
952 * found in the list is returned.
953 * @p
954 *
955 * @param(suffixList) an array of target suffix strings
956 * (see `{@link #suffix}`).
957 *
958 * @a(returns)
959 * This function returns the suffix string of a target compatible with
960 * this target or `null` if no such suffix is found in the list of
961 * suffixes specified by the first argument.
962 *
963 */
964 String selectSuffix(StringArray suffixList);
965
966 /*!
967 * ======== sectMap ========
968 * Output section name to segment type mapping
969 *
970 * This hash table is used to determine whether a particular object file
971 * output section (".text", ".stack", etc.) requires 'data', 'code' or
972 * 'stack' memory segment.
973 *
974 * This `sectMap` is referenced by linker command file templates during
975 * generation to create linker command files. The Platform defines the
976 * default memory segments for code and data, and based on this map and
977 * the default segments, the linker command file template places an
978 * output section into a physical memory segment.
979 *
980 * Note that the `{@link xdc.cfg.Program}` object and the
981 * `{@link xdc.platform.IPlatform}` instance have a
982 * `sectMap` parameter. Both the `Program`'s and `IPlatform`'s `sectMap`
983 * can augment and/or override the placement for a section, but
984 * `{@link xdc.cfg.Program#sectMap}` takes precedence. Therefore, this
985 * `sectMap` and the default segments from the platform define an
986 * initial section map which is then augmented by the `Program`'s and
987 * `IPlatform`'s section map.
988 */
989 readonly config String sectMap[string];
990
991 /*!
992 * ======== TypeInfo ========
993 * @_nodoc
994 *
995 * @see #StdTypes
996 */
997 struct TypeInfo {
998 int size;
999 int align;
1000 }
1001
1002 /*!
1003 * ======== StdTypes ========
1004 * Standard base types supported by all targets
1005 *
1006 * @see #stdTypes
1007 */
1008 struct StdTypes {
1009 TypeInfo t_IArg;
1010 TypeInfo t_Char;
1011 TypeInfo t_Double;
1012 TypeInfo t_Float;
1013 TypeInfo t_Fxn;
1014 TypeInfo t_Int;
1015 TypeInfo t_Int8;
1016 TypeInfo t_Int16;
1017 TypeInfo t_Int32;
1018 TypeInfo t_Int40;
1019 TypeInfo t_Int64;
1020 TypeInfo t_Long;
1021 TypeInfo t_LDouble;
1022 TypeInfo t_LLong;
1023 TypeInfo t_Ptr;
1024 TypeInfo t_Short;
1025 TypeInfo t_Size;
1026 }
1027
1028 /*!
1029 * ======== stdInclude ========
1030 * Standard C/C++ types header
1031 *
1032 * This string identifies a header containing the C/C++ definitions
1033 * required to enable use of `xdc/std.h` in C/C++ sources; see
1034 * `{@link xdc}`.
1035 *
1036 * The value of this string is used by `xdc/std.h` to include
1037 * target-specific definitions of the types `Int8`, `Int16`, etc. In
1038 * addition, this header supplies target-specific definitions of the
1039 * predefined `xdc_target__*` macros required by `{@link xdc xdc/std.h}`.
1040 *
1041 * Since this header must supply target-specific values for
1042 * target-independent names the structure of this header is usually of
1043 * the form:
1044 * @p(code)
1045 * // if target macros are not already defined,
1046 * #if !defined(xdc_target_macros_include__)
1047 * // include target-specific definitions
1048 * #if defined(TARGET1)
1049 * #include "target1.h"
1050 * #elif defined(TARGET2)
1051 * #include "target2.h"
1052 * #elif ...
1053 * :
1054 * #else
1055 * #error unsupported target
1056 * #endif
1057 * #endif
1058 * // include common definitions
1059 * :
1060 * @p
1061 * The check of the symbol `xdc_target_macros_include__` exists to
1062 * allow others that define new targets to include this header to
1063 * get common definitions for a family of related targets.
1064 *
1065 * To simplify the creation of the target-specific header files, the
1066 * template file `stddefs.xdt` in this package can be used to
1067 * automatically generate the required definitions from each target's
1068 * `.xdc` specification.
1069 */
1070 readonly config String stdInclude;
1071
1072 /*!
1073 * ======== stdTypes ========
1074 * Size and alignment for standard base types
1075 *
1076 * The values of size are the values returned by the
1077 * target-specific `sizeof()` operator applied to the specified
1078 * type (as defined by the C language). The align value is the number
1079 * of chars used in the alignment of the specified type.
1080 */
1081 readonly config StdTypes stdTypes = {
1082 t_IArg : { size: 0, align: 0 },
1083 t_Char : { size: 0, align: 0 },
1084 t_Double : { size: 0, align: 0 },
1085 t_Float : { size: 0, align: 0 },
1086 t_Fxn : { size: 0, align: 0 },
1087 t_Int : { size: 0, align: 0 },
1088 t_Int8 : { size: 0, align: 0 },
1089 t_Int16 : { size: 0, align: 0 },
1090 t_Int32 : { size: 0, align: 0 },
1091 t_Int40 : { size: 0, align: 0 },
1092 t_Int64 : { size: 0, align: 0 },
1093 t_Long : { size: 0, align: 0 },
1094 t_LDouble : { size: 0, align: 0 },
1095 t_LLong : { size: 0, align: 0 },
1096 t_Ptr : { size: 0, align: 0 },
1097 t_Short : { size: 0, align: 0 },
1098 t_Size : { size: 0, align: 0 },
1099 };
1100
1101 /*!
1102 * ======== bitsPerChar ========
1103 * The number of bits in a variable of type `char`
1104 *
1105 * This constant allows one to determine the precise number of bits in
1106 * each of the types specified in the stdTypes map. For example, the
1107 * number of bits in the target `T`'s `int` type is
1108 * @p(code)
1109 * T.stdTypes.t_Int.size * T.bitsPerChar
1110 * @p
1111 */
1112 readonly config Int bitsPerChar = 8;
1113 }
1114 1115 1116
1117