MCUXpresso IDE FreeRTOS Debug Guide
MCUXpresso IDE FreeRTOS Debug Guide
Debug Guide
Rev. 11.5.0 — 11 January, 2022 User guide
NXP Semiconductors MCUXpresso IDE FreeRTOS Debug Guide
11 January, 2022
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
1. Introduction .................................................................................................................. 1
2. LinkServer FreeRTOS Thread Aware Debugging ........................................................... 2
2.1. Behavior when thread aware debugging ............................................................. 4
2.2. Required Source Code Changes ........................................................................ 5
2.2.1. Modify – File tasks.c ................................................................................ 5
2.2.2. Modify – File FreeRTOSConfig.h ................................................................... 5
2.2.3. Create – New File freertos_tasks_c_additions.h ........................................... 6
2.3. Detection and placement of FreeRTOS Debug Config block ................................. 6
2.3.1. Debugger Messages ............................................................................... 6
2.3.2. Placement of Config block ....................................................................... 7
2.4. Switching between all-stop and non-stop debug modes ....................................... 8
3. FreeRTOS Task Aware Debug Views ........................................................................... 9
3.1. Showing the FreeRTOS TAD Views ................................................................... 9
3.2. Task List View ................................................................................................... 9
3.3. Task Notifications View .................................................................................... 10
3.4. Queue List View .............................................................................................. 12
3.5. Timer List View ................................................................................................ 13
3.6. Heap Usage View ............................................................................................ 14
3.6.1. Memory Scheme in Use ........................................................................ 14
3.6.2. Heap Usage View Functionality ............................................................. 14
3.7. Timeouts ......................................................................................................... 15
4. Thread Aware Debugging with Other Debug Probes ..................................................... 16
4.1. PEmicro Probes ............................................................................................... 16
4.2. SEGGER J-Link Probes ................................................................................... 16
5. Legal information ........................................................................................................ 18
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
1. Introduction
Many of the examples provided as part of MCUXpresso SDK and LPCOpen packages are built
around the FreeRTOS real time operating system. FreeRTOS is also a popular choice when
developing MCU software applications for real products.
This guide examines some of the functionality included in MCUXpresso IDE to assist you
in debugging applications built around FreeRTOS. It does not provide any information on
FreeRTOS itself or on developing applications that use FreeRTOS.
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
The source code modifications required are described in Required Source Code
Changes [5].
Note: Example projects supplied as part of MCUXpresso IDE compatible SDK packages should
already have had these changes made to them.
Without these changes, or if Non-Stop debug mode is used, only the current thread will be seen
in the Debug View, as shown in the below screenshot:
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
However, once the necessary changes are made to the application source, and All-Stop debug
mode is used, the Debug View will display each thread separately, as shown in the next
screenshot:
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
In the below example, the MCU is halted in Thread #6, but a backtrace for Thread #1 is also
opened up (and backtrace information for Threads #7, #8, and #9 is also available):
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
The following notes describe the FreeRTOS project modifications required to enable thread
aware debug.
Note: Example projects supplied as part of MCUXpresso IDE compatible SDK packages should
already have had these changes made to them. And future releases of FreeRTOS are also
expected to include the same changes. Thus these changes are generally only required for LPC
preinstalled parts with LPCOpen FreeRTOS using projects.
#if ( configINCLUDE_FREERTOS_TASK_C_ADDITIONS_H == 1 )
#include "freertos_tasks_c_additions.h"
static void freertos_tasks_c_additions_init( void )
{
#ifdef FREERTOS_TASKS_C_ADDITIONS_INIT
FREERTOS_TASKS_C_ADDITIONS_INIT();
#endif
}
#endif
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
#define configINCLUDE_FREERTOS_TASK_C_ADDITIONS_H 1
#define configUSE_TRACE_FACILITY 1
<install dir>/ide/Examples/Misc
For convenience, the freertos_tasks_c_additions.h header file can be placed in the same folder as
the FreeRTOSConfig.h header file.
There is also one edit to freertos_tasks_c_additions.h itself that may be required for a particular
FreeRTOS project configuration. The macro configFRTOS_MEMORY_SCHEME describes the project heap
mechanism using a value 1 – 5 according to the following:
If both of these criteria are met, then when you start your debug session, confirmation that
LinkServer FreeRTOS Thread Aware Debugging is active is recorded in the “Debug Messages”
log inside the IDE’s Console view:
...
GDB nonstop mode disabled (using allstop mode)
FreeRTOS stack backtrace is enabled
...
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
If the image is debugged in Non-Stop mode, then the log will indicate that thread aware debugging
will not be available:
...
GDB nonstop mode enabled
FreeRTOS stack backtrace is disabled in Non-stop mode (use All-stop)
...
If the image does not contain the FreeRTOS Debug Config block, at all, then this section of the
Debug Messages log will make no reference to FreeRTOS thread awareness:
...
GDB nonstop mode enabled
...
or
...
GDB nonstop mode disabled (using allstop mode)
...
This is done in the freertos_debugconfig.ldt linker script template file, which attempts to determine
if the project is a FreeRTOS-using one . This is done based on the FreeRTOS component being
included in the project (for SDK-based projects,) or from the pathname (for non-SDK projects,
based on pre-installed parts).
This will cause a FreeRTOS line, similar to the one in the following snippet, to be placed in the
main generated linker script (.ld) file inside your project’s Debug (or Release) folder:
.text : ALIGN(4)
{
*(.text*)
KEEP(*freertos*/tasks.o(.rodata*)) /* FreeRTOS Debug Config */
*(.rodata .rodata.* .constdata .constdata.*)
. = ALIGN(4);
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
} > PRPROGRAM_FLASH
If this FreeRTOS check within the managed linker script mechanism fails for some reason, then
you can force the inclusion of the FreeRTOS Debug Config in your project by adding a folder to
root directory of your project called “linkscripts” and adding a file to it called “user.ldt” containing
the following:
<#assign force_freertos=true>
For more details of linker script template files, please see the MCUXpresso IDE User Guide.
However, you can also easily modify an existing launch configuration file to switch between All-
Stop and Non-Stop as follows.
• Open the project up in the Project Explorer view and double click on the appropriate launch
configuration file (typically “projname LinkServer Debug.launch”)
• Switch to the GDB Debugger tab
• Tick / Untick the " Non-Stop mode" option, as required.
• Click on Apply to save, then Continue
Any further debug sessions of your project will now use the newly selected debug mode.
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
Note: These Views are independent of the debug probe being used, as they just use GDB
commands to receive information from the target.
The Views are “stop mode” Views: with the target halted or stopped, the Views will query the
device under debug and read the necessary information through the debug connection.
This will also happen during single stepping, so to improve stepping performance it is advisable
to:
1. Only have the needed Views in the foreground/visible, or close the Views if they are not used.
2. Make use of the Pause View feature, allowing you to single step without the Views constantly
reloading data.
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
TCB#
Task Name
Task Handle
Task State
Priority
Stack Usage
• Graphical view of current stack usage, with current allocation and stack size available to the
task
Event Object
• Lists the object a blocked task is waiting for. Use vQueueAddToRegistry() to assign a symbolic
name to semaphore, mutex, and queues with configQUEUE_REGISTRY_SIZE greater than zero
Runtime
Stack base
Stack Top
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
A double-level table helps finding the information about notifications on each task. The top
level table shows the list of tasks and summarized details about task notifications, whereas the
secondary table lists each notification entry, indicating state and actual data decoded in several
formats.
TCB#
Task Name
Task Handle
# Received
# Waiting
Waiting for...
• The notification indexes the task is waiting for
By selecting an entry from the top level table, the secondary table will show the actual array of
notification entries. The number of items match the value of configTASK_NOTIFICATION_ARRAY_ENTRIES
in FreeRTOS V10.4.0 and newer versions, or it is a single element otherwise.
Address
State
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
Data [DEC]
Data [HEX]
Data [BIN]
• Notification’s value, binary representation
Data [ASCII]
• Number of queue
Queue Name
Address
Length
• Length of queue. The first number indicates the number of elements in the queue, followed by
the maximum number of elements possible
Item Size
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
# Tx Waiting
# Rx Waiting
• Number of tasks waiting until an element is placed into the queue
Queue Type
Head
Tail
Read from
Write to
ID
Timer Name
• Name of timer
Period (ticks)
Auto reload?
Timer Number
• Number of timer
Timer callback
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
If the freeRTOSMemoryScheme variable is to be used, then this can be defined as follows, but you must
ensure that there is a reference to this symbol, so that it is not removed by the linker.
Type
Heap Base
Heap End
Heap Usage
Free Space
In the lower part of the View there is information about the heap memory blocks:
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
• Block number
Details
• Allocated, Free or the Task Stack or Task TCB
Block Start
Block End
Size
• Size of memory
3.7 Timeouts
When using slow debug probes such as the OpenSDA debug probes fitted to many FRDM
boards, it is possible that timeouts will be reported within the IDE.
The timeout period can be extended if this occurs using the Workspace preference as shown
below:
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
However on odd occasions this can cause problems and it is possible to turn it off using the
launch configuration server parameter:
-kernel=none
To turn it on, enable the “Select RTOS plugin” option for “GDBServer/RTOSPlugin_FreeRTOS”
in the J-Link Launch Configuration for your project:
Alternatively, this default can be changed for new launch configurations via an IDE Workspace
J-Link preference as show below:
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.
5. Legal information
Information in this document is provided solely to enable system and software implementers to
use NXP products. There are no express or implied copyright licenses granted hereunder to
design or fabricate any integrated circuits or integrated circuits based on the information in this
document.
NXP makes no warranty, representation, or guarantee regarding the suitability of its products for
any particular purpose, nor does NXP assume any liability arising out of the application or use of
any product or circuit, and specifically disclaims any and all liability, including without limitation
consequential or incidental damages. “Typical” parameters that may be provided in NXP data
sheets and/or specifications can and do vary in different applications, and actual performance
may vary over time. All operating parameters, including “Typicals”, must be validated for
each customer application by customer’s technical experts. NXP does not convey any license
under its patent rights nor the rights of others. NXP sells products pursuant to standard terms
and conditions of sale, which can be found at the following address: https://www.nxp.com/
SalesTermsandCondition.
While NXP has implemented advanced security features, all products may be subject to
unidentified vulnerabilities. Customers are responsible for the design and operation of their
applications and products to reduce the effect of these vulnerabilities on customer’s applications
and products, and NXP accepts no liability for any vulnerability that is discovered. Customers
should implement appropriate design and operating safeguards to minimize the risks associated
with their applications and products.
NXP, the NXP logo, Freescale, the Freescale logo, Kinetis and Tower are trademarks of NXP
B.V.
Arm, Cortex, Thumb, TrustZone, Mbed, Keil, CoreSight are registered trademarks of Arm Limited
(or its subsidiaries) in the US and/or elsewhere. Microsoft, Azure ThreadX are trademarks of the
Microsoft group of companies. FreeRTOS™ and FreeRTOS.org™ are trade marks of Amazon
Web Services, Inc. SEGGER Embedded Studio is a trademark of SEGGER Microcontroller
GmbH. J-Link is a trademark of SEGGER MICROCONTROLLER GMBH & CO. KG IAR
trademark is owned by IAR Systems AB. Java and all Java-based trademarks are trademarks
of Oracle Corporation in the United States, other countries, or both. Linux is the registered
trademark of Linus Torvalds in the U.S. and other countries. UNIX is a registered trademark
of The Open Group in the United States and other countries. Eclipse, CDT are trademarks of
Eclipse Foundation, Inc.
MCUXpresso IDE FreeRTOS Debug Guide - All information provided in this document is subject to legal disclaimers © 2022 NXP Semiconductors. All rights reserved.