| /* --COPYRIGHT--,EPL |
| * Copyright (c) 2008 Texas Instruments and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * Texas Instruments - initial implementation |
| * |
| * --/COPYRIGHT--*/ |
| /* |
| * ======== ITarget.xdc ======== |
| */ |
| package xdc.bld; |
| |
| /*! |
| * ======== ITarget ======== |
| * The interface between code generation tool-chains and the XDC Build |
| * Engine. |
| * |
| * This interface defines an abstract interface that must be supported by |
| * a compiler tool-chain in order to be used in an XDC build environment. |
| * This interface allows the XDC Build engine to treat all compiler tool |
| * chains uniformly; thus, it is possible to add support for a new compiler |
| * without making *any* changes to the build engine. |
| */ |
| metaonly interface ITarget { |
| |
| /*! |
| * ======== Model ======== |
| * Target runtime model. |
| * |
| * @field(`endian`) this string specifies the endianess of the |
| * generated code. Valid values include: |
| * @p(dlist) |
| * - `"big"` |
| * big endian |
| * - `"little"` |
| * little endian |
| * - `null` |
| * unspecified |
| * @p |
| * |
| * @field(`codeModel`) this string specifies a target-specific code size |
| * model. Valid values include: |
| * @p(dlist) |
| * - `"near"` |
| * C54 near mode |
| * - `"far"` |
| * C54 far mode |
| * - `undefined` |
| * unspecified |
| * @p |
| * |
| * @field(`dataModel`) this string specifies a target-specific data size |
| * model. Valid values include: |
| * @p(dlist) |
| * - `"large"` |
| * C55, C28 large model |
| * - `undefined` |
| * unspecified |
| * @p |
| * |
| * @field(`shortEnums`) this flag specifies if a target fits the values |
| * of an enumeration into the smallest integer type |
| * that can accept all values. If that is the case, |
| * this flag must be set to `true`. If all values are |
| * the size of an Int, this flag can be either set |
| * to `false` or left unspecified. |
| * @see #model |
| */ |
| struct Model { |
| String endian; /*! endian-ness of this target */ |
| String codeModel; /*! target-specific code model */ |
| String dataModel; /*! target-specific data model */ |
| Bool shortEnums; /*! if true, enums are packed into smallest integral type */ |
| } |
| |
| /*! |
| * ======== name ======== |
| * Nickname for this target. |
| * |
| * This name is typically the name of the module without the package |
| * name prefix. Thus, it is not necessarily globally unique. |
| * |
| * Use the `$name` property of the module to get a globally unique name |
| * for the target. |
| */ |
| readonly config String name; |
| |
| /*! |
| * ======== suffix ======== |
| * Suffix appended to all objs, libraries, and executable. |
| * |
| * All files generated by this target (object files, archives, |
| * executables, etc.) have file names whose extensions end with |
| * suffix. In particular, targets create files with the following |
| * extensions: |
| * @p(dlist) |
| * - `".a<suffix>"` |
| * archive files (i.e., libraries) |
| * - `".o<suffix>"` |
| * object files |
| * - `".s<suffix>"` |
| * assembly language source (see `{@link #scompile()}`) |
| * - `".x<suffix>"` |
| * executable files |
| * @p |
| * This suffix should be chosen to globally and uniquely identify the |
| * EABI (Embedded Application Binary Interface) of the objects produced |
| * by this target. Targets with the same suffix should produce 100% EABI |
| * compatible objects and, targets with different suffixes should produce |
| * objects with incompatible EABIs. |
| * |
| * @see #scompile() |
| */ |
| readonly config String suffix; |
| |
| /*! |
| * ======== compatibleSuffixes ======== |
| * Array of suffixes used by targets compatible with this target |
| * |
| * This array is used to identify a set of targets that produce |
| * code that can be linked with code produced by this target, where the |
| * order of suffixes defines the order of preferrence. This |
| * parameter is used by `findSuffixes()`. |
| * |
| * For example, an Arm target which builds for v6 architecture might have |
| * the following values in its `compatibleSuffix`: ["v5T", "MV470"]. |
| * This means that code produced by targets with suffixes "v5T' and |
| * "MV470" can be linked with code produced by that target, and that "v5T" |
| * code is more preferred than "MV470" code. |
| */ |
| config String compatibleSuffixes[]; |
| |
| /*! |
| * ======== isa ======== |
| * CPU Instruction Set Architecture (ISA) |
| * |
| * This parameter is used to identify a set of targets that produce |
| * code for a common ISA. This is used by build scripts that need to |
| * build for all targets that support a particular device. |
| * |
| * For example, the build script for a package that is designed for |
| * the TMS32064xx (and no other CPU) can easily specify that it |
| * should be built for all targets that generate code for the |
| * TMS320C64xx without having to specify a specific target. This |
| * allows the user to add new targets (big endian, little endian, |
| * different compilers, etc.) that build for the TMS320C64xx without |
| * having to modify the package's build script. |
| * |
| * Note that this field should not be confused with platform ISA |
| * names; this field is defined by target tool-chains and may differ |
| * from the names given by a CPU device. |
| * |
| * @see xdc.platform.ICpuDataSheet |
| */ |
| readonly config String isa; |
| |
| /*! |
| * ======== model ======== |
| * Run-time model |
| * |
| * This structure identifies a particular run-time model |
| * used by the compiler to generate instructions. |
| */ |
| readonly config Model model; |
| |
| /*! |
| * ======== os ======== |
| * Name of OS required to run programs built for this target. |
| * |
| * Native executables are run by the host OS. This OS often |
| * defines runtime interfaces that all executables (implicitly or |
| * explicitly) use. |
| * |
| * If os is undefined, then no OS is required. |
| */ |
| readonly config String os; |
| |
| /*! |
| * ======== rts ======== |
| * Name of a run-time support package to include |
| * |
| * Development environments often provide a set of common run-time |
| * support functions that all other code can easily utilize; e.g., |
| * some means for performing a "printf", normal program termination |
| * with "exit status", etc. If the `rts` parameter is non-`null`, it is |
| * the name of a package that is implicitly imported when building |
| * any executable that is built using this target. If `rts` is |
| * undefined, no rts package is imported. |
| * |
| * This parameter makes it possible for the target producer to name |
| * a package that provides a target-specific implementation of a runtime |
| * support interface. Clients of a target do not need to explicitly |
| * name a target specific rts implementation; thus, it is not |
| * possible for the client to inadvertently name the wrong (or an |
| * incompatible) rts implementation. |
| * |
| * Note: this package is *NOT* included if the executable's |
| * `{@link xdc.bld.Executable#attrs}.rtsName` attribute is set to `null`; |
| * see {@link xdc.bld.Executable#Attrs}. |
| */ |
| readonly config String rts; |
| |
| /*! |
| * ======== base ======== |
| * A target that this target is based upon. |
| * |
| * If non-`null`, this target shares the same tool-chain of the specified |
| * base target. This parameter is used to determine various default |
| * values for target configuration parameters. For example, the default |
| * setting of `{@link #rootDir}` is the value of the base's |
| * `{@link #rootDir}` setting. |
| */ |
| readonly config ITarget.Module base; |
| |
| /*! |
| * ======== dllExt ======== |
| * @_nodoc dlls are not yet fully supported |
| */ |
| config String dllExt; |
| |
| /*! |
| * ======== execExt ======== |
| * Extension for executables. |
| * |
| * Operating systems and tools often have a strong preference for a |
| * specific extension for executables; e.g., Windows expects executables |
| * to have the extension "`.exe`". If this parameter is set, executables |
| * will be given the specified extension instead of the default |
| * "`.x<suffix>`", where `<suffix>` is the target's suffix parameter. |
| * |
| * The `execExt` is an expression that is expanded prior to use. |
| * Expressions of the form "`$(name)`" within the |
| * pattern string are expanded if "`name`" is one of the built-in |
| * variables listed below. |
| * |
| * Built-in variables for `execExt`: |
| * @p(dlist) |
| * - `trgName` |
| * the target's `name` property |
| * - `trgSuffix` |
| * the target's `suffix` property |
| * - `platPName` |
| * the executable's platform package name |
| * - `platIName` |
| * the executable's platform instance name |
| * @p |
| * |
| * @a(Example) If you want to build a portable executable for multiple |
| * targets side-by-side and you want (or need) to use a fixed extension |
| * such as ".out" for all executables, setting `execExt` to |
| * `"_$(trgSuffix).out"` for all targets ensures that all generated |
| * executables will have unique names and yet share a common extension |
| * of `".out"`. |
| */ |
| config String execExt; |
| |
| /*! |
| * ======== platform ======== |
| * The default platform name for this target |
| * |
| * Build scripts often build for just one platform per target. This |
| * parameter allows one to establish a default platform for each |
| * target in a build. |
| * |
| * If this parameter is `null` or `undefined` and `{@link #platforms}` |
| * array is non-empty, it is initialized to be the first element of the |
| * platforms array (i.e., `{@link #platforms[0]}`). |
| */ |
| config String platform; |
| |
| /*! |
| * ======== platforms ======== |
| * A set of platforms that can support this target |
| * |
| * Some build scripts build executables for "all" platforms; e.g., |
| * regression test suites. This parameter allows one to establish |
| * a set of platforms that build scripts can legitimately use to |
| * create executables, for example. |
| * |
| * If this array is empty (i.e., has length 0) and `{@link #platform}` |
| * is non-`null`, platforms is initialized to an array of one element |
| * equal to `{@link #platform}`. |
| */ |
| config String platforms[] = []; |
| |
| /*! |
| * ======== binaryParser ======== |
| * The name of a object file parser |
| * |
| * The value of this configuration parameter is the name of a |
| * module or Java class that implements the `xdc.rta.IOFReader` interface. |
| * This interface is used to extract information from the object files |
| * produced by this target. |
| * |
| * @_nodoc object file readers are not yet fully supported |
| */ |
| config String binaryParser; |
| |
| /*! |
| * ======== version ======== |
| * The Compatibility Key associated with this target. |
| * |
| * @a(Readonly) This value is automatically computed by the XDC Build |
| * Engine by executing the `{@link #getVersion()}` function after |
| * `package.bld` completes but prior to generating `package.mak`. |
| */ |
| config String version; |
| |
| /*! |
| * ======== versionRaw ======== |
| * The unmodified version string associated with this target. |
| * |
| * @a(Readonly) This value is automatically computed by the XDC Build |
| * Engine by executing the `{@link #getVersion()}` function after |
| * `package.bld` completes but prior to generating `package.mak`. |
| * |
| * @_nodoc |
| */ |
| config String versionRaw; |
| |
| /*! |
| * ======== DebugGen ======== |
| * Debugger integration support. |
| * |
| * This structure specifies additional files that are generated |
| * in order to support integration with a debugger. For example, the |
| * default setting for TI targets specifies the generation of CCS |
| * project files that allow one to easily debug executables that have |
| * been constructed from multiple packages. |
| * |
| * There are two "types" of debug support files that are generated; |
| * one for the package as a whole, and one for each executable. |
| * Since packages may contain portable sources that are built for more |
| * than one target, a "package-level" file is generated for each target |
| * used in the package. A separate file is generated for each |
| * executable built within the package. |
| * |
| * The `execTemplate` and `packageTemplate` fields name a template that |
| * is expanded in the context of the config model and the build |
| * model, respectively. These fields should be set to a file name |
| * string which is relative to the package path; e.g., the string |
| * "`ti/targets/cc_exec.xdt`" refers to the file "`cc_exec.xdt`" in the |
| * `ti.targets` package located along the package path. |
| * |
| * Preconditions for the `execTemplate`: |
| * @p(dlist) |
| * - `this` |
| * the configured program object (`xdc.cfg.Program`); |
| * i.e., the program object *after* the program's |
| * configuration script completes. |
| * - `$args` |
| * array of arguments passed to the template |
| * |
| * - `$args[1]` |
| * the name of the executable being produced for this |
| * configuration. |
| * |
| * - `environment` |
| * hash table of XDC global parameters; e.g., `"xdc.path"`, |
| * `"xdc.root"`, ... |
| * @p |
| * Preconditions for the `packageTemplate`: |
| * @p(dlist) |
| * - `this` |
| * the "package contents" object (i.e., |
| * `xdc.bld.PackageContents`) *after* the package's |
| * build script (`package.bld`) completes. |
| * - `$args` |
| * array of arguments passed to the template |
| * |
| * - `$args[0]` |
| * the target (a module implementing the |
| * `{@link xdc.bld.ITarget}` interface) |
| * |
| * - `$args[1]` |
| * hash-table of all package sources |
| * |
| * - `environment` |
| * hash table of XDC global parameters; e.g., `"xdc.path"`, |
| * `"xdc.root"`, ... |
| * @p |
| * The `execPattern` and `packagePattern` fields are expressions that |
| * are expanded prior to template expansion to determine the name of |
| * the output file. Expressions of the form "`$(name)`" within the |
| * pattern string are expanded if "`name`" is one of the built-in |
| * variables listed below. |
| * |
| * Built-in variables for `execPattern`: |
| * @p(dlist) |
| * - `cfgName` |
| * the name of the generated configuration file (without |
| * any directory prefix); |
| * - `cfgDir` |
| * the name of the directory containing the config file; |
| * - `exeName` |
| * the name of the executable file (without any |
| * directory prefix); |
| * - `exeDir` |
| * the directory containing the executable file. |
| * @p |
| * Both the `exeDir` and `cfgDir` are relative to the directory |
| * containing the `package.bld` script. |
| * |
| * Built-in variables for `packagePattern`: |
| * @p(dlist) |
| * - `pkgName` |
| * the package's name (e.g., `"ti.targets"`); |
| * - `trgName` |
| * the target's `name` property; |
| * - `trgSuffix` |
| * the target's `suffix` property. |
| * @p |
| * |
| * @see #debugGen |
| */ |
| struct DebugGen { |
| String execTemplate; /*! debugger template for executable */ |
| String execPattern; /*! exec file name pattern */ |
| String packageTemplate; /*! debugger template for package */ |
| String packagePattern; /*! package file name pattern */ |
| } |
| |
| /*! |
| * ======== debugGen ======== |
| * Debugger/IDE file generation support. |
| * |
| * This parameter allows one to automatically generate files that |
| * can be used by an IDE to more easily debug (and possibly rebuild) |
| * specified goals. |
| * |
| * To avoid unnecessary build time overhead, these files are not always |
| * generated; by default, they are only generated for "debug" profiles. |
| * The generation of these files is controlled by the |
| * `{@link xdc.cfg.Program#gen}` configuration parameter. To force these |
| * files to be generated for a particular executable, add the following |
| * line to the executable's program configuration script: |
| * @p(code) |
| * Program.gen.debuggerFiles = true; |
| * @p |
| * |
| * It is also possible to disable the generation of selected files by |
| * setting the appropriate fields of `{@link #DebugGen}` to `null` in |
| * your `config.bld` script. |
| */ |
| config DebugGen debugGen; |
| |
| /*! |
| * ======== Extension ======== |
| * File extension to file type association. |
| * |
| * This structure is used by the Build Engine to determine whether a |
| * file should be treated as C++, C, or assembly language source. |
| * |
| * @field(suf) the file extension including any '.' characters |
| * |
| * @field(typ) the type of the file having this extension. |
| * Allowable file type identifiers include: |
| * @p(dlist) |
| * - `"c"` |
| * C language source file |
| * - `"asm"` |
| * assembly language source file |
| * - `"cpp"` |
| * C++ language source file |
| * @p |
| * @see #extensions |
| */ |
| struct Extension { |
| String suf; /*! file extension (including any '.') */ |
| String typ; /*! type of this file; e.g., `"c"`, `"asm"`, ... */ |
| }; |
| |
| /*! |
| * ======== extensions ======== |
| * File extensions recognized by this target. |
| * |
| * This is a user modifiable table used to customize file extensions |
| * recognized by each target. |
| * |
| * For example, to add a new assembly language extension, say "`.s64`", |
| * to the target `ti.targets.C64P`, add the following lines to the |
| * build model startup script: |
| * @p(code) |
| * var C64P = xdc.module('ti.targets.C64P'); |
| * C64P.extensions[".s64"] = { |
| * suf: ".s64", typ: "asm" |
| * }; |
| * @p |
| * Note that individual targets may add additional language types. |
| * |
| * It is also possible to remove default extensions. For example, to |
| * remove the "`.asm`" extension from the target `ti.targets.C64P`, add |
| * the following lines to the build model startup script: |
| * @p(code) |
| * var C64P = xdc.module('ti.targets.C64P'); |
| * delete C64P.extensions[".asm"]; |
| * @p |
| */ |
| config Extension extensions[string] = [ |
| [".asm", {suf: ".asm", typ: "asm"}], |
| [".c", {suf: ".c", typ: "c" }], |
| [".cpp", {suf: ".cpp", typ: "cpp"}], |
| [".cxx", {suf: ".cxx", typ: "cpp"}], |
| [".C", {suf: ".C", typ: "cpp"}], |
| [".cc", {suf: ".cc", typ: "cpp"}], |
| ]; |
| |
| /*! |
| * ======== versionMap ======== |
| * Map of compiler version numbers to compatibility keys. |
| * |
| * `versionMap` is a user modifiable table used to map tool-chain |
| * version numbers to Compatibility Keys. |
| * |
| * Each target defines the format of the tool-chain version obtained |
| * from the tool-chain. The user can then map new tool-chain version |
| * strings to an appropriate compatibility key. |
| * |
| * Each target must respect the mapping defined by this table; i.e., |
| * if the user supplies a compatibility key in this map, it must be |
| * returned when `{@link #getVersion()}` is called. |
| * |
| * Thus, it is possible for the user to assert that any two compiler |
| * tool chains should be treated as equivalent (or incompatible) by |
| * mapping their version numbers to identical (incompatible) |
| * compatibility keys. |
| * |
| * @see ti.targets.ITarget#versionMap |
| */ |
| config String versionMap[string] = [ |
| ]; |
| |
| /*! |
| * ======== alignDirectiveSupported ======== |
| * The compiler supports an align directive. |
| */ |
| readonly config Bool alignDirectiveSupported = false; |
| |
| /*! |
| * ======== rootDir ======== |
| * Installation directory for this target's code generation tools. |
| * |
| * Since each target potentially "wraps" a different compiler tool-chain |
| * and each tool-chain will, in general, assume a different physical |
| * design for the installation of the compiler and its associated |
| * libraries and headers, one must consult each specific target to know |
| * how to set this parameter. |
| * |
| * If the `{@link #base}` parameter is `null`, this parameter *must* be |
| * set by the user; otherwise, `rootDir` defaults to the value |
| * `base.rootDir`. |
| */ |
| config String rootDir; |
| |
| /*! |
| * ======== CompileOptions ======== |
| * Options passed to the compiler/assembler. |
| * |
| * @field(aopts) a string of target-specific assembler options |
| * @field(copts) a string of target-specific C/C++ compiler options |
| * @field(cfgcopts) a string of C/C++ compiler options for C config file, |
| * includes 'copts' in addition to the value passed |
| * @field(defs) a string of macro definitions each of the form |
| * "`-Dname=value`" separated by white space |
| * @field(incs) a string of include directories each of the form |
| * "`-Idir`" separated by white space |
| * |
| * @a(Predefined Macros) |
| * The XDC Build Engine automatically adds several predefined macros via |
| * `-D` definitions that enable conditional compilation of source files |
| * based on build-specific attributes. |
| * @p(dlist) |
| * - `xdc_bld__profile_`{profile_name} |
| * this symbol is always defined and {profile_name} is the |
| * compile goal's (see `{@link #CompileGoal}`) profile name. |
| * @p |
| * |
| * In addition, each target defines a set of macros that enable clients |
| * to portably support big/little endian targets, for example. These |
| * macros are indirectly included by sources that include `xdc/std.h`; |
| * see `{@link xdc}`. |
| * |
| * @see #OptionSet |
| * @see #CompileGoal |
| * @see xdc |
| */ |
| struct CompileOptions { |
| String aopts; /*! goal specific ASM options */ |
| String copts; /*! goal specific C compiler options */ |
| String cfgcopts; /*! goal specific C config file options */ |
| String defs; /*! goal specific C/ASM definition options */ |
| String incs; /*! goal specific C/ASM include options */ |
| }; |
| |
| /*! |
| * ======== OptionSet ======== |
| * Collection of tool-chain options. |
| * |
| * This structure is used to define a collection of tool-chain |
| * options that are used as a group to achieve some effect supported |
| * by the tool-chain. For example, some compilers require that |
| * specific options be passed to the compiler *and* linker in order |
| * to generate execution profile information or code coverage |
| * statistics. |
| * |
| * @field(compilerOptions) a set of compiler/assembler options |
| * @field(linkOpts) a string of target-specific linker options |
| * @field(archiveOpts) a string of target-specific archiver options |
| * @field(filters) an array of filters applied (in order) to |
| * tool-chain commands |
| * |
| * @see #profiles |
| */ |
| struct OptionSet { |
| CompileOptions compileOpts; /*! profile-specific compiler opts */ |
| String linkOpts; /*! profile-specific linker opts */ |
| String archiveOpts; /*! profile-specific archiver opts */ |
| |
| ITargetFilter.InstDesc filters[]; /*! ITargetFilter instance descs */ |
| }; |
| |
| /*! |
| * ======== profiles ======== |
| * Profiles supported by this target. |
| * |
| * A profile is a collection of tool options used to create a |
| * library or executable that supports a certain "flavor" of library |
| * or executable; e.g., "debug" or "release". |
| * |
| * Some profile names are supported by all targets even though the |
| * targets use different compilers (and therefore different options). |
| * These profile names makes it possible for a package to build |
| * libraries or executables in a "debug" (or "release") profile |
| * independent of the target, for example. |
| * |
| * All targets are required to support "debug" and "release" profile |
| * names. |
| * |
| * Profile options are added to beginning of any goal specific options |
| * specified by the user before being passed to the target. |
| */ |
| config OptionSet profiles[string] = [ |
| ["release", {}], |
| ["debug", {}], |
| ]; |
| |
| /*! |
| * ======== CompileGoal ======== |
| * The goal specification passed to the `{@link #compile}` |
| * function. |
| * |
| * @see #compile |
| * @see #scompile |
| */ |
| struct CompileGoal { |
| String base; /*! base name of the source and destination */ |
| String dstPrefix; /*! directory prefix of destination file */ |
| String dstSuffix; /*! suffix of destination file; e.g., ".o62" */ |
| String srcSuffix; /*! optional suffix of source file; e.g., ".c" */ |
| String srcPrefix; /*! optional directory prefix of source file */ |
| String profile; /*! index into profiles map */ |
| CompileOptions opts;/*! goal specific compiler options */ |
| Bool configOpts; /*! true if compiling the generated C config file */ |
| }; |
| |
| /*! |
| * ======== LinkGoal ======== |
| * The goal specification passed to the `{@link #link}` function. |
| * |
| * @see #link |
| */ |
| struct LinkGoal { |
| String base; /*! base name of the source and destination */ |
| String dstPrefix; /*! directory prefix of destination file */ |
| String dstSuffix; /*! suffix of destination file; e.g., ".x62" */ |
| String files; /*! string of files to link with */ |
| String profile; /*! index into profiles map */ |
| String opts; /*! goal specific linker options */ |
| Bool dllMode; /*! true if we're linking an assembly */ |
| Bool isRom; /*! reflects the `isRom` attribute */ |
| }; |
| |
| /*! |
| * ======== ArchiveGoal ======== |
| * The goal specification passed to the `{@link #archive}` |
| * function. |
| * |
| * @see #archive |
| */ |
| struct ArchiveGoal { |
| String base; /*! base name of the source and destination */ |
| String dstPrefix; /*! directory prefix of destination file */ |
| String dstSuffix; /*! suffix of destination file; e.g., ".a62" */ |
| String files; /*! String of files to archive */ |
| String profile; /*! index into profiles map */ |
| String opts; /*! goal specific archiver options */ |
| }; |
| |
| /*! |
| * ======== CommandSet ======== |
| * The commands necessary to create a specified goal. |
| * |
| * This structure is the return value of the `{@link #compile}`, |
| * `{@link #link}` and `{@link #archive}` functions. This value is then |
| * used to generate a makefile or any other files necessary to generate |
| * a specified goal. |
| * |
| * @field(msg) a brief synopsis of the commands specified by `cmds`; |
| * this string is output in lieu of `cmds` when building |
| * in "non-verbose" mode. |
| * |
| * @field(cmds) a single string of commands that must be executed |
| * to complete the specified operation. Multiple |
| * commands may be specified by separating each command |
| * with the '\n' character. |
| * |
| * To facilitate the creation of "portable" makefiles and |
| * to simplify the implementation of targets, certain |
| * distinguished "macros" may be embedded in this string. |
| * The build engine replaces these macros with the |
| * values described below. |
| * @p(dlist) |
| * - `$(rootDir)` |
| * the target's `{@link #rootDir}` configuration |
| * parameter |
| * - `$(packageBase)` |
| * the target package's |
| * `{@link xdc.IPackage#packageBase}` property |
| * - `$(XDCINCS)` |
| * a set of "-I" options that names each |
| * repository in the package path |
| * @p |
| * |
| * @field(envs) an array of "name=value" strings that represent |
| * environment variables that are defined prior to the |
| * execution of the commands specified by `cmds` |
| * |
| * @field(path) an array of directory names that are used to compose |
| * the PATH environment variable that is in effect when |
| * the commands specified by `cmds` are run. |
| * |
| * @see #archive |
| * @see #compile |
| * @see #scompile |
| * @see #link |
| */ |
| struct CommandSet { |
| String msg; /*! brief message describing subsequent commands */ |
| String cmds; /*! commands necessary to generate goal */ |
| String path[]; /*! host-independent representation of PATH */ |
| String envs[]; /*! environment variable settings for the cmds */ |
| }; |
| |
| /*! |
| * ======== archive ======== |
| * Create an archive. |
| * |
| * This function is called during makefile generation to convert build |
| * goals into specific commands that generate the specified goal. |
| * |
| * @param(goal) the `{@link #ArchiveGoal}` defining the archive to build. |
| * |
| * @a(returns) |
| * This function returns a `{@link #CommandSet}`. If non-`null`, this |
| * object defines the commands that must be executed to create the |
| * specified object file. If `null`, then goal can not be achieved. |
| * |
| * @a(throws) `Error` exceptions are thrown for fatal errors. |
| */ |
| CommandSet* archive(ArchiveGoal *goal); |
| |
| /*! |
| * ======== compile ======== |
| * Compile a source file into an object file. |
| * |
| * This function is called during makefile generation to convert build |
| * goals into specific commands that generate the specified object |
| * file goal. |
| * |
| * @param(goal) a `{@link #CompileGoal}` that specifies what file to |
| * compile, the output file name, and any goal-specific |
| * options to use |
| * |
| * @a(returns) |
| * This function retuns a `{@link #CommandSet}`. If non-`null`, |
| * this object defines the commands that must be executed to create the |
| * specified object file. If `null`, then goal can not be achieved. |
| * |
| * @a(throws) `Error` exceptions are thrown for fatal errors. |
| */ |
| CommandSet* compile(CompileGoal *goal); |
| |
| /*! |
| * ======== scompile ======== |
| * Compile a source file into an assembly language file. |
| * |
| * This function is called during makefile generation to convert build |
| * goals into specific commands that generate the specified assembly |
| * language source goal. |
| * |
| * @param(goal) a `{@link #CompileGoal}` that specifies what file to |
| * compile, the output file name, and any goal-specific |
| * options to use |
| * |
| * @a(returns) |
| * This function returns a `{@link #CommandSet}`. If non-`null`, this |
| * object defines the commands that must be executed to create the |
| * specified assembly language file. If `null`, then goal |
| * can not be achieved or is unnecessary (e.g., because |
| * the source file is already an asm file). |
| * |
| * @a(throws) `Error` exceptions are thrown for fatal errors. |
| */ |
| CommandSet* scompile(CompileGoal *goal); |
| |
| /*! |
| * ======== link ======== |
| * Link object files to produce an executable. |
| * |
| * This function is called during makefile generation to convert build |
| * goals into specific commands that generate the specified goal. |
| * |
| * @param(goal) a `{@link #LinkGoal}` that specifies the output file |
| * name, a list of files to link with, and any goal-specific |
| * options to use |
| * |
| * @a(returns) |
| * This function returns a `{@link #CommandSet}`. If non-`null`, this |
| * object defines the commands that must be executed to create the |
| * specified object file. If `null`, then goal can not be |
| * achieved. |
| * |
| * @a(throws) `Error` exceptions are thrown for fatal errors. |
| */ |
| CommandSet* link(LinkGoal *goal); |
| |
| /*! |
| * ======== getVersion ======== |
| * Get a target-specific Compatibility Key string |
| * |
| * This function is called during makefile generation to obtain a |
| * target-specific Compatibility Key string. This string is of the |
| * form: |
| * @p(code) |
| * "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>" |
| * @p |
| * where, `<pkg>.<mod>` is the name of the target, and `<d0>`, `<d1>`, |
| * etc. forms a Compatibility Key. |
| * |
| * @a(returns) |
| * This function returns a string that encodes the name of the target |
| * and its Compatibility Key. |
| * |
| * @a(throws) `Error` exceptions are thrown for fatal errors. |
| */ |
| String getVersion(); |
| |
| typedef String StringArray[]; |
| |
| /*! |
| * ======== getISAChain ======== |
| * Get this target's ISA "is compatible with" relation. |
| * |
| * Returns an array of ISA names (including this target's ISA) that |
| * represents the "is a" relation between ISA's. The array starts with |
| * the most general ISA and ends with this target's ISA or with the |
| * optionally specified argument. This relation is used to: |
| * @p(nlist) |
| * - pre-define macro definitions that enable code to be |
| * conditionally compiled based on compatible versions of a |
| * target's ISA. |
| * |
| * - locate appropriate source files during makefile generation; |
| * each ISA named in a chain causes the extensions ".s"isa to be |
| * added to the ITarget.extensions table (in the reverse order |
| * that they appear in the chain). For example, if a target's |
| * ISA is "64P" and the returned chain is ["62", "64", "64P"], |
| * the following assembly language suffixes are added to |
| * the target's extensions table: ".s64P", ".s64", ".s62". |
| * @p |
| * |
| * This relation may also be used in the future to help validate |
| * combinations of targets and platforms; a target's CPU ISA must |
| * appear on the chain specified by the platform's CPU ISA. |
| * |
| * @param(isa) the ISA identifier string for the ISA to lookup; if null |
| * then the target's ISA is used (ITarget.isa). |
| * |
| * @a(returns) |
| * This function returns an array of ISA strings where the last string |
| * is the optionally specified ISA string or this target's ISA, |
| * and the first string is the "base" ISA in the |
| * is source compatible" relationship. |
| * If the specified ISA string is not in this target's chain |
| * of compatible targets, `null` is returned. |
| * |
| * @a(throws) `Error` exceptions are thrown for fatal errors. |
| * |
| */ |
| function getISAChain(isa); |
| |
| /*! |
| * ======== findSuffix ======== |
| * Find the suffix that is compatible with this target. |
| * |
| * This function determines the list of targets supported by the |
| * package given as the argument. From that list, this function |
| * returns the suffix of a target that is compatible with this target. |
| * Compatibility in this case means that object files created by a |
| * target having the suffix returned by this function can be linked |
| * into an executable produced using this target. In the case where more |
| * than one suffix is compatible, this function returns a suffix in the |
| * following order of preference: |
| * @p(nlist) |
| * - if this target's suffix is in the list, that suffix is returned. |
| * |
| * - suffixes from `compatibleSuffixes` are matched against the list |
| * in the order they appear in `compatibleSuffixes`, and the first one |
| * found in the list is returned. |
| * @p |
| * |
| * @param(pkg) a package object or an array of target suffix strings |
| * (see `{@link #suffix}`). |
| * |
| * @a(returns) |
| * This function returns the suffix string of a target compatible with |
| * this target or `null` if `pkg` does not support any target compatible |
| * with this target. |
| * |
| */ |
| function findSuffix(pkg); |
| |
| /*! |
| * ======== selectSuffix ======== |
| * Select the suffix that is compatible with this target. |
| * |
| * From a list of suffixes supplied as an argument, this function |
| * returns the suffix compatible with this target. Compatibility in |
| * this case means that object files created by a target having the |
| * suffix returned by this function can be linked into an executable |
| * produced using this target. In the case where more than one suffix |
| * is compatible, this function returns a suffix in the following order |
| * of preference: |
| * @p(nlist) |
| * - if this target's suffix is in the list, that suffix is returned. |
| * |
| * - suffixes from `compatibleSuffixes` are matched against the list |
| * in the order they appear in `compatibleSuffixes`, and the first one |
| * found in the list is returned. |
| * @p |
| * |
| * @param(suffixList) an array of target suffix strings |
| * (see `{@link #suffix}`). |
| * |
| * @a(returns) |
| * This function returns the suffix string of a target compatible with |
| * this target or `null` if no such suffix is found in the list of |
| * suffixes specified by the first argument. |
| * |
| */ |
| String selectSuffix(StringArray suffixList); |
| |
| /*! |
| * ======== sectMap ======== |
| * Output section name to segment type mapping |
| * |
| * This hash table is used to determine whether a particular object file |
| * output section (".text", ".stack", etc.) requires 'data', 'code' or |
| * 'stack' memory segment. |
| * |
| * This `sectMap` is referenced by linker command file templates during |
| * generation to create linker command files. The Platform defines the |
| * default memory segments for code and data, and based on this map and |
| * the default segments, the linker command file template places an |
| * output section into a physical memory segment. |
| * |
| * Note that the `{@link xdc.cfg.Program}` object and the |
| * `{@link xdc.platform.IPlatform}` instance have a |
| * `sectMap` parameter. Both the `Program`'s and `IPlatform`'s `sectMap` |
| * can augment and/or override the placement for a section, but |
| * `{@link xdc.cfg.Program#sectMap}` takes precedence. Therefore, this |
| * `sectMap` and the default segments from the platform define an |
| * initial section map which is then augmented by the `Program`'s and |
| * `IPlatform`'s section map. |
| */ |
| readonly config String sectMap[string]; |
| |
| /*! |
| * ======== TypeInfo ======== |
| * @_nodoc |
| * |
| * @see #StdTypes |
| */ |
| struct TypeInfo { |
| int size; |
| int align; |
| } |
| |
| /*! |
| * ======== StdTypes ======== |
| * Standard base types supported by all targets |
| * |
| * @see #stdTypes |
| */ |
| struct StdTypes { |
| TypeInfo t_IArg; |
| TypeInfo t_Char; |
| TypeInfo t_Double; |
| TypeInfo t_Float; |
| TypeInfo t_Fxn; |
| TypeInfo t_Int; |
| TypeInfo t_Int8; |
| TypeInfo t_Int16; |
| TypeInfo t_Int32; |
| TypeInfo t_Int40; |
| TypeInfo t_Int64; |
| TypeInfo t_Long; |
| TypeInfo t_LDouble; |
| TypeInfo t_LLong; |
| TypeInfo t_Ptr; |
| TypeInfo t_Short; |
| TypeInfo t_Size; |
| } |
| |
| /*! |
| * ======== stdInclude ======== |
| * Standard C/C++ types header |
| * |
| * This string identifies a header containing the C/C++ definitions |
| * required to enable use of `xdc/std.h` in C/C++ sources; see |
| * `{@link xdc}`. |
| * |
| * The value of this string is used by `xdc/std.h` to include |
| * target-specific definitions of the types `Int8`, `Int16`, etc. In |
| * addition, this header supplies target-specific definitions of the |
| * predefined `xdc_target__*` macros required by `{@link xdc xdc/std.h}`. |
| * |
| * Since this header must supply target-specific values for |
| * target-independent names the structure of this header is usually of |
| * the form: |
| * @p(code) |
| * // if target macros are not already defined, |
| * #if !defined(xdc_target_macros_include__) |
| * // include target-specific definitions |
| * #if defined(TARGET1) |
| * #include "target1.h" |
| * #elif defined(TARGET2) |
| * #include "target2.h" |
| * #elif ... |
| * : |
| * #else |
| * #error unsupported target |
| * #endif |
| * #endif |
| * // include common definitions |
| * : |
| * @p |
| * The check of the symbol `xdc_target_macros_include__` exists to |
| * allow others that define new targets to include this header to |
| * get common definitions for a family of related targets. |
| * |
| * To simplify the creation of the target-specific header files, the |
| * template file `stddefs.xdt` in this package can be used to |
| * automatically generate the required definitions from each target's |
| * `.xdc` specification. |
| */ |
| readonly config String stdInclude; |
| |
| /*! |
| * ======== stdTypes ======== |
| * Size and alignment for standard base types |
| * |
| * The values of size are the values returned by the |
| * target-specific `sizeof()` operator applied to the specified |
| * type (as defined by the C language). The align value is the number |
| * of chars used in the alignment of the specified type. |
| */ |
| readonly config StdTypes stdTypes = { |
| t_IArg : { size: 0, align: 0 }, |
| t_Char : { size: 0, align: 0 }, |
| t_Double : { size: 0, align: 0 }, |
| t_Float : { size: 0, align: 0 }, |
| t_Fxn : { size: 0, align: 0 }, |
| t_Int : { size: 0, align: 0 }, |
| t_Int8 : { size: 0, align: 0 }, |
| t_Int16 : { size: 0, align: 0 }, |
| t_Int32 : { size: 0, align: 0 }, |
| t_Int40 : { size: 0, align: 0 }, |
| t_Int64 : { size: 0, align: 0 }, |
| t_Long : { size: 0, align: 0 }, |
| t_LDouble : { size: 0, align: 0 }, |
| t_LLong : { size: 0, align: 0 }, |
| t_Ptr : { size: 0, align: 0 }, |
| t_Short : { size: 0, align: 0 }, |
| t_Size : { size: 0, align: 0 }, |
| }; |
| |
| /*! |
| * ======== bitsPerChar ======== |
| * The number of bits in a variable of type `char` |
| * |
| * This constant allows one to determine the precise number of bits in |
| * each of the types specified in the stdTypes map. For example, the |
| * number of bits in the target `T`'s `int` type is |
| * @p(code) |
| * T.stdTypes.t_Int.size * T.bitsPerChar |
| * @p |
| */ |
| readonly config Int bitsPerChar = 8; |
| } |
