metaonly module xdc.cfg.Program
index URL

The Program object for the configuration object model

This module defines the "root" of the configuration object model; all configuration settings are for the executable represented by this object. Program configuration scripts reference this module via the global variable Program; i.e., Program implicitly initialized as follows: [ more ... ]
XDCscript usage meta-domain sourced in xdc/cfg/Program.xdc
var Program = xdc.useModule('xdc.cfg.Program');
module-wide constants & types
    var obj = new Program.GenerationOptions// Options that control the files generated as part of program configuration;
        obj.debuggerFiles// if true, generate debugger "project" files = Bool  ...
    var obj = new Program.SectionSpec// Map that instructs the linker where to place output sections;
        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.argSize// The size allocated for command line args to the executable = UInt 0x200;
    Program.build// This program's build attributes = Any undefined;
    Program.buildPackage// The name of the executable's package = String undefined;
    Program.codeModel// The memory model for code = String null;
    Program.cpu// The execution context "seen" by the executable = IExeContext.Instance undefined;
    Program.dataModel// The memory model for data = String null;
    Program.endian// The endianess of the executable = String null;
    Program.execCmd// The command used to run this executable = String undefined;
    Program.gen// Generation options for this executable = Program.GenerationOptions undefined;
    Program.global// Global variable declarations = Any[string] undefined;
    Program.heap// The size of the executable's initial heap = UInt 0x1000;
    Program.linkTemplate// The template for the Program's linker command file = String null;
    Program.main// The main entry point for the program = Int(*)(Int,Char*[]) undefined;
    Program.name// The name of the executable file = String undefined;
    Program.platform// The executable's platform instance object = IPlatform.Instance undefined;
    Program.platformName// The name of the executable's platform = String undefined;
    Program.sectMap// A section name to SectionSpec mapping = Any[string] undefined;
    Program.stack// The size of the executable's initial stack = UInt 0x1000;
    Program.sysStack// The size of the executable's initial system stack = UInt 0x1000;
module-wide functions
    Program.exportModule// Force all the symbols of a module to be part of a configuration(String modName) returns Void
    Program.getSectMap// Return the complete mapping of section names to SectionSpec entries() returns Any
 
DETAILS
This module defines the "root" of the configuration object model; all configuration settings are for the executable represented by this object. Program configuration scripts reference this module via the global variable Program; i.e., Program implicitly initialized as follows:
      var Program = xdc.useModule('xdc.cfg.Program');
After a configuration script completes successfully, the XDC runtime generates the following files:
  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 used during this final link step. This linker command file is produced by expanding a template specified by xdc.cfg.Program.linkTemplate. Each template is responsible for expanding templates specified by each imported package's getSects method (see xdc.IPackage.getSects). This allows each package participating in the configuration of an executable to contribute a portion of the executable's linker command file.
struct Program.GenerationOptions
index URL

Options that control the files generated as part of program configuration

XDCscript usage meta-domain
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
index URL

Map that instructs the linker where to place output sections

XDCscript usage meta-domain
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
index URL

The size allocated for command line args to the executable

XDCscript usage meta-domain
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).
config Program.build  // module-wide
index URL

This program's build attributes

XDCscript usage meta-domain
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
index URL

The name of the executable's package

XDCscript usage meta-domain
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
index URL

The memory model for code

XDCscript usage meta-domain
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
index URL

The execution context "seen" by the executable

XDCscript usage meta-domain
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
index URL

The memory model for data

XDCscript usage meta-domain
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
index URL

The endianess of the executable

XDCscript usage meta-domain
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
index URL

The command used to run this executable

XDCscript usage meta-domain
Program.execCmd = String undefined;
DETAILS
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
NOTE
This parameter is ignored if the exec command is specified as part of the test; see xdc.bld.Test.Attrs. and <args> are the arguments specified in the test (if any).
config Program.gen  // module-wide
index URL

Generation options for this executable

XDCscript usage meta-domain
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
index URL

Global variable declarations

XDCscript usage meta-domain
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
xdc.bld.Executable.addObjects
config Program.heap  // module-wide
index URL

The size of the executable's initial heap

XDCscript usage meta-domain
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
index URL

The template for the Program's linker command file

XDCscript usage meta-domain
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.
config Program.main  // module-wide
index URL

The main entry point for the program

XDCscript usage meta-domain
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.name  // module-wide
index URL

The name of the executable file

XDCscript usage meta-domain
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
index URL

The executable's platform instance object

XDCscript usage meta-domain
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
index URL

The name of the executable's platform

XDCscript usage meta-domain
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
index URL

A section name to SectionSpec mapping

XDCscript usage meta-domain
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";
NOTE
If BIOS 5 configuration script (Tconf script) is executed, the section allocations configured in the Tconf script take precedence over any settings for the same sections in this parameter.
SEE
SectionSpec, xdc.platform.IPlatform.sectMap, xdc.bld.ITarget.sectMap
config Program.stack  // module-wide
index URL

The size of the executable's initial stack

XDCscript usage meta-domain
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
index URL

The size of the executable's initial system stack

XDCscript usage meta-domain
Program.sysStack = UInt 0x1000;
DETAILS
On platforms that support a separate "system stack", this parameter sets its initial size (in units of chars).
Program.exportModule()  // module-wide
index URL

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

XDCscript usage meta-domain
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
index URL

Return the complete mapping of section names to SectionSpec entries

XDCscript usage meta-domain
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.
NOTE
If BIOS 5 configuration script (Tconf script) is executed, the section allocations configured in the Tconf script are also being returned.
generated on Tue, 24 Aug 2010 15:39:43 GMT