Trace in Framework Components

From Texas Instruments Embedded Processors Wiki

Jump to: navigation, search

Translate this page to

Trace in Framework Components

Introduction

Framework Components, as of the 2.00 release, provides a lot of useful 'trace' information that can be used by customers for debugging issues and sometimes even just for understanding the control flow in their applications etc.

How to enable trace in Framework Components

The mechanism of enabling trace continues to change and evolve and what follows is guide on the mechanism to enable trace for your particular Framework Components release.

Note that once trace is enabled, users of Codec Engine may use the CE_DEBUG feature to acquire the trace if the algorithm is 'remote'.

Framework Components 2.00 to 2.21

Tracing in these releases is built using the "GT" trace mechanism (ti/sdo/utils/trace/gt.h). Enabling trace in these releases requires the following additions in your (server or application) config files:-

Set up GT

//GT is the module that allows tracing
var GT = xdc.useModule("ti.sdo.utils.trace.GT");
 
//GT requires a function to be configured that it will use to "malloc" for its internal data structures. 
//It also needs a function that it will use to actually 'print' out the trace for the user.
 
//GTINFRA is a module made available by FC that provides implementations of the functions above.
var GTINFRA = xdc.useModule("ti.sdo.fc.utils.gtinfra.GTINFRA");
GTINFRA.runtimeEnv = GTINFRA.NONE;
 
GT.MALLOCFXN = "myMalloc";
GT.PRINTFXN = "printfCaller";
//You can override the above functions with your own, and not use the GTINFRA module provided by FC

Enable trace for individual FC modules

var RMAN = xdc.useModule("ti.sdo.fc.rman.RMAN");
RMAN.trace = true;      //Enables trace for RMAN
RMAN.debug = true;      //Allows debug libraries to get linked in for RMAN

Framework Components 2.22 and later 2.x releases

Tracing in these releases is still built for GT, but the syntax to enable trace has changed. In earlier releases, each FC module had a _.debug_ and a _.trace_ configuration parameter, that you would turn on/off to enable/disable debug builds and/or trace. That part has changed in these releases and instead _profile_ setting for each module (or for FC has a whole) is used to specify the trace/debug modes of libraries that link into the final executable. Here's what you need in the cfg file to enable trace/debug libraries:-

Set up GT

var GT = xdc.useModule("ti.sdo.utils.trace.GT");
var GTINFRA = xdc.useModule("ti.sdo.fc.utils.gtinfra.GTINFRA");
GTINFRA.runtimeEnv = GTINFRA.NONE;
GT.MALLOCFXN = "myMalloc";
GT.PRINTFXN = "printfCaller";

Enable trace/debug for individual or all FC modules

//Switch to debug + trace profile for all FC modules
xdc.useModule('ti.sdo.fc.global.Settings').profile = "debug_trace";
 
//Alternatively, to use debug profile for all FC modules, use this:
//xdc.useModule('ti.sdo.fc.global.Settings').profile = "debug";
 
//Switch on trace for some modules specifically.
xdc.loadPackage('ti.sdo.fc.rman').profile = "debug_trace";
xdc.loadPackage('ti.sdo.fc.edma3').profile = "debug_trace";

Framework Components 3.00

As of the 3.00 release, the underlying mechanism of trace changed from GT to "xdc.runtime.Log". Details on using xdc.runtime.Log are available here [1]. But in short, all Framework Components now support a xdc.runtime.Diags mask (instead of the old GT masks) and all GT_trace statements in FC have been replaced with corresponding Log_printf statements.

Following are quick steps to enable logging in Framework Components

Add this file Log setup.cfg to your app directory, right next to your server config file. This file initializes the Logger and the Diags mask so that all tracing is currently switched OFF.

In your cfg file add the following:-

utils.importFile("Log_setup.cfg");        //Import the file with the log setup
 
//Setting default tracing OFF for all levels
Defaults.common$.diags_ENTRY = Diags.RUNTIME_OFF;
Defaults.common$.diags_EXIT  = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER1 = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER2 = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER3 = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER4 = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER5 = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER6 = Diags.RUNTIME_OFF;
Defaults.common$.diags_USER7 = Diags.RUNTIME_OFF;
 
//Setting tracing on only for RMAN ENTRY/EXIT information
RMAN.common$.diags_ENTRY = Diags.RUNTIME_ON;
//Setting tracing on only for RMAN USER4 level trace information
RMAN.common$.diags_USER4 = Diags.RUNTIME_ON;
//Setting tracing for on only for HDVICP2 level trace information
HDVICP.common$.diags_USER4 = Diags.RUNTIME_ON;
 
//Setting tracing on for all xdc.runtime.* modules. This is usually a lot of information so best to leave it
commented out.
//Diags.setMaskMeta("xdc.runtime.%", Diags.ALL, Diags.RUNTIME_ON);
//Trace on at ERRORS ONLY for all modules under ti.sdo.fc.*
Diags.setMaskMeta("ti.sdo.fc.%", Diags.USER7, Diags.RUNTIME_ON); 
 
//Trace on at USER4 LEVEL for all FC
Diags.setMaskMeta("ti.sdo.fc.%", Diags.USER4 | Diags.USER2, Diags.RUNTIME_ON);
 
//ALL Trace on for ALL FC
Diags.setMaskMeta("ti.sdo.fc.%", Diags.ALL, Diags.RUNTIME_ON);

For linking in FC's debug libraries do the following

//Debug libs for DSKT2 only
xdc.useModule('ti.sdo.fc.dskt2').profile = "debug"
//Debug libs for all FC contributions.
xdc.useModule('ti.sdo.fc.global.Settings').profile = "debug"

Framework Components 3.20-Current

As with Framework Components 3.00, the 3.20 release uses xdc.runtime.Log as the underlying mechanism of trace. However, the method of enabling logging for Framework Components (FC) modules is somewhat different from Framework Components 3.00:

The xdc.runtime.Registry module must be added to the application's configuration file.

Setting xdc.runtime.Diags masks for FC modules in the application's configuration file no longer has any effect. The Diags masks must now be set at run-time in order to take effect.

This change is due to changing the FC implementation from being XDC-spec'd SW (where XDC generates some of your code during configuration, including Logging support) back to 'classic C' SW like they were in FC 2.x. This decision was made to remove the hard requirement for XDC configuration - which is often required in non-BIOS environments. The xdc.runtime.Registry module enables classic C libraries to have their own Log masks, so users can enable/disable them independently.

Note: The above does not apply to BIOS or xdc.runtime modules, as those remain XDC-spec'd modules.

Example Configuration File Log Setup

Your Log setup.cfg file must first configure the logger you wish to use. For example, to use xdc.runtime.LoggerSys and have the log data output through C Standard I/O, add the following lines to your Log setup.cfg file:

/* Set up to use stdio */
var System = xdc.useModule('xdc.runtime.System');
System.SupportProxy = xdc.useModule('xdc.runtime.SysStd');
 
var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
var LoggerSysParams = new LoggerSys.Params();
 
var Defaults = xdc.useModule('xdc.runtime.Defaults');
Defaults.common$.logger = LoggerSys.create(LoggerSysParams);

Now add the following code at the end of your Log setup.cfg file to allow logging of Framework Components 3.20 modules (this code is not necessary for logging BIOS or xdc.runtime modules):

// Enable logging for metaonly modules
var Main = xdc.useModule('xdc.runtime.Main');
 
var Diags = xdc.useModule('xdc.runtime.Diags');
Diags.setMaskMeta('xdc.runtime.Main', Diags.ALL, Diags.RUNTIME_ON);
 
var Registry = xdc.useModule('xdc.runtime.Registry');
Diags.setMaskMeta("xdc.runtime.Registry", Diags.ALL, Diags.RUNTIME_OFF);

Run-Time Code for Enabling Logging

We can enable logging of FC modules at run-time using Diags_setMask(), however, this will only take effect after the module is initialized. This can be a problem if the module does not have an init() API available to the application (for example, DSKT2), but is initialized on the first call to any of its APIs (eg, first call to DSKT2_createAlg() will cause DSKT2 to be initialized). The application would miss any trace of the module's initialization code and first API call. For example, if you have the following code in your app.c file, you will not see any log data from DSKT2_createAlg().

Diags_setMask(DSKT2_MODNAME"+EX1234567");
alg = DSKT2_createAlg(scratchId, fxns, NULL, (IALG_Params *)&params);

To get around this problem, we have added a new FCSettings module that can be used to set a default Diags mask, which each FC module will initialize its own Diags mask to upon initialization. Here is the way to get logging for the first call to DSKT2_createAlg():

Include the header file, FCSettings.h.

#include <ti/sdo/fc/global/FCSettings.h>

Initialize the FCSettings module, and set its Diags mask to the default that you want for your other FC modules. For example,

to enable all logging for DSKT2_createAlg(), and the following code to your app.c file:

/* Set default mask for FC modules */
FCSettings_init();
Diags_setMask(FCSETTINGS_MODNAME"+EX1234567");
 
/* Now call DSKT2_createAlg */
alg = DSKT2_createAlg(scratchId, fxns, NULL, (IALG_Params *)&params);

We will make more tracing details available, if needed, after future FC releases

For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article Trace in Framework Components here.