Using xdc.runtime Logging/Example 6

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  offline version generated on 18-Nov-2017 00:11 UTC 

Using xdc.runtime Logging/Example 6

How to create and use custom Log Events


Using Custom Log Events

The example below illustrates the use of Log.write1 to write an event defined by a custom module of your own. This module, named local.log.Events, is provided in the next section.

Since we are using an event defined in local.log.Events, we mustn't forget to add this to our application's configuration script; otherwise, when we build the application we will get "undefined reference to ..." errors from the linker. As a rule, whenever you #include the C header of a RTSC module, you must also add an xdc.useModule() of that module to your configuration script.

#include <xdc/runtime/Log.h>
#include <local/log/Events.h>
/*  ======== main ======== */
Int main(Int argc, String argv[])
    /* write some HELLO events */
    Log_write1(Events_HELLO, 0);
    Log_write1(Events_HELLO, 1);
    return (0);
/* enable 'ENTRY' events for main.c */
var Diags = xdc.useModule("xdc.runtime.Diags");
var Main = xdc.useModule("xdc.runtime.Main");
Main.common$.diags_ENTRY = Diags.RUNTIME_ON;
/* create a logger & make it the logger for all app code */
var Logger = xdc.useModule("xdc.runtime.LoggerSys");
Main.common$.logger = Logger.create();

The output produced by the application is shown below.

xdc.runtime.Main: 0: Hello world!
xdc.runtime.Main: 1: Hello world!

The Events Module

This section shows the complete set of files necessary to create a new module that specifies a set of custom Log Events. The module specification below couldn't be simpler: it declares the name of the new module, Events, and defines a new Log.Event named HELLO that accepts a single integer argument. This argument can, for example, be used in your application to represent a channel ID, a thread ID, or simply a call counter.

import xdc.runtime.Log;
import xdc.runtime.Diags;
module Events {
    config Log.Event HELLO = {
        mask: Diags.ENTRY,
        msg: "%d: Hello world!"

The Package Files

Since all modules must live in a package we also need to create a two other files:

  1. package.xdc - a file that define the package's name and identifies the modules it contains, and
  2. package.bld - a file that specifies everything that needs to be included in the package.

Since this package does not contain any source files that need to be compiled or included in the this package, the package.bld file can be empty. Why is it needed at all if it can be empty? The existence of package.bld tells RTSC tooling that this package is "buildable" while the contents specify what should be built.

package local.log { 
    module Events; 
/* nothing more to say (package.xdc said it all) */

The package.xdc file is largely self explanatory; it defines the name of the package, local.log, and it specifies the module contained in the package, Events.

The package.bld file, on the other hand, requires some explanation. The existence of package.bld indicates that the package is (re)buildable and, because the RTSC build engine's default behavior is sufficient for this package, the package.bld file can be empty.

Finally, before the Events module can be used, this package must be built using the xdc command. Because this package does not contain any C code, there is no need to setup any compilers nor specify a runtime platform. It is sufficient to simply cd to the package's directory and type xdc.

% cd local/log
% xdc
making package.mak (because of package.bld) ...
generating interfaces for package local.log (because package/ is older than package.xdc) ...
    translating Events
all files complete.

See also

Using xdc.runtime Logging/Example 2 Events provided by all RTSC target modules
Using xdc.runtime Logging/Example 3 Adding logging to existing code bases
Using xdc.runtime Logging/Example 4 Adding Logging to RTSC Modules
Using xdc.runtime Logging/Example 5 Controlling Logging
[printable version]  offline version generated on 18-Nov-2017 00:11 UTC 
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference