UIA 2.0 LoggingSetup

PLEASE NOTE: This page is UNDER CONSTRUCTION.

UIA Logging Setup

This page applies to UIA_2_00_00_01 and later.

The LoggingSetup module is used to aid in configuring SYS/BIOS logging using UIA and System Analyzer support for your application. The LoggingSetup module automates the process of configuring an application to use UIA events, and configures SYS/BIOS modules to capture user-specified information such as CPU Load, Task Load and Task Execution so that it can be displayed by System Analyzer. It also automates the creation of infrastructure modules such as loggers, the ServiceManager and RTA modules to enable the capture and upload of the events over a user-specified transport. Both JTAG and Non-JTAG transports are supported.

Built-in Software Instrumentation

TI-RTOS provides a number of built-in software instrumentation events that can be logged in order to provide detailed insight into the performance and operation of your application. This section of the Logging Setup configuration page provides the ability to specify which of these built-in software instrumentation events you would like to enable or disable.

RTOS Load Analysis

Enabling RTOS Load Analysis configures TI-RTOS to log "Load" events which provide status information about the utilization of the processor. There are a number of different Load events that can be logged:

• CPU Load: the amount of time not spent in the idle task
• Task Load: the amount of time spent in each class
• Swi Load: the amount of time spent in Software Interrupt Routines
• Hwi Load: the amount of time spent in Hardware Interrupt Routines

You can control the frequency that Load events are logged by adding the following code to your application's configuration (.cfg) file:

 var Load = xdc.useModule('ti.sysbios.utils.Load');
 Load.windowInMs = 100; // configure to log every 100ms instead of the default period of 500ms.

CAUTION: logging Load events at a high frequency can cause a large number of events per second to be logged, leading to dropped events and slowdowns in the handling and processing of the event data. Logging SWI and HWI Load events will cause extra time to be spent in these interrupt service routines, which may impact the real-time performance of your application.

System Analyzer's CPU Load and Task Load analysis features provide both statistical analysis and graphs over time of the enabled Load events. For more information about how to use System Analyzer's Load Analysis features, please see the following:

• System Analyzer's User Guide.
• Tutorial 3: Real-time visibility for SysBios

• Tutorial 3C: How to use the System Analyzer Execution Graph and Task Load Graph

---

RTOS Execution Analysis

Enabling RTOS Execution Analysis configures TI-RTOS to log "Context Switch" events which provide status information about the execution state of the RTOS. There are a number of different Context Switch events that can be logged:

• Task Context: enables logging of Task ready, block, switch, yield, sleep, set priority, and exit events.
• Swi Context: enables logging of Software Interrupt post, begin, and end events
• Hwi Context: enables logging of Hardware Interrupt begin, and end events

Enabling event logging for Swi Context and Hwi Context allows you to see the execution status of individual Swi and Hwi threads.
CAUTION: Application performance may be impacted if you enable such logging for applications with Swi or Hwi functions that run frequently. In addition, logging many frequent events increases the chance of dropped events.

System Analyzer's Execution Graph provides a timeline view of the Context Switch events that are logged, allowing you to understand the execution sequence of your application. For more information about how to use System Analyzer's Execution Graph feature, please see the following:

• System Analyzer's User Guide.
• Tutorial 3: Real-time visibility for SysBios

• Tutorial 3C: How to use the System Analyzer Execution Graph and Task Load Graph

---

Task Profiler

Enabling Task Profiler configures TI-RTOS to log Task Context Switch events, Swi Context Switch events and Hwi Context Switch events which provide status information about the execution state of the RTOS.

CAUTION: Application performance may be impacted if you enable Task Profiler for applications with Swi or Hwi functions that run frequently. In addition, logging many frequent events increases the chance of dropped events.

System Analyzer's Task Profile analysis feature provides a histogram view that shows the percent of time that each Task, Swi and Hwi thread spent in each of its possible states. For more information about how to use System Analyzer's Task Profiler feature, please see the following:

• System Analyzer's User Guide.

---

Context-Aware Function Profiler

Enabling Function Profiler configures UIA's UIAProfile module for use with compiler-generated function entry and exit hook functions to enable logging of timestamped events whenever a function enters or exits. It also configures TI-RTOS to log Task Context Switch events, Swi Context Switch events and Hwi Context Switch events which provide status information about the execution state of the RTOS.

NOTE: In order to enable Function Profiling, you will need to configure your project's Build Settings to enable the compiler's Entry/Exit Hook options. For step-by-step instructions on how to do this, please see System Analyzer Tutorial 1F: Function Profiling

CAUTION:: The real-time performance of your application will be slowed down by the overhead associated with the function entry and exit hook functions.

System Analyzer's Context Aware Function Profiling analysis feature provides a histogram view that shows the percent of time that each Task, Swi and Hwi thread spent in each of its possible states. For more information about how to use System Analyzer's Task Profiler feature, please see the following:

• System Analyzer's User Guide.
• Tutorial: Function Profiling

---

User-written Software Instrumentation

The UIA package provides a number of software instrumentation events and APIs that you can use to provide detailed insight into the performance and operation of your code. This section of the Logging Setup configuration page allows you to configure which of these UIA software instrumentation events and APIs you would like to include with your project.

The following tutorials provide step-by-step instructions on how to use UIA to instrument your software.

Error, Warning, Info and Print Events (e.g Log_print2)

The xdc.runtime.Log module provides basic instrumentation APIs to log errors, warnings, events and generic instrumentation statements. A key advantage of these APIs is that they are designed for real-time instrumentation, with the burden of processing and decoding format strings handled by the host.

Enable the Error, Warning, Info and Print Events option in LoggingSetup to allow these events to be logged.

The following tutorials show how to log Error, Warning, Info and Print Events to instrument your application code, and how to use System Analyzer to view the logged events:
Tutorial: How to instrument your application code to log errors, warnings, and informational events
Tutorial: LogUC.h - reducing the number of cycles required to log an event

---

Benchmarking

The ti.uia.events.UIABenchmarking module provides events that can be used to measure the amount of time spent between two points in your application. You can use System Analyzer's Duration Analysis feature and Execution Analysis feature to visualize the results.

Enable the Benchmarking option in LoggingSetup to make the UIABenchmark module available for use within your application and to configure System Analyzer to display the Duration Analysis view.

The following tutorial shows how to benchmark your application code, and how to use System Analyzer to view the logged benchmark events:
Tutorial: How to benchmark your application code so that you can see how long it takes to execute code on a running system

---

Counting and Graphing

The ti.uia.events.UIAEvt module's UIAEvt_intWithKey event allows counts and values within your application code to be logged. You can use System Analyzer's Count Analysis graphs to view the values logged on a timeline, showing how the values change over time.

Enable the Counting and Graphing option in LoggingSetup to make the UIAEvt module available for use within your application and to configure System Analyzer to display the Count Analysis view.

The following tutorial shows how to instrument your application code to log counts and data values, and how to use System Analyzer to view the logged values graphically:
Tutorial: Graphing Events

---

Snapshot Events

Snapshot events allow dynamic target state information to be logged. This lets you capture the execution context of the application at a particular moment in time. The ti.uia.runtime.LogSnapshot module provides APIs to log a block of memory along with information about the memory block, to log a string that is on the heap (as opposed to a constant string reference), and to log the name of a dynamically object such as a task so that the name can be displayed in System Analyzer.

Enable the Snapshot Events option in LoggingSetup to make the LogSnapshot module available for use within your application.

The following tutorial shows how to instrument your application code to log dynamically allocated strings, and how to read the logged strings using System Analyzer:
Tutorial: How to upload the contents of dynamically allocated strings so that references to them can be displayed as text

---

Run-time Control of Event Logging

You can configure your application so that the events are 'always off' or 'always on' (which cuts down on the CPU overhead associated with logging the events in your application) or, if you wish, you can programmatically configure which types of events are logged at runtime ('runtime on' or 'runtime off') using the xdc.runtime.Diags module's setMask API.

Enable the RuntimeControl option in LoggingSetup to allow your application to use the Diags_setMask API to configure which events to log at runtime. The following tutorial shows how to control which events in your application are enabled and disabled: Tutorial: How to control which events in your application are enabled and disabled

---

Loggers

The Software Instrumentation events that your application logs are typically stored in a buffer in memory by a 'Logger' and are then transported to the host for long-term storage and analysis. This section of the Logging Setup configuration page allows you to configure which type of Logger you would like to use and how you would like to transport the events once they have been logged.

To Upload Events over JTAG, select one of the following 3 loggers:

• LoggerMin (minimal footprint logger, stop-mode JTAG)

• Select LoggerMin if your target device is memory-constrained. LoggerMin offers the lowest memory overhead of all of the loggers
• Tutorial: Configuring your application to upload event data over JTAG

• LoggerStopMode (stop-mode JTAG)

• Select LoggerStopMode if your primary concern is minimizing the CPU overhead associated with logging an event
• Tutorial: Configuring your application to upload event data over JTAG

• LoggerRunMode JTAG (run-mode JTAG on c6x and c28x only)

• Select LoggerRunMode JTAG for C6X and C28x targets, as these targets support run-mode JTAG accesses
• Tutorial: Configuring your application to upload event data over JTAG

To Upload Events over other (non-JTAG) transports, select one of the following 2 loggers:

• LoggerRunMode Ethernet upload (for use with the NDK)

• Select LoggerRunMode Ethernet in order to upload events over Ethernet (UDP, with TCP/IP as a control channel).
• Tutorial: Configuring the NDK to enable UIA to use Ethernet as a Transport

• LoggerIdle (upload in Idle loop)

• Select LoggerIdle if you wish to upload events over a serial connection (either USB or UART)
• Tutorial: Using LoggerIdle

---

Logger Buffers

Buffer Sizes

There are two key considerations when choosing the size of buffer to use with the selected logger:

• Keeping the buffer small conserves valuable target memory
• Making the buffer larger allows more events to be stored

UIA software instrumentation events generally range in size from 8 bytes to 48 bytes each. When an event is logged and there is not enough room in the Logger Buffer to store it, either the current event is dropped (if using LoggerRunMode) or one or more of the oldest events are dropped (if using any other type of logger). For run-mode transports such as USB, UART, Ethernet or run-mode JTAG, the buffer acts as a temporary holding site for events while they are waiting to be uploaded over the transport. When using stop-mode JTAG as a transport, the size of the buffer will determine how many of the most recently logged events will be available for analysis by System Analyzer.

Typically, if you are on a memory constrained target, you will want to use smaller buffer sizes in order to fit within the available memory. LoggerMin and LoggerIdle both log all events to a single buffer in order to minimize the memory footprint required to store events. The consequence of using a single buffer is that any type of event (e.g. a Load event) can bump out a 'more important' event such as an Error event. For these types of loggers, therefore, it is best to log only events that you are interested in and disable other sources of events that you are not interested in.

If you are not on a memory-constrained device, it is recommended that you use either LoggerStopMode or LoggerRunMode. Multiple instances of these loggers can be created, allowing Load events, SysBios task events and user-written software events to be stored in separate logger buffers. Make the buffer sizes large if possible - e.g. increase the User-written Log Events buffer and RTOS Execution Events buffer sizes to 32K (32768) or more, and the RTOS Load Events buffer to 4096 or more. As the buffers are allocated to L2 SRAM by default, you may need to allocate the buffers into a different section of memory, as described in the next section.

---

Memory Section

By default, the Memory Section Name is set to null, which instructs LoggingSetup to locate the logger buffers in the default region of data memory (typically either SRAM or L2SRAM). If you would prefer to locate the buffers in a different section of memory (e.g. to to free up the this memory for other uses), you can specify which type of memory to allocate the buffers in by setting LoggingSetup's Memory Section Name entry to the name of the memory section to use (case sensitive, no quotation marks) - e.g. DDR3

(The available memory section names for your device can be determined by either looking in the MEMORY CONFIGURATION section of the .map file that is generated when you build your application or from the Platform file that you are using. )

In response, LoggingSetup will create a memory section named ".uiaLoggerBuffers" in the specified memory region and allocate the Logger buffers memory from that section.

---

Multicore Event Correlation

Events that are logged by different CPUs are typically timestamped using a timer that is local to that CPU in order to avoid the overhead of going off-chip to read a shared timer. In order to correlate one CPU’s events with those logged by another CPU, it is necessary to log "sync point events" that have, as parameters, both the local CPU’s timestamp value and a "global timestamp" that was read from a global shared timer. Any CPUs that log sync point events with global timestamps read from the same global shared timer can be correlated with each other and displayed against a common timeline for analysis and comparison.

The ti.uia.runtime.LogSync module is provided in order to support this type of event correlation. It provides sync events that are used to correlate timestamp values.

Enable the Multicore Event Correlation option in LoggingSetup to make the LogSync module available for use within your application.

The following tutorial shows how to instrument your application code to log sync point events, and how to use System Analyzer to display the correlated events from multiple cores on a common timeline:
Tutorial: Working with Multicore Devices and Multicore Event Correlation

---

Links

• System Analyzer Tutorials Home Page
• System Analyzer Home Page