metaonly interface gnu.targets.arm.IM

Common interface for Cortex M bare metal targets

This defines common parameters of Cortex M bare metal targets. The targets generate code compatible with the "v7M" architecture.
XDCspec summary sourced in gnu/targets/arm/IM.xdc
metaonly interface IM {  ...
    // inherits gnu.targets.ITarget
        // inherits xdc.bld.ITarget3
            // inherits xdc.bld.ITarget2
                // inherits xdc.bld.ITarget
XDCspec declarations sourced in gnu/targets/arm/IM.xdc
package gnu.targets.arm;
 
metaonly interface IM inherits ITarget {
module-wide constants & types
    typedef String StringArray// [];
 
        String files// String of files to archive;
        String profile// index into profiles map;
        String opts// goal specific archiver options;
    };
 
    metaonly struct Command// Required command and options {
        String cmd// the command to run;
        String opts// required options for the command;
    };
 
    };
 
        String profile// index into profiles map;
    };
 
        String aopts// goal specific ASM options;
    };
 
    metaonly struct DebugGen// Debugger integration support {
        String execPattern// exec file name pattern;
    };
 
    };
 
        String files// string of files to link with;
        String profile// index into profiles map;
        String opts// goal specific linker options;
        Bool isRom// reflects the isRom attribute;
    };
 
    metaonly struct Model// Target runtime model {
        String endian// endian-ness of this target;
        String codeModel// target-specific code model;
        String dataModel// target-specific data model;
    };
 
        String linkOpts// profile-specific linker opts;
    };
 
    };
 
        ITarget.TypeInfo t_IArg;
        ITarget.TypeInfo t_Char;
        ITarget.TypeInfo t_Double;
        ITarget.TypeInfo t_Float;
        ITarget.TypeInfo t_Fxn;
        ITarget.TypeInfo t_Int;
        ITarget.TypeInfo t_Int8;
        ITarget.TypeInfo t_Int16;
        ITarget.TypeInfo t_Int32;
        ITarget.TypeInfo t_Int40;
        ITarget.TypeInfo t_Int64;
        ITarget.TypeInfo t_Long;
        ITarget.TypeInfo t_LDouble;
        ITarget.TypeInfo t_LLong;
        ITarget.TypeInfo t_Ptr;
        ITarget.TypeInfo t_Short;
        ITarget.TypeInfo t_Size;
    };
module-wide config parameters
    readonly config Bool CYGWIN// Is the target's compiler a cygwin executable = false;
    override readonly config Bool alignDirectiveSupported// The compiler supports an align directive = true;
    override readonly config ITarget2.Command ar// The command used to create an archive = {
        cmd: "$(rootDir)/bin/$(GCCTARG)-ar",
        opts: "cr"
    };
    readonly config ITarget2.Command arBin//  = {
        cmd: "bin/arm-none-eabi-ar ",
        opts: ""
    };
        cmd: "$(rootDir)/bin/$(GCCTARG)-gcc -c -x assembler",
        opts: ""
    };
        cmd: "$(rootDir)/bin/$(GCCTARG)-gcc -c -MD -MF $@.dep",
        opts: ""
    };
    readonly config String isa// CPU Instruction Set Architecture (ISA);
    override readonly config ITarget2.Command lnk// The command used to link executables = {
        cmd: "$(rootDir)/bin/$(GCCTARG)-gcc",
        opts: ""
    };
    override readonly config ITarget.Model model// Run-time model = {
        endian: "little",
        codeModel: "thumb2",
        shortEnums: true
    };
    readonly config String name// Nickname for this target;
    override readonly config String rts// Name of a run-time support package to include = "gnu.targets.arm.rtsv7M";
    readonly config String sectMap// Output section name to segment type mapping[string];
    override readonly config String stdInclude// Standard C/C++ types header = "gnu/targets/arm/std.h";
        t_IArg: {
            size: 4,
            align: 4
        },
        t_Char: {
            size: 1,
            align: 1
        },
        t_Double: {
            size: 8,
            align: 8
        },
        t_Float: {
            size: 4,
            align: 4
        },
        t_Fxn: {
            size: 4,
            align: 4
        },
        t_Int: {
            size: 4,
            align: 4
        },
        t_Int8: {
            size: 1,
            align: 1
        },
        t_Int16: {
            size: 2,
            align: 2
        },
        t_Int32: {
            size: 4,
            align: 4
        },
        t_Int64: {
            size: 8,
            align: 8
        },
        t_Long: {
            size: 4,
            align: 4
        },
        t_LDouble: {
            size: 8,
            align: 8
        },
        t_LLong: {
            size: 8,
            align: 8
        },
        t_Ptr: {
            size: 4,
            align: 4
        },
        t_Short: {
            size: 2,
            align: 2
        },
        t_Size: {
            size: 4,
            align: 4
        }
    };
 
    override config String GCCTARG// The name of the platform executing programs produced by this target = "arm-none-eabi";
        prefix: "",
        suffix: ""
    };
        prefix: "",
        suffix: ""
    };
        prefix: "$(ccOpts.prefix)",
        suffix: "$(ccOpts.suffix)"
    };
        prefix: "-Wunused -Wunknown-pragmas -ffunction-sections -fdata-sections ",
        suffix: "-Dfar= -D__DYNAMIC_REENT__ "
    };
    config String execExt// Extension for executables;
        [
            ".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"
            }
        ]
    ];
        prefix: "",
        suffix: "-Wl,-Map=$(XDCCFGDIR)/$@.map -lstdc++ -L$(rootDir)/lib"
    };
    override config String platform// The default platform name for this target = "ti.platforms.tiva:TM4C1294NCPDT";
        [
            "debug",
            {
                compileOpts: {
                    copts: "-g",
                    defs: "-D_DEBUG_=1"
                },
                linkOpts: "-g"
            }
        ],
        [
            "release",
            {
                compileOpts: {
                    copts: " -O2 "
                },
                linkOpts: " "
            }
        ]
    ];
        [
            "gcc3.2",
            "1,0,3.2,0"
        ]
    ];
module-wide functions
    String initVers// ();
}
 
typedef IM.StringArray
XDCspec declarations sourced in gnu/targets/arm/IM.xdc
typedef String StringArray[];
 
 
struct IM.ArchiveGoal

The goal specification passed to the archive function

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
};
 
SEE
 
struct IM.Command

Required command and options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly struct Command {
    String cmd;
    // the command to run
    String opts;
    // required options for the command
};
 
FIELDS
cmd — name of a tool-chain executable without any path information. The location of this executable is specified by the binDir (or pathPrefix) configuration parameter.
opts — required options passed to the command; these options can not be changed or eliminated by user's configuration script.
DETAILS
The compile, link, and archive functions in this interface are implemented by expanding the strings specified in this structure and inserting strings from the Options structure to form a single command. The strings in this structure can not be changed by the user (they are fixed by the target), but the string in the Options structure may be changed by the user.
The final command is: Command.cmd Options.prefix Command.opts Options.suffix
 
struct IM.CommandSet

The commands necessary to create a specified goal

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
};
 
FIELDS
msg — a brief synopsis of the commands specified by cmds; this string is output in lieu of cmds when building in "non-verbose" mode.
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.
$(rootDir)
the target's rootDir configuration parameter
$(packageBase)
the target package's xdc.IPackage.packageBase property
$(XDCINCS)
a set of "-I" options that names each repository in the package path
envs — an array of "name=value" strings that represent environment variables that are defined prior to the execution of the commands specified by cmds
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.
DETAILS
This structure is the return value of the compile, link and archive functions. This value is then used to generate a makefile or any other files necessary to generate a specified goal.
SEE
 
struct IM.CompileGoal

The goal specification passed to the compile function

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
    ITarget.CompileOptions opts;
    // goal specific compiler options
    Bool configOpts;
    // true if compiling the generated C config file
};
 
SEE
 
struct IM.CompileOptions

Options passed to the compiler/assembler

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
};
 
FIELDS
aopts — a string of target-specific assembler options
copts — a string of target-specific C/C++ compiler options
cfgcopts — a string of C/C++ compiler options for C config file, includes 'copts' in addition to the value passed
defs — a string of macro definitions each of the form "-Dname=value" separated by white space
incs — a string of include directories each of the form "-Idir" separated by white space
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.
xdc_bld__profile_{profile_name}
this symbol is always defined and {profile_name} is the compile goal's (see CompileGoal) profile name.
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 xdc.
SEE
 
struct IM.DebugGen

Debugger integration support

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
};
 
DETAILS
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:
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", ...
Preconditions for the packageTemplate:
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 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", ...
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:
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.
Both the exeDir and cfgDir are relative to the directory containing the package.bld script.
Built-in variables for packagePattern:
pkgName
the package's name (e.g., "ti.targets");
trgName
the target's name property;
trgSuffix
the target's suffix property.
SEE
 
struct IM.Extension

File extension to file type association

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly struct Extension {
    String suf;
    // file extension (including any '.')
    String typ;
    // type of this file; e.g., "c", "asm", ..
};
 
FIELDS
suf — the file extension including any '.' characters
typ — the type of the file having this extension. Allowable file type identifiers include:
"c"
C language source file
"asm"
assembly language source file
"cpp"
C++ language source file
DETAILS
This structure is used by the Build Engine to determine whether a file should be treated as C++, C, or assembly language source.
SEE
 
struct IM.LinkGoal

The goal specification passed to the link function

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
};
 
SEE
 
struct IM.Model

Target runtime model

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly 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
};
 
FIELDS
— (endian) this string specifies the endianess of the generated code. Valid values include:
"big"
big endian
"little"
little endian
null
unspecified
(codeModel) this string specifies a target-specific code size model. Valid values include:
"near"
C54 near mode
"far"
C54 far mode
undefined
unspecified
(dataModel) this string specifies a target-specific data size model. Valid values include:
"large"
C55, C28 large model
undefined
unspecified
(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
 
struct IM.OptionSet

Collection of tool-chain options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly struct OptionSet {
    ITarget.CompileOptions compileOpts;
    // profile-specific compiler opts
    String linkOpts;
    // profile-specific linker opts
    String archiveOpts;
    // profile-specific archiver opts
    ITargetFilter.InstDesc filters[];
    // ITargetFilter instance descs
};
 
FIELDS
compilerOptions — a set of compiler/assembler options
linkOpts — a string of target-specific linker options
archiveOpts — a string of target-specific archiver options
filters — an array of filters applied (in order) to tool-chain commands
DETAILS
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.
SEE
 
struct IM.Options

User configurable command options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly struct Options {
    String prefix;
    // options that appear before Command.opts
    String suffix;
    // options that appear after Command.opts
};
 
DETAILS
The option strings allow the user to pass additional parameters to the executable that is responsible for compiling, linker, or archiving. See xdc.bld.ITarget2.Command.
 
struct IM.StdTypes

Standard base types supported by all targets

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
metaonly struct StdTypes {
    ITarget.TypeInfo t_IArg;
    ITarget.TypeInfo t_Char;
    ITarget.TypeInfo t_Double;
    ITarget.TypeInfo t_Float;
    ITarget.TypeInfo t_Fxn;
    ITarget.TypeInfo t_Int;
    ITarget.TypeInfo t_Int8;
    ITarget.TypeInfo t_Int16;
    ITarget.TypeInfo t_Int32;
    ITarget.TypeInfo t_Int40;
    ITarget.TypeInfo t_Int64;
    ITarget.TypeInfo t_Long;
    ITarget.TypeInfo t_LDouble;
    ITarget.TypeInfo t_LLong;
    ITarget.TypeInfo t_Ptr;
    ITarget.TypeInfo t_Short;
    ITarget.TypeInfo t_Size;
};
 
SEE
 
config IM.CYGWIN  // module-wide

Is the target's compiler a cygwin executable

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config Bool CYGWIN = false;
 
DETAILS
Since file names produced by cygwin-based tools differ from the names understood by other Windows executables, it is important to avoid using the names output by cygwin tools as input to non-cygwin programs. This property tells the target whether or not it's possible to use the output from gcc -MD -MF, for example.
 
config IM.alignDirectiveSupported  // module-wide

The compiler supports an align directive

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config Bool alignDirectiveSupported = true;
 
 
config IM.ar  // module-wide

The command used to create an archive

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config ITarget2.Command ar = {
    cmd: "$(rootDir)/bin/$(GCCTARG)-ar",
    opts: "cr"
};
 
 
config IM.arBin  // module-wide
XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config ITarget2.Command arBin = {
    cmd: "bin/arm-none-eabi-ar ",
    opts: ""
};
 
 
config IM.asm  // module-wide

The command used to assembles assembly source files into object files

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config ITarget2.Command asm = {
    cmd: "$(rootDir)/bin/$(GCCTARG)-gcc -c -x assembler",
    opts: ""
};
 
 
config IM.base  // module-wide

A target that this target is based upon

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config ITarget.Module base;
 
DETAILS
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 rootDir is the value of the base's rootDir setting.
 
config IM.bitsPerChar  // module-wide

The number of bits in a variable of type char

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config Int bitsPerChar = 8;
 
DETAILS
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
      T.stdTypes.t_Int.size * T.bitsPerChar
 
config IM.cc  // module-wide

The command used to compile C/C++ source files into object files

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config ITarget2.Command cc = {
    cmd: "$(rootDir)/bin/$(GCCTARG)-gcc -c -MD -MF $@.dep",
    opts: ""
};
 
 
config IM.isa  // module-wide

CPU Instruction Set Architecture (ISA)

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config String isa;
 
DETAILS
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
 
config IM.lnk  // module-wide

The command used to link executables

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config ITarget2.Command lnk = {
    cmd: "$(rootDir)/bin/$(GCCTARG)-gcc",
    opts: ""
};
 
 
config IM.model  // module-wide

Run-time model

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config ITarget.Model model = {
    endian: "little",
    codeModel: "thumb2",
    shortEnums: true
};
 
DETAILS
This structure identifies a particular run-time model used by the compiler to generate instructions.
 
config IM.name  // module-wide

Nickname for this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config String name;
 
DETAILS
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.
 
config IM.os  // module-wide

Name of OS required to run programs built for this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config String os;
 
DETAILS
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.
 
config IM.rts  // module-wide

Name of a run-time support package to include

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config String rts = "gnu.targets.arm.rtsv7M";
 
DETAILS
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 xdc.bld.Executable.attrs.rtsName attribute is set to null; see xdc.bld.Executable.Attrs.
 
config IM.sectMap  // module-wide

Output section name to segment type mapping

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config String sectMap[string];
 
DETAILS
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 xdc.cfg.Program object and the 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 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.
 
config IM.stdInclude  // module-wide

Standard C/C++ types header

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config String stdInclude = "gnu/targets/arm/std.h";
 
DETAILS
This string identifies a header containing the C/C++ definitions required to enable use of xdc/std.h in C/C++ sources; see 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 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:
      // 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
          :
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.
 
config IM.stdTypes  // module-wide

Size and alignment for standard base types

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override readonly config ITarget.StdTypes stdTypes = {
    t_IArg: {
        size: 4,
        align: 4
    },
    t_Char: {
        size: 1,
        align: 1
    },
    t_Double: {
        size: 8,
        align: 8
    },
    t_Float: {
        size: 4,
        align: 4
    },
    t_Fxn: {
        size: 4,
        align: 4
    },
    t_Int: {
        size: 4,
        align: 4
    },
    t_Int8: {
        size: 1,
        align: 1
    },
    t_Int16: {
        size: 2,
        align: 2
    },
    t_Int32: {
        size: 4,
        align: 4
    },
    t_Int64: {
        size: 8,
        align: 8
    },
    t_Long: {
        size: 4,
        align: 4
    },
    t_LDouble: {
        size: 8,
        align: 8
    },
    t_LLong: {
        size: 8,
        align: 8
    },
    t_Ptr: {
        size: 4,
        align: 4
    },
    t_Short: {
        size: 2,
        align: 2
    },
    t_Size: {
        size: 4,
        align: 4
    }
};
 
DETAILS
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.
 
config IM.suffix  // module-wide

Suffix appended to all objs, libraries, and executable

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
readonly config String suffix;
 
DETAILS
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:
".a<suffix>"
archive files (i.e., libraries)
".o<suffix>"
object files
".s<suffix>"
assembly language source (see scompile())
".x<suffix>"
executable files
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
 
config IM.BINVERS  // module-wide

Version number of binutils used with the compiler; e.g., "2.19"

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String BINVERS = null;
 
DETAILS
This string can be supplied by the user, otherwise it is obtained by running "ld -v".
 
config IM.GCCTARG  // module-wide

The name of the platform executing programs produced by this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String GCCTARG = "arm-none-eabi";
 
DETAILS
This string can be supplied by the user, otherwise is is obtained from the compiler and follows the GNU standard format (<cpu>-<manufacturer>-<os> or <cpu>-<manufacturer>-<kernel>-<os>); e.g., "arm-none-eabi" or "x86_64-unknown-linux-gnu".
When building a GCC compiler, there are three different execution platforms to consider: the platform used to "build" the compiler, the "host" platform that runs the compiler, and the "target" platform that runs the executables produced by the compiler. All three platforms are identified using a configuration name defined by GNU Autotools. GCCTARG is the name of the "target" platform.
 
config IM.GCCVERS  // module-wide

Version number of the GCC compiler; e.g., "3.2"

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String GCCVERS = null;
 
DETAILS
This string can be supplied by the user, otherwise it is obtained by running "gcc -dumpversion".
 
config IM.arOpts  // module-wide

User configurable archiver options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config ITarget2.Options arOpts = {
    prefix: "",
    suffix: ""
};
 
 
config IM.asmOpts  // module-wide

User configurable assembler options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config ITarget2.Options asmOpts = {
    prefix: "",
    suffix: ""
};
 
 
config IM.bspLib  // module-wide

bspLib is assigned the name of the BSP library. The specified library is included on the link line

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String bspLib = "nosys";
 
DETAILS
Possible values for this field are "nosys" and "rdimon" with the default being "nosys".
 
config IM.ccConfigOpts  // module-wide

User configurable compiler options for the generated config C file

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config ITarget2.Options ccConfigOpts = {
    prefix: "$(ccOpts.prefix)",
    suffix: "$(ccOpts.suffix)"
};
 
DETAILS
By default, this parameter inherits values specified in ccOpts. The strings "$(ccOpts.prefix)" and "$(ccOpts.suffix)" are expanded into the values specified by ccOpts for this target.
 
config IM.ccOpts  // module-wide

User configurable compiler options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config ITarget2.Options ccOpts = {
    prefix: "-Wunused -Wunknown-pragmas -ffunction-sections -fdata-sections ",
    suffix: "-Dfar= -D__DYNAMIC_REENT__ "
};
 
 
config IM.compatibleSuffixes  // module-wide

Array of suffixes used by targets compatible with this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String compatibleSuffixes[] = [ ];
 
DETAILS
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 IM.debugGen  // module-wide

Debugger/IDE file generation support

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config ITarget.DebugGen debugGen;
 
DETAILS
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 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:
	    Program.gen.debuggerFiles = true;
It is also possible to disable the generation of selected files by setting the appropriate fields of DebugGen to null in your config.bld script.
 
config IM.execExt  // module-wide

Extension for executables

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String execExt;
 
DETAILS
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:
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
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 IM.extensions  // module-wide

File extensions recognized by this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config ITarget.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"
        }
    ]
];
 
DETAILS
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:
      var C64P = xdc.module('ti.targets.C64P');
      C64P.extensions[".s64"] = {
          suf: ".s64", typ: "asm"
      };
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:
      var C64P = xdc.module('ti.targets.C64P');
      delete C64P.extensions[".asm"];
 
config IM.includeOpts  // module-wide

Additional user configurable target-specific include path options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String includeOpts = "";
 
 
config IM.lnkOpts  // module-wide

User configurable linker options

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config ITarget2.Options lnkOpts = {
    prefix: "",
    suffix: "-Wl,-Map=$(XDCCFGDIR)/$@.map -lstdc++ -L$(rootDir)/lib"
};
 
 
config IM.noStdLinkScript  // module-wide

Don't use the standard linker script

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config Bool noStdLinkScript = false;
 
DETAILS
If true, add a -T flag before the generated package/cfg/*.xdl file passed to the linker. This flag suppresses use of the standard linker script implicit in the GCC flow, which effectively says the generated .xdl file assumes total control for all MEMORY and SECTION directives.
 
config IM.platform  // module-wide

The default platform name for this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String platform = "ti.platforms.tiva:TM4C1294NCPDT";
 
DETAILS
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 platforms array is non-empty, it is initialized to be the first element of the platforms array (i.e., platforms[0]).
 
config IM.platforms  // module-wide

A set of platforms that can support this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String platforms[] = [ ];
 
DETAILS
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 platform is non-null, platforms is initialized to an array of one element equal to platform.
 
config IM.profiles  // module-wide

Profiles supported by this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config ITarget.OptionSet profiles[string] = [
    [
        "debug",
        {
            compileOpts: {
                copts: "-g",
                defs: "-D_DEBUG_=1"
            },
            linkOpts: "-g"
        }
    ],
    [
        "release",
        {
            compileOpts: {
                copts: " -O2 "
            },
            linkOpts: " "
        }
    ]
];
 
DETAILS
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 IM.rawVersion  // module-wide

The raw version string from the compiler

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String rawVersion;
 
READONLY
This value is automatically computed by the XDC Build Engine by executing the getRawVersion() function after package.bld completes but prior to generating package.mak.
 
config IM.remoteHost  // module-wide

Remote host used to run compiler, linker, and archiver tools

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String remoteHost;
 
DETAILS
If remoteHost is null (or undefined), the configured compiler is run locally; otherwise, remoteHost is taken to be the host name of the machine that that should be used to run the specified compiler.
All target commands are prefixed with a command that uses rsh to run the commands on the specified host. Thus, in order to use this setting, the remote machine must be support rsh and the user must have permission to run commands from the local machine on the remote host named remoteHost. This usually involves adding a line to the user's ~/.rhosts file on the remote machine of the form:
      local-machine-name user-name
where local-machine-name is the name of the local machine and user-name is the user's login name on the local machine.
 
config IM.rootDir  // module-wide

Installation directory for this target's code generation tools

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String rootDir;
 
DETAILS
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 base parameter is null, this parameter *must* be set by the user; otherwise, rootDir defaults to the value base.rootDir.
 
config IM.targetPkgPath  // module-wide

targetPkgPath controls the path to the package that contains the GNU libraries

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
config String targetPkgPath = null;
 
 
config IM.version  // module-wide

The Compatibility Key associated with this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String version;
 
DETAILS
The first two components of this target's Compatibility Key are '1,0'. The rest of the Key represents the compiler version. The third component combines the major and the minor version number in the format Major.Minor. The fourth component is the patch number.
READONLY
This value is automatically computed by the XDC Build Engine by executing the getVersion() function after package.bld completes but prior to generating package.mak.
EXAMPLE
If this target's rootDir points to the compiler version 3.4.6, the Compatibility Key is [1,0,3.4,6].
 
config IM.versionMap  // module-wide

Map of GCC compiler version numbers to compatibility keys

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
override config String versionMap[string] = [
    [
        "gcc3.2",
        "1,0,3.2,0"
    ]
];
 
DETAILS
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 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.
This map translates version string information from the compiler into a compatibility key. The compatibilty key is used to validate consistency among a collection of packages used in a configuration.
The compiler version string is "gcc<ver>", where <ver> is GCCVERS.
If a compiler version is not found in this map the default is "1,0,<ver>", where <ver> is the compiler version number. Thus, the user only needs to extend this table when a significant incompatibility occurs or when two versions of the compiler should be treated as 100% compatible.
SEE
 
IM.archive()  // module-wide

Create an archive

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
 
ARGUMENTS
goal — the ArchiveGoal defining the archive to build.
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified goal.
RETURNS
This function returns a 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.
THROWS
Error exceptions are thrown for fatal errors.
 
IM.asmName()  // module-wide

The function that converts a C name into an assembly name

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String asmName(String CName);
 
 
IM.compile()  // module-wide

Compile a source file into an object file

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
 
ARGUMENTS
goal — a CompileGoal that specifies what file to compile, the output file name, and any goal-specific options to use
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified object file goal.
RETURNS
This function retuns a 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.
THROWS
Error exceptions are thrown for fatal errors.
 
IM.findSuffix()  // module-wide

Find the suffix that is compatible with this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
function findSuffix(pkg);
 
ARGUMENTS
pkg — a package object or an array of target suffix strings (see suffix).
DETAILS
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:
  1. if this target's suffix is in the list, that suffix is returned.
  2. 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.
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.
 
IM.genConstCustom()  // module-wide

Return any custom generated code related to generated constants

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String genConstCustom(ITarget2.StringArray names, ITarget2.StringArray types);
 
DETAILS
This function is invoked for each constant in the generated config C file. This includes module-level config parameter, as well as the internal data structures that define modules, interfaces and instances. A target is given a chance to add any target-specific pragmas or attributes for the generated constants. The set of the data supplied to this function overlaps with the data supplied to genVisibleData, so their output must be coordinated to avoid duplicate or inconsistent definitions or directives.
PARAMS
array of constant names generated in the config C file
array of types; each type corresponds to the element of names with the same index
RETURNS
This function returns custom C code that will be embedded into the generated config C file. If there is nothing to be added, this function returns null. If a target never generates any such code, it can rely on the default implementation that always returns null.
 
IM.genVisibleData()  // module-wide

Return any custom generated code related to data generated in the config C file

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String genVisibleData(ITarget2.StringArray quals, ITarget2.StringArray types, ITarget2.StringArray names);
 
DETAILS
This function is invoked for each module-level configuration parameter in the configuration. Such parameters are represented by constants in the generated config C file.
A target is given a chance to add any target-specific pragmas or attributes for the generated constants. The set of the data supplied to this function overlaps with the data supplied to genConstCustom, so their output must be coordinated to avoid duplicate or inconsistent definitions or directives.
PARAMS
array of declaration qualifiers for the generated data
array of types for the generated data
array of variable names; each name corresponds to the elements of quals and types with the same index
RETURNS
This function returns custom C code that will be embedded into the generated config C file. The purpose of the function is to allow targets to add pragmas or attributes to prevent elimination of data in case of partially linker objects. If there is nothing to be added, this function returns null. If a target never generates any such code, it can rely on the default implementation that always returns null.
 
IM.genVisibleFxns()  // module-wide

Return any custom generated code related to functions generated in the config C file

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String genVisibleFxns(ITarget2.StringArray types, ITarget2.StringArray names, ITarget2.StringArray args);
 
PARAMS
array of types of functions' return values
array of functions' names; each name corresponds to the elements of types and args with the same index
array of functions' argument lists, including qualifiers
RETURNS
This function returns custom C code that will be embedded into the generated config C file. The purpose of the function is to allow targets to add pragmas or attributes to prevent elimination of functions in case of partially linker objects.
 
IM.genVisibleLibFxns()  // module-wide

Return any custom generated code related to functions that are included in the configuration, but are not generated in the config C file

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String genVisibleLibFxns(ITarget2.StringArray types, ITarget2.StringArray names, ITarget2.StringArray args);
 
PARAMS
array of types of functions' return values
array of functions' names; each name corresponds to the elements of types and args with the same index
array of functions' argument lists, including qualifiers
RETURNS
This function returns custom C code that will be embedded into the generated config C file. The purpose of the function is to allow targets to add pragmas or attributes to prevent elimination of functions in case of partially linker objects. These functions are managed separately from the functions that are generated in the config C file because some pragmas and attributes can be used only for functions defined in the same compilation unit where the paragmas and attributes are generated. For functions that are not generated in the config C file, and the mentioned restrictions exist, targets may have to create references that will prevent elimination of functions defined outside of the config C file.
 
IM.getISAChain()  // module-wide

Get this target's ISA "is compatible with" relation

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
function getISAChain(isa);
 
ARGUMENTS
isa — the ISA identifier string for the ISA to lookup; if null then the target's ISA is used (ITarget.isa).
DETAILS
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:
  1. pre-define macro definitions that enable code to be conditionally compiled based on compatible versions of a target's ISA.
  2. 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".
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.
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.
THROWS
Error exceptions are thrown for fatal errors.
 
IM.getRawVersion()  // module-wide

Get a target-specific raw compiler version string

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String getRawVersion();
 
DETAILS
This function is called during makefile generation to obtain a target-specific raw compiler version string.
RETURNS
This function returns a string, typically provided by the compiler itself, that identifies the version of the compiler referenced by rootDir.
THROWS
Error exceptions are thrown for fatal errors.
 
IM.getVersion()  // module-wide

Get a target-specific Compatibility Key string

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String getVersion();
 
DETAILS
This function is called during makefile generation to obtain a target-specific Compatibility Key string. This string is of the form:
      "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>"
where, <pkg>.<mod> is the name of the target, and <d0>, <d1>, etc. forms a Compatibility Key.
RETURNS
This function returns a string that encodes the name of the target and its Compatibility Key.
THROWS
Error exceptions are thrown for fatal errors.
 
IM.initVers()  // module-wide
XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String initVers();
 
 
IM.link()  // module-wide

Link object files to produce an executable

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
 
ARGUMENTS
goal — a LinkGoal that specifies the output file name, a list of files to link with, and any goal-specific options to use
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified goal.
RETURNS
This function returns a 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.
THROWS
Error exceptions are thrown for fatal errors.
 
IM.scompile()  // module-wide

Compile a source file into an assembly language file

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
 
ARGUMENTS
goal — a CompileGoal that specifies what file to compile, the output file name, and any goal-specific options to use
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified assembly language source goal.
RETURNS
This function returns a 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).
THROWS
Error exceptions are thrown for fatal errors.
 
IM.selectSuffix()  // module-wide

Select the suffix that is compatible with this target

XDCspec declarations sourced in gnu/targets/arm/IM.xdc
String selectSuffix(ITarget.StringArray suffixList);
 
ARGUMENTS
suffixList — an array of target suffix strings (see suffix).
DETAILS
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:
  1. if this target's suffix is in the list, that suffix is returned.
  2. 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.
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.
generated on Tue, 14 Feb 2017 20:00:15 GMT