SystemAnalyzerTutorial1C

System Analyzer Tutorial 1C

How to control which events in your application are enabled and disabled

The xdc.runtime.Diags module defines a set of flags called Diagnostic Masks that are used to control which events are logged. Each event is defined with one or more Diags Mask flags. For example, here's how the the UIABenchmark_startInstanceWithStr event is defined in the ti.uia.events.UIABenchmark module:

This event will only be logged when the module that contains the call to log the event also has the Diags.ANALYSIS mask configured to enable logging of the event.

The module's Diags mask flags may be set at configuration time and / or at run time. At configuration time, the mask flags can be configured with one of 4 'modes', which controls how the associated code is generated:

Configuring the flag as either ALWAYS_ON or ALWAYS_OFF eliminates an if statement in the generated code, and so reduces the overhead associated with logging the event. Configuring the flag as either RUNTIME_OFF or RUNTIME_ON allows the user to determine at runtime whether to log the event or not.

The table below shows the complete set of Diags mask flags that are available. The Control Character is used by C code to configure the flags at runtime, and the Category Name is used in the .cfg file to identify the flag at configuration time:

In order to support filtering of events based on priority level, events in each category can also be assigned a 2-bit 'level' value:

The `STATUS` category is the only category where the levels are given explicit meaning to ensure consistency. Within the `STATUS` category, the meaning of the levels is defined by the constants `EMERGENCY`, `CRITICAL`, `ERROR`, and `WARNING`:

Here's how the Error event that is logged when you call the Log_errorX API is defined in the xdc.runtime.Log module. Note the use of "level: Diags.ERROR" to assign the appropriate status level to the event. The status level is how System Analyzer knows which icon to display beside the event in the LogView:

Let's take a look at the contents of the systemAnalyzerTutorial1.cfg file in order to see how the Diags Masks have been configured for Tutorial1:

From this we can see that:

• Status events (e.g. events written by the Log_errorX and Log_warningX APIs) are always logged
• Analysis events such as the UIABenchmark events are logged by default, but can be turned off
• Info events such as those written by the Log_infoX API are logged by default
• USER1 events are always logged
• USER2 events are not logged by default
• USER3-USER6 events are logged by default

Let's now take a look at the contents of the tutorial1c.c file:

The Log_print0 API takes as its first parameter a user-specified Diags Mask, allowing the logging of that particular event to be controlled by the setting of the specified Diags Mask. Let's look at the each line of code to see what it does:

• Line 52: Since Diags_USER1 has been configured as ALWAYS_OFF, we would expect this event to never be logged.
• Line 53: Since Diags_USER2 has been configured as RUNTIME_OFF, we would expect this event to not be logged by default, but we should be able to enable logging of the event.
• Line 54: Since Diags_USER3 has been configured as RUNTIME_ON, we would expect this event to be logged by default, but we should be able to disable logging of the event.
• Line 59: This line shows how to do runtime configuration of a Diags mask. The API takes the name of the module (in this case, xdc.runtime.Main, the module that all standard 'C' code belongs to by default), followed by either a "+" to enable logging or "-" to disable logging, followed by a control character to indicate which Diags mask is being configured (see the table at the top of this page for the list of control characters). So "xdc.runtime.Main+2" instructs the API to set Diags_USER2 = RUNTIME_ON from that point onwards in the execution of the code associated with the xdc.runtime.Main module.
• Line 60: Since Diags_USER2 has now been re-configured as RUNTIME_ON, we would expect this event to be logged now.
• Line 65: This line disables logging of Diags_USER2 events in the main module.

After you've run Tutorial1C, the System Analyzer LogView should look something like the following, which shows the two events controlled by Diags_USER3 and then Diags_USER2 were logged as expected:

Next: * Tutorial 1D: How to upload the contents of dynamically allocated strings so that references to them can be displayed as text

Links:

• Tutorial 1A: How to instrument your application code to log errors, warnings, and informational events
• Tutorial 1B: How to benchmark your application code so that you can see how long it takes to execute code on a running system
• Tutorial 1D: How to upload the contents of dynamically allocated strings so that references to them can be displayed as text
• Tutorial 1E: LogUC.h - reducing the number of cycles required to log an event
• Back up to the System Analyzer Tutorials page
• Back up to the System Analyzer Home