SystemAnalyzerTutorial1A

System Analyzer Tutorial 1A

How to instrument your application code to log errors, warnings, and informational events

This tutorial demonstrates the use of the Log module to log a number of different types of events, and how to run and use System Analyzer to display the events. Let's start by running Tutorial 1A (see the Getting Started page for how to build and run the tutorials.)

After you have run Tutorial 1A, the System Analyzer Log View should display the events that were logged.

• To make it easier to read the event data, please click on the AutoFit button in the System Analyzer Log View toolbar.

The table should now look something like this:

If you can, it will be helpful to look at the tutorial1a.c file in an editor.

Logging Info Events: Hello World!

The code:

What is displayed:

Things to notice: The file name and line number that the Log_info API call was logged from is automatically displayed at the start of the output string.

Logging Warnings

The code:

What is displayed:

Things to notice: The string that is used to define the warning message can include printf format specifiers to control how parameters are displayed. The %d format specifier tells System Analyzer to display the value of param1 as a decimal value.

Logging Errors

The code:

What is displayed:

Things to notice: The "Error" column in the System Analyzer Log View has nothing to do with whether the event itself is an Error event! Instead, it displays icons that indicate when System Analyzer encountered an unexpected condition when it was trying to upload, decode or display the events. For example, each UIA event has a 'sequence number' that indicates the order in which the event was logged.

The following icons will be displayed in the Error column if the sequence numbers are not sequential:

 : Data Loss

• a gap in the sequence numbers for events coming from the same Logger buffer was detected)

 : Sequence Error

• the sequence number for the event was higher than the previous event's sequence number

Using Predefined Error Codes: e.g. Critical and Fatal errors

The code:

What is displayed:

Things to notice: The comment suggests reading the CDOC documentation for the predefined events to understand what parameters are expected to be logged with the event. In general, when you are using a UIA API or event for the first time, it is a good idea to read the documentation associated with it. Please see How to read UIA CDOC documentation for information on how to read CDOCs, the UIA event .msg format, etc. Another good reference is CCS Help: search for Events Provided by UIA for an overview of predefined events provided by UIA and info about the special formatting codes that can be used (e.g. %$F).

Logging Low priority details

The code:

What is displayed:

Things to notice: The Log_error, Log_warning and Log_info APIs have the format string as the first parameter, but the Log_write API used here has it as the third parameter. Also, the Log_write API requires the format string to be cast as an IArg (i.e. an integer). This is because the Log_write APIs are generic APIs that take a UIA event as the first parameter and then from 0 to 8 IArg values for the remaining parameters. The parameters that should be passed in are defined as part of the .msg format for the UIA event, and are described in the CDOC documentation for the event. Since predefined events need to be logged using the Log_write API, all parameters that are not integers should be cast as IArg values.

An important thing to realize is that, if you try to log a string using the Log_write API, you are actually only capturing the address of the string. If the string is a constant string (e.g. the name of the file that is referenced by the __FILE__ preprocessor macro), System Analyzer will be able to look up the text associated with the string from the application's .out file and display it properly. However, strings that are not constant values are not available in the .out file and will not be resolvable. Tutorial 1D covers how to use the LogSnapshot_writeString API to log strings that are stored in memory.

Logging Statistics

The code:

What is displayed:

Things to notice: Using System Analyzer's analysis views is covered in Tutorial 2: Graphing Events.

Include files and the .cfg file

In order for the compiler and linker to build the program, references to the APIs and constants that are used must be resolved. There are two parts to this: adding #include statements to your .c code, and adding xdc.useModule statements in your application's .cfg file.

The code:

The systemAnalyzerTutorial1.cfg file entries: (Note that this file was called mcsaTutorial1.cfg in earlier versions of the UIA package)

The .cfg file acts as a kind of linker command file, identifying which modules need to be used in the building of the project. It also provides a way to define constants and 'configuration parameters' for the modules that are used.

(Note: UIABenchmark events are used in System Analyzer Tutorial 1B, which is why the line var UIABenchmark = xdc.useModule('ti.uia.events.Benchmark') is present in the .cfg file)

More information about how to work with .cfg files is provided in System Analyzer Tutorial 1D.

Next: Tutorial 1B: how to benchmark your application code so that you can see how long it takes to execute code on a running system

Links:

• 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 1C: how to control which events in your application are enabled and disabled
• 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