From RTSC-Pedia

[printable version]

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

RTSC Module Primer/Lesson 9

Modules, packages, and testing — bringing it all together

The example presented in this lesson—considerably richer than any we've seen so far—once again reinforces material covered earlier while simultaneously introducing some more programming idioms. After first examining a new module that illustrates further dimensions of the instance object life-cycle, we'll then touch upon the all-important topic of module testing. Here, we'll explore a simple organizational pattern involving a pair of RTSC packages—one containing modules, another containing test programs—which the xdc command can nevertheless manage as an integrated set.

Being our last programming example, we've tried to forge a "grand finale" that not only brings together many of the principal themes established in earlier lessons but also exposes a few advanced aspects of RTSC demanding deeper investigation on your part moving forward. Our next (and final) lesson will direct you towards other documentation resources found in the RTSC-Pedia that build upon everything you've already learned about programming in RTSC.

Specifying the module

The module acme.filters.Fir manages instance objects representing finite-impulse-response filters, each parameterized with their own set of coefficients and each maintaining their own internal history. After creating a filter instance, client applications would use the per-instance function apply to transform a frame of input data into a corresponding frame of output—as you'll see later on in one of the module's test programs. Now, however, we'll focus on the Fir module from the perspective of its supplier and highlight some extensions to the general programming idioms for instance modules first introduced in Lesson 8.

/*! Collection of DSP filter modules */    
package acme.filters {    
    module Fir;	
};

/*! Simple Finite Impulse Response (FIR) filter */
@InstanceInitError
@InstanceFinalize
module Fir {
 
instance:
 
    /*! Number of data-values per frame */
    config Int frameLen = 64;
 
    /*! Create a new filter
     *
     *  @param(coeffs)      filter coefficients
     *  @param(coeffsLen)   number of coefficients
     */
    create(Int16 coeffs[], Int coeffsLen);
 
    /*! Apply this filter and update its internal history
     *  @param(inFrame)    readonly frame of input data
     *  @param(outFrame)   next frame of output data
     */
    Void apply(Int16 inFrame[], Int16 outFrame[]);
 
internal:
 
    struct Instance_State {
        Int16 coeffs[];         /* create argument */
        Int coeffsLen;          /* create argument */
        Int frameLen;           /* instance config */
        Int16 history[];        /* filter history */
    }
}

As hinted in the last lesson, the declaration of create at line 3 of Fir.xdc includes additional arguments—here, an array of coefficients used internally by the per-instance function apply when filtering a frame of input data. Unlike per-instance configs—which each have a "reasonable" default value that clients can elect not to overwrite—callers of a corresponding Mod_create function declared with additional arguments must pass a corresponding set of values.

Anticipating the target-implementation of Fir (coming momentarily), the Instance_State declaration beginning at line 4 of Fir.xdc includes a history array whose length is a function of coeffsLen and frameLen. This suggests that instances objects created dynamically through client calls to Fir_create or Fir_construct would internally lead to further dynamic allocation of this history array from some suitable memory heap. Details aside for a moment, the new @InstanceInitError attribute back at line 1 declares that intializing per-instance state inside Fir can potentially raise an error (say, if memory were unavailable). Similarly, the @InstanceFinalize attribute at line 2 declares that the Fir target-implementation will explicitly intercept client calls to Fir_delete or Fir_destruct—presumably to free the previously-allocated history array associated with the current instance object.

Implementing the module (target-domain)

Turning now to Fir.c, pay particular attention to the expanded signature of Fir_Instance_init—which generalizes the Mod_Instance_init pattern first seen in the context of RandGen back in Lesson 8. You should also take note of Fir_Instance_finalize—another special function supporting one particular aspect of the instance object life-cycle.

#include <xdc/runtime/Error.h>
#include <xdc/runtime/Memory.h>
#include "package/internal/Fir.xdc.h"
 
#include <string.h>
 
static SizeT historySize(Fir_Object *obj)    /* helper function */
{
    return (obj->coeffsLen + obj->frameLen - 1) * sizeof (Int16);
}
 
Int Fir_Instance_init(Fir_Object *obj, Int16 coeffs[], Int coeffsLen,
                      const Fir_Params *params, Error_Block* eb)
{
    obj->coeffs = coeffs;
    obj->coeffsLen = coeffsLen;
    obj->frameLen = params->frameLen;
 
    obj->history = Memory_calloc(NULL, historySize(obj), 4, eb);
    return 0;
}
 
Void Fir_Instance_finalize(Fir_Object *obj, Int status)
{
    Memory_free(NULL, obj->history, historySize(obj));
}
 
Void Fir_apply(Fir_Object *obj, Int16 inFrame[], Int16 outFrame[])
{
    Int i, j;
    Int32 sum;
 
    Int coeffsLen = obj->coeffsLen;
    Int frameLen = obj->frameLen;
 
    Int16 *history = obj->history;
    Int16 *coeffs = obj->coeffs;
 
    memcpy(&history[coeffsLen - 1], inFrame, frameLen * sizeof (Int16));
 
    for (j = 0; j < frameLen; j++) {
        sum = 0;
        for (i = 0; i < coeffsLen; i++) {
            sum += history[i + j] * coeffs[i];
        }
 
        *outFrame++ = (Int16)(sum >> 15);
    }
 
    memcpy(history, &history[frameLen], (coeffsLen - 1) * sizeof (Int16));    
}

Turning first to the definition of Fir_Instance_init beginning at line 2, its expanded signature results from two separate declarations found in the module's spec file:

• the create declaration at line 3 of Fir.xdc contributed the additional coeffs and coeffsLen arguments, which are subsequently retained in the instance object; and

• the @InstanceInitError declaration at line 1 of Fir.xdc contributed the additional eb argument, which is subsequently used to handle memory allocation errors.

As already hinted, Fir_Instance_init internally calls upon Memory_calloc to allocate and zero-fill a block of memory large enough to hold the history array associated with this instance object. Generalizing the familiar calloc function of standard C, the extra arguments to Memory_calloc give the caller additional degrees of control:

• arg #1 designates the heap to use for the allocation, with NULL implying a system-wide default;
• arg #2 designates the number of bytes to allocate, here returned by historySize defined at line 1;
• arg #3 designates the addressing alignment for the allocation, represented by a power-of-two; and
• arg #4 passes an Error_Block* used to raise/handle errors, with NULL triggering a default strategy.

The last argument passed to Memory_calloc of course tracks the eb argument passed to Fir_Instance_init; and this eb argument in turn reflects the last argument passed by the client to Fir_create or Fir_construct—which also happens to be of type Error_Block*. Once again, passing NULL as this final argument would trigger a default error strategy—typically, print an appropriate message and then abort execution whenever the program raises an error. In the case of the Fir_Instance_init function defined back at line 2, a NULL value for eb here implies that control would not return from Memory_calloc should the latter function raise an out-of-memory error.

Besides contributing its eb argument, the original @InstanceInitError declaration back at line 1 of Fir.xdc also changed the return type of the Fir_Instance_init function from Void to Int. In general, the value returned from this form of the Mod_Instance_init function serves as a completion status which, if non-zero, signifies some sort of failure has occurred while initializing the current instance object and that the function has abruptly returned. In the latter case, RTSC effectively reverses the effects of the outstanding call to create or construct by performing the internal equivalent of a delete or destruct call on the current instance object.

The Fir_Instance_finalize function defined at line 3 of Fir.c effectively complements Fir_Instance_init, relinquishing any resources successfully acquired in the latter function. Automatically invoked in response to client calls to Fir_delete or Fir_destruct, the Instance_finalize function here calls Memory_free within arguments similar to those passed earlier to Memory_calloc after line 2. Note that since Fir_Instance_init returns a completion status (due to @InstanceInitError), RTSC automatically forwards this value to Fir_Instance_finalize if non-zero. Client-initiated calls to Fir_delete or Fir_destruct—implying an earlier corresponding call to Fir_create or Fir_construct had succeeded—pass 0 as the status argument to Fir_Instance_finalize.

Implementing the module (meta-domain)

The new dimension of memory allocation in the target-function Fir_Instance_init results in corresponding additions to the special XDCscript meta-function instance$static$init defined in Fir.xs. Here, however, the history array associated with each statically-created instance object is likewise statically-allocated.

var Error, Memory, Program;
 
function module$use()
{
    Error = xdc.useModule('xdc.runtime.Error');
    Memory = xdc.useModule('xdc.runtime.Memory');
    Program = xdc.useModule('xdc.cfg.Program');
}
 
function instance$static$init(obj, coeffs, coeffsLen, params)
{
    obj.coeffs = coeffs;
    obj.coeffsLen = coeffsLen;
    obj.frameLen = params.frameLen;
 
    Memory.staticPlace(obj.history, 4, null);
    obj.history.length = historySize(obj);
}
 
function historySize(obj)    /* helper function */
{
    var sz =  Program.build.target.stdTypes.t_Int16.size;
    return (obj.coeffsLen + obj.frameLen - 1) * sz;
}

Since RTSC happens to invoke the special function module$use before instance$static$init, we've leveraged the former function to initialize some file-level variables declared at line 1. In the case of Memory—referencing the xdc.runtime.Memory module—instance$static$init invokes one of its meta-functions at line 2 to statically locate the history array associated with the current instance object. While clearly different from the target-side call to Memory_calloc back at line 2 of Fir.c, the 2nd and 3rd arguments to Memory.staticPlace analogously designate the addressing alignment and memory section (heap) used for this allocation.

Following an idiom rooted in JavaScript, we've dimensioned obj.history at line 3 of Fir.xs by simply assigning to the special length property available on all XDCscript arrays. In this case, we've used a (private) historySize meta-function defined in Fir.xs in exactly the same way as Fir_Instance_init used a (private) historySize target-function defined at line 1 of Fir.c. Though highly "dynamic" in the meta-domain, obj.history (like obj itself) at the end of the day becomes a static C variable in the target-domain.

Testing the module

Suppliers of RTSC modules—like all good software engineers—will no doubt maintain a suite of test programs that systematically exercise all client-visible features of each module ("black-box" tests) as well as various aspects of each module's internal implementation ("white-box" tests). Consider, for example, a black-box test of acme.filters.Fir that applies a newly-created filter to a known frame of data and outputs the results. As a byproduct, this test program also uses the acme.utils.Bench module to measure the elapsed time of the call to Fir_apply.

#include <acme/filters/Fir.h>
#include <acme/utils/Bench.h>
#include <xdc/runtime/System.h>
 
#define COEFFSLEN 4
#define FRAMELEN 20
 
static Int16 coeffs[COEFFSLEN] = {20000, 21000, 22000, -3000}; 
 
static Int16 inFrame[FRAMELEN] = {0,1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6,7,8,9};
static Int16 outFrame[FRAMELEN];
 
static Void printOut();
 
Int main()
{
    Fir_Handle fir;
    Fir_Params params;
 
    Fir_Params_init(&params);
    params.frameLen = FRAMELEN;
 
    fir = Fir_create(coeffs, COEFFSLEN, &params, NULL);  /* create filter */
    Bench_begin("\t--> Portable Baseline");              /* start benchmark */
    Fir_apply(fir, inFrame, outFrame);                   /* run filter */
    Bench_end();                                         /* stop and display timing */
    printOut();                                          /* display results */
    Fir_delete(&fir);                                    /* delete filter */
 
    return 0;
}
 
static Void printOut()
{
    Int i;
    String comma = "";
 
    System_printf("\toutFrame = {");
    for (i = 0; i < FRAMELEN; i++) {
        System_printf("%s%d", comma, outFrame[i]);
        comma = ",";
    }
    System_printf("}\n");
}

As you would expect, the call to Fir_create at line 1 above takes two additional arguments, matching the declaration back at line 3 of Fir.xdc; and as we already noted, all of these parameters (including the NULL-valued Error_Block*) eventually arrive at Fir_Instance_init defined at line 2 of Fir.c. Similarly, the call to Fir_delete at line 2 above would internally invoke Fir_Instance_finalize defined at line 3 of Fir.c.

Turning to the corresponding meta-program for FirTest1, configuring the Bench module here takes on a new twist.

var Program = xdc.useModule('xdc.cfg.Program');
 
var Bench = xdc.useModule('acme.utils.Bench');
var Fir = xdc.useModule('acme.filters.Fir');
var System = xdc.useModule('xdc.runtime.System');
 
Bench.enableFlag = (Program.build.target.isa == "64P");

Once again, we've leveraged the wealth of information attached to the special xdc.cfg.Program module—here, to conditionally assign Bench.enableFlag based on the current program's target. Though somewhat contrived since Bench does work on all targets (though perhaps with less-than-useful accuracy on some), this fragment nevertheless illustrates a RTSC meta-programming technique that often eliminates the need for an #ifdef __64plus__ preprocessor directives in the corresponding target-program.

Managing a test-suite

Though we've only presented a single test program here, you could well imagine a package with multiple modules that in turn each implement multiple functions having multiple test programs—dozens, if not hundreds; and the problem only compounds itself when a single supplier offers multiple packages (acme.filters, acme.utils, and so on).

As in last few lessons, the package.bld script for a package like acme.filters will only build target libraries containing compiled implementations for each module in the package—but no executable programs.

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

Instead, all executable test programs pertaining to the acme.filters package will themselves reside in another package named (by convention) acme.filters.test that otherwise contains no modules. The package.xdc spec file for this new package in turn explicitly requires (using a new XDCspec keyword) the presence of other RTSC packages upon which the content of acme.filters.test in someway depends—including, but not limited to, our original acme.filters package.

requires acme.filters;
requires acme.utils;
 
/*! Companion tests for acme.filters */    
package acme.filters.test {    
    /* no modules */	
};

Turning now to the package.bld script for our acme.filters.test package—which easily scales when managing more than one test—the script features a doubly-nested for each loop used to not only iteratively build the same test program for multiple targets but to iterate over a set of tests as well.

var Build = xdc.useModule('xdc.bld.BuildEnvironment');
var Pkg = xdc.useModule('xdc.bld.PackageContents');
 
var TEST_NAMES = ["FirTest1"];
 
for each (var targ in Build.targets) {
    for each (var testName in TEST_NAMES) {
        Pkg.addExecutable(testName, targ, targ.platform).addObjects([testName + ".c"]);
    }
}

In practice, development of modules inside a package like acme.filters and development of test programs for these modules inside a package like acme.filters.test will proceed in parallel. To streamline the repetitive re-builds of either package as well as to ensure both packages remain in sync with one another before executing any tests, we'll rely upon an extended form of the xdc command that operates on a set of packages designated using the -P option and its variants.

For example, you could invoke a single xdc test -PR . command from within the «examples»/acme/filters directory to systematically build both packages before executing all test programs. Or, if you prefer, sitting inside the «examples»/acme/filters/tests package you can achieve the same results by invoking xdc test -PD . which automatically recognizes acme.filters as a dependent package (per line 1 of its package.xdc spec). In the latter case, the -PD option will also re-build the dependent acme.utils package—just in case you happened to make a change to (say) the Bench module.

See also

[printable version]

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