metaonly module xdc.cfg.Program

The Program object for the configuration object model

This module defines the "root" of the configuration object model; all "top-level" configuration settings for the executable are provided by this object. Program configuration scripts reference this module via the global variable Program; i.e., Program is implicitly initialized as follows: [ more ... ]
Configuration settings sourced in xdc/cfg/Program.xdc
var Program = xdc.useModule('xdc.cfg.Program');
module-wide constants & types
 
        obj.runSegment// segment where section contents are run = String  ...
        obj.loadSegment// segment where section contents are loaded = String  ...
        obj.runAddress// start address of section when run = UInt  ...
        obj.loadAddress// start address of section when loaded = UInt  ...
        obj.runAlign// alignment of section within runSegment = UInt  ...
        obj.loadAlign// alignment of section within loadSegment = UInt  ...
        obj.type// target-specific flags = String  ...
        obj.fill// fill value = UInt  ...
module-wide config parameters
    Program.global// Global variable declarations = Any[string] undefined;
    Program.main// The main entry point for the program = Int(*)(Int,Char*[]) undefined;
module-wide functions
 
DETAILS
This module defines the "root" of the configuration object model; all "top-level" configuration settings for the executable are provided by this object. Program configuration scripts reference this module via the global variable Program; i.e., Program is implicitly initialized as follows:
      var Program = xdc.useModule('xdc.cfg.Program');
After a configuration script completes successfully, the following files are generated:
  1. package/cfg/<exe_name>.c
  2. package/cfg/<exe_name>.xdl
where <exe_name> is the name of the executable with the final '.' character replaced with an '_'.
The generated C file contains code and data from each module used by the program and must be compiled and linked with the other sources to produce the final executable. The generated linker command file must also be added during this final link step.
The linker command file is produced by expanding a template provided by the platform specifed during configuration and contains hardware and compiler specific directives required by the target modules that are part of the program's configuration. This template expands other templates specified by each imported package's getSects method, for example. This allows each package participating in the configuration executable to automatically contribute a portion of the executable's linker command file.
You can modify or augment the contents of this file via sectionsExclude and sectionsTemplate. It is even possible to completely replace the template used to generate this file via linkTemplate. These configuration options provide the user complete control of the linker command file
 
struct Program.GenerationOptions

Options that control the files generated as part of program configuration

Configuration settings
var obj = new Program.GenerationOptions;
 
    obj.debuggerFiles = Bool  ...
    // if true, generate debugger "project" files
 
FIELDS
debuggerFiles — If set to true in a configuration script, debugger project files will be generated as part of the configuration step. If set to false, these files will not be generated.
If it is not set (or set to undefined) and the environment variable environment["xdc.cfg.gen.debuggerFiles"] is non-null, then the default value of this parameter is taken to be the value of the following expression:
		    environment["xdc.cfg.gen.debuggerFiles"] == "true"
This makes it is possible to enable the generation of debugger project files from build scripts by passing the option -Dxdc.cfg.gen.debuggerFiles=true to the configuration tool (see xdc.bld.Executable.Attrs.xsopts or xdc.bld.PackageContents.Attrs.xsopts).
Finally, if debuggerFiles is not set (or set to undefined) and the environment variable above is not defined, the generation of debugger project files occurs only if xdc.cfg.Program.build.profile contains the string "debug". So, unless otherwise specified, debug profiles result in debugger project files being generated.
 
struct Program.SectionSpec

Map that instructs the linker where to place output sections

Configuration settings
var obj = new Program.SectionSpec;
 
    obj.runSegment = String  ...
    // segment where section contents are run
    obj.loadSegment = String  ...
    // segment where section contents are loaded
    obj.runAddress = UInt  ...
    // start address of section when run
    obj.loadAddress = UInt  ...
    // start address of section when loaded
    obj.runAlign = UInt  ...
    // alignment of section within runSegment
    obj.loadAlign = UInt  ...
    // alignment of section within loadSegment
    obj.type = String  ...
    // target-specific flags
    obj.fill = UInt  ...
    // fill value
 
FIELDS
runSegment — Defines the memory segment where the section is to be run.
loadSegment — Defines the memory segment where the section is to be loaded. If 'runSegment' or 'loadSegment' is defined, but not both, the linker is instructed to use the defined field as the load and run allocation for the section.
runAddress — Defines the memory address where the section is to be run. It is an error if both 'runSegment' and 'runAddress' are specified.
loadAddress — Defines the memory address where the section is to be loaded. It is an error if both 'loadSegment' and 'loadAddress' are specified. If 'runAddress' or 'loadAddress' is defined, but not both, the linker is instructed to use the defined field as the load and run address for the section.
runAlign — If runSegment is specified, runAlign determines the alignment. It is an error if both 'runAlign' and 'runAddress' are specified.
loadAlign — If runSegment is specified, runAlign determins the alignment. It is an error if both 'loadAlign' and 'loadAddress' are specified.
type — Defines flags for special section types (COPY, DSECT, NOLOAD).
fill — Defines the value to initialize an uninitialized section.
DETAILS
This structure contains some fields that are specific to TI targets. On non-TI targets, such fields are ignored.
 
config Program.argSize  // module-wide

The size allocated for command line args to the executable

Configuration settings
Program.argSize = UInt 0x200;
 
DETAILS
On platforms that require static allocation of space to hold command line arguments, this parameter specifies its maximum size (in units of chars).
Command line arguments are passed to C's main function when it's declared via the prototype: int main(int argc, char *argv[]). the argv array points to an array of strings allocated from the memory block whose size is controlled by argSize.
Setting argSize to 0 means that no argv array will be allocated and the application main() function should be declared as int main(void).
 
config Program.build  // module-wide

This program's build attributes

Configuration settings
Program.build = Any undefined;
 
DETAILS
This parameter allows arbitrary build attributes to be carried forward from the Build Object Model (BOM) into the configuration model for program configuration scripts to read.
Conceptually, this config parameter should be declared as follows:
      struct BuildAttrs inherits xdc.bld.Executable.Attrs {
          config xdc.bld.ITarget.Module target;
      };
All parameters of the target associated with the executable being configured are available through 'Program.build.target'. Any config parameter set in the BOM's xdc.bld.Executable.attrs is also available through build. For example, the name of the target is Program.build.target.name and the name of the executable's configuration script is Program.build.cfgScript.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.buildPackage  // module-wide

The name of the executable's package

Configuration settings
Program.buildPackage = String undefined;
 
DETAILS
This is the full package name (relative to the package's repository) of the package that contains the executable being configured.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.codeModel  // module-wide

The memory model for code

Configuration settings
Program.codeModel = String null;
 
DETAILS
This parameter is an alias for build.target.model.codeModel and is set to one of the following target-specific values: "near", "far", "large", or null.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.cpu  // module-wide

The execution context "seen" by the executable

Configuration settings
Program.cpu = IExeContext.Instance undefined;
 
DETAILS
Since the execution context is largely determined by the CPU that runs the executable, this configuration parameter allows scripts with access to the program object to conditionally configure based on CPU characteristics (e.g., ISA or revision of a chip).
READONLY
This parameter is set by the platform's implementation of xdc.IPackage (i.e., package.xs).
 
config Program.dataModel  // module-wide

The memory model for data

Configuration settings
Program.dataModel = String null;
 
DETAILS
This parameter is an alias for build.target.model.dataModel and is set to one of the following target-specific values: "near", "far", "large", or null.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.endian  // module-wide

The endianess of the executable

Configuration settings
Program.endian = String null;
 
DETAILS
This parameter is an alias for build.target.model.dataModel and is set to one of the following values: "big", "little", or null.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.execCmd  // module-wide

The command used to run this executable

Configuration settings
Program.execCmd = String undefined;
 
DETAILS
This string is used to create a command that runs the executable from the command line. If it is not set by the configuration script, it is set by the program's platform package (during program configuration).
This command is run as follows:
      execCmd <prog> <args>
where, <prog> is the name of the executable and <args> are the arguments specified in the test (if any).
NOTE
This parameter is ignored if the exec command is specified as part of the test; see xdc.bld.Test.Attrs.
 
config Program.gen  // module-wide

Generation options for this executable

Configuration settings
Program.gen = Program.GenerationOptions undefined;
 
DETAILS
This configuration parameter allows the program configuration script to control (to some extent) what files are generated as part of the configuration process.
 
config Program.global  // module-wide

Global variable declarations

Configuration settings
Program.global = Any[string] undefined;
 
DETAILS
Assignments to this hash table become global symbols that can be used to directly reference objects. These objects are declared in a generated header that is indirectly included by the header xdc/cfg/global.h.
Configuration scripts define symbols by adding new properties to global.
      Program.global.myInstance = Mod.create();
      Program.global.myString = "hello world";
Programs can reference the symbols defined in global by including the C/C++ header xdc/cfg/global.h as follows:
      #include <pkg/Mod.h>
      #include <xdc/cfg/global.h>
         :
      Mod_fxn(myInstance, ...);
      printf("greetings: %s\n", myString);
To compile sources that include xdc/cfg/global.h, one symbol must be defined before including this header:
xdc_cfg__header__
the package qualified name of the executable-specific C/C++ header generated by the program configuration tool; e.g., local/examples/package/cfg/mycfg_x62.h.
For example, to compile sources that reference the values declared in global for a TI C6x target with a generated configuration header named package/cfg/mycfg_x62.h in a package named local.examples the following command line is sufficient:
      cl6x -Dxdc_cfg__header__=local/examples/package/cfg/mycfg_x62.h ...
The xdc_cfg__header__ symbol is automatically defined when you use the the XDC Build Engine (xdc.bld) to create executables; see xdc.bld.Executable.addObjects
SEE
 
config Program.heap  // module-wide

The size of the executable's initial heap

Configuration settings
Program.heap = UInt 0x1000;
 
DETAILS
On platforms that enable control of the size of the heap managed by the run-time support function malloc(), this parameter specifies its initial size (in units of chars).
 
config Program.linkTemplate  // module-wide

The template for the Program's linker command file

Configuration settings
Program.linkTemplate = String null;
 
DETAILS
A template is used to create the linker command file for each program. It can be optionally specified by setting this configuration parameter in the program's configuration script. If linkTemplate it is not set or set to null, the template is obtained from the platform associated with this program (i.e., the platform named by the platform config in this module). See IPlatform.getLinkTemplate.
The linkTemplate string names a package path relative path; e.g., if the linker template you want to specify is "templates/big_n_hairy.xdt" in the package myCompany.myPackage, linkTemplate should be set to:
      "myCompany/myPackage/templates/big_n_hairy.xdt"
If linkTemplate begins with the string "./", the file is NOT searched for along the package path; instead the file name is taken to specify a file relative to the current working directory.
In any case, if linkTemplate is non-null, the file must exist; otherwise, the configuration step will fail.
SEE
 
config Program.main  // module-wide

The main entry point for the program

Configuration settings
Program.main = Int(*)(Int,Char*[]) undefined;
 
DETAILS
This parameter is optionally set by the user's program configuration script. If it is not set, then a "legacy" main() function is assumed to be linked into the program; otherwise, the value of main is used as the "main" entry point to the program.
 
config Program.memoryExclude  // module-wide

Exclude memory definitions from linker command file generation

Configuration settings
Program.memoryExclude = Bool false;
 
DETAILS
This parameter accepts boolean values. If true, it disables default memory definitions from being added to the generated linker command file.
This allows the user to define a custom memory map in a separate file and add it to the linker's command line.
SEE
 
config Program.name  // module-wide

The name of the executable file

Configuration settings
Program.name = String undefined;
 
DETAILS
This is the full file name (relative to the package's base) of the executable that results from this configuration.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.platform  // module-wide

The executable's platform instance object

Configuration settings
Program.platform = IPlatform.Instance undefined;
 
DETAILS
The platform instance that provided an execution context for the executable being configured.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.platformName  // module-wide

The name of the executable's platform

Configuration settings
Program.platformName = String undefined;
 
DETAILS
This field is the name of the platform instance used to create the executable; e.g., "ti.platforms.sim55xx", or "ti.platforms.sim6xxx:TMS320C6416".
Platform instance names have the form:
      <platform_pkg>:<instance_id>
where <platform_pkg> is the name of the platform package responsible for creating the platform instance and the optional ":<instance_id>" is a suffix that uniquely identifies the creation parameters for this instance.
The creation parameters are the values specified by the map xdc.bld.BuildEnvironment.platformTable; if this map does not contain the platform instance name, the instance is created with default values that are specific to the platform.
READONLY
This parameter is set by the generated program configuration script and must not be modified.
 
config Program.sectMap  // module-wide

A section name to SectionSpec mapping

Configuration settings
Program.sectMap = Any[string] undefined;
 
DETAILS
This is a program specific mapping of output section names to SectionSpec objects. The map supports mapping of section names to memory names; see xdc.platform.IPlatform.sectMap.
This parameter enables program configurations to place named sections in platform specific memory regions. During generation of the linker command file, sections are mapped to named memories by first consulting this table; if the table does not contain a mapping, the target classifies each section as either "code", "data" or "stack" xdc.bld.ITarget.sectMap and the platform defines a memory region for each of these section types (xdc.platform.IPlatform.codeMemory/ xdc.platform.IPlatform.dataMemory). If this does not produce a result, an error is generated. It is important to note that sectMap does not contain the complete section allocation for the program. It only contains the entries explicitly added to sectMap. To get the complete section allocation, a user should call getSectMap.
Suppose for example that the platform defines a memory segment named "DDR2". The following configuration statement places everything from the ".text" section into the "DDR2" segment.
      Program.sectMap[".text"] = new Program.SectionSpec();
      Program.sectMap[".text"].loadSegment = "DDR2";
SEE
 
config Program.sectionsExclude  // module-wide

Sections to exclude from linker command file generation

Configuration settings
Program.sectionsExclude = String null;
 
DETAILS
The sectionsExclude string is a JavaScript regular expression that is used to identify names of sections that should NOT be be handled by the normal linker command file generation process.
Sections whose name matches sectionsExclude must be handled using a custom linker command file or by specifying a custom template (see sectionsTemplate or linkTemplate).
EXAMPLES
To completely override the placement of all output sections you can define sectionsExclude to match any string.
      // Note: the '.' below represents _any_ character, not just "."
      Program.sectionsExclude = ".*";
To override output sections that begin with '.' you must specify the literal character '.' and use the '^' character to match the beginning of the string.
      // the sequence '^\.' matches just "." at the start of the name
      Program.sectionsExclude = "^\.";
To override a specific sections you should be careful to supply a regular expression that matches the entire section name. You can use '$' to match the end of the name.
      // match only ".const" or ".text"
      Program.sectionsExclude = "^\.const$|^\.text$";
SEE
 
config Program.sectionsTemplate  // module-wide

Replace the sections portion of the generated linker command file

Configuration settings
Program.sectionsTemplate = String null;
 
DETAILS
The sectionsTemplate string names a template that is used to replace the "SECTIONS" content to the generated linker command file. This is useful especially when excluding specific sections via sectionsExclude or when taking full control of the linker command file via linkTemplate is unnecessary. The original "SECTIONS" content is computed and passed as an argument to this template, which makes it relatively simple to perform small changes to the "SECTIONS" content without having to explicitly handle every section required by the compiler toolchain.
The sectionsTemplate string names a package path relative path; e.g., if the linker template you want to specify is "templates/mySections.xdt" in the package myCompany.myPackage, sectionsTemplate should be set to:
      "myCompany/myPackage/templates/mySections.xdt"
If sectionsTemplate begins with the string "./", the file is NOT searched for along the package path; instead the file name is taken to specify a file relative to the current working directory.
In any case, if sectionsTemplate is non-null, the file must exist; otherwise, the configuration step will fail.
During expansion of this template, there are three "parameters" that can be referenced to generate new content.
this
reference to the Program object
$args[0]
is the complete section map derived from Program.sectMap; some special sections relevant to XDCtools are added to the map defined by Program.sectMap.
$args[1]
is a string that contains the content that would have been placed in the SECTIONS portion of the generated linker command file. This allows templates to easily modify this content or simply add statements before or after it.
EXAMPLE
The following template, specific to TI compiler tools, adds start and size symbols for the .stack section and ensures that the stack is the first section to be allocated in its designated memory segment.
    %// first output allocation for the .stack section
    %var sectMap = $args[0];
    %var stack = sectMap[".stack"];
       .stack: >`stack.loadSegment` START(_stack_start) SIZE(_stack_size)
    %
    %// now append the normally generated content
    `$args[1]`
Note: this example requires that the .stack section be excluded from the normal generation via sectionsExclude; otherwise this section will be specified twice by the template shown above.
      Program.sectionsExclude = "^\.stack$";
SEE
 
config Program.stack  // module-wide

The size of the executable's initial stack

Configuration settings
Program.stack = UInt 0x1000;
 
DETAILS
On platforms that enable control of the initial stack size (the stack that exists immediately after reset), this parameter specifies its initial size (in units of chars).
 
config Program.sysStack  // module-wide

The size of the executable's initial system stack

Configuration settings
Program.sysStack = UInt 0x1000;
 
DETAILS
On architectures that maintain a separate "system stack" in addition to the normal stack, this parameter sets its initial size (in units of chars). This parameter is ignored for those architectures for which there is just a single stack; in other words, almost all known architectures.
This parameter is used on later generation TI/C55 16-bit DSPs where, in order to compatibly support 24-bit addresses, a separate system call/return stack that stores the upper address bits is employed.
 
Program.exportModule()  // module-wide

Force all the symbols of a module to be part of a configuration

Configuration settings
Program.exportModule(String modName) returns Void
 
DETAILS
Although a call xdc.useModule() will force some of a module's methods to be part of a configuration, the linker is still free to omit any symbols that are not referenced. Use of exportModule will force all methods of the specified module to be available.
 
Program.getSectMap()  // module-wide

Return the complete mapping of section names to SectionSpec entries

Configuration settings
Program.getSectMap() returns Any
 
DETAILS
The returned map is assembled from xdc.bld.ITarget.sectMap, xdc.platform.IPlatform.sectMap, xdc.platform.IPlatform.codeMemory, xdc.platform.IPlatform.dataMemory, xdc.platform.IPlatform.stackMemory and sectMap. The function can be called at any time during configuration, but if it is called before all packages had a chance to change sectMap, the returned map may not correspond to the actual section allocation as configured in the linker command file.
RETURNS
getSectMap returns a map with section names as keys and SectionSpec entries as values.
generated on Fri, 28 Feb 2014 04:57:03 GMT