From RTSC-Pedia

[printable version]

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

Using xdc.runtime Logging/Example 1

Classic "hello world" using Log

"hello world"

In this section, we use a single configuration file for two different C programs: a "hello world" application and a simple variant that illustrates runtime control of Log events. This configuration (shown below) allows runtime control of all events, enables "info" events for non-RTSC modules, and outputs events via System_printf.

var Log = xdc.useModule("xdc.runtime.Log");
var Diags = xdc.useModule("xdc.runtime.Diags");
 
/* enable runtime control of "info" events for non-modules */
var Main = xdc.useModule("xdc.runtime.Main");
Main.common$.diags_INFO = Diags.RUNTIME_ON;
 
/* use the LoggerSys ILogger service provider */
var Logger = xdc.useModule("xdc.runtime.LoggerSys");
 
/* create and bind a logger for all non-module code */
Main.common$.logger = Logger.create();

In outline, the configuration file

1. gets a reference to the Main module (via xdc.useModule()) so that subsequent statements can configure this module 1. The configuration of the Main module applies to all application code that is not already a RTSC module; i.e., all application code and any existing library code.
2. enables runtime control of "info" events for the Main module and sets them to be initially enabled (Diags.RUNTIME_ON) 2. Alternatively, we could have set them to be initially disabled by setting Main.common$.diags_INFO to Diags.RUNTIME_OFF.
3. uses the LoggerSys module 3 to create an instance of a Log event "handler" and sets this handler to be the Main module's logger 4. Instances of LoggerSys simply print events as they occur using System_printf()

This first C application simply logs a "hello world" using the Log_info0 API. This API generates an event of the category INFO, which is used for generic informational events. The event generated by Log_info0 also prepends the file and line number of the call site.

The event will be generated whenever "info" (Diags_INFO) events are enabled. Because the configuration enabled "info" events for all application code, the first Log_info0() statement generates the output shown on the right of the C source. Notice that, in addition to the file and line number and the "hello world" string, LoggerSys prints the name of the module that generated the event: in this case, xdc.runtime.Main.

#include <xdc/std.h>
 
#include <xdc/runtime/Log.h>
#include <xdc/runtime/Diags.h>
 
int main(int argc, String argv[])
{
    Log_info0("hello world");
 
    return (0);
}

xdc.runtime.Main: "app.c", line 8: hello world

If a module's diagnostics are configured to allow real-time control, the application can enable and disable the production of diagnostic events via Diags_setMask(). This method takes a string argument which it interprets as a specification of what to enable or disable. The next example application uses Diags_setMask() to disable and then re-enable "info" events for the Main module.

#include <xdc/std.h>
 
#include <xdc/runtime/Log.h>
#include <xdc/runtime/Diags.h>
 
int main(int argc, char *argv[])
{
    /* disable info events associated with Main */
    Diags_setMask("xdc.runtime.Main-F");
 
    Log_info0("hello world");    /* DISABLED */
 
    /* enable info events associated with Main */
    Diags_setMask("xdc.runtime.Main+F");
 
    Log_info0("hello again");    /* ENABLED */
 
    return (0);
}

xdc.runtime.Main: "app.c", line 16: hello again

Since the configuration enabled runtime control, the use of Diags_setMask() causes the first Log_info0() statement to be skipped; the string "xdc.runtime.Main-F" tells Diags_setMask() to disable "info" events (-F) for the xdc.runtime.Main module. The second call to Diags_setMask() enables "info" events for Main and, as a result, the second Log_info0() statement generates an event which is output by LoggerSys as shown to the right of the C source. The string passed to Diags_setMask() can enable, disable, or set any number of event categories, apply to any number of modules, and even has limited support for wildcards. The format of this string is described in Reference API Documentation for Diags_setMask().

Rather than modifying the C source to enable/disable event generation it is often desirable to run exactly the same executable but vary which events are enabled or disabled. This is easily accomplished if your program loader supports passing arguments (or environment variables) as part of loading the executable. In this case, the application can simply call Diags_setMask() with a string that is supplied by the loader.

char *eventMask = getenv("EVENT_MASK");
if (eventMask != NULL) {
    Diags_setMask(eventMask);
}

See also

[printable version]

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