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