RTT APIs and Configurations
Table of contents
- API Functions
- SEGGER_RTT_ConfigDownBuffer()
- SEGGER_RTT_ConfigUpBuffer()
- SEGGER_RTT_GetKey()
- SEGGER_RTT_HasKey()
- SEGGER_RTT_Init()
- SEGGER_RTT_printf()
- SEGGER_RTT_Read()
- SEGGER_RTT_SetTerminal()
- SEGGER_RTT_TerminalOut()
- SEGGER_RTT_Write()
- SEGGER_RTT_WaitKey()
- SEGGER_RTT_WriteString()
- SEGGER_RTT_GetAvailWriteSpace()
- RTT Modes
- RTT Configuration
- Channel buffer configuration
- Color control sequences
- TELNET channel of J-Link software
API Functions
| API | Usage |
| SEGGER_RTT_ConfigDownBuffer() | Configure or add a down buffer by specifying its name, size and flags |
| SEGGER_RTT_ConfigUpBuffer() | Configure or add an up buffer by specifying its name, size and flags |
| SEGGER_RTT_GetKey() | Reads one character from SEGGER RTT buffer 0. Host has previously stored data there |
| SEGGER_RTT_HasKey() | hecks if at least one character for reading is available in SEGGER RTT buffer |
| SEGGER_RTT_Init() | Initializes the RTT Control Block |
| SEGGER_RTT_printf() | Send a formatted string to the host |
| SEGGER_RTT_Read() | Read characters from any RTT down channel which have been previously stored by the host |
| SEGGER_RTT_SetTerminal() | Set the "virtual" terminal to send following data on channel 0 |
| SEGGER_RTT_TerminalOut() | Send one string to a specific "virtual" terminal |
| SEGGER_RTT_WaitKey() | Waits until at least one character is available in SEGGER RTT buffer 0. Once a character is available, it is read and returned |
| SEGGER_RTT_Write() | Send data to the host on an RTT channel |
| SEGGER_RTT_WriteString() | Write a 0-terminated string to an up channel via RTT |
| SEGGER_RTT_GetAvailWriteSpace() | Returns the number of bytes available in the ring buffer |
SEGGER_RTT_ConfigDownBuffer()
Configure or add a down buffer by specifying its name, size and flags.
Syntax
int SEGGER_RTT_ConfigDownBuffer (unsigned BufferIndex, const char* sName, char* pBuffer, int BufferSize, int Flags);
| Parameter | Meaning |
| BufferIndex | Index of the buffer to configure. Must be lower than SEGGER_RTT_MAX_NUM_DOWN_CHANNELS. |
| sName | Pointer to a 0-terminated string to be displayed as the name of the channel. |
| pBuffer | Pointer to a buffer used by the channel. |
| BufferSize | Size of the buffer in Bytes. |
| Flags | Flags of the channel (blocking or non-blocking). Flags[1:0]: RTT operating mode. Flags[23:2]: Reserved for future use. Flags[31:24]: Used for validity check, must be zero. |
| Return Value | Meaning |
| >= 0 | OK |
| < 0 | Error |
Example
// Configure down buffer 1
SEGGER_RTT_ConfigDownBuffer(1, "DataIn", &abDataIn[0], sizeof(abDataIn),
SEGGER_RTT_MODE_NO_BLOCK_SKIP);
Once a buffer is configured only the flags of the buffer should be changed.
SEGGER_RTT_ConfigUpBuffer()
Configure or add an up buffer by specifying its name, size and flags.
Syntax
int SEGGER_RTT_ConfigUpBuffer (unsigned BufferIndex, const char* sName, char* pBuffer, int BufferSize, int Flags);
| Parameter | Meaning |
| BufferIndex | Index of the buffer to configure. Must be lower than SEGGER_RTT_MAX_NUM_UP_CHANNELS. |
| sName | Pointer to a 0-terminated string to be displayed as the name of the channel. |
| pBuffer | Pointer to a buffer used by the channel. |
| BufferSize | Size of the buffer in Bytes. |
| Flags | Flags of the channel (blocking or non-blocking). Flags[1:0]: RTT operating mode. Flags[23:2]: Reserved for future use. Flags[31:24]: Used for validity check, must be zero. |
| Return Value | Meaning |
| >= 0 | OK |
| < 0 | Error |
Example
// Configure up buffer 1 to work in blocking mode
SEGGER_RTT_ConfigUpBuffer(1, "DataOut", &abDataOut[0], sizeof(abDataOut),
SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL);
Once a buffer is configured only the flags of the buffer should be changed.
SEGGER_RTT_GetKey()
Reads one character from SEGGER RTT buffer 0. Host has previously stored data there.
Syntax
int SEGGER_RTT_GetKey (void);
| Return Value | Meaning |
| >= 0 | Character which has been read (0 - 255) |
| < 0 | No character available (empty buffer) |
Example
int c;
c = SEGGER_RTT_GetKey();
if (c == 'q') {
exit();
}
SEGGER_RTT_HasKey()
Checks if at least one character for reading is available in SEGGER RTT buffer.
Syntax
int SEGGER_RTT_HasKey (void);
| Return Value | Meaning |
| 1 | At least one character is available in the buffer |
| 0 | No characters are available to be read |
Example
if (SEGGER_RTT_HasKey()) {
int c = SEGGER_RTT_GetKey();
}
SEGGER_RTT_Init()
Initializes the RTT Control Block.
Syntax
void SEGGER_RTT_Init (void);
Should be used in RAM targets, at start of the application.
SEGGER_RTT_printf()
Send a formatted string to the host.
Syntax
int SEGGER_RTT_printf (unsigned BufferIndex, const char * sFormat, ...)
| Parameter | Meaning |
| BufferIndex | Index of the up channel to sent the string to |
| sFormat | Pointer to format string, followed by arguments for conversion |
| Return Value | Meaning |
| >= 0 | Number of bytes which have been sent. |
| < 0 | Error |
Example
SEGGER_RTT_printf(0, "SEGGER RTT Sample. Uptime: %.10dms.", /*OS_Time*/ 890912);
// Formatted output on channel 0: SEGGER RTT Sample. Uptime: 890912ms.
Additional Information
Conversion specifications have following syntax:
%[flags][FieldWidth][.Precision]ConversionSpecifier%Supported flags:
| Flag | Meaning | |:---|:---| | - | Left justify within the field width | | + | Always print sign extension for signed conversions | | 0 | Pad with 0 instead of spaces. Ignored when using '-'-flag or precision |
Supported conversion specifiers:
| Conversion specifier | Meaning | |:---|:---| | c | Print the argument as one char | | d | Print the argument as a signed integer | | u | Print the argument as an unsigned integer | | x | Print the argument as an hexadecimal integer | | s | Print the string pointed to by the argument | | p | Print the argument as an 8-digit hexadecimal integer. (Argument shall be a pointer to void) |
SEGGER_RTT_Read()
Read characters from any RTT down channel which have been previously stored by the host.
Syntax
unsigned SEGGER_RTT_Read (unsigned BufferIndex, char* pBuffer, unsigned BufferSize);
| Parameter | Meaning |
| BufferIndex | Index of the down channel to read from |
| pBuffer | Pointer to a character buffer to store the read characters |
| BufferSize | Number of bytes available in the buffer |
| Return Value | Meaning |
| >= 0 | Number of bytes that have been read. |
char acIn[4];
unsigned NumBytes = sizeof(acIn);
NumBytes = SEGGER_RTT_Read(0, &acIn[0], NumBytes);
if (NumBytes) {
AnalyzeInput(acIn);
}
SEGGER_RTT_SetTerminal()
Set the "virtual" terminal to send following data on channel 0.
Syntax
void SEGGER_RTT_SetTerminal(char TerminalId);
| Parameter | Meaning |
| TerminalId | Id of the virtual terminal (0-9) |
Example
// Send a string to terminal 1 which is used as error out.
SEGGER_RTT_SetTerminal(1); // Select terminal 1
SEGGER_RTT_WriteString(0, "ERROR: Buffer overflow");
SEGGER_RTT_SetTerminal(0); // Reset to standard terminal
All following data which is sent via channel 0 will be printed on the set terminal until the next change
SEGGER_RTT_TerminalOut()
Send one string to a specific "virtual" terminal.
Syntax
int SEGGER_RTT_TerminalOut (char TerminalID, const char* s);
| Parameter | Meaning |
| TerminalId | Id of the virtual terminal (0-9) |
| s | Pointer to 0-terminated string to be sent |
| Return Value | Meaning |
| >= 0 | Number of bytes sent to the terminal |
| < 0 | Error |
Example
// Sent a string to terminal 1 without changing the standard terminal.
SEGGER_RTT_TerminalOut(1, "ERROR: Buffer overflow.");
SEGGER_RTT_TerminalOut does not affect following data which is sent via channel 0.
SEGGER_RTT_Write()
Send data to the host on an RTT channel.
Syntax
unsigned SEGGER_RTT_Write (unsigned BufferIndex, const char* pBuffer, unsigned NumBytes);
| Parameter | Meaning |
| BufferIndex | Index of the up channel to send data to |
| pBuffer | Pointer to data to be sent |
| NumBytes | Number of bytes to send |
| Return Value | Meaning |
| >= 0 | Number of bytes which have been sent |
| < 0 | Error |
With SEGGER_RTT_Write() all kinds of data, not only printable ones can be sent.
SEGGER_RTT_WaitKey()
Waits until at least one character is available in SEGGER RTT buffer 0. Once a character is available, it is read and returned.
Syntax
int SEGGER_RTT_WaitKey (void);
| Return Value | Meaning |
| >= 0 | Character which has been read (0 - 255) |
Example
int c = 0;
do {
c = SEGGER_RTT_WaitKey();
} while (c != 'c');
SEGGER_RTT_WriteString()
Write a 0-terminated string to an up channel via RTT.
Syntax
unsigned SEGGER_RTT_WriteSting (unsigned BufferIndex, const char* s);
| Parameter | Meaning |
| BufferIndex | Index of the up channel to send string to |
| s | Pointer to 0-terminated string to be sent |
| Return Value | Meaning |
| >= 0 | Number of bytes which have been sent |
Example
SEGGER_RTT_WriteString(0, "Hello World from your target.\n");
SEGGER_RTT_GetAvailWriteSpace()
Returns the number of bytes available in the ring buffer.
Syntax
unsigned SEGGER_RTT_GetAvailWriteSpace (unsigned BufferIndex);
| Parameter | Meaning |
| BufferIndex | Index of the up channel that should be checked for space |
| Return Value | Meaning |
| >= 0 | Number of bytes that are free in the selected up buffer |
Example
unsigned NumBytesFree;
NumBytesFree = SEGGER_RTT_GetAvailWriteSpace(0);
RTT Modes
| Mode | Explanation |
| Background mode | It is the fastest mode with a transfer speed of up to ~2MB/s |
| Legacy background mode | Legacy version of Background mode, which does not come with handling on probe firmware side, leading to lower transfer speeds |
| Stop mode | Pseudo RTT mode. CPU is halted to read data. Introduced for CPUs that do not support Background-Access |
RTT Configuration
| Define / Routine | Meaning |
| SEGGER_RTT_MAX_NUM_DOWN_BUFFERS | Maximum number of down (to target) channels |
| SEGGER_RTT_MAX_NUM_UP_BUFFERS | Maximum number of up (to host) channels |
| BUFFER_SIZE_DOWN | Size of the buffer for default down channel 0 |
| BUFFER_SIZE_UP | Size of the buffer for default up channel 0 |
| SEGGER_RTT_PRINT_BUFFER_SIZE | Size of the buffer for SEGGER_RTT_printf to bulk-send chars |
| SEGGER_RTT_LOCK() | Locking routine to prevent interrupts and task switches from within an RTT operation |
| SEGGER_RTT_UNLOCK() | Unlocking routine to allow interrupts and task switches after an RTT operation |
| SEGGER_RTT_IN_RAM | Indicate the whole application is in RAM to prevent falsely identifying the RTT Control Block in the init segment by defining as 1 |
Channel buffer configuration
| Define | Meaning |
| SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL | A call to a writing function will block, if the up buffer is full |
| SEGGER_RTT_MODE_NO_BLOCK_SKIP | If the up buffer has not enough space to hold all of the incoming data, nothing is written to the buffer |
| SEGGER_RTT_MODE_NO_BLOCK_TRIM | If the up buffer has not enough space to hold all of the incoming data, the available space is filled up with the incoming data while discarding any excess data |
SEGGER_RTT_TerminalOut()ensures that implicit terminal switching commands are always sent out, even while using the non-blocking modes.- The buffer configuration only effects the target device buffers, not the host buffers.
Color control sequences
| Configuration | Meaning |
| RTT_CTRL_RESET | Reset the text color and background color |
| RTT_CTRLTEXT* | Set the text color to one of the following colors BLACK RED GREEN YELLOW BLUE MAGENTA CYAN WHITE BRIGHT_BLACK BRIGHT_RED BRIGHT_GREEN BRIGHT_YELLOW BRIGHT_BLUE BRIGHT_MAGENTA BRIGHT_CYAN BRIGHT_WHITE |
| RTT_CTRLBG* | Set the background color to one of the following colorss BLACK RED GREEN YELLOW BLUE MAGENTA CYAN WHITE BRIGHT_BLACK BRIGHT_RED BRIGHT_GREEN BRIGHT_YELLOW BRIGHT_BLUE BRIGHT_MAGENTA BRIGHT_CYAN BRIGHT_WHITE |