Consuming Configurable Content

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 24-Feb-2019 01:02 UTC 

Consuming Configurable Content

Introduction to the RTSC configuration process



Any application that uses a RTSC package needs a configuration file. This file contains statements that configure the contents of the packages used by the application and is read by a hosted configuration tool,, which generates static C data structures that must be linked into your application. Your C/C++ program code can do additional dynamic configuration, but this generated static data defines the starting point.

The configuration file uses simple JavaScript (EcmaScript) syntax to set properties and call methods provided by objects provided by XDCtools. The combination of JavaScript and the script objects provided by XDCtools is referred to as XDCscript. For more information about the language used for configuration, see The XDCscript Language.

RTSC configuration serves the following purposes:

  • Specifies the modules and packages to use and static objects to create.
  • Performs integrity checks between specified and dependent packages; see Compatibility Keys for a description of these checks.
  • Sets configuration variables (options) for modules and objects to change their default runtime behavior.

The RTSC configuration framework enables packages to customize their content based on your hardware platform and your application's requirements. Configuration scripts specify your application's requirements, and the RTSC configuration framework uses these scripts to generate files that must be integrated into your normal application build: The following figure shows how these files fit into the typical build process. RTSC provides tools to simplify the integration of these files into your build environment.


The RTSC configuration file is a .cfg file. When you process the .cfg file, the files shown in the "Config Output" block are generated. This is a simplified diagram. Actually, processing the .cfg file generates several other files that, while useful, are not required for the examples shown in this document.

As a consumer of RTSC-based content, you don't need to know about all of the generated files. Two files of particular interest are:

  • appcfg.obj—An object file created by compiling a generated appcfg.c file that contains static data structures and functions referenced by the packages named (directly or indirectly) by the configuration script. During single-step debugging of your application, you may step into appcfg.c.
  • appcfg.cmd—A linker command file, also generated by the configuration process, that contains the list of libraries supplied by the packages referenced by the configuration script as well as platform-specific memory definition and placement information.

When you are learning to use XDC, you will likely use the utility described later in this article to process your configuration file. That utility generates the following additional important files from your configuration file:

  • compiler.opt—Contains compiler command-line options for your target and platform. This file allows you to easily compile your application's sources using the same options used to create appcfg.obj. You can thus avoid bugs that would result from linking together files compiled with mismatched runtime assumptions.
  • linker.cmd—Corresponds to the appcfg.cmd file. Contains the linker options required to use the content from the packages required by the application.

It is these two files that are commonly integrated into your build flow. As you develop and troubleshoot your application, you may want to review the figure earlier in this section to see which files need to use and reference others.

A configuration example

In this section we illustrate configuration with a simple "Hello World" application that uses the xdc.runtime.System module from the xdc.runtime package.

The C code

The C code.  The following statements comprise the entire "Hello World" application:

#include <xdc/std.h>
#include <xdc/runtime/System.h>
int main() {
    System_printf("Hello World!\n");
    return (0);

The first #include statement is required in all C code that uses RTSC modules and defines a set of portable "base types" used by all modules. The second #include statement allows the C code to use the System_printf() function is provided by the xdc.runtime.System module. Notice how the package name "xdc.runtime" is part of the #include statement; the same pattern of using the package name, with dots replaced with slashes, is used for all modules. For more examples and information about using and creating modules, see the RTSC Module Primer.

The configuration code

The configuration code.  In order to build and run the "Hello World" application above, you must first create a configuration file called, say, hello.cfg. For this example, the following JavaScript statement must be in this file:

var System = xdc.useModule("xdc.runtime.System");

The xdc.useModule() method enables the application to use the xdc.runtime.System module. Notice that, like the #include statement in the C source, the xdc.useModule() statement names both the module and the package. As a general rule, if your application directly references a module, your application's configuration script should have a corresponding xdc.useModule() statement naming the module referenced.

If you don't explicitly request one of the xdc.runtime modules (via xdc.useModule()) and no other module requested uses any of the modules in this package, a direct reference to any of the xdc.runtime modules from your application's sources may result in link-time errors.

In more complex applications, you will add additional configuration statements to this file to use various modules, set properties of modules, and create and configure instances of the objects managed by these modules. Some modules of the xdc.runtime package, for example, support a rich set of configuration parameters that can have a significant affect on the performance and footprint of your application. In the case of the System module , for example, there is a configuration parameter named maxAtexitHandlers. This parameter sets the maximum number of "atexit handlers" that can be bound at runtime; a static table of size maxAtexitHandlers is statically allocated to hold these handlers. If your application never calls System_atexit(), you can save precious application data space by setting maxAtexitHandlers to zero.

var System = xdc.useModule("xdc.runtime.System");
System.maxAtexitHandlers = 0;    /* don't reserve any space for System_atexit() */

For a complete list of all configuration parameters supported by the modules you use, see the module's reference documentation. Beyond any supplied by the package containing these modules, a module's reference documentation is always available via the cdoc tool. See Using the CDOC reference help system.

As you develop applications, the configuration step is one you are likely to revisit as you add functionality to your C code or tune the performance of the modules it uses.

Integrating configuration into your build flow

In this section, you use the tool provided with XDCtools to process the hello.cfg configuration file above. Processing the file generates a compiler.opt file to be used when you compile the application and a linker.cmd file to be used when you link the application. The compiler.opt file allows you to easily compile your application's sources using the same options used to create hellocfg.obj. To simplify your link step, the linker.cmd file is the hellocfg.cmd file with an added reference to hellocfg.obj.

Before a configuration script can be processed, however, you need to specify the "target" compiler and the hardware "platform" required to run your application. In general terms:

  • A target identifies a specific compiler and an ISA and runtime model supported by the compiler. For example, the TI C6000 compiler for the C64+ ISA running in big endian mode.
  • A platform identifies the hardware execution environment as seen by your application. For example, a DM6446 EVM with 64 MB of DDR2 external memory.

The configuration tool uses simple string names to identify targets and platforms. For detailed information about targets and platforms see Introduction to Targets and Platforms.

Choosing a target

The "target" identifies a specific compiler, ISA, and runtime model supported by the compiler. It is used during the configuration process to compile the generated C file with the right compiler options. Some example target strings are:

  • ti.targets.C64, ti.targets.C64_big_endian, ti.targets.C64P, ti.targets.C64P_big_endian
  • gnu.targets.Linux86, gnu.targets.Mingw
  • microsoft.targets.Net32, microsoft.targets.Win32

To see the latest list of targets, open the CDOC online documentation (see Using the CDOC reference help system). You can expand the ti.targets, microsoft.targets, and gnu.targets packages to see a list of currently supported targets as well as details about compiler options required by these targets. For a snapshot of the targets available see Existing Targets.

Choosing a platform

The "platform" is a name that identifies a specific board and its settings. It specifies a particular device and memory map on which an application will run. It is used during the configuration process by packages that require platform-specific information, such as the memory map, the initial CPU clock speed, or the revision of the device running the application.

The full list of platform packages available is visible in the CDOC online documentation in the list of packages under ti.platforms. See Using the CDOC reference help system for information about using CDOC. Examples include:

  • ti.platforms.sim6xxx
  • ti.platforms.dsk5510
  • ti.platforms.evmDM6437

If you are developing for a platform that is not listed in the online documentation, you may be able to use the ti.platforms.generic platform. For more information about how to define a platform instance using this platform package, see the CDOC online documentation for the ti.platforms.generic package.


The tool processes configuration files and produces output files that are required to link your application and compile sources that reference values defined by the configuration files. For example, to generate files from the hello.cfg configuration shown above, use the following command line:

xs -t <target> -p <platform> -c <compiler_location> hello.cfg
  • The -t option specifies the target.
  • The -p option specifies the platform.
  • The -c option specifies the location of the compiler you want to use.

For example:

xs -t ti.targets.C64 -p ti.platforms.sim6xxx -c c:/CCStudio_v3.3/C6000/cgtools hello.cfg

This command generates two output files, hello/compiler.opt and hello/linker.cmd, which must be integrated into the build of this application.

this linker command file names all libraries that must be passed to the linker to link your application
this text file contains compiler options required to build C source that reference values defined by hello.cfg

Since every build environment is different, it's best to look at specific examples of how these files are used to create a complete application. See Consuming Configurable Content/makefiles for simple makefile integration.

Example build integrations

You can integrate the step of running configuro into your makefile or Code Composer Studio project file as described in the following topics.

makefiles RTSC configuration with makefiles
CCStudio Using configuro within Code Composer Studio 3.x

The configuro tool is designed to allow you to create a single configuration that can be shred among more than one application. This allows you to cleanly separate the configuration process from the rest of your build process and allows you to avoid unnecessary runs of configuro when, for example, building a test suite where each test uses a common configuration. The following topics illustrate how this can be accomplished.

Sharing a Configuration via make Using make to build multiple applications that share a configuration
[printable version]  [offline version]offline version generated on 24-Feb-2019 01:02 UTC 
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference