Using VisualGDB FreeRTOS Tracing to Optimize Real-time Code

This tutorial shows how to use the FreeRTOS tracing feature of VisualGDB to optimize a simple FreeRTOS UART driver based on queues. We will create a basic project using queues to buffer the incoming and outgoing UART data, measure the delays in various components of our setup and show how to optimize them.

Before you begin, install VisualGDB 5.2 or later.

  1. Ensure that you are using a board that can communicate with your computer via the COM port. We will use the STM32F410-Nucleo board that has an on-board ST-Link 2.1 that provides a virtual COM port connected to UART2 on the device, however the steps below will work for any other USB-to-UART bridge as long as it is connected to the device. Plug in the board and take a note of the COM port number in Device Manager:01-devmgr
  2. Start Visual Studio and open the VisualGDB Embedded Project Wizard:02-prjname
  3. Select “Create a new project -> Embedded Binary”:03-msbuild
  4. Select the ARM toolchain and your device. We will use the STM32F410RB device installed on the STM32F410-Nucleo board:03-device
  5. Select the “LEDBlink (FreeRTOS)” sample and ensure that the FreeRTOS CPU core matches your CPU core and the floating point setting on the previous page: 04-rtos
  6. Select OpenOCD as the debug method and click “Detect” to automatically detect the rest of the settings:05-debug
  7. Press “Finish” to generate the project. The first thing we will do is test that the UART connection is working. Change the main source file extension to .cpp and replace its contents with the following code:

    If you are using a different board, you will need to find out which UART is connected to the COM port you are using and change the following parts of the code:

    Value New value
    __USART2_CLK_ENABLE() __USARTx_CLK_ENABLE() where X is your USART number
    USART2 USARTx where X is your USART number
    __GPIOA_CLK_ENABLE() __GPIOx_CLK_ENABLE() where X is the GPIO port that has your USART pins
    GPIO_PIN_3 and GPIO_PIN_2 GPIO pins that correspond to the RX and TX signals for your USART
    GPIO_AF7_USART2 Alternate function numbers that switch the RX and TX pins to USART mode
    GPIO2 GPIOx where X is the GPIO port that has your USART pins
  8. Build the project and ensure it succeeds: 06-loop
  9. Open VisualGDB Project Properties and enable the raw terminal on the COM port connected to your device:07-terminal
  10. Press F5 to start the program. Try typing some characters in the COM port window in Visual Studio to see that they are echoed back with 1 added to them:08-echo
  11. Now we will modify our code to use FreeRTOS. We will create 2 threads:
    1. The first thread will read numbers from the COM port and sleep for the amount of milliseconds specified by each number
    2. The second thread will send the messages generated by the first thread character-by-character while the first one is sleeping

    First modify the SysTickHandler to call the handler from FreeRTOS when the scheduler is active:

    Then declare 2 queues that will be used to store sent and received data:

    Then add a main thread that will read characters from g_InQueue, interpret them as numbers, wait and print status messages via UART_Printf():

    Add a UART_Printf() function that will send the output to g_OutQueue:

    Add a handler for the “UART character received” event that will put the received byte to g_InQueue:

    Add a similar handler to the “UART character sent” event that will notify the sending thread by posting an event to g_SendReadySemaphore:

    Add the sending thread that will wait until the UART hardware is ready (signaled through g_SendReadySemaphore) and then send the next byte queued in g_OutQueue:

    Finally put this all together by creating the threads, queues and the semaphore in the main() function after the last HAL_GPIO_Init():
  12. Build your program, run it and try entering small numbers to get the main thread to sleep for some milliseconds. Ensure that the program responds properly:09-run
  13. Now we will use the VisualGDB FreeRTOS tracing to get see whether the driver could be optimized. Open the Dynamic Analysis page of VisualGDB Project Properties and enable the ‘Allow tracing various RTOS events’ checkbox. Then click at the ‘add reference’ link to automatically reference the profiling framework:10-profiler
  14. On STM32F410 device the profiler framework will not build because it is missing the TIM2 timer used by the sampling profiler:11-timer
  15. You can easily fix this by adding SAMPLING_PROFILER_TIMER_INSTANCE=5 to preprocessor macros on the MSBuild Settings page:12-inst
  16. Build and start your program; wait until it loads and press ‘break all’. Use the Threads window to display the list of active RTOS threads:13-threadsNote that having the window open will cause VisualGDB to analyze the threads after each stop and will reduce the performance. It is recommended to close the Threads window when not actively using it.
  17. Open the Real-Time watch window and add the threads to the watch. VisualGDB will automatically suggest known thread names:14-thrnames
  18. Next add the g_InQueue and g_OutQueue queues. You can either type in their names, or right-click on them in the source code and select ‘Add to real-time watch’:15-queues
  19. Resume the program and type ‘100<ENTER>’ in the COM port window. Note how the real-time watch will show several bursts of activity on the input queue (one for each received character) followed by a longer burst on the output queue (when the ‘WAIT’ message is printed):16-out
  20. Zoom in on the ‘out’ queue activity. You will see how the queue is quickly filled while the main thread is running and then is slowly emptied by the send thread. Measure the time between the maximum queue size (start of transmission) and the time when it is fully emptied (end of transmission):17-queue
  21. To make things clearer we will use a custom real-time watch to plot the times of the ‘Receive complete’ and ‘Send complete’ events on the same scale. Include the <CustomRealTimeWatches.h> file, declare an instance of EventStreamWatch and post events there from both HAL_UART_RxCpltCallback() and HAL_UART_TxCpltCallback():18-events
  22. Run the program again, add g_UARTInterrupts and g_SendReadySemaphore to real-time watch, then resume it, type ‘100<ENTER>’  in the COM port window and observe the timing:19-txThe graph clearly shows that out of almost 1 ms spent between subsequent timer interrupts most of the time is spent by the IDLE thread while the send thread is queued despite the g_SendReadySemaphore being signaled.
  23. This can be fixed by adding the following line to the end of HAL_UART_RxCpltCallback() and HAL_UART_TxCpltCallback():

  24. This forces the thread switch immediately after the interrupt handler returns, makes the send thread get activated sooner and considerably reduces the delay between the interrupt and reading the output queue:22-shorter
  25. The 140 microsecond delay caused by the context switch is still relatively large. We can reduce it further by trying to read the queue directly from the ‘send complete’ callback and sending it immediately:
  26. This eliminates the extra context switches: g_OutQueue is now read by the interrupt handler from the context of the IDLE thread and once all data is sent, the send thread is activated:23-mintimeCongratulations! By analyzing the timings and reducing the unnecessary delays you have managed to make the UART driver almost 5x faster.