Segger - Real Time Terminal

Real Time Terminal

SEGGER's Real Time Terminal (RTT) is the new technology for interactive user I/O in embedded applications.
With RTT it is possible to output information from the target microcontroller as well as sending input to the application at a very high speed without affecting the target's real time behaviour.

RTT supports multiple up (to the host) and down (to the target) channels to write and read data of different kinds. The default implementation uses one channel per direction:

ChannelTypical PurposeUp-channel 0Terminal outputDown-Channel 0Keyboard input

SEGGER RTT can be used with any J-Link model and any supported target processor which allows background memory access, which are Cortex-M and RX targets.

Data from Up-channel 0 can be read via a Telnet connection to localhost:19021, which is opened by the J-Link software locally on the computer, when the J-Link is active. The Telnet connection also receives keyboard input for Down-channel 0.

 

The J-Link RTT Client, which automatically connects and re-connects to an open J-Link connection is part of the J-Link Software and Documentation Pack and can be used instead of a simple Telnet client.

 

With J-Link RTT Logger, data from Up-Channel 1 can be read and logged to a file. This channel can for example be used to send performance analysis data to the host.

J-Link RTT Logger opens a dedicated connection to J-Link and can be used stand-alone, without running a debugger.

The application is part of the J-Link Software and Documentation Pack.

The source of J-Link RTT Logger can be used as a starting point to integrate RTT in other PC applications, like debuggers and is part of the J-Link SDK.

 

 Download RTT Implementation and Sample Code

How it works

Real Time Terminal uses a SEGGER RTT Control Block structure in the target's memory to manage data reads and writes.

The control block contains a ring buffer structure per channel describing their state in the target system’s memory and pointing to some buffer space in memory. Up and down channels can be configured separately.

When RTT is active on the host, either by connecting via Telnet or RTT Client, or by using a debugger with integrated RTT support, J-Link automatically looks for the SEGGER RTT Control Block in the target's known RAM regions. Debuggers and other applications using RTT can also specify the address of the control block to speed up detection or if the block cannot be found automatically.

The data to be written to the host is stored in the buffer in the target's memory. The data structures are periodically monitored by the J-Link probe and the buffer content is read only when necessary.

Data from the host is written by the J-Link to the In-buffer in the target's memory and can be read from there by the embedded application.

RTT does not need any additional pin or hardware, despite the J-Link connected via the standard debug port to the target. It does not require any configuration of the target or in the debugging environment and can even be used with varying target speeds.

SEGGER RTT can be used in parallel to a running debug session, without intrusion, as well as without any IDE or debugger at all. 
A simple Telnet Client can be attached to any instance of J-Link.

Internal structures

The image shows the simplified structure in the target.

There may be any numer of "Up Buffer Descriptors" (Target -> Host), as well as any number of "Down Buffer Descriptors" (Host -> Target). Each buffer size can be configured individually.
The gray areas in the buffers are the areas that contain valid data.
For Up buffers, the Write Pointer is written by the target, the Read Pointer is written by the debug probe (J-Link, Host).
When Read and Write Pointers point to the same element, the buffer is empty. This assures there is never a race condition.

 

 Performance

The performance of SEGGER RTT is significantly higher than any other technology used to output data to a host PC. An average line of text can be output in one microsecond or less. Basically only the time to do a single memcopy(),

The speed comparison was done on an STM32F407 Cortex-M4 running at 168 MHz . Overhead for printf() calls removed.

Implementation

The SEGGER RTT implementation is written in ANSI C and can be integrated into any embedded application using the code, available for download below.
RTT can be used via a simple and easy to use API. It is even possible to override the standard printf() functions to use RTT. Using RTT reduces the time taken for printf() to a minimum and allows printing debug information to the host PC, while the application is performing time critical, real time tasks.

The SEGGER RTT implementation includes a simple implementation of printf() which can be used to write a formatted string via RTT. SEGGER_RTT_Printf() is smaller than most standard library printf implementations and does not require heap and only a configureable ammount of stack.

The SEGGER RTT implementation is fully configurable with pre-processor defines. Reading and writing can be made task-safe with Lock() and Unlock() routines, the number of buffers, as well as the size of the terminal buffers can be set up easily.

API Functions

Function NameDescriptionSEGGER_RTT_Read()Read data from an input buffer.SEGGER_RTT_Write()Write data to an output buffer.SEGGER_RTT_WriteString()Write a zero-terminated string to an output buffer.SEGGER_RTT_printf()Write a formatted string to an output buffer.SEGGER_RTT_GetKey()Get one character from input buffer 0.SEGGER_RTT_HasKey()Check if a character is available in input buffer 0.SEGGER_RTT_WaitKey()Wait for a character to be available in input buffer 0 and get it.SEGGER_RTT_ConfigUpBuffer()Configure an up (output) buffer.SEGGER_RTT_ConfigDownBuffer()Configure a down (input) buffer.SEGGER_RTT_Init()Initialize RTT Control Block structure when using RAM only targets.

Memory Footprint

MemoryUsageROM Usage~500 BytesRAM Usage24 Bytes fixed + (24 + SizeofBuffer) Bytes / channel

 

 Download RTT Implementation and Sample Code

Example Code

RTT is kept as simple as possible and can be used without any configuration.

/**********************************************************************               SEGGER MICROCONTROLLER GmbH & Co KG                  **       Solutions for real time microcontroller applications         ************************************************************************                                                                    **       (c) 2014  SEGGER Microcontroller GmbH & Co KG                **                                                                    **       www.segger.com     Support: [e-mail]               **                                                                    ***********************************************************************----------------------------------------------------------------------File    : RTT.cPurpose : Simple implementation for output via RTT.          It can be used with any IDE.           --------  END-OF-HEADER  ---------------------------------------------*/#include "SEGGER_RTT.h"static void _Delay(int period) {  int i = 100000*period;  do { ; } while (i--);}int main(void) {  do {    SEGGER_RTT_WriteString(0, "Hello World from SEGGER!\r\n");    _Delay(100);  } while (1);  return 0;}/*************************** End of file ****************************/

printf() with RTT

The low-level functions used in libraries for printf() can often be easily overridden, to provide own output functions.

The SEGGER RTT implementation pack includes the required code for GCC/Newlib, IAR and KEIL MDK which can simply be included in the project to retarget printf() to output the data via RTT.

Additinally the SEGGER RTT implementation pack includes a simplified version of printf(), SEGGER_RTT_printf(), which can be used to print formatted strings via RTT, directly, without a standard library.

Supported Targets

RTT can be used with any target, which is supported by J-Link and allows background memory access while the target is running.

CoreRTTCortex-M0Cortex-M0+Cortex-M1Cortex-M3Cortex-M4Cortex-M7RX100RX200RX600

RTT in PC Applications

Instead of running an external Telnet client, RTT can also be directly integrated in any PC application, like a debugger, in either of two ways.

The application can either establish a socket connection to the RTT Telnet Server (listening on localhost:19021) 
or use the J-Link RTT API which is part of the J-Link SDK, to directly configure RTT and get / send data.

Using ANSI control sequences to change display of data

All data read via RTT is flushed like read from the target without any modification.

This allows processing of ANSI control sequences by the application which prints the RTT data to display data in bold or change its color. Processing of ANSI control sequences in terminal applications is natively supported in the Linux console. On Windows a wrapper application like ANSICON (http://adoxa.altervista.org/ansicon) is needed and can be used to call the RTT Client.Some Telnet applications like PuTTY support ANSI control sequences on windows, too.

FAQ

Q:
How does J-Link find the RTT buffer?A:There are 2 ways: If the Debugger (IDE) knows the address of the SEGGER_RTT structure, it passes it to J-Link. This is for example done by J-Link Debugger. If an other debugger that is not SEGGER-RTT aware is used, such as IAR's Embedded Workbench or emIDE, then J-Link searches for the ID in the known target RAM during execution of the program, transparently in the background. The process of locating the ID string takes just fractions of a second and does not delay program execution.  Q:I am debugging a RAM-only application. J-Link finds an RTT buffer, but I get no output. What can I do?

A:

 In case the init section af an application is stored in RAM, J-Link mit falsely identify the block in the init section instead of the actual one in the data section.

To prevent this, set the define SEGGER_RTT_IN_RAM to 1. Now J-Link will find the correct RTT buffer, but only after calling the first SEGGER_RTT function in the application. A call to SEGGER_RTT_Init() at the beginning of the application is recommended.

  Q:Can this also be used on targets that do not have the SWO pin?A:Yes, the debug interface is used. This can be JTAG or SWD (2pins only!) on most Cortex-M devices, or even the FINE interface on some Renesas devices, just like the Infineon SPD interface (single pin!)  Q:
Can this also be used on Cortex-M0 and M0+?A:Yes.  Q:
Some terminal output (printf) Solutions "crash" program execution when executed outside of the debug environment, because they use a Software breakpoint that triggers a hardfault without debugger or halt because SWO is not initialized. That makes it impossible to run a Debug-build in stand-alone mode.
What about SEGGER-RTT?A:SEGGER-RTT uses non-blocking mode per default, which means it does not halt program execution if no debugger is present and J-Link is not even connected. The application program will continue to work.  Q:I do not see any output, although the use of RTT in my application is correct. What can I do?

A:

In some cases J-Link cannot locate the RTT buffer in the known RAM region.

In this case the possible region or the exact address can be set manually via a J-Link exec command:

• Set ranges to be searched for RTT buffer: SetRTTSearchRanges <RangeStart [Hex]> <RangeSize >[, <Range1Start [Hex]> <Range1Size>, ...] (Available in V4.92 or higher)
• Set address of the RTT buffer: SetRTTAddr <RTTBufferAddress [Hex]>
• Set address of the RTT buffer via J-Link Control Panel -> RTTerminal

J-Link exec commands can be executed in most applications, for example in J-Link Commander via "exec <Command>", in J-Link GDB Server via "monitor exec <Command>" or in IAR EW via "__jlinkExecCommand("<Command>");" from a macro file.