System Analyzer Tutorial 5A

Tutorial 5A: A Flight Recorder logger: using LoggerStreamer to log events to memory and uploading the events to a binary file for off-line analysis in System Analyzer

Pre-requisites for this tutorial:

• A board with a C66XX device (e.g. TMDXEVM6670L, TMDXEVM6678L or TMDXEVM6614LE)
• CCSv5.2 or later
• System Analyzer 1.1 or later
• Target content package uia_1_01_01_14 or later

In this tutorial, we will create a project that uses a very low overhead logger named LoggerStreamer to store events in a circular array of UIA Packet buffers in memory. A Debug Server Scripting (DSS) script is provided that uploads the events from memory and saves them to a binary file that can be analyzed off-line by System Analyzer. This enables a lightweight ‘flight recorder’ style of logging events that can be used in situations where real-time monitoring is not required, but analysis of the events leading up to a crash is needed. Along the way, we'll discuss how to configure the LoggerStreamer module and how to implement the callback functions that LoggerStreamer interacts with.

Building the Tutorial Project

To get started, we'll create a new project based on a template project that ships with the UIA package:

CCSv5.2:

• In CCS, select File / New / CCS Project /
• Configure the New Project Wizard as shown below:

• Click Next, and select the Platform that corresponds to your target device. E.g. for the 6670 EVM, configure it as shown below:

• Click Finish. This should add a new project to your workspace. You should be able to build this project without errors.

CCSv5.3 and Later:

• The attached zip file contains the same CCS project as described for CCSv5.2: File:Tutorial5A LoggerStreamer.zip

A brief overview of the Tutorial Project

LoggerStreamer logs events directly into memory buffers that are provided by the application. Before the memory buffers can be used, they need to be initialized to contain the UIA Packet Header information by calling the LoggerStreamer_initBuffer API. This is typically handled by a user-written "priming" function that the logger has been configured to use. When an event is logged and LoggerStreamer determines that there is not enough room to store the event in the buffer it is currently using, it calls the user-written "exchange" function, passing it the pointer to the buffer it has filled (so that it can be e.g. sent out over Ethernet using UDP to the PC that System Analyzer is running on). The exchange function returns a pointer to the next buffer to use (or NULL if there are no available buffers).

Here's the .cfg script that is used to configure the LoggerStreamer module:

And here's the .c code that is used to define an array of 3 1024 byte buffers, as well as the prime and exchange functions:

Some requirements on the buffers used to log events:

• buffer length must be a multiple of 4
• buffer start address must be word-aligned
• buffer start address should be cache aligned

• (Note: to keep the tutorial code simple, the buffers in the tutorial are not cache aligned.)

If the buffer is to be uploaded to SystemAnalyzer over Ethernet using UDP, the buffer size should be less than 1500 or whatever the MTU (Maximum Transmission Unit) size is. (See Tutorial 5C for more information on how to optimize the performance and throughput of LoggerStreamer, including how to cache align buffers and how to determine your system's MTU size.)

The tutorial logs events using the "LogUC" (Log unconditional) APIs Log_printUC1 and Log_writeUC0 in order to reduce the CPU overhead. For more information on these APIs, please see Tutorial 1E: LogUC.h - reducing the number of cycles required to log an event.

Running the Tutorial Project

• Launch a debug session for your target device:

• connect to the first C66XX CPU on the device
• do a system reset (Run / Reset / System Reset)

• run the Global Default Initialization GEL script for the EVM

• For the C6670: Scripts / LC_EVM_C6670_Functions / Global_Default_Setup

• Load the project. It should halt at main.
• Set a breakpoint in main.c at the return statement in the exchange function.
• Configure the breakpoint so that it has a Skip Count of 2 so that the breakpoint will only hit once all three of the buffers have been filled.

• In the editor, right click on the breakpoint icon in the left-hand gutter and select Breakpoint Properties.
• Change the Skip Count to 2

• Run the program until it halts at the breakpoint

• verify that the count variable has a value of 3

A Debug Server Script to upload captured events

For the tutorial, we will use a Debug Server Scripting (DSS) script to upload the captured event buffers via JTAG and store them to a binary file.

Here's a .zip file that contains the Tutorial5A_readLogBuffers.js DSS script: File:Tutorial5A readLogBuffers.zip. To follow along with the steps in the tutorial, please unzip the file into c:\.

You may need to make some modifications to this script in order to use it in your setup.

• The following line in the Tutorial5A_readLogBuffers.js script is used to specify which CPU the script will interact with:

• The string passed to debugServer.openSession must match exactly the string displayed in the Debug View for the CPU that you wish the script to interact with:

• To change the script to work with a different CPU or with a different emulator, open the .js file in a text editor (e.g. Notepad++) and change the string to match the text shown in the Debug View for the CPU you wish to use. The string is case sensitive.
• Note: If you try to edit the file in CCS using File / Open, you will likely encounter a Microsoft JScript error. You can get around this by importing the file into your project (File / Import / File System, browse to file and specify the tutorial project folder in your CCS workspace). In The CCS Project Explorer, right click on the file and select Open With / Other... / C/C++ Editor. This editor provides syntax coloring and does not try to use Microsoft JScript to parse it.

• The script is tailored to work with the tutorial example, but can be easily modified to work with other applications.

• The script references the "count" and "buffer" symbols defined in the tutorial's logger.c file. If you are using different names for these items in your application's .c code, change the symbol names used in the script to match.
• The following variables in the script must reflect values in your application: numPackets, bufferSize, isBigEndian.

• The script saves the packets to the folder specified by the strOutputFolderName variable ("c:/ti").

• If you wish to change the directory that the file is written to, edit the string assigned to the strOutputFolderName variable.
• Note that the name of the file MUST be systemAnalyzerData.bin for System Analyzer to be able to recognize it.

Uploading the captured events

• Open the scripting console (View / Scripting Console)
• run the script by typing loadJSFile "c:/Tutorial5A_readLogBuffers.js"

• Tip: use the 'up arrow' on your keyboard to recall previous commands entered into the Scripting Console. Commands entered during previous CCS sessions can be recalled in this way too.
• The script outputs status messages to the console to provide feedback on what it is doing

This will save the uploaded buffers (each containing a UIA event packet) to c:\ti\systemAnalyzerData.bin To view the events:

• Tools / System Analyzer / Open Binary File

• For CCSv5.2, at the top of the dialog, specify the full path to the binary file (c:\ti\systemAnalyzerData.bin)

• 

• For later releases, at the top of the dialog, specify the Folder Name that the binary file is located in (c:/ti)

• 

• Click on the Create UIA Config File button to create a custom configuration for System Analyzer.

• Create a custom configuration for System Analyzer, consisting of an Event Transport set to Type = None and a single endpoint, with the .out file set to the location of the .out file for this tutorial, as shown below:
  

• Save this to the root folder of the tutorial project in the CCS workspace for later use.

• Click the Start button to process the bin file

This will display the events that were captured in a view named "Binary File - : Logs".

The breakpoint that we placed in the exchange function ensured that the UIA packets were properly closed by LoggerStreamer. The script contains a "flush" function that detects if the UIA packet was actively being logged to (i.e. had an incomplete packet header) and, if so, updates the packet header prior uploading the buffers. It then restores the original state of any memory locations it has modified so that the target can go on running normally.

To demonstrate this:

• remove or disable the breakpoint in the exchange function
• run the target
• manually halt the target ( Run / Suspend)
• re-run the script in the scripting console (recall the last used command by clicking on the Scripting Console to bring it into focus and hitting the up arrow key on your keyboard, and then hitting Enter.

• The console output will show which memory locations were altered in order to close the active packet, and then indicate that the original values were restored after the packets were uploaded.

To update the System Analyzer Binary File - :Logs view to show the newly uploaded events:

• click the red Stop button in the view toolbar

• 
• the icon will change to a green triangle
• 

• click the button again to upload the events from the same file as you used previously.

Configuring SysBios to use LoggerStreamer to upload SysBios events

To configure SysBios to log events using LoggerStreamer, add the following lines to your .cfg script:

• var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
• LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_STREAMER;

Then rebuild your application.

You should be able to run the application, halt it, run the script, and view the events captured to the binary file using System Analyzer as described above.

To view the SysBios task switching events graphically, click on the small black triangle to the right of the "Analyze" label in the Logs view toolbar and select Execution Graph:

See Tutorial 3 for more information on how to configure and view SysBios events.

Next:Tutorial 5B: Using LoggerStreamer and the PDK Trace Framework.

Links

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