AN008: Printf with Segger RTT

Back in the old days when debugging was precarious we like to use printf a lot, but a lot. Semihosting was the defacto solution but it was slow, very slow. Then came the RTT, a faster and more reliable solution. The RTT is a feature of the J-Link debugger that allows you to send data from the target to the host in real-time. This is very useful when you need to debug a system that is time-sensitive.

Ok, as you may wonder RTT is a feature that only works when you have a segger jlink debugger, lucky for us some Nucleo boards has their possibility to change the ST-Link firmware to a J-Link firmware. This is the case of the Nucleo-G0RB1 board, which is the one we use in one of our trainings.

Download the application SEGGER STLinkReflash utility from this page ( also install the J-Link software package and windows drivers ) ST-Link On board and follow the instruction to reflash the board. This needs to be carried out in Windows

Installing the new debug tools in Linux

In Arch Linux we can use our favorite AUR helper to install the J-Link software package, in this case we will use paru. (you can also download form the segger website and install for a different linux distro ). Hey maybe you want to try to make a container with the segger tools and avoid any kind of installation Part 8: GUI application in docker

$ paru -S jlink-software-and-documentation jlink-systemview

Locate the RTT source files under the J-Link installation directory, in my case it is located at /opt/SEGGER/JLink_V794/RTT/RTT_Sample or C:\Program Files\SEGGER\JLink_V794\Samples\RTT copy the files into your project following the next directory structure:

rtt
├── Inc
│   ├── SEGGER_RTT_Conf.h
│   └── SEGGER_RTT.h
└── Src
    ├── SEGGER_RTT_ASM_ARMv7M.S
    ├── SEGGER_RTT.c
    ├── SEGGER_RTT_printf.c
    └── SEGGER_RTT_Syscalls_GCC.c

We assume you are using our template with a makefile, so we will add the following lines to the makefile to include RTT source file to our build process:

# directories with source files to compiler (.c y .s)
SRC_PATHS  = app
SRC_PATHS += cmsisg0/startups
SRC_PATHS += halg0/Src
SRC_PATHS += rtt/Source
SRC_PATHS += rtt/Syscalls # just in case you decide to use redirection
# directories with header files
INC_PATHS  = app
INC_PATHS += cmsisg0/core
INC_PATHS += cmsisg0/registers
INC_PATHS += halg0/Inc
INC_PATHS += rtt/Source

Add the following files to be compile as part of the project, (if you are using a Cortex-M3, M4 or M7 you also need to add SEGGER_RTT_ASM_ARMv7M.S file )

SRCS += SEGGER_RTT.c SEGGER_RTT_printf.c

Also comment the following line in the makefile and uncomment the one below to call the JLink GDB server instead of the OpenOCD server ( replace stm32g0b1re for your particular part number )

#---open a debug server conection------------------------------------------------------------------
open :
#	openocd -f board/st_nucleo_g0.cfg
	JLinkGDBServerCL -if SWD -device stm32g0b1re -port 3333

And in the .gdbinit replace the lines for OpenOCD with the following ones

#---connect and load program
target remote localhost:3333
#mon arm semihosting enable
load
#mon reset halt
mon reset
break main
continue

Testing the printf functions

Now we are ready to do some write and read some messages from the RTT, the following code is a simple example of how to use the RTT to send and receive messages from the target to the host. Write and build the code using make.

#include "bsp.h"
#include "SEGGER_RTT.h"

int main( void )
{
    int i = 0;
    /* Initialize HAL */
    HAL_Init( );
    /*Init RTT library*/
    SEGGER_RTT_Init();

    while(1)
    {
        i++;
        SEGGER_RTT_printf( 0, "Hola Mundo %d\n", i );
        HAL_Delay( 1000 );  
    }

    return 0u;
}

In Windows you need to add the path to the J-Link software package to the environment variable PATH. Please stop using Windows!!!!

Open a terminal and run the following command to start the GDB server

$ make open
make open
JLinkGDBServer -if SWD -device stm32g0b1re -nogui -port 3333
SEGGER J-Link GDB Server V8.20 Command Line Version
...
Target voltage: 3.30 V
Listening on TCP/IP port 3333

Open another terminal and run the following command to start the GDB client and then run the program by typing continue and hitting enter

$ make debug
arm-none-eabi-gdb Build/temp.elf -iex "set auto-load safe-path /"
GNU gdb (GDB) 16.2
...
Breakpoint 1, main () at app/main.c:27
27          uint32_t i = 0;
(gdb) continue

And now just type in another terminal (the third one) the following command to read the messages from the target

$ JLinkRTTClient
###RTT Client: ************************************************************ 
###RTT Client: *               SEGGER Microcontroller GmbH                * 
###RTT Client: *   Solutions for real time microcontroller applications   * 
###RTT Client: ************************************************************ 
###RTT Client: *                                                          * 
###RTT Client: *       (c) 2012 - 2016  SEGGER Microcontroller GmbH       *
###RTT Client: *                                                          *
###RTT Client: *     www.segger.com     Support: support@segger.com       *
###RTT Client: *                                                          *
###RTT Client: ************************************************************
###RTT Client: *                                                          *
###RTT Client: * SEGGER J-Link RTT Client   Compiled Nov 29 2023 13:43:55 *
###RTT Client: *                                                          *
###RTT Client: ************************************************************

###RTT Client: -----------------------------------------------        
###RTT Client: Connecting to J-Link RTT Server via localhost:19021 ...###RTT Client: Connected.

SEGGER J-Link V7.94 - Real time terminal output
SEGGER J-Link ST-LINK V1.0, SN=779643008
Process: JLinkGDBServerCL.exe
Hola Mundo 1
Hola Mundo 2
Hola Mundo 3
Hola Mundo 4

You can also stop the program and make it wait to receive a character from the keyboard using the following SEGGER_RTT_WaitKey() function.

#include "bsp.h"
#include "SEGGER_RTT.h"

int main( void )
{
    char a;
    /* Initialize HAL */
    HAL_Init( );
    /*Init RTT library*/
    SEGGER_RTT_Init();

    while(1)
    {
        SEGGER_RTT_printf( 0, "Press a key: ", a );
        /*Wait for a key to be pressed*/    
        a = SEGGER_RTT_WaitKey();
        /*Print the value of i in the terminal 0*/
        SEGGER_RTT_printf( 0, "\nChar received %c\n", a );
    }

    return 0u;
}

There is a non-blocking version of this function called SEGGER_RTT_GetKey() it will return -1 if no key is pressed. ideal to use with if statements.

#include "bsp.h"
#include "SEGGER_RTT.h"

int main( void )
{
    signed char a;
    /* Initialize HAL */
    HAL_Init( );
    /*Init RTT library*/
    SEGGER_RTT_Init();

    while(1)
    {
        SEGGER_RTT_printf( 0, "Press a key: ", a );
        /*get the key pressed, if there was one*/ 
        a = SEGGER_RTT_GetKey();   
        /*ask if there was a key stroke or not*/
        if( a != -1 )
        {
            /*Print the value of i in the terminal 0*/
            SEGGER_RTT_printf( 0, "\nChar received %c\n", a );
        }
        /*Delay 50ms, enough to sample any key*/
        HAL_Delay( 50 );  
    }

    return 0u;
}

In case using VSCode to debug there is a way to add the RTT terminal, to avoid using so many terminals, just go back and read AN003: VSCode Intellisense

Multiple Terminals

By default the RTT uses Terminal 0, but you can use. The following code shows how to use the RTT with multiple terminals

#include "bsp.h"
#include "SEGGER_RTT.h"

int main( void )
{
    GPIO_InitTypeDef GPIO_InitStruct;
    uint32_t i = 0;

    /* Initialize HAL */
    HAL_Init( );
    /*Init RTT library*/
    SEGGER_RTT_Init();

    for( ;; )
    {
        i++;
        /*Print the value of i in the terminal 0*/
        SEGGER_RTT_SetTerminal( 0 );
        SEGGER_RTT_printf( 0, "Terminal 0 %d\n", i );
        /*Print the value of i in the terminal 1*/
        SEGGER_RTT_SetTerminal( 1 );
        SEGGER_RTT_printf( 0, "Terminal 1 %d\n", i );

        HAL_Delay( 1000u );
    }

    return 0u;
}

JLinkRTTClient is just a basic like terminal tool to display and read messages from channel 0, you must use the JLinkRTTViewer GUI to display messages from multiple channels.

Configuration file

In the file SEGGER_RTT_Conf.h you can found some macros to configure the RTT software, the main configuration are basically buffers, been the most important one the BUFFER_SIZE_UP, keep in mind that if you use a lot of print statements you gonna need more buffer space. Anyway you can modify values in this file but another solutions is to declare these same macros before including the RTT header.

#include "bsp.h"
/*the size of each buffer for printf will 2k */
#define BUFFER_SIZE_UP                            ( 2048 )
#include "SEGGER_RTT.h"

Well, this was a very basic introduction, at the end of the day we do not use printf in the final version of our programs, but it is very useful when you need to debug certain cases. There are more functions and functionalities that you can use with the RTT but at the end of the day I don't use them because the same debugger is quiet more powerful.

In case you want to know more about the RTT you can check the offical SEGGER RTT documentation