SystemAnalyzerTutorial1E

System Analyzer Tutorial 1E

LogUC.h - reducing the number of cycles required to log an event

A new set of low overhead logging macros were introduced in uia_1_01_01_14.

UIA release uia_1_01_01_14 introduces a new set of APIs that you can use to log events more efficiently: the "LogUC.h macros", which are defined in ti/uia/runtime/LogUC.h.

The macros have the same signature as those provided by xdc/runtime/Log.h, but have "UC" before the digit at the end of the API name that indicates the number of parameters supported. The "UC" stands for "UnConditional" - the events are logged unconditionally without checking the Diags masks. This reduces the number of cycles required to log the event (even more than you would achieve by setting the Diags masks to ALWAYS_ON), but at the cost of not being able to use the Diags masks to control which events are logged and which ones are not.

Here are the APIs that are defined in the ti/uia/runtime/LogUC.h include file:

LogUC.h APIs

API	Description	0 parameter syntax	Max parameter syntax	Example
Log_writeUC	Write a user-specified event.	Log_writeUC0(evt); ...	Log_writeUC5(evt, a1, a2, a3, a4, a5);	Log_writeUC3(UIABenchmark_startInstanceWithStr,(IArg)"My descriptive text",2,(IArg)"MySortTag");
Log_printUC	Log a printf-style string. Note: the mask is ignored. It is included for consistency with the xdc.runtime.Log.h macros.	Log_printUC0(mask, fmt); ...	Log_printUC6(mask, fmt, a1, a2, a3, a4, a5, a6);	Log_printUC0(Diags_USER1,"Hello World.");
Log_errorUC	Log an error event.	Log_errorUC0(fmt); ...	Log_errorUC5(fmt, a1, a2, a3, a4, a5);	Log_errorUC2("This is an error with two parameters: %d,0x%x",param1,param2);
Log_warningUC	Log a warning event.	Log_warningUC0(fmt); ...	Log_warningUC5(fmt, a1, a2, a3, a4, a5);	Log_warningUC1("This is a warning with one parameter: %d",param1);
Log_infoUC	Log an informational event.	Log_infoUC0(fmt); ...	Log_infoUC5(fmt, a1, a2, a3, a4, a5);	Log_infoUC0("Hello World!");

In order to see how much CPU this saves, let's rework Tutorial 1B so that it uses the LogUC APIs instead of the Log APIs. Since LogUC.h uses low-level APIs that are provided by the xdc.runtime.Log module, we don't need to change the .cfg file. All the changes that are required are in the tutorial1b.c file. Open this file in the CCS editor and make the following changes:

• Add the following line after the other #include statements:

• #include <ti/uia/runtime/LogUC.h>

• Replace (Edit / Find/Replace) all instances of Log_write3 with Log_writeUC3
• Save the file and rebuild the project
• Follow the steps in Tutorial1B to re-run the benchmarking analysis

One way to control whether an unconditional event is logged or not is to dynamically enable or disable the logger(s). Here's how to do this at runtime:

Edit the .cfg file and, following the line logger.instance.name = "Main logger"; add the following line:

• Program.global.hLogger = logger;

What this does is define a global symbol named hLogger that can be used in your program, and assigns the address of the logger handle to this symbol.

Edit the tutorial1b.c file and add the following two include file references:

• #include <ti/uia/runtime/LoggerStopMode.h> // to reference the loggers' enable and disable APIs
• #include <xdc/cfg/global.h> // to reference global symbols such as hLogger.

Then add the calls to LoggerStopMode_disable(hLogger); and LoggerStopMode_enable(hLogger); as shown below:

If you re-build the tutorial, re-load it and run it again, you will see that the events that are between the disable and enable API calls are not logged.

In order to reduce the CPU overhead associated with logging an event even further, you may be able to use more highly optimized loggers such as LoggerStreamer and LoggerSTM if they are supported by the device you are using. (LoggerStreamer is covered in System Analyzer Tutorial 5, and LoggerSTM is covered in System Analyzer Tutorial 6 ).

Next: Tutorial 1F: Function Profiling

Links:

• Back up to the System Analyzer Tutorials page
• Back up to the System Analyzer Home