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:
After a configuration script completes successfully, the following files
are generated:
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.
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).
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
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 |
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
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:
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
XDCscript usage |
meta-domain |
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 |
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 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
config Program.sectionsExclude // module-wide |
|
Sections to exclude from linker command file generation
XDCscript usage |
meta-domain |
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$";
config Program.sectionsTemplate // module-wide |
|
Replace the sections portion of the generated linker command file
XDCscript usage |
meta-domain |
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$";
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 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
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.