metaonly module xdc.cfg.Program

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 ... ]
XDCspec summary sourced in xdc/cfg/Program.xdc
metaonly module Program {  ...
XDCscript usage meta-domain
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
 
XDCspec declarations sourced in xdc/cfg/Program.xdc
package xdc.cfg;
 
metaonly module Program {
module-wide constants & types
    };
 
        String type// target-specific flags;
        UInt fill// fill value;
    };
module-wide config parameters
    config String codeModel// The memory model for code = null;
    config String dataModel// The memory model for data = null;
    config String endian// The endianess of the executable = null;
    config Any global// Global variable declarations[string];
    config UInt heap// The size of the executable's initial heap = 0x1000;
    config Int (*main// The main entry point for the program)(Int,Char*[]);
    config String name// The name of the executable file;
module-wide functions
}
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

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

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

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

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

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

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

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

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

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

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

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

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
 
config Program.heap  // module-wide

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

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

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

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

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

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

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 prog.SectionSpec();
      Program.sectMap[".text"].runSegment = "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
 
config Program.stack  // module-wide

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

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

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

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 Wed, 06 Jan 2010 18:40:45 GMT