SystemAnalyzerTutorial2A

System Analyzer Tutorial 2A:

Configuring your application to upload event data over JTAG

Under construction...

In , "transports" are used to move events from the target to the host and messages between the target and the host. One of the key goals of the Unified Instrumentation Architecture is to make it possible to change the transport(s) (i.e. the infrastructure used to upload event data and transfer messages between the target and host) without having to modify the application source code. I.e. the APIs used to log an event remain consistent regardless of the underlying infrastructure used to store events in memory or transport them to the host.

This makes it easy to, for example, use JTAG as a transport in the early stages of development in the lab, before an O/S is even up and running, and to use Ethernet as a transport in order to monitor and interact with deployed systems in the field.

This is achieved by using macros (e.g. Log_writeX, Log_printX, Log_errorX) to log the events, and generating the code to 'hook in' the back-end event loggers that are assigned to application modules via symbols and data structures that are generated at 'configuration time'. (For more info on this, please see the RTSCpedia).

Let's take a look at some of the loggers available that support uploading events over JTAG:

ti.uia.runtime Loggers that support uploading events over JTAG

Name	Purpose	Details
LoggerStopMode	Circular buffer that allows the Debug Server to upload events when the target halts	Once the buffer is full, new events overwrite the oldest events in the circular buffer. Works with all targets. Used in Tutorial 1.
LoggerCircBuf	Circular buffer that supports real-time JTAG event upload. Also supports Ethernet transports.	New events are dropped when the circular buffer is full (required in order to allow events to be read atomically from the buffer while the target is running). Another LoggerStopMode logger can be configured as an 'Overflow logger' to capture the dropped events. (Click here for details.)
LoggerProbePoint	Same as LoggerCircBuf, except that labels are defined at the points in the code where the buffer is written to, allowing the Debug Server to insert probe points (i.e. breakpoints where the target is automatically run after the breakpoint has hit) that enable the newly written events to be uploaded to the host as soon as they are written.	Primarily intended for use on simulators, but also works on targets connected via a JTAG emulator.

Let's take a look at the systemAnalyzerTutorial2.cfg file to see how Loggers for this tutorial are configured:

The "var Logger = xdc.useModule(..." line brings the ti.uia.runtime.LoggerCircBuf module into the application. The subsequent lines show how to statically allocate a 32678 byte buffer for the logger (which is created offline by calling the Logger.create script API from the .cfg script). To change the size of the buffer, simply set the transferBufSize to the desired number of bytes. (Please see Advanced memory placement for details on how to specify where in memory the buffer is to be located.)

The last line assigns a user-friendly name for the logger, which is helpful in situations where you have multiple loggers defined. (You may, for example, want to define a separate logger for BIOS events so that the events logged by your application code are not lost due to a high volume of BIOS-related events).

The following line shows how to configure the logger you've just created as the logger to be used by the Main module (i.e. the 'module' that all of your normal C code is assigned to):

Configuration parameters that are common to all XDC modules are defined as part of the "common$" attribute, defined in xdc.runtime.IModule. (The "$" suffix is a naming convention used in XDC to avoid namespace collisions with other 'normal' configuration options). In this case, we're configuring the Main module to use the logger we created earlier in the .cfg script to log the events into a LoggerCircBuf circular buffer.

Next: Tutorial 2B: Using the UIAEvt_intWithKey event to log values over time

Links

• Tutorial 2C: Working with System Analyzer's Count Analysis graphs
• System Analyzer Tutorial 1
• System Analyzer Tutorials Home Page
• System Analyzer Home Page