McsaTutorial1D

Tutorial 1D:

(for UIA_1_00_01_17 and earlier releases)

Note: System Analyzer's support for analysis of UIARoundtripEvents is currently under construction, and will be introduced in a later release of System Analyzer. Tutorial 1D has been reworked to show how to log dynamically allocated strings so that the string text can be displayed correctly in System Analyzer's log view.

Up until this point in System Analyzer Tutorial 1, we've been working with events that have already been configured for you in mcsaTutorial1.cfg (renamed systemAnalyzerTutorial1.cfg in later versions of UIA), and use C code provided in the various .c files. This part of the tutorial will walk through what you need to do in order to use a UIA module in your application, including:

• the types of errors you will see if you have not added the module to your .cfg file
• how to add a module to your application's .cfg file
• how to reference the module from your .c code

It also demonstrates the use of the LogSnapshot module to upload the contents of dynamically allocated strings, so that references to that string that are made in subsequent events will be able to be displayed as text in System Analyzer.

To get started, please

1. erase the mcsaTutorial1.gel and tutorial1d.c files in your project
2. download and unzip the attached Tutorial1d.zip file
3. copy the files in this zip file into your project's folder
4. in the CCS Project Explorer, right click on the project and select Refresh

Let's take a look at the code in tutorial1d.c:

On line 26, you can see that the #include for the LogSnapshot.h is now enabled, which would seem to be sufficient to allow the C code to use the APIs defined in the LogSnapshot module. If you try to build this project, you will get something along the lines of the following error output to the console:

To resolve this, open up the mcsaTutorial1.cfg file by right clicking on the mcsaTutorial1.cfg file in the CCS Project Explorer view and selecting Open With->XDCscript Editor (or double click it and select the 'Source' tab at the bottom of the edit pane.) Add the following statement:

Save this .cfg file and rebuild - it should now build cleanly.

What the line you added to the .cfg file does is configure the application to use a particular module. In this case the module name is "LogSnapshot", and the package the module belongs in is named "ti.uia.runtime" .

Some background info on .cfg files and XDC modules:

.cfg files use JavaScript syntax. Note that when referencing the module in the .cfg file, the package name elements are separated by '.', whereas in .c files, the package name elements are separated by '/' in the include file path, and by "_" when referencing an API or a constant in the .c code itself.

XDC modules consist of 3 parts: c code (LoggerSnapshot.c), an 'XDC spec file' (LoggerSnapshot.xdc) and a script file (LoggerSnapshot.xs) that is run at configuration time. In this case, the script file for LoggerSnapshot takes care of configuring the ti.uia.events.UIASnapshot module for use so that the LogSnapshot_writeString API can use the UIASnapshot_stringOnHeap event to log the contents of the string we are interested in capturing. (For more information on XDC, please see the RTSCpedia).

Running Tutorial 1D

To run Tutorial 1D, launch the simulator you've been using, load the newly built tutorial program, load the .gel file, run Tools->System Analyzer->Live, select "Until data transfer is manually paused", and from the main CCS menu select Scripts->System Analyzer Tutorial 1->Tutorial1D_ LoggingDynamicStrings). You should see 3 events displayed in the LogView:

What this demonstrates:

• The first time the Log_print statement logs an event, the %s reference cannot be properly resolved.
• The second event shown is the LogSnapshot event. For very long strings, the upload of the string contents may be split across multiple snapshot events in order to keep the event memory footprint smaller than the maxEventSize configuration parameter of the logger used to log the events (in this case, LoggerStopMode.maxEventSize = 128 bytes).
• The third event shows the event logged by the last Log_print event, and shows the proper text for the dynamically allocated szMyString string.

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

• Tutorial 2: Graphing Events
• Back up to the System Analyzer Tutorials page
• Back up to the System Analyzer Home