1 /* --COPYRIGHT--,EPL
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * --/COPYRIGHT--*/
12 /*
13 * ======== ITarget.xdc ========
14 *
15 *! Revision History
16 *! ================
17 *! 14-Nov-2008 sasha added typed signatures for functions
18 *! 04-Oct-2006 toddm Removed parameter dataSection
19 *! 26-Sep-2006 sasha Added parameter dataSection
20 *! 27-Jul-2005 sasha Moved the section map from platforms to targets
21 *! 24-May-2006 jonr Changed Arg to IArg
22 */
23 package xdc.bld;
24
25 /*!
26 * ======== ITarget ========
27 * The interface between code generation tool-chains and the XDC Build
28 * Engine.
29 *
30 * This interface defines an abstract interface that must be supported by
31 * a compiler tool-chain in order to be used in an XDC build environment.
32 * This interface allows the XDC Build engine to treat all compiler tool
33 * chains uniformly; thus, it is possible to add support for a new compiler
34 * without making *any* changes to the build engine.
35 */
36 metaonlyinterface ITarget {
37
38 /*!
39 * ======== Model ========
40 * Target runtime model.
41 *
42 * @field(`endian`) this string specifies the endianess of the
43 * generated code. Valid values include:
44 * @p(dlist) 45 * - `"big"`
46 * big endian
47 * - `"little"`
48 * little endian
49 * - `null`
50 * unspecified
51 * @p 52 *
53 * @field(`codeModel`) this string specifies a target-specific code size
54 * model. Valid values include:
55 * @p(dlist) 56 * - `"near"`
57 * C54 near mode
58 * - `"far"`
59 * C54 far mode
60 * - `undefined`
61 * unspecified
62 * @p 63 *
64 * @field(`dataModel`) this string specifies a target-specific data size
65 * model. Valid values include:
66 * @p(dlist) 67 * - `"large"`
68 * C55, C28 large model
69 * - `undefined`
70 * unspecified
71 * @p 72 * @see #model
73 */
74 struct Model {
75 String endian; /*! endian-ness of this target */
76 String codeModel; /*! target-specific code model */
77 String dataModel; /*! target-specific data model */
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(defs) a string of macro definitions each of the form
566 * "`-Dname=value`" separated by white space
567 * @field(incs) a string of include directories each of the form
568 * "`-Idir`" separated by white space
569 *
570 * @a(Predefined Macros) 571 * The XDC Build Engine automatically adds several predefined macros via
572 * `-D` definitions that enable conditional compilation of source files
573 * based on build-specific attributes.
574 * @p(dlist) 575 * - `xdc_bld__profile_`{profile_name}
576 * this symbol is always defined and {profile_name} is the
577 * compile goal's (see `{@link #CompileGoal}`) profile name.
578 * @p 579 *
580 * In addition, each target defines a set of macros that enable clients
581 * to portably support big/little endian targets, for example. These
582 * macros are indirectly included by sources that include `xdc/std.h`;
583 * see `{@link xdc}`.
584 *
585 * @see #OptionSet
586 * @see #CompileGoal
587 * @see xdc
588 */
589 struct CompileOptions {
590 String aopts; /*! goal specific ASM options */
591 String copts; /*! goal specific C compiler options */
592 String defs; /*! goal specific C/ASM definition options */
593 String incs; /*! goal specific C/ASM include options */
594 };
595
596 /*!
597 * ======== OptionSet ========
598 * Collection of tool-chain options.
599 *
600 * This structure is used to define a collection of tool-chain
601 * options that are used as a group to achieve some effect supported
602 * by the tool-chain. For example, some compilers require that
603 * specific options be passed to the compiler *and* linker in order
604 * to generate execution profile information or code coverage
605 * statistics.
606 *
607 * @field(compilerOptions) a set of compiler/assembler options
608 * @field(linkOpts) a string of target-specific linker options
609 * @field(archiveOpts) a string of target-specific archiver options
610 * @field(filters) an array of filters applied (in order) to
611 * tool-chain commands
612 *
613 * @see #profiles
614 */
615 struct OptionSet {
616 CompileOptions compileOpts; /*! profile-specific compiler opts */
617 String linkOpts; /*! profile-specific linker opts */
618 String archiveOpts; /*! profile-specific archiver opts */
619
620 ITargetFilter.InstDesc filters[]; /*! ITargetFilter instance descs */
621 };
622
623 /*!
624 * ======== profiles ========
625 * Profiles supported by this target.
626 *
627 * A profile is a collection of tool options used to create a
628 * library or executable that supports a certain "flavor" of library
629 * or executable; e.g., "debug" or "release".
630 *
631 * Some profile names are supported by all targets even though the
632 * targets use different compilers (and therefore different options).
633 * These profile names makes it possible for a package to build
634 * libraries or executables in a "debug" (or "release") profile
635 * independent of the target, for example.
636 *
637 * All targets are required to support "debug" and "release" profile
638 * names.
639 *
640 * Profile options are added to beginning of any goal specific options
641 * specified by the user before being passed to the target.
642 */
643 config OptionSet profiles[string] = [
644 ["release", {}],
645 ["debug", {}],
646 ];
647
648 /*!
649 * ======== CompileGoal ========
650 * The goal specification passed to the `{@link #compile}`
651 * function.
652 *
653 * @see #compile
654 * @see #scompile
655 */
656 struct CompileGoal {
657 String base; /*! base name of the source and destination */
658 String dstPrefix; /*! directory prefix of destination file */
659 String dstSuffix; /*! suffix of destination file; e.g., ".o62" */
660 String srcSuffix; /*! optional suffix of source file; e.g., ".c" */
661 String srcPrefix; /*! optional directory prefix of source file */
662 String profile; /*! index into profiles map */
663 CompileOptions opts;/*! goal specific compiler options */
664 Bool configOpts; /*! true if compiling the generated C config file */
665 };
666
667 /*!
668 * ======== LinkGoal ========
669 * The goal specification passed to the `{@link #link}` function.
670 *
671 * @see #link
672 */
673 struct LinkGoal {
674 String base; /*! base name of the source and destination */
675 String dstPrefix; /*! directory prefix of destination file */
676 String dstSuffix; /*! suffix of destination file; e.g., ".x62" */
677 String files; /*! string of files to link with */
678 String profile; /*! index into profiles map */
679 String opts; /*! goal specific linker options */
680 Bool dllMode; /*! true if we're linking an assembly */
681 Bool isRom; /*! reflects the `isRom` attribute */
682 };
683
684 /*!
685 * ======== ArchiveGoal ========
686 * The goal specification passed to the `{@link #archive}`
687 * function.
688 *
689 * @see #archive
690 */
691 struct ArchiveGoal {
692 String base; /*! base name of the source and destination */
693 String dstPrefix; /*! directory prefix of destination file */
694 String dstSuffix; /*! suffix of destination file; e.g., ".a62" */
695 String files; /*! String of files to archive */
696 String profile; /*! index into profiles map */
697 String opts; /*! goal specific archiver options */
698 };
699
700 /*!
701 * ======== CommandSet ========
702 * The commands necessary to create a specified goal.
703 *
704 * This structure is the return value of the `{@link #compile}`,
705 * `{@link #link}` and `{@link #archive}` functions. This value is then
706 * used to generate a makefile or any other files necessary to generate
707 * a specified goal.
708 *
709 * @field(msg) a brief synopsis of the commands specified by `cmds`;
710 * this string is output in lieu of `cmds` when building
711 * in "non-verbose" mode.
712 *
713 * @field(cmds) a single string of commands that must be executed
714 * to complete the specified operation. Multiple
715 * commands may be specified by separating each command
716 * with the '\n' character.
717 *
718 * To facilitate the creation of "portable" makefiles and
719 * to simplify the implementation of targets, certain
720 * distinguished "macros" may be embedded in this string.
721 * The build engine replaces these macros with the
722 * values described below.
723 * @p(dlist) 724 * - `$(rootDir)`
725 * the target's `{@link #rootDir}` configuration
726 * parameter
727 * - `$(packageBase)`
728 * the target package's
729 * `{@link xdc.IPackage#packageBase}` property
730 * - `$(XDCINCS)`
731 * a set of "-I" options that names each
732 * repository in the package path
733 * @p 734 *
735 * @field(envs) an array of "name=value" strings that represent
736 * environment variables that are defined prior to the
737 * execution of the commands specified by `cmds`
738 *
739 * @field(path) an array of directory names that are used to compose
740 * the PATH environment variable that is in effect when
741 * the commands specified by `cmds` are run.
742 *
743 * @see #archive
744 * @see #compile
745 * @see #scompile
746 * @see #link
747 */
748 struct CommandSet {
749 String msg; /*! brief message describing subsequent commands */
750 String cmds; /*! commands necessary to generate goal */
751 String path[]; /*! host-independent representation of PATH */
752 String envs[]; /*! environment variable settings for the cmds */
753 };
754
755 /*!
756 * ======== archive ========
757 * Create an archive.
758 *
759 * This function is called during makefile generation to convert build
760 * goals into specific commands that generate the specified goal.
761 *
762 * @param(goal) the `{@link #ArchiveGoal}` defining the archive to build.
763 *
764 * @a(returns) 765 * This function returns a `{@link #CommandSet}`. If non-`null`, this
766 * object defines the commands that must be executed to create the
767 * specified object file. If `null`, then goal can not be achieved.
768 *
769 * @a(throws) `Error` exceptions are thrown for fatal errors.
770 */
771 CommandSet* archive(ArchiveGoal *goal);
772
773 /*!
774 * ======== compile ========
775 * Compile a source file into an object file.
776 *
777 * This function is called during makefile generation to convert build
778 * goals into specific commands that generate the specified object
779 * file goal.
780 *
781 * @param(goal) a `{@link #CompileGoal}` that specifies what file to
782 * compile, the output file name, and any goal-specific
783 * options to use
784 *
785 * @a(returns) 786 * This function retuns a `{@link #CommandSet}`. If non-`null`,
787 * this object defines the commands that must be executed to create the
788 * specified object file. If `null`, then goal can not be achieved.
789 *
790 * @a(throws) `Error` exceptions are thrown for fatal errors.
791 */
792 CommandSet* compile(CompileGoal *goal);
793
794 /*!
795 * ======== scompile ========
796 * Compile a source file into an assembly language file.
797 *
798 * This function is called during makefile generation to convert build
799 * goals into specific commands that generate the specified assembly
800 * language source goal.
801 *
802 * @param(goal) a `{@link #CompileGoal}` that specifies what file to
803 * compile, the output file name, and any goal-specific
804 * options to use
805 *
806 * @a(returns) 807 * This function returns a `{@link #CommandSet}`. If non-`null`, this
808 * object defines the commands that must be executed to create the
809 * specified assembly language file. If `null`, then goal
810 * can not be achieved or is unnecessary (e.g., because
811 * the source file is already an asm file).
812 *
813 * @a(throws) `Error` exceptions are thrown for fatal errors.
814 */
815 CommandSet* scompile(CompileGoal *goal);
816
817 /*!
818 * ======== link ========
819 * Link object files to produce an executable.
820 *
821 * This function is called during makefile generation to convert build
822 * goals into specific commands that generate the specified goal.
823 *
824 * @param(goal) a `{@link #LinkGoal}` that specifies the output file
825 * name, a list of files to link with, and any goal-specific
826 * options to use
827 *
828 * @a(returns) 829 * This function returns a `{@link #CommandSet}`. If non-`null`, this
830 * object defines the commands that must be executed to create the
831 * specified object file. If `null`, then goal can not be
832 * achieved.
833 *
834 * @a(throws) `Error` exceptions are thrown for fatal errors.
835 */
836 CommandSet* link(LinkGoal *goal);
837
838 /*!
839 * ======== getVersion ========
840 * Get a target-specific Compatibility Key string
841 *
842 * This function is called during makefile generation to obtain a
843 * target-specific Compatibility Key string. This string is of the
844 * form:
845 * @p(code) 846 * "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>"
847 * @p 848 * where, `<pkg>.<mod>` is the name of the target, and `<d0>`, `<d1>`,
849 * etc. forms a Compatibility Key.
850 *
851 * @a(returns) 852 * This function returns a string that encodes the name of the target
853 * and its Compatibility Key.
854 *
855 * @a(throws) `Error` exceptions are thrown for fatal errors.
856 */
857 String getVersion();
858
859 typedef String StringArray[];
860
861 /*!
862 * ======== getISAChain ========
863 * Get this target's ISA "is compatible with" relation.
864 *
865 * Returns an array of ISA names (including this target's ISA) that
866 * represents the "is a" relation between ISA's. The array starts with
867 * the most general ISA and ends with this target's ISA or with the
868 * optionally specified argument. This relation is used to:
869 * @p(nlist) 870 * - pre-define macro definitions that enable code to be
871 * conditionally compiled based on compatible versions of a
872 * target's ISA.
873 *
874 * - locate appropriate source files during makefile generation;
875 * each ISA named in a chain causes the extensions ".s"isa to be
876 * added to the ITarget.extensions table (in the reverse order
877 * that they appear in the chain). For example, if a target's
878 * ISA is "64P" and the returned chain is ["62", "64", "64P"],
879 * the following assembly language suffixes are added to
880 * the target's extensions table: ".s64P", ".s64", ".s62".
881 *
882 * - determine the assembly language suffix used during legacy BIOS
883 * configuration; the first element of the target's ISA chain
884 * defines the suffix. For example, if a target's ISA is "64P"
885 * and the returned chain is ["62", "64", "64P"], the assembly
886 * suffix is ".s62".
887 * @p 888 *
889 * This relation may also be used in the future to help validate
890 * combinations of targets and platforms; a target's CPU ISA must
891 * appear on the chain specified by the platform's CPU ISA.
892 *
893 * @param(isa) the ISA identifier string for the ISA to lookup; if null
894 * then the target's ISA is used (ITarget.isa).
895 *
896 * @a(returns) 897 * This function returns an array of ISA strings where the last string
898 * is the optionally specified ISA string or this target's ISA,
899 * and the first string is the "base" ISA in the
900 * is source compatible" relationship.
901 * If the specified ISA string is not in this target's chain
902 * of compatible targets, `null` is returned.
903 *
904 * @a(throws) `Error` exceptions are thrown for fatal errors.
905 *
906 */
907 function getISAChain(isa);
908
909 /*!
910 * ======== findSuffix ========
911 * Find the suffix that is compatible with this target.
912 *
913 * This function determines the list of targets supported by the
914 * package given as the argument. From that list, this function
915 * returns the suffix of a target that is compatible with this target.
916 * Compatibility in this case means that object files created by a
917 * target having the suffix returned by this function can be linked
918 * into an executable produced using this target. In the case where more
919 * than one suffix is compatible, this function returns a suffix in the
920 * following order of preference:
921 * @p(nlist) 922 * - if this target's suffix is in the list, that suffix is returned.
923 *
924 * - suffixes from `compatibleSuffixes` are matched against the list
925 * from the first to the last, and the first one with the match is
926 * returned.
927 * @p 928 *
929 * @param(pkg) a package object or an array of target suffix strings
930 * (see `{@link #suffix}`).
931 *
932 * @a(returns) 933 * This function returns the suffix string of a target compatible with
934 * this target or `null` if `pkg` does not support any target compatible
935 * with this target.
936 *
937 */
938 function findSuffix(pkg);
939
940 /*!
941 * ======== selectSuffix ========
942 * Select the suffix that is compatible with this target.
943 *
944 * From a list of suffixes supplied as an argument, this function
945 * returns the suffix compatible with this target. Compatibility in
946 * this case means that object files created by a target having the
947 * suffix returned by this function can be linked into an executable
948 * produced using this target. In the case where more than one suffix
949 * is compatible, this function returns a suffix in the following order
950 * of preference:
951 * @p(nlist) 952 * - if this target's suffix is in the list, that suffix is returned.
953 *
954 * - suffixes from `compatibleSuffixes` are matched against the list
955 * from the first to the last, and the first one with the match is
956 * returned.
957 * @p 958 *
959 * @param(suffixList) an array of target suffix strings
960 * (see `{@link #suffix}`).
961 *
962 * @a(returns) 963 * This function returns the suffix string of a target compatible with
964 * this target or `null` if no such suffix is found in the list of
965 * suffixes specified by the first argument.
966 *
967 */
968 String selectSuffix(StringArray suffixList);
969
970 /*!
971 * ======== sectMap ========
972 * Output section name to segment type mapping
973 *
974 * This hash table is used to determine whether a particular object file
975 * output section (".text", ".stack", etc.) requires 'data', 'code' or
976 * 'stack' memory segment.
977 *
978 * This `sectMap` is referenced by linker command file templates during
979 * generation to create linker command files. The Platform defines the
980 * default memory segments for code and data, and based on this map and
981 * the default segments, the linker command file template places an
982 * output section into a physical memory segment.
983 *
984 * Note that the `{@link xdc.cfg.Program}` object and the
985 * `{@link xdc.platform.IPlatform}` instance have a
986 * `sectMap` parameter. Both the `Program`'s and `IPlatform`'s `sectMap`
987 * can augment and/or override the placement for a section, but
988 * `{@link xdc.cfg.Program#sectMap}` takes precedence. Therefore, this
989 * `sectMap` and the default segments from the platform define an
990 * initial section map which is then augmented by the `Program`'s and
991 * `IPlatform`'s section map.
992 */
993 readonlyconfig String sectMap[string];
994
995 /*!
996 * ======== TypeInfo ========
997 * @_nodoc 998 *
999 * @see #StdTypes
1000 */
1001 struct TypeInfo {
1002 int size;
1003 int align;
1004 }
1005
1006 /*!
1007 * ======== StdTypes ========
1008 * Standard base types supported by all targets
1009 *
1010 * @see #stdTypes
1011 */
1012 struct StdTypes {
1013 TypeInfo t_IArg;
1014 TypeInfo t_Char;
1015 TypeInfo t_Double;
1016 TypeInfo t_Float;
1017 TypeInfo t_Fxn;
1018 TypeInfo t_Int;
1019 TypeInfo t_Int8;
1020 TypeInfo t_Int16;
1021 TypeInfo t_Int32;
1022 TypeInfo t_Int40;
1023 TypeInfo t_Int64;
1024 TypeInfo t_Long;
1025 TypeInfo t_LDouble;
1026 TypeInfo t_LLong;
1027 TypeInfo t_Ptr;
1028 TypeInfo t_Short;
1029 TypeInfo t_Size;
1030 }
1031
1032 /*!
1033 * ======== stdInclude ========
1034 * Standard C/C++ types header
1035 *
1036 * This string identifies a header containing the C/C++ definitions
1037 * required to enable use of `xdc/std.h` in C/C++ sources; see
1038 * `{@link xdc}`.
1039 *
1040 * The value of this string is used by `xdc/std.h` to include
1041 * target-specific definitions of the types `Int8`, `Int16`, etc. In
1042 * addition, this header supplies target-specific definitions of the
1043 * predefined `xdc_target__*` macros required by `{@link xdc xdc/std.h}`.
1044 *
1045 * Since this header must supply target-specific values for
1046 * target-independent names the structure of this header is usually of
1047 * the form:
1048 * @p(code) 1049 * // if target macros are not already defined,
1050 * #if !defined(xdc_target_macros_include__)
1051 * // include target-specific definitions
1052 * #if defined(TARGET1)
1053 * #include "target1.h"
1054 * #elif defined(TARGET2)
1055 * #include "target2.h"
1056 * #elif ...
1057 * :
1058 * #else
1059 * #error unsupported target
1060 * #endif
1061 * #endif
1062 * // include common definitions
1063 * :
1064 * @p 1065 * The check of the symbol `xdc_target_macros_include__` exists to
1066 * allow others that define new targets to include this header to
1067 * get common definitions for a family of related targets.
1068 *
1069 * To simplify the creation of the target-specific header files, the
1070 * template file `stddefs.xdt` in this package can be used to
1071 * automatically generate the required definitions from each target's
1072 * `.xdc` specification.
1073 */
1074 readonlyconfig String stdInclude;
1075
1076 /*!
1077 * ======== stdTypes ========
1078 * Size and alignment for standard base types
1079 *
1080 * The values of size are the values returned by the
1081 * target-specific `sizeof()` operator applied to the specified
1082 * type (as defined by the C language). The align value is the number
1083 * of chars used in the alignment of the specified type.
1084 */
1085 readonlyconfig StdTypes stdTypes = {
1086 t_IArg : { size: 0, align: 0 },
1087 t_Char : { size: 0, align: 0 },
1088 t_Double : { size: 0, align: 0 },
1089 t_Float : { size: 0, align: 0 },
1090 t_Fxn : { size: 0, align: 0 },
1091 t_Int : { size: 0, align: 0 },
1092 t_Int8 : { size: 0, align: 0 },
1093 t_Int16 : { size: 0, align: 0 },
1094 t_Int32 : { size: 0, align: 0 },
1095 t_Int40 : { size: 0, align: 0 },
1096 t_Int64 : { size: 0, align: 0 },
1097 t_Long : { size: 0, align: 0 },
1098 t_LDouble : { size: 0, align: 0 },
1099 t_LLong : { size: 0, align: 0 },
1100 t_Ptr : { size: 0, align: 0 },
1101 t_Short : { size: 0, align: 0 },
1102 t_Size : { size: 0, align: 0 },
1103 };
1104
1105 /*!
1106 * ======== bitsPerChar ========
1107 * The number of bits in a variable of type `char`
1108 *
1109 * This constant allows one to determine the precise number of bits in
1110 * each of the types specified in the stdTypes map. For example, the
1111 * number of bits in the target t's `int` type is
1112 * @p(code) 1113 * t.stdTypes.t_Int.size * t.bitsPerChar
1114 * @p 1115 */
1116 readonlyconfig Int bitsPerChar = 8;
1117 }
1118 /*
1119 * @(#) xdc.bld; 1, 0, 2,215; 7-29-2009 14:53:06; /db/ztree/library/trees/xdc-t56x/src/packages/
1120 */
1121