From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

RTSC Module Primer/Lesson 1

Basic concepts — constructing "Hello World"

Like every other programming text on the planet, we'll begin with a minimal "Hello World" program to illustrate some basic concepts of RTSC. While fundamentally rooted in the C programming language, RTSC introduces new capabilities for configuring and building embedded applications which augment more familiar processes of constructing C programs. Pay careful attention to these differences, however subtle they may appear—these are the essence of RTSC.

Reading the program

The code for this simplest of applications resides in two source files, and not just one as you might have expected. The first file (prog.c) should seem "obvious" to anyone fluent in C (though our use of the C language may seem a little stylized). But the second file (prog.cfg) is truly something new and different—a RTSC meta-program that serves to configure the corresponding target-program.

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

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

Before examining the three labeled lines in these source files, suffice it to say that this RTSC program uses—is a client of—a RTSC module whose canonical, fully-qualified ("long") name is xdc.runtime.System. Briefly, a RTSC module defines a programmatic boundary between client and supplier characterized by:

• a public specification featuring a cohesive and stable collection of constants, types, and functions (what others might term an "API") visible to and used by the module's clients; and

• an internal implementation known to the module's supplier but whose code/data otherwise remain hidden from any clients and are potentially subject to change.

Each RTSC module in turn must reside within some RTSC package, where a package simultaneously serves as a logical as well as a physical container for a set of modules:

• logically, a package provides a globally-unique programmatic namespace that scopes the definition of any its constituent modules, much as a C struct scopes the definition of its fields; and

• physically, a package represents a similarly named directory that houses all public/internal files associated with the specification/implementation of its modules.

In our example at hand, the module canonically referred to as xdc.runtime.System resides in a package whose (canonical) name is xdc.runtime. Besides System, this package houses other modules such as Memory, Error, and Startup which we will use in later examples.

From the C programmer's perspective, using a RTSC module is not unlike working with most legacy libraries—you first #include some .h header files and then you use the constants, types, and functions declared therein; lines 1 and 2 in the code above apply this pattern for the xdc.runtime.System module. As a rule, the #include directive for any RTSC module will always designate its corresponding .h file through a directory path that derives from the module's fully-qualified name in an obvious way. On the other hand, references to any constants, types, or functions spec'd by a module (such as the call to System_printf at line 2 above) will generally occur through C language identifiers of the form ModuleName_elementName, reinforcing the fact that RTSC modules themselves serve as a namespace that further scopes the definition of other programmatic elements.

Turning to the second file in our example, the statement at line 3 says it all—even though you're not necessarily sure what role prog.cfg plays in the overall flow, let alone what language we're speaking here. By design, all RTSC target-programs—C programs with a main() entry-point—conceptually begin life within a corresponding RTSC meta-program that executes on your host-computer before the final compile/link of your application. In the example at hand, the prog.cfg meta-program simply prescribes that the prog.c target-program will be using the xdc.runtime.System module during its own execution; as a rule, xdc.useModule calls in the meta-program will mirror #include directives in the target-program. In the lessons that follow, the role of prog.cfg will expand to incorporate other aspects of RTSC program configuration.

And as for the meta-language used to express meta-programs, RTSC introduces a special-purpose language known as XDCscript—a superset of industry-standard JavaScript that builds upon Mozilla's openly available Rhino implementation. Already a mainstay in DSP/BIOS as its textual configuration language (tconf), we have in fact extended Rhino/JavaScript to better integrate with other elements in the overall RTSC development flow—for sure, you won't find xdc.useModule described in any current textbooks about JavaScript.

Configuring RTSC programs

RTSC configuration, as we've already hinted, occurs before the final compile/link of your application: executing the prog.cfg meta-program serves as a "pre-build" step that ultimately affects the compiling and linking of the prog.c target-program. To ease integration into existing program build flows—whether driven by command-line tools or a graphical IDE—we'll initially rely on another tool known as configuro to orchestrate the RTSC configuration process:

Included as part of the XDCtools product you've already installed in Lesson 0, configuro generates two output files that in turn become inputs to the compiler and linker when building your target-program:

• compiler.opt, which sets all -D and -I flags needed to locate any RTSC module headers included by this program (such as xdc/runtime/System.h); and

• linker.cmd, which enumerates the appropriate pre-compiled libraries containing implementations of any RTSC modules used by this program (such as xdc.runtime.System).

Besides the prog.cfg meta-program, input to configuro will typically designate a RTSC target as well as a RTSC platform—pre-defined XDCscript recipes that respectively guide the compiling and linking of prog.c in our example at hand:

• a RTSC target knows how to compile C sources into an object-code library for a particular CPU instruction set and memory model using a specific vendor tool-chain; and

• a RTSC platform knows how to link and execute a C program for a particular hardware board (real or simulated) featuring a specific complement of processors, memory, and peripherals.

While clearly impacting the contents of compiler.opt and linker.cmd, the wealth of information encapsulated within a RTSC target and RTSC platform is generally available throughout the XDCscript environment—during execution of the prog.cfg meta-program as well as from within special back-end meta-functions we'll encounter later on.

Building and running the program

As a concrete illustration of the build flow, the directory «examples»/lesson1 in your installation contains a makefile along with copies of prog.c and prog.cfg. The makefile itself simply includes the «examples»/common.mak file which you edited in Lesson 0.

Using a version of gmake bundled with XDCtools (and assuming you've added «xdcroot» to your PATH), invoking the command gmake all from within the «examples»/lesson1 directory should yield the following messages:

>> gmake all
«xdcroot»/xs xdc.tools.configuro -c «c6xtools» -t ti.targets.C64P -p ti.platforms.sim64Pxx -o cfgsite prog.cfg
making package.mak (because of package.bld) ...
generating interfaces for package cfgsite (because package/package.xdc.xml is older than package.xdc) ...
configuring prog.x64P from package/cfg/prog_x64P.cfg ...
cl64P package/cfg/prog_x64P.c ...
«c6xtools»/bin/cl6x -q -@cfgsite/compiler.opt -c prog.c
«c6xtools»/bin/lnk6x -q -z -c prog.obj cfgsite/linker.cmd -o prog.out -l «c6xtools»/lib/rts64plus.lib

Lines 1, 2, and 3 respectively follow the flow outlined in the earlier figure, but now with all the details of invoking these tools made explicit. We'll revisit these messages in the next lesson and explain a little more about what you're seeing here.

And last but not least, you can run the example by invoking gmake test from the command-line—the output should be obvious!

See also

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC