1 /*
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * */
12 /*
13 * ======== ITarget.xdc ========
14 */
15 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 metaonlyinterface 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 readonlyconfig 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 readonlyconfig 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 readonlyconfig 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 readonlyconfig 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 readonlyconfig 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}. It is also not included if the
204 * executable is a legacy DSP/BIOS program.
205 */
206 readonlyconfig String rts;
207
208 /*!
209 * ======== base ========
210 * A target that this target is based upon.
211 *
212 * If non-`null`, this target shares the same tool-chain of the specified
213 * base target. This parameter is used to determine various default
214 * values for target configuration parameters. For example, the default
215 * setting of `{@link #rootDir}` is the value of the base's
216 * `{@link #rootDir}` setting.
217 */
218 readonlyconfig ITarget.Module base;
219
220 /*!
221 * ======== dllExt ========
222 * @_nodoc dlls are not yet fully supported
223 */
224 config String dllExt;
225
226 /*!
227 * ======== execExt ========
228 * Extension for executables.
229 *
230 * Operating systems and tools often have a strong preference for a
231 * specific extension for executables; e.g., Windows expects executables
232 * to have the extension "`.exe`". If this parameter is set, executables
233 * will be given the specified extension instead of the default
234 * "`.x<suffix>`", where `<suffix>` is the target's suffix parameter.
235 *
236 * The `execExt` is an expression that is expanded prior to use.
237 * Expressions of the form "`$(name)`" within the
238 * pattern string are expanded if "`name`" is one of the built-in
239 * variables listed below.
240 *
241 * Built-in variables for `execExt`:
242 * @p(dlist) 243 * - `trgName`
244 * the target's `name` property
245 * - `trgSuffix`
246 * the target's `suffix` property
247 * - `platPName`
248 * the executable's platform package name
249 * - `platIName`
250 * the executable's platform instance name
251 * @p 252 *
253 * @a(Example) If you want to build a portable executable for multiple
254 * targets side-by-side and you want (or need) to use a fixed extension
255 * such as ".out" for all executables, setting `execExt` to
256 * `"_$(trgSuffix).out"` for all targets ensures that all generated
257 * executables will have unique names and yet share a common extension
258 * of `".out"`.
259 */
260 config String execExt;
261
262 /*!
263 * ======== platform ========
264 * The default platform name for this target
265 *
266 * Build scripts often build for just one platform per target. This
267 * parameter allows one to establish a default platform for each
268 * target in a build.
269 *
270 * If this parameter is `null` or `undefined` and `{@link #platforms}`
271 * array is non-empty, it is initialized to be the first element of the
272 * platforms array (i.e., `{@link #platforms[0]}`).
273 */
274 config String platform;
275
276 /*!
277 * ======== platforms ========
278 * A set of platforms that can support this target
279 *
280 * Some build scripts build executables for "all" platforms; e.g.,
281 * regression test suites. This parameter allows one to establish
282 * a set of platforms that build scripts can legitimately use to
283 * create executables, for example.
284 *
285 * If this array is empty (i.e., has length 0) and `{@link #platform}`
286 * is non-`null`, platforms is initialized to an array of one element
287 * equal to `{@link #platform}`.
288 */
289 config String platforms[] = [];
290
291 /*!
292 * ======== binaryParser ========
293 * The name of a object file parser
294 *
295 * The value of this configuration parameter is the name of a
296 * module or Java class that implements the ?? interface. This
297 * interface is used to extract information from the object files
298 * produced by this target.
299 *
300 * @_nodoc object file readers are not yet fully supported
301 */
302 config String binaryParser;
303
304 /*!
305 * ======== version ========
306 * The Compatibility Key associated with this target.
307 *
308 * @a(Readonly) This value is automatically computed by the XDC Build
309 * Engine by executing the `{@link #getVersion()}` function after
310 * `package.bld` completes but prior to generating `package.mak`.
311 */
312 config String version;
313
314 /*!
315 * ======== versionRaw ========
316 * The unmodified version string associated with this target.
317 *
318 * @a(Readonly) This value is automatically computed by the XDC Build
319 * Engine by executing the `{@link #getVersion()}` function after
320 * `package.bld` completes but prior to generating `package.mak`.
321 *
322 * @_nodoc 323 */
324 config String versionRaw;
325
326 /*!
327 * ======== DebugGen ========
328 * Debugger integration support.
329 *
330 * This structure specifies additional files that are generated
331 * in order to support integration with a debugger. For example, the
332 * default setting for TI targets specifies the generation of CCS
333 * project files that allow one to easily debug executables that have
334 * been constructed from multiple packages.
335 *
336 * There are two "types" of debug support files that are generated;
337 * one for the package as a whole, and one for each executable.
338 * Since packages may contain portable sources that are built for more
339 * than one target, a "package-level" file is generated for each target
340 * used in the package. A separate file is generated for each
341 * executable built within the package.
342 *
343 * The `execTemplate` and `packageTemplate` fields name a template that
344 * is expanded in the context of the config model and the build
345 * model, respectively. These fields should be set to a file name
346 * string which is relative to the package path; e.g., the string
347 * "`ti/targets/cc_exec.xdt`" refers to the file "`cc_exec.xdt`" in the
348 * `ti.targets` package located along the package path.
349 *
350 * Preconditions for the `execTemplate`:
351 * @p(dlist) 352 * - `this`
353 * the configured program object (`xdc.cfg.Program`);
354 * i.e., the program object *after* the program's
355 * configuration script completes.
356 * - `$args`
357 * array of arguments passed to the template
358 *
359 * - `$args[1]`
360 * the name of the executable being produced for this
361 * configuration.
362 *
363 * - `environment`
364 * hash table of XDC global parameters; e.g., `"xdc.path"`,
365 * `"xdc.root"`, ...
366 * @p 367 * Preconditions for the `packageTemplate`:
368 * @p(dlist) 369 * - `this`
370 * the "package contents" object (i.e.,
371 * `xdc.bld.PackageContents`) *after* the package's
372 * build script (`package.bld`) completes.
373 * - `$args`
374 * array of arguments passed to the template
375 *
376 * - `$args[0]`
377 * the target (a module implementing the
378 * `{@link xdc.bld.ITarget}` interface)
379 *
380 * - `$args[1]`
381 * hash-table of all package sources
382 *
383 * - `environment`
384 * hash table of XDC global parameters; e.g., `"xdc.path"`,
385 * `"xdc.root"`, ...
386 * @p 387 * The `execPattern` and `packagePattern` fields are expressions that
388 * are expanded prior to template expansion to determine the name of
389 * the output file. Expressions of the form "`$(name)`" within the
390 * pattern string are expanded if "`name`" is one of the built-in
391 * variables listed below.
392 *
393 * Built-in variables for `execPattern`:
394 * @p(dlist) 395 * - `cfgName`
396 * the name of the generated configuration file (without
397 * any directory prefix);
398 * - `cfgDir`
399 * the name of the directory containing the config file;
400 * - `exeName`
401 * the name of the executable file (without any
402 * directory prefix);
403 * - `exeDir`
404 * the directory containing the executable file.
405 * @p 406 * Both the `exeDir` and `cfgDir` are relative to the directory
407 * containing the `package.bld` script.
408 *
409 * Built-in variables for `packagePattern`:
410 * @p(dlist) 411 * - `pkgName`
412 * the package's name (e.g., `"ti.targets"`);
413 * - `trgName`
414 * the target's `name` property;
415 * - `trgSuffix`
416 * the target's `suffix` property.
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 *
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 *
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 readonlyconfig 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 * @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 *
884 * - determine the assembly language suffix used during legacy BIOS
885 * configuration; the first element of the target's ISA chain
886 * defines the suffix. For example, if a target's ISA is "64P"
887 * and the returned chain is ["62", "64", "64P"], the assembly
888 * suffix is ".s62".
889 * @p 890 *
891 * This relation may also be used in the future to help validate
892 * combinations of targets and platforms; a target's CPU ISA must
893 * appear on the chain specified by the platform's CPU ISA.
894 *
895 * @param(isa) the ISA identifier string for the ISA to lookup; if null
896 * then the target's ISA is used (ITarget.isa).
897 *
898 * @a(returns) 899 * This function returns an array of ISA strings where the last string
900 * is the optionally specified ISA string or this target's ISA,
901 * and the first string is the "base" ISA in the
902 * is source compatible" relationship.
903 * If the specified ISA string is not in this target's chain
904 * of compatible targets, `null` is returned.
905 *
906 * @a(throws) `Error` exceptions are thrown for fatal errors.
907 *
908 */
909 function getISAChain(isa);
910
911 /*!
912 * ======== findSuffix ========
913 * Find the suffix that is compatible with this target.
914 *
915 * This function determines the list of targets supported by the
916 * package given as the argument. From that list, this function
917 * returns the suffix of a target that is compatible with this target.
918 * Compatibility in this case means that object files created by a
919 * target having the suffix returned by this function can be linked
920 * into an executable produced using this target. In the case where more
921 * than one suffix is compatible, this function returns a suffix in the
922 * following order of preference:
923 * @p(nlist) 924 * - if this target's suffix is in the list, that suffix is returned.
925 *
926 * - suffixes from `compatibleSuffixes` are matched against the list
927 * from the first to the last, and the first one with the match is
928 * returned.
929 * @p 930 *
931 * @param(pkg) a package object or an array of target suffix strings
932 * (see `{@link #suffix}`).
933 *
934 * @a(returns) 935 * This function returns the suffix string of a target compatible with
936 * this target or `null` if `pkg` does not support any target compatible
937 * with this target.
938 *
939 */
940 function findSuffix(pkg);
941
942 /*!
943 * ======== selectSuffix ========
944 * Select the suffix that is compatible with this target.
945 *
946 * From a list of suffixes supplied as an argument, this function
947 * returns the suffix compatible with this target. Compatibility in
948 * this case means that object files created by a target having the
949 * suffix returned by this function can be linked into an executable
950 * produced using this target. In the case where more than one suffix
951 * is compatible, this function returns a suffix in the following order
952 * of preference:
953 * @p(nlist) 954 * - if this target's suffix is in the list, that suffix is returned.
955 *
956 * - suffixes from `compatibleSuffixes` are matched against the list
957 * from the first to the last, and the first one with the match is
958 * returned.
959 * @p 960 *
961 * @param(suffixList) an array of target suffix strings
962 * (see `{@link #suffix}`).
963 *
964 * @a(returns) 965 * This function returns the suffix string of a target compatible with
966 * this target or `null` if no such suffix is found in the list of
967 * suffixes specified by the first argument.
968 *
969 */
970 String selectSuffix(StringArray suffixList);
971
972 /*!
973 * ======== sectMap ========
974 * Output section name to segment type mapping
975 *
976 * This hash table is used to determine whether a particular object file
977 * output section (".text", ".stack", etc.) requires 'data', 'code' or
978 * 'stack' memory segment.
979 *
980 * This `sectMap` is referenced by linker command file templates during
981 * generation to create linker command files. The Platform defines the
982 * default memory segments for code and data, and based on this map and
983 * the default segments, the linker command file template places an
984 * output section into a physical memory segment.
985 *
986 * Note that the `{@link xdc.cfg.Program}` object and the
987 * `{@link xdc.platform.IPlatform}` instance have a
988 * `sectMap` parameter. Both the `Program`'s and `IPlatform`'s `sectMap`
989 * can augment and/or override the placement for a section, but
990 * `{@link xdc.cfg.Program#sectMap}` takes precedence. Therefore, this
991 * `sectMap` and the default segments from the platform define an
992 * initial section map which is then augmented by the `Program`'s and
993 * `IPlatform`'s section map.
994 */
995 readonlyconfig String sectMap[string];
996
997 /*!
998 * ======== TypeInfo ========
999 * @_nodoc 1000 *
1001 * @see #StdTypes
1002 */
1003 struct TypeInfo {
1004 int size;
1005 int align;
1006 }
1007
1008 /*!
1009 * ======== StdTypes ========
1010 * Standard base types supported by all targets
1011 *
1012 * @see #stdTypes
1013 */
1014 struct StdTypes {
1015 TypeInfo t_IArg;
1016 TypeInfo t_Char;
1017 TypeInfo t_Double;
1018 TypeInfo t_Float;
1019 TypeInfo t_Fxn;
1020 TypeInfo t_Int;
1021 TypeInfo t_Int8;
1022 TypeInfo t_Int16;
1023 TypeInfo t_Int32;
1024 TypeInfo t_Int40;
1025 TypeInfo t_Int64;
1026 TypeInfo t_Long;
1027 TypeInfo t_LDouble;
1028 TypeInfo t_LLong;
1029 TypeInfo t_Ptr;
1030 TypeInfo t_Short;
1031 TypeInfo t_Size;
1032 }
1033
1034 /*!
1035 * ======== stdInclude ========
1036 * Standard C/C++ types header
1037 *
1038 * This string identifies a header containing the C/C++ definitions
1039 * required to enable use of `xdc/std.h` in C/C++ sources; see
1040 * `{@link xdc}`.
1041 *
1042 * The value of this string is used by `xdc/std.h` to include
1043 * target-specific definitions of the types `Int8`, `Int16`, etc. In
1044 * addition, this header supplies target-specific definitions of the
1045 * predefined `xdc_target__*` macros required by `{@link xdc xdc/std.h}`.
1046 *
1047 * Since this header must supply target-specific values for
1048 * target-independent names the structure of this header is usually of
1049 * the form:
1050 * @p(code) 1051 * // if target macros are not already defined,
1052 * #if !defined(xdc_target_macros_include__)
1053 * // include target-specific definitions
1054 * #if defined(TARGET1)
1055 * #include "target1.h"
1056 * #elif defined(TARGET2)
1057 * #include "target2.h"
1058 * #elif ...
1059 * :
1060 * #else
1061 * #error unsupported target
1062 * #endif
1063 * #endif
1064 * // include common definitions
1065 * :
1066 * @p 1067 * The check of the symbol `xdc_target_macros_include__` exists to
1068 * allow others that define new targets to include this header to
1069 * get common definitions for a family of related targets.
1070 *
1071 * To simplify the creation of the target-specific header files, the
1072 * template file `stddefs.xdt` in this package can be used to
1073 * automatically generate the required definitions from each target's
1074 * `.xdc` specification.
1075 */
1076 readonlyconfig String stdInclude;
1077
1078 /*!
1079 * ======== stdTypes ========
1080 * Size and alignment for standard base types
1081 *
1082 * The values of size are the values returned by the
1083 * target-specific `sizeof()` operator applied to the specified
1084 * type (as defined by the C language). The align value is the number
1085 * of chars used in the alignment of the specified type.
1086 */
1087 readonlyconfig StdTypes stdTypes = {
1088 t_IArg : { size: 0, align: 0 },
1089 t_Char : { size: 0, align: 0 },
1090 t_Double : { size: 0, align: 0 },
1091 t_Float : { size: 0, align: 0 },
1092 t_Fxn : { size: 0, align: 0 },
1093 t_Int : { size: 0, align: 0 },
1094 t_Int8 : { size: 0, align: 0 },
1095 t_Int16 : { size: 0, align: 0 },
1096 t_Int32 : { size: 0, align: 0 },
1097 t_Int40 : { size: 0, align: 0 },
1098 t_Int64 : { size: 0, align: 0 },
1099 t_Long : { size: 0, align: 0 },
1100 t_LDouble : { size: 0, align: 0 },
1101 t_LLong : { size: 0, align: 0 },
1102 t_Ptr : { size: 0, align: 0 },
1103 t_Short : { size: 0, align: 0 },
1104 t_Size : { size: 0, align: 0 },
1105 };
1106
1107 /*!
1108 * ======== bitsPerChar ========
1109 * The number of bits in a variable of type `char`
1110 *
1111 * This constant allows one to determine the precise number of bits in
1112 * each of the types specified in the stdTypes map. For example, the
1113 * number of bits in the target t's `int` type is
1114 * @p(code) 1115 * t.stdTypes.t_Int.size * t.bitsPerChar
1116 * @p 1117 */
1118 readonlyconfig Int bitsPerChar = 8;
1119 }
1120 /*
1121 * @(#) xdc.bld; 1, 0, 2,293; 9-14-2010 16:36:16; /db/ztree/library/trees/xdc/xdc-v49x/src/packages/
1122 */
1123