Consuming Configurable Content
Introduction to the RTSC configuration process
Contents[hide] |
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, xdc.tools.configuro, 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:
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:
When you are learning to use XDC, you will likely use the xdc.tools.configuro utility described later in this article to process your configuration file. That utility generates the following additional important files from your configuration file:
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.
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 following statements comprise the entire "Hello World" application:
| hello.c | |
| | #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. 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:
hello.cfg 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.
In this section, you use the xdc.tools.configuro 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:
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.
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:
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.
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:
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 xdc.tools.configuro 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 xdc.tools.configuro -t <target> -p <platform> -c <compiler_location> hello.cfg |
For example:
| | xs xdc.tools.configuro -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.
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.
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 |
