Adding RTA to Your SYS/BIOS Application

Overview

This article shows how to configure your SYS/BIOS (BIOS 6) target application to support the Real-Time Analysis tools in CCSv4. Specifically, this article provides detailed steps for doing this using XGCONF in CCSv4.

For help configuring your DSP/BIOS (BIOS 5) application, see this article.

For troubleshooting BIOS 6 RTA in CCSv4, see this article.

The Stairstep Example

The SYS/BIOS Stairstep example provides an example configuration of RTA, and is a good starting point for new applications with RTA support enabled.

The Stairstep example is a good demonstration of RTA capabilities. It runs indefinitely (unlike the other examples) and is designed to incrementally increase the CPU load graph every 5 seconds.

What's Required For Logging

There are two things that must happen in order to get data to the RTA tools on the host.

The first is that logging must be enabled on the target--there must be log buffers created and assigned to the correct modules to store the records, and the desired log statements must be enabled.

The second is that the application must be configured to transmit the logged records from the target to the host via RTDX. This is done using the SYS/BIOS RTA Agent. Note that if your target does not support RTDX, it is still possible to use RTA in stop-mode.

Adding RTA to an Existing Application With Grace

As of SYS/BIOS 6.32.01.38, configuration of RTA has been greatly simplified through the Grace configuration pages. From the System Overiew page, click the RTA box to be taken to the RTA Agent page.

Adding RTA to an Existing Application (Without Grace)

Note: The following information does not apply after SYS/BIOS 6.32.01.38. This and later releases include neatly organized Grace pages which simplify the configuration of SYS/BIOS and RTA.

We'll look at adding RTA to your configuration in two steps:

1. Adding the ti.sysbios.rta.Agent module to transfer records to the host, and to configure logging for SYS/BIOS modules.
2. Adding an additional LoggerBuf instance to capture user events such as Log_print and Log_info.

Adding the RTA Agent

The RTA Agent is a service running on the target at Task level which transmits the log events from the target to the host via RTDX.

This module has a secondary function which is to automatically configure logging to some reasonable defaults for all BIOS modules. This ensures that you will receive all of the log records necessary to display the CPU and thread load graphs, and the SYS/BIOS Execution graph. To see SYS/BIOS events (Task switches, Hwi start and stop, etc.), all you need to do is include the Agent in your configuration.

To add the RTA Agent to your configuration:

In the 'Available Packages' tab, type 'Agent' in the filter box, or find it under SYS/BIOS -> Diagnostics -> RTA and RTDX -> Agent.

Right click on 'Agent' and select 'Use Agent' to add it to your configuration.

From here you can control various properties of the Agent, relating to both the Agent thread on the target and to configuration of logging for BIOS modules. For example, you can configure how large to make the log buffers for SYS/BIOS records.

The default configuration of the Agent module should be enough to ensure that you get SYS/BIOS records in RTA.

If you do not want to receive any of the BIOS events (you might be more interested in your own Log_print statements, and want to conserve bandwidth), you can prevent the Agent from setting up the logging of BIOS events by setting 'configureSystemLog' to false. Note: If you've used the Defaults module (See "The Defaults Module" below) to configure logging for some modules, these defaults will apply to the BIOS modules as well, and you may get BIOS events even though you set 'configureSystemLog' to false.

Adding a LoggerBuf for User Log Statements

The Agent automatically configures logging for BIOS modules, but it is likely that you have your own Log statements that you want to see in RTA, and you'll need to configure logging for these separately.

To do this, we need to create another LoggerBuf instance to store those records and assign it to the xdc.runtime.Main module.

Every RTSC module (e.g. BIOS and IPC modules) can be assigned a separate Logger instance for capturing logs. The xdc.runtime.Main module is used for logging done by application C code.

First, we need to create another LoggerBuf instance. Find the 'LoggerBuf' module in 'Available Packages' and add it to your configuration if it is not already.

Then, in the 'Outline' view in XGCONF, right click on LoggerBuf and select "New LoggerBuf..."

In the 'Create new LoggerBuf' dialog, give the instance a reasonable name such as "MyLogger". You may also choose to increase the size of the buffer using the 'numEntries' parameter.

Now that we've created a LoggerBuf instance to use, we need to assign it to the xdc.runtime.Main module so that our Log_print statements will be sent to it.

Select the 'Main' module from the 'Outline' view, and click on the 'xdc.runtime' tab in the main XGCONF window. Under 'Diagnostics', click in the 'Value' column for the 'logger' property. You should see a drop down list showing the logger you created. Select your logger to assign it to the Main module.

Now that your Log statements have a buffer to go to, we need to enable the appropriate "diags" categories for the Main module. Just as every RTSC module can have its own logger instance, every module has its own "diags mask" which specifies which categories of diagnostics are enabled. The xdc.runtime.Main module's diags mask is used to enable or disable the Log_print statements in your application C code.

Which diags categories you need to enable depends on the format of your Log statements.

XDCtools 3.20 and later includes a "Log_info" API for easily adding Log statements to your applications. If you are using Log_info, then you just need to enable the diags_INFO category.

For example, in your C-code you might have: Log_info("Hello World!");

Then you would need to enable the diags_INFO category as below:

Note:Use RUNTIME_ON if you want to be able to enable or disable the statement dynamically at runtime. If not, you can use ALWAYS_ON which provides a small optimization in the context of application C-code and a significant optimization in the context of RTSC modules.

If you are using Log_print, then you need to enable the diags category that you chose in your Log_print call. For example, if your C-code contains the following statement:

Log_print(Diags_USER1, "Hello World!");

Then you need to enable Diags_USER1.

Advanced Logging Configuration

Enabling Logging for Non-BIOS Modules

If you want to enable logging for a module outside of SYS/BIOS, such as in IPC, you can follow similar steps as above for configuring logging for xdc.runtime.Main.

You can create a separate LoggerBuf instance for the IPC modules, or use the one you created for Main.

You will also need to enable the appropriate diags categories for these modules. These modules define specific events which they log, and the event's diags category is specified by the event definition. See the module documentation for the event definitions.

By convention, SYS/BIOS and IPC modules use the Diags_USER1 and Diags_USER2 categories for their events, where events which provide a higher level of detail use Diags_USER2.

The Defaults Module

You may find it tedious to configure and enable logging for all IPC modules, though. An easier approach is to use the xdc.runtime.Defaults module. The settings in the Defaults module will be applied to all RTSC modules except those that have been explicitly configured differently. So, if you've been following the above steps, then the Defaults module would apply to all IPC modules, but not to BIOS modules (assuming you've left 'configureSystemLog' as true) or xdc.runtime.Main (since we configured that module explicitly).

Select the 'Defaults' module from the 'Outline' view, then click the xdc.runtime tab. As you did for xdc.runtime.Main, specify a logger instance and enable the appropriate diags categories. In the below screenshot, a separate logger has been created named "IpcLogger" and assigned to Defaults. Also, diags USER1 and USER2 have been enabled to turn on logging for all IPC modules.