Run-Time Logging Panel¶

Overview¶

The Run-Time Logging panel is used to evaluate and optimize performance of Sensor Controller tasks running at full speed on a physical CC26xx/CC13xx device. During run-time logging the Sensor Controller runs autonomously, while the System CPU transfers data structure information to and from Sensor Controller Studio. The logged data structures can be displayed graphically in Sensor Controller Studio, or the data can be saved to file for external analysis.

Shortcut : Ctrl + L

The main differences between run-time logging and task testing are summarized in the table below:

	Run-Time Logging	Task Testing
Purpose	Performance evaluation and optimization	Evaluation, systematic testing and debugging
Execution speed	Timing matches actual application	All code within a task code block runs at full speed. Timing between task code blocks cannot be controlled precisely, and depends on communication with PC.
Preparations	Enable the Run-Time Logging resource and use the associated procedures in task code to control logging	Specify a sequence of actions for each task iteration in the Task Testing Panel
Communication interface(s)	UART + JTAG, UART only, or TCP/IP	JTAG
Task count supported	One or more tasks within one project	One task at a time
Data structure logging	Selected data structures are logged. Overflow can occur, data discarded silently.	All data structures are logged. No overflow.
Data structure editing	Data structures that are not logged can be modified at any time	All data structure values can be modified, but only while the target is stopped. New data structure member values can be loaded from file and be applied between task iterations.

Preparations and Setup¶

The task data structures ( cfg , input , output and state ) can either be logged or editable:

Logged data structures can be reported to Sensor Controller Studio for graphical display. In a typical use-case, the output data structure will be logged.
Editable data structures can be modified in Sensor Controller Studio while the Sensor Controller is running. In a typical use-case, the cfg and input data structures will be editable.

Run-time logging is not enabled by default because it adds both code and data to the generated AUX RAM image, and also because the Sensor Controller itself must be able to control when and which data structures shall be reported to Sensor Controller Studio.

To enable run-time logging for a task, go to the Task Panel and enable the Run-Time Logging resource under Development Tools . Then use the associated procedures to trigger data structure logging in task code (see the Run-Time Logging resource for details and examples):

rtlLogStructs(bvStructs) - Requests that the specified data structures shall be sent to the Run-Time Logging panel.
rtlGetLogMask(bvStructs) - Returns which data structures are selected as logged in the Run-Time Logging panel for the current task.
rtlCheckLogDone(done) - Checks whether the last rtlLogStructs() call has taken effect.
rtlWaitLogDoneUs(timeout) - Waits until the last rtlLogStructs() call has taken effect (the requested data structures have been copied from AUX RAM) or the specified timeout expires.
rtlLogCancel() - Cancels the last rtlLogStructs() call if it has not yet taken effect.

Log requests are independent of ALERT interrupts.

Normally there will be one vector (meaning one point along the graph X-axis) for each log request. When using Multi-Buffered Output Data Exchange there will be one vector for each output buffer. In that case the cfg and input data structures will be reported together with the first output buffer, and the state data structure will be reported together with the last output buffer.

Connection Types and Connection Settings¶

There are three different ways to connect to the target:

Local without application, using JTAG and UART¶

Sensor Controller Studio downloads a generic System CPU application and all parameters and data into the system RAM through an XDS100v3 or XDS110 JTAG debug probe.

Sensor Controller Studio then communicates with the target over UART, at the specified baud rate through the specified RX and TX pins.

During the run-time logging session the JTAG interface is used to update resource related register settings such as RTC tick interval for the RTC-Based Execution Scheduling resource.

This is the default connection type, and also the recommended connection type for most uses of run-time logging.

Connection settings:

COM port filter - Select which COM ports to display (relevant TI XDS COM ports only, or all COM ports)
COM port - Select the COM port to be used for UART communication
- For XDS110, select the Application/User COM port
- The selection defaults to the last used COM port, if available
Baud rate - Select the baud rate to be used for UART communication
- For the “local without application” connection type, this setting is simply a tradeoff between data bandwidth and robustness
UART RX pin - Specify the DIO that the target CC13xx/CC26xx device shall use as UART RX pin
- If a board has been selected in the I/O Mapping Panel , this setting will automatically default to the UART RX” pin for that board
- This setting is stored in the project file
UART TX pin - Specify the DIO that the target CC13xx/CC26xx device shall use as UART TX pin
- If a board has been selected in the I/O Mapping Panel , this setting will automatically default to the “UART TX” pin for that board
- This setting is stored in the project file

Local with application, using NPI (Network Processor Interface) over UART¶

A custom run-time logging application must be programmed manually into flash memory before the run-time logging session begins. The application must contain an up-to-date SCIF driver, and must implement the NPI protocol. See the Run-Time Logging NPI Protocol document for details.

Sensor Controller Studio communicates with the target over UART at the specified baud rate.

Note that while this connection type in theory allows for a full application to run in parallel on the target, the data handling for run-time logging can break the application timing, or the application can cause data loss for run-time logging. Note also that run-time logging uses a significant amount of RAM.

Connection settings:

COM port filter - Select which COM ports to display (relevant TI XDS COM ports only, or all COM ports)
COM port - Select the COM port to be used for UART communication
- For XDS110, select the Application/User COM port
- The selection defaults to the last used COM port, if available
Baud rate - Select the baud rate to be used for UART communication
- For the “local with application” connection type, this setting must match the manually programmed firmware

Remote with application, using NPI (Network Processor Interface) over TCP/IP¶

A custom run-time logging application must be programmed manually into flash memory before the run-time logging session begins. The application must contain an up-to-date SCIF driver, and must implement the NPI protocol. See the Run-Time Logging NPI Protocol document for details.

Sensor Controller Studio communicates with an NPI server over TCP/IP, which in turn communicates with the target using UART or another suitable interface.

Note that while this connection type in theory allows for a full application to run in parallel on the target, the data handling for run-time logging can break the application timing, or the application can cause data loss for run-time logging. Note also that data buffers for run-time logging use a significant amount of RAM.

Connection settings:

IP address - Specify the IP address of the NPI server (127.0.0.1 for local host)
Port number - Specify the TCP port number used by the NPI server

Target Interaction Commands¶

The Run-Time Logging panel can be in one of the states listed below. Each state enables a subsets of the run-time logging commands, which can be triggered from the Run-Time Logging menu, the panel toolbar or keyboard shortcuts:

Disconnected with unsuccessful code generation
- All commands disabled
Disconnected with successful code generation
- Connect - F12 : Connect to the target (a target selection window appears if JTAG debug probe firmware update is needed or multiple targets are available)
Connected, stopped
- Disconnect - F12 : Disconnect from the target
- Restart Run-Time Logging - F7 : Restart run-time logging (equivalent to Clear Data Vectors + Start Run-Time Logging )
- Start Run-Time Logging - F5 : Starts the tasks enabled for run-time logging
Connected, running/paused
- Disconnect - F12 : Disconnect from the target
- Restart Run-Time Logging - F7 : Restart run-time logging (equivalent to Stop Run-Time Logging + Clear Data Vectors + Start Run-Time Logging )
- Pause Run-Time Logging - F8 : Pause/unpause run-time logging (target discards all data logged while paused)
- Stop Run-Time Logging - F6 : Stop the tasks enabled for run-time logging
Error state
- Disconnect - F12 : Disconnect from the target

Graph¶

The Graph tab in the Run-Time Logging panel displays data structure member values for each rtlLogStructs() procedure call as line graphs.

Data Structure Member Selection and Editing¶

Select logged data structure members for graphical display by checking and unchecking these in the list to the right. The selection can be changed at any point without losing data.

For logged data structures, the data structure list normally displays the last logged values. Logged data structure members cannot be edited.

For editable data structures, the data structure list displays the last values written to the target. These values can be modified at any time during a run-time logging session:

To start editing: Select the data structure member to be edited and press Enter , or double-click on the data structure member value.
To finish editing: Press Enter .
To cancel editing: Press Esc or select a different data structure member.

If the Sensor Controller modifies an editable data structure member, this will not reflected in the data structure list.

The data structure list can also display the data structure member values at a particular point in the graph. Click and hold the left mouse button in the graph area to view the values at that point. This temporarily disables auto-scrolling.

Zooming and Scrolling¶

Use the mouse scroll wheel to zoom and scroll in the graph:

While pressing no keys: Scroll vertically
While pressing Ctrl : Zoom vertically
While pressing Shift : Scroll horizontally
While pressing Ctrl + Shift : Zoom horizontally

When auto-scrolling is enabled (on by default), the graph area scrolls to the right automatically when new vectors are added to the graph. Use the Auto-Scroll command to toggle this behavior.

When auto-scaling is enabled (off by default), the Y-axes will scale to the currently visible values. Otherwise, the Y-axes will cover all observed values along the entire X-axis. Use the Auto-Scale command to toggle this behavior.

Graph Customization¶

The Customize Graphs… command allows for different data structure members to be displayed together in one graph section.

Each data structure member that can be selected in the Run-Time Logging panel’s data structure list can be used as a parent graph .

For each parent graph it is possible to add one or more child graphs , that is any data structure member within the same task. For each child graph it is possible to specify:

A label to be displayed in the data structure list. If no label is specified, the child graph name is used.
Scaling factor and offset, which allows the value range of the child graph to be matched to the value range of the parent graph. Values of the selected data structure member are first multiplied by the scaling factor, and then the offset is added.

A child graph is displayed when the associated parent graph data structure member is selected in the data structure list.

Child graph parameters are stored in the project file, and child graphs are shared between task testing and run-time logging. A child graph is removed automatically if data structures are changed so that the selected parent graph and/or child graph no longer exist.

Configuration Sliders¶

To ease parameter tuning it is possible to add configuration sliders in the area below the data structure list. Each slider can control one single- or array-type cfg data structure member.

Press the Add… button in the upper right corner of the configuration slider area to create a new slider control. For existing configuration sliders, press the Edit button to make changes to the slider, or press the Remove button to remove the slider.

For each slider, specify the following in the Configuration Slider window:

Name - Enter a label to be displayed above the configuration slider
Task - Select task
Data structure member - Select the cfg data structure member to be controlled
Slider minimum value - The slider value in the left-most position
Slider maximum value - The slider value in the right-most position
ECMAScript - Write a function body that allows the slider to control the selected data structure member. Use the following pre-declared variables:
- Variable slider is the current value of the slider
- Variable size is the size of an array data structure member, or 0 for a non-array data structure member
- For a non-array data structure member: Write the new value of the selected data structure member to variable value
- For an array data structure member: Write the new values of the selected data structure member to variables value[i] , where i is between 0 and size -1

Configuration slider parameters and the last slider value are stored in the project file. A configuration slider is removed automatically if the controlled data structure member is removed from the task.

ECMAScript Examples¶

For a slider value X , the following script writes 2 * X to the controlled non-array data structure member:

value = slider * 2;

For a slider value X , the following script writes 1 << X to the X ‘th entry of the controlled array data structure member, and 0 to all other array entries:

for (n = 0; n < size; n++) {
    if (slider == n) {
        value[n] = 1 << n;
    } else {
        value[n] = 0;
    }
}

Data Handling Commands¶

The following commands can be used to save data vectors (all logged data structure members):

Save Data Vectors : Save logged data vectors to CSV file (one line per log request in the Sensor Controller task code)
Clear Data Vectors : Clear logged data vectors

Output CSV File Format¶

The CSV files are formatted as follows:

The first row specifies the member name for each column (for example “cfg.hysteresis” or “cfg.pBinThresholds.[2]”), with the task name as prefix if multiple tasks are enabled for run-time logging (for example “Analog Light Sensor.cfg.hysteresis” or “Analog Light Sensor.cfg.pBinThresholds.[2]”)
There is one data row for each Sensor Controller log request
Data structures values that have not yet been logged by the Sensor Controller are represented by empty cells

The CSV column separation character is “;” by default. The character can be changed in the Preferences Panel .

Limitations¶

Note the following limitations:

The Sensor Controller task code should not run continuously in a loop. If that is the case:
- Once the task is running, it cannot be stopped or restarted. Using the Stop and Restart commands will cause an error.
- Once the task is running, any attempt to edit data structure member or using a configuration slider will cause an error.
When UART is used to communicate with the target, the UART must be operational at all times. This means that the MCU domain must never enter standby mode.
Log data transfer can be overloaded in the System CPU application, in the USB serial port or in the reception on the PC. Data loss due to overflow, data corruption or synchronization loss is not indicated.
While the NPI protocol supports payloads up to 64 KB, Sensor Controller Studio does not accept payload sizes above 4096 bytes. This prevents long breaks during synchronization loss, and reduces risk of false frame detection during synchronization loss.