From RTSC-Pedia

[printable version]

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

Overview of xdc.runtime/Example 1

Using xdc.runtime in native host applications

Leveraging Native OS Services

The xdc.runtime package's modules are designed to be used in environments where only a minimal subset of the ANSI C Standard Library is available. At the same time, these modules can be easily used in environments where you want them to use existing Standard Library support; e.g., using malloc() and free() for memory allocation and fwrite() for character I/O. In order to support both use cases, the xdc.runtime modules define several configuration parameters that allow the user to precisely control how much of the ANSI C Standard Library is required by the xdc.runtime package.

In this example we show how to configure the xdc.runtime packages to leverage the services of an ANSI C Standard Library. The xdc.runtime package optionally uses the ANSI C Standard Library to allocate memory, perform character I/O, and perform application shutdown. Since the Memory module handles all memory management and the System module is responsible for all character I/O and application shutdown, we need to configure the Memory and System modules to leverage the ANSI C Standard Library.

Configuring the Memory Module

All memory allocation within the xdc.runtime package is handled via calls to Memory_alloc() or Memory_calloc() and both take a heap parameter from which the memory is allocated. This heap parameter is either NULL, indicating that Memory should use the configured "default heap", or it is a non-NULL instance pointer created by some heap module. The Memory module itself does not reference any memory allocation functions from the ANSI C Standard Library, any such references are made indirectly via the specified heap instance. So, to eliminate all references to malloc() and free(), it is sufficient to ensure that all heaps instances come from modules that do not reference malloc() or free().

The xdc.runtime package contains two heap managers: HeapMin and HeapStd. The HeapStd module simply uses malloc() and free(). However, HeapMin simply manages a "high water" mark within a pre-configured static buffer. As a result, HeapMin can be used in applications that do not need dynamic memory management to eliminate references to malloc() and free().

By default, the Memory module uses HeapStd as the "default heap" when NULL is passed as the first parameter to Memory_alloc() or Memory_calloc(). Fortunately the Memory module provides a configuration parameter, Memory.defaultHeapInstance, that allows you to specify an alternative default heap.

var HeapSys = xdc.useModule("xdc.runtime.HeapSys");
var Memory = xdc.useModule("xdc.runtime.Memory");
Memory.defaultHeapInstance = HeapSys.create({size: 4096});

For more information about how to create custom heap mangers see Extending xdc.runtime Memory.

Configuring the System Module

The System module is responsible for basic character output and application termination. In order to enable System to operate in different environments with a variety of character output options, System relies on a "provider" module that implements the ISystemProvider interface. The System module provides a configuration parameter, System.SupportProxy, which determines the "provider" module used. The default provider is SysMin.

/* Configure System to use the SysStd provider for immediate character output. */
var System = xdc.useModule("xdc.runtime.System");
var SysStd = xdc.useModule("xdc.runtime.SysStd");
System.SupportProxy = SysStd;

The xdc.runtime package contains two system providers: SysMin and SysStd.

With SysStd, print statements will output immediately to the console. The SysStd module uses putchar() and fflush() for basic character output.

The SysMin module, on the other hand, simply copies the characters to a buffer, and the characters are only output when System_flush() is called. By default, SysMin will output the characters to the console when System_flush is called. If you want the characters output in a different way, such as over a UART, you can define your own output function and configure SysMin.outputFxn to reference it. Also, the size of the SysMin buffer and its placement are configurable.

Code size restrictions may dictate that you do not want your application to pull in the ANSI C Standard Library. With the exception of exit(), atexit(), and abort(), the System module does not directly reference any ANSI C Standard Library functions; any other references are the result of the System module's supporting module System.SupportProxy. For example, the SysMin support module will call fwrite() to output characters written to its internal buffer.

If neither SysMin nor SysStd are appropriate for your application, you may need to create your own ISystemProvider module. For information about how to create a new ISystemProvider module see Extending xdc.runtime System.

A Complete Example

Combining the configuration options illustrated above, we can create a configuration of the xdc.runtime package that leverages an existing ANSI C Standard Library to create a complete implementation of the xdc.runtime package.

#include <xdc/std.h>
 
#include <xdc/runtime/System.h>
#include <xdc/runtime/Memory.h>
 
#include <string.h>
 
/* ======== main ======== */
Int main(Int argc, String argv[])
{
    Int i;
    Char *buf;
 
    buf = Memory_calloc(NULL, 80, 0, NULL);
    strcat(buf, "hello world");
 
    for (i = 0; i < 3; i++) {
        System_printf("%s: %d\n", buf, i);
    }
    return (0);
}

var System = xdc.useModule("xdc.runtime.System");
var Memory = xdc.useModule("xdc.runtime.Memory");
 
/* use target's ANSI Standard Library support library */
var SysStd = xdc.useModule("xdc.runtime.SysStd");
System.SupportProxy = SysStd;
 
/* ensure all memory manager references go to HeapStd */
var HeapStd = xdc.useModule("xdc.runtime.HeapStd");
Memory.defaultHeapInstance = HeapStd.create({size: 4096});

See also

[printable version]

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