TraceUtil

END OF LIFE

Note that TraceUtils is no longer recommended. This article remains for existing users.

Introduction

TraceUtil is an ARM-side module that simplifies using Codec Engine's complex tracing features. It lets the user, at build time and/or run time, say what trace levels they want and where they want the trace collected. At run-time, user can turn on or off tracing features by writing command strings to a named Unix pipe.

Use TraceUtil for debugging, to collect real-time data, or both.

Note: TraceUtil is not supported in Codec Engine 3.x.

Features

TraceUtil takes care of three kinds of tracing that Codec Engine modules can produce:

• Tracing on the ARM side: many Codec Engine and other ARM-side modules drop tidbits of information that give insight about their state, or they print warning and fatal error messages.
• Tracing on the DSP side: same as ARM-side modules -- except this is often the only way to find out what is going on on the DSP. Arm-side code can use printf() or the user can fire up GDB, but for DSP, tracing is often the only way to send a line of text over to the Arm.
• BIOS 5 logging on the DSP side: BIOS 5 can collect information on various system events like task switching etc. This information, called "BIOS log" (because it uses the BIOS 5 LOG module) is important when you use the Socrates tool to analyze performance. Unlike the first two kinds of trace, which are ASCII texts, BIOS log is a binary file.

TraceUtil lets you specify what tracing features you want when you build your application, and lets you override some of all of those specs via Linux shell environment variables when you run the application.

Configuring TraceUtil for use at build time

To use TraceUtil, when you build your application you must have this line added to your application's configuration (.cfg) script (anywhere in the script is fine):

<syntaxhighlight lang='javascript'> var TraceUtil = xdc.useModule('ti.sdo.ce.utils.trace.TraceUtil'); </syntaxhighlight>

If you don't do anything else, this will configure TraceUtil to:

• print all errors and warnings from the ARM (tracemask "*=67") on the standard output
• have the DSP print all errors and warnings; Arm will collect them every 200ms and print on standard output
• not do any BIOS logging

You can modify the default behavior by assigning the TraceUtil.attrs field. For complete details, please see the reference documentation for the "ti.sdo.ce.utils.trace.TraceUtil" module.

A commonly used .attrs assignment is the DVT/SoCrates profile:

<syntaxhighlight lang='javascript'> TraceUtil.attrs = TraceUtil.SOCRATES_TRACING; </syntaxhighlight>

With this profile, the GPP and DSP enable "SoCrates tracing", which includes BIOS logging. GPP trace is stored in /tmp/cearmlog.txt file, DSP trace in /tmp/cedsp0log.txt, and BIOS logging in /tmp/bioslog.dat. The polling rate is also pre-defined. However: the application begins to run without tracing enabled. To turn tracing on, the user -- or a program -- must write the "turn trace on" command to the trace command pipe.

Another profile is the 'full tracing' profile:

<syntaxhighlight lang='javascript'> TraceUtil.attrs = TraceUtil.FULL_TRACING; </syntaxhighlight>

The output destinations are the same as for SOCRATES_TRACING, but it enables all levels of trace for both the GPP and the DSP.

Supporting TraceUtil in your app's C code

To collect the trace that the DSP silently produces, you have to add these lines of C code to your Arm application:

<syntaxhighlight lang='c'>

1. include <ti/sdo/ce/utils/trace/TraceUtil.h>

/* ... */ TraceUtil_start(engineName); /* engineName is a string; call after CERuntime_init */ /* ... */ TraceUtil_stop(); /* call at the end of your app */ </syntaxhighlight>

This code spawns a (p)thread that every 200ms (by default) collects all available DSP trace and dumps it to a file or standard output. (It also collects and stores DSP BIOS log if you wanted it so.)

Configuring TraceUtil for use at application start time

Before you run your TraceUtil-powered application, if you set one or more environment variables below, you will change TraceUtil properties that you specified in your .cfg script:

CE_TRACE                - trace mask for the Arm side, e.g. CE_TRACE="*=0567;OM-0"
CE_TRACEFILE            - output file for Arm trace, e.g. CE_TRACE="trace/armtrace.txt"; if
                          it can't be opened (e.g. points to a directory that doesn't exist)
                          the trace will go to the standard output. (Try CE_TRACEFILE=/ for that.)
CE_TRACEFILEFLAGS       - file creation flags for all files to be opened, e.g. CE_TRACEFILEFLAGS="a"
                          (meaning "append"), or "w" (write); these are standard fopen() flags
TRACEUTIL_DSP0TRACEFILE - output file for the DSP trace; same remark holds as for the Arm trace
TRACEUTIL_DSP0BIOSFILE  - output binary file for the BIOS log; if can't be open, will not be collected
TRACEUTIL_DSP0TRACEMASK - trace mask for the DSP side, e.g. TRACEUTIL_DSP0TRACEMASK="*+01;ti.bios=01234567"
TRACEUTIL_REFRESHPERIOD - number of milliseconds before the Arm thread collects all available DSP trace
                          since the last time it did it
TRACEUTIL_CMDPIPE       - name of a Unix named pipe ("fifo") where the TraceUtil listens for run-time
                          trace commands
TRACEUTIL_VERBOSE       - when set to 1 makes TraceUtil print the what trace settings (masks, files)
                          it uses and where it gets them from. When set to 2 and up it shows more
                          debugging info.
                          You almost always want TRACEUTIL_VERBOSE=1 set.

If you use bash shell on Linux, it is especially convenient to set environment variables in the same line where you start your application, so they apply to that execution of the application only:

CE_TRACE="*+5" CE_TRACEFILE="mylog" TRACEUTIL_VERBOSE=1 ./app.out

Note These environment variables are read once, at application startup time. Changing them after the application is executing will not have any effect: when the application runs, the application process gets its own copy of environment variables (changing them in the shell process does not affect the application process), and the application reads its copy of environment variables only when it initializes.

Controlling trace at app execution time through a named pipe

If the TRACEUTIL_CMDPIPE variable is set to a valid name, or TraceUtil.attrs.cmdPipeFile build-time option is set (as it is for TraceUtil.SOCRATES_TRACING profile), the TraceUtil thread listens for any tracing commands that appear in the pipe.

• SOCRATES_TRACING profile uses the command pipe feature: the pipe is by default defined to be /tmp/cecmdpipe, but can be overriden by a value specified in TRACEUTIL_CMDPIPE environment variable
• when you start socrates-enabled app, initially it shows no trace other than (potentially) warnings and errors
  • that is, unless you defined CE_TRACE="*+5" TRACEUTIL_DSP0TRACEMASK="*+5,ti.bios=3" env. vars before the app started
  • or, you did mkfifo /tmp/cecmdpipe; echo socrates=on > /tmp/cecmdpipe before running the app
    • mkfifo is necessary only for the first run; TraceUtil creates the pipe if it doesn't exist, and doesn't delete it at the end
• when the socrates app is running, you turn tracing on by writing socrates=on string to the /tmp/cecmdpipe file.
  • you turn tracing off by writing socrates=off string to the /tmp/cecmdpipe file
• in both cases the best way to write the string to the pipe is open-write-close (as opposed to keeping the pipe file open for writing throughout the session, though that works, too)
• [create_pipe]->open_pipe->write_text->close_pipe sequence can be either done by a person or script (as in the example above) or from a C program
• command pipe accepts any commands like tracemask=someArmTraceMask and dsp0tracemask=someDspTraceMask
• socrates=on and socrates=off pipe commands are defined as alias' for a group of appropriate socrates masks
  • alias definitions are in the TraceUtil.xdc file, and enables/disable both GPP and DSP tracing.

Valid trace pipe commands

Below is the list of supported trace pipe commands. Note that only one command per line should be written to the trace pipe.

• tracemask={Arm trace mask value} sets the trace mask on the Arm, e.g. tracemask=*+01234567,OM-1
• dsp0tracemask={DSP0 trace mask value} sets the DSP0 trace mask, e.g. dsp0tracemask=*-1,ti.bios-012
• refreshperiod={number of milliseconds} sets the refresh period for DSP0 trace and log collection; if 0, there will be no collection until a non-0 refreshperiod is specified; example: refreshperiod=10
• resetfiles (no arguments) resets all open files -- Arm trace, DSP0 trace, DSP0 log (i.e. those that are in use) -- by truncating them to 0 bytes.

As with socrates=on, the Arm application integrator can define, in his application config script, command pipe aliases that issue several pipe commands, as in this example:

<syntaxhighlight lang='javascript'> var TraceUtil = xdc.useModule('ti.sdo.ce.utils.trace.TraceUtil'); TraceUtil.attrs.cmdAliases = [

   {
       alias: "mycommands_1",
       cmds:  [
              "resetfiles",
              "tracemask=*+5",
              "dsp0tracemask=*+5,ti.bios+3",
              "refreshperiod=200",
       ],
   },
   {
       alias: "mycommands_2",
       cmds:  [
              "tracemask=*-5",
              "refreshperiod=0",
              "dsp0tracemask=*-5,ti.bios-3"
       ],
   },
   /* and so on -- no limit on the number of aliases */

]; </syntaxhighlight>

A note on configuring the DSP server for BIOS logging

If you set TraceUtil on the Arm side to use BIOS logging, you must have BIOS logging enabled in your DSP server image. That you do by adding this one line to your DSP server's configuration script:

<syntaxhighlight lang='javascript'> var LogServer = xdc.useModule('ti.sdo.ce.bioslog.LogServer'); </syntaxhighlight>

If your DSP server is incapable of BIOS logging, you will see Arm-side error/warning messages like,

LogClient_connect> Error: failed to locate server queue, Check if your DSP image has BIOS logging enabled

and

LogClient_fwriteLogs> Warning: not connected to the BIOS log server on the DSP, cannot collect any BIOS log data.