From RTSC-Pedia

[printable version]

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

RTSC Module Primer/Lesson 6

Modules — generalizing "Hello World"

Before turning to the implementation of acme.utils.Bench and bravo.math.RandGen in the pair of lessons that follow, we'll first dissect a very simple module named Talker that illustrates some common programming idioms used when supplying any RTSC module. The Talker module also illustrates an important design technique seen throughout RTSC—generalizing functionality by replacing "hard-coded" C constants with module configuration parameters.

Introducing the module

Our Talker module resides in a package named lesson6, found in a corresponding directory named «examples»/lesson6; and like all RTSC packages, the lesson6 directory contains a special package.xdc source file which not only names the package as a whole but now introduces some modules within its programmatic scope.

package lesson6 {
    module Talker;
};

Note that package.xdc simply declares the existence of lesson6.Talker as a RTSC module—all client-visible features of the module itself are formally specified in a separate file named Talker.xdc, which we'll examine momentarily. For now, though, consider a sample client program that uses the Talker module.

var Talker = xdc.useModule('lesson6.Talker');
 
Talker.text = "Goodnight Moon";
Talker.count = 3;

#include <lesson6/Talker.h>
 
Int main()
{
    Talker_print();
    return 0;
}

Working backwards, calling the function Talker_print at line 3 of the target-program prog.c will repetitively output a client-configurable text-string assigned at line 1 of the corresponding meta-program; the assignment at line 2 controls the repetition count. The Talker module's text and count configs have the values "Hello World" and 1 as their respective defaults, implying that Talker_print will still output something meaningful even with lines 1 and 2 removed from prog.cfg.

Specifying the module

As mentioned earlier, the file Talker.xdc formally specifies the client-visible features of the Talker module illustrated informally by our sample program. Also written in XDCspec—RTSC's C-like specification language—the contents of this file should remind you of the sorts of declarations normally found in C headers included by client programs. Indeed, the xdc command just introduced in Lesson 5 will automatically generate the <lesson6/Talker.h> module header from the Talker.xdc module spec when building the lesson6 package as a whole.

module Talker {
 
    config String text = "Hello World";
    config Int count = 1;
 
    Void print();
}

Again working backwards, the function specification at line 3 mirrors the syntax of standard C, declaring the function's return type (Void in this case) as well as the names and types of its arguments (none in this case); and the config specifications at lines 1 and 2—ignoring the new XDCspec keyword—should remind you of a standard C variable declaration with an optional initializer. Finally, note that the client-visible features text, count, and print ultimately exist within the scope of the Talker module—just as Talker exists within the scope of the lesson6 package.

Implementing the module

Just as client programs in RTSC comprise a target-program (prog.c) as well as a corresponding meta-program (prog.cfg), suppliers of spec'd RTSC modules will generally implement functionality in two complementary programming domains:

• a target-domain, where C-based functions implemented by the module supplier are eventually bound into client programs executing on specific hardware platforms; and

• a meta-domain, where XDCscript meta-functions also implemented by the module supplier play an active role during the design-time configuration of these same client programs.

Turning first to the target-domain implementation of the Talker module—found in a source file rather predictably named Talker.c—you'll sense the same "look-and-feel" in its stylized use of C seen in all of the prog.c target-programs we've examined so far.

#include <xdc/runtime/System.h>
#include "package/internal/Talker.xdc.h"
 
Void Talker_print()
{
    Int i;
    for (i = 0; i < Talker_count; i++) {
        System_printf("%s\n", Talker_text);
    }
}

Like any prog.c client program, a module's target-implementation must first #include the headers of any other RTSC modules used therein—in this case, the Talker module itself is a client of xdc.runtime.System and hence the directive found at line 1. But unlike a top-level RTSC program, a module's target-implementation must then include a special "internal" header file following the pattern illustrated on line 2.

Moving on to the definition of the Talker_print function beginning at line 3, we once again see the familiar naming idiom ModuleName_elementName used within its body—whether referencing the count and text configs belonging to the Talker module or else the printf function belonging to the xdc.runtime.System module. Needless to say, the values held by Talker_count and Talker_text at lines 4 and 5 reflect earlier assignments to Talker.count and Talker.text at lines 1 and 2 of the client's prog.cfg meta-program; or, if no such assignments had occurred, these configs would instead hold default values spec'd in Talker.xdc.

Finally, let's turn to the implementation of the Talker module within the meta-domain—in a source file named Talker.xs that contains definitions of special XDCscript functions that support inclusion of this module within some client program.

function module$use()
{
    xdc.useModule('xdc.runtime.System');
}

Remembering that calls to xdc.useModule in the meta-domain will mirror corresponding #include directives in the target-domain, the call at line 6 of Talker.xs parallels line 1 of Talker.c. As a rule, any module that itself becomes a client of another RTSC module must implement its own version of the special XDCscript function module$use with the necessary calls to xdc.useModule—no different than what we've already seen in prog.cfg meta-programs.

Once the client's prog.cfg meta-program completes, control passes to the special module$use function associated with each RTSC module already designated in prior calls to xdc.useModule; the process then continues recursively until all modules used directly or indirectly by the top-level program have had their opportunity to participate. Needless to say, calling xdc.useModule multiple times on the same module will have no adverse effects as this process unfolds—much as target-domain header files guard against multiple inclusion to ensure the compiler doesn't process the same set of definitions more than once.

Building the package

No different than Lesson 5, you can once again use various forms of the xdc command to clean, rebuild, and execute the contents of the current package:

But since the lesson6 package also contains the Talker module and its target-implementation in Talker.c, however, we'll need to make one important addition to the lesson6/package.bld script which in turns drives the underlying XDCtools build engine.

var Build = xdc.useModule('xdc.bld.BuildEnvironment');
var Pkg = xdc.useModule('xdc.bld.PackageContents');
 
for each (var targ in Build.targets) {
    Pkg.addLibrary("lib/" + Pkg.name, targ).addObjects(["Talker.c"]);
    Pkg.addExecutable("prog", targ, targ.platform).addObjects(["prog.c"]);
}

Similar to the addExecutable method introduced in Lesson 5, the addLibrary call on line 1 of package.bld prescribes creation of an object code library of the designated name for each active target encountered in the Build.targets collection; and like addExecutable, the result of this call on line 1 becomes input to an addObjects method which here lists all of the target-implementation source files requiring compilation followed by archiving into this library—in this case, just Talker.c. As you might expect, invoking xdc all from the command-line results in some extra lines of output that reflect the additional build steps implied by the new addLibrary call—something we'll dissect in the next lesson when we introduce even more forms of the xdc command.

See also

[printable version]

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