NXP Semiconductors MCUXpresso IDE MQX RTOS Guide

MCUXpresso IDE MQX RTOS
Debug Guide
Rev. 11.7.0 — 12 January, 2023 User guide

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
12 January, 2023
Copyright © 2023 NXP Semiconductors
All rights reserved.
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. ii

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
1. Introduction .................................................................................................................. 1
2. LinkServer MQX RTOS Thread Aware Debugging ......................................................... 2
2.1. Behavior when thread aware debugging ............................................................. 3
2.2. Required Source Code Changes ........................................................................ 4
2.2.1. Modify mqx.c ............................................................................................ 5
2.3. Debugger Messages .......................................................................................... 6
2.4. Switching between all-stop and non-stop debug modes ....................................... 7
3. Thread Aware Debugging with Other Debug Probes ...................................................... 9
3.1. PEmicro Probes ................................................................................................ 9
3.2. SEGGER J-Link Probes ..................................................................................... 9
4. Legal information ........................................................................................................ 10
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. iii

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
1. Introduction
The MQX Real-Time Operating System (RTOS) provides real-time performance within a small,
configurable footprint. The RTOS is tightly integrated with 32-bit MCUs and MPUs from NXP and
is provided with commonly used device drivers.
The MQX RTOS is designed to have a modern, component-based microkernel architecture
allowing for customization by feature, size, and speed by selecting the components engineers
wish to include while meeting the tight memory constraints of embedded systems.
This guide is intended to highlight debugging capabilities of the MCUXpresso IDE when dealing
with an MQX RTOS based application. It does not provide any information on MQX RTOS itself
or on developing applications that use MQX RTOS.
For more information on MQX RTOS please visit MQX homepage.
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 1

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
2. LinkServer MQX RTOS Thread Aware Debugging
When debugging via LinkServer debug probes, the MCUXpresso IDE debugger can provide
MQX RTOS thread aware debug if:
1. All the needed symbols ( _mqx_version_number, _mqx_vendor, _mqx_kernel_data, MQX_init_struct and,
optionally,_mqx_debug_config)arepresentintheexecutablefile.Ifanyofthemandatorysymbols
is missing from the executable, debugger will be unable to extract information from the MQX
RTOS kernel, thus not capable of offering GDB thread awareness functionality.
2. Debugging is carried out in All-Stop mode (rather than the default Non-Stop mode). This
selection is made when first making a debug connection for a particular project (or after
deleting an existing launch configuration). For more details, please see the MCUXpresso IDE
User Guide.
Note: If Non-Stop debug mode is used, only the current thread will be seen in the Debug view,
as shown in the screenshot below:
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 2

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
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:
2.1 Behavior when thread aware debugging
MCUXpresso IDE LinkServer MQX RTOS thread aware debugging is available once the MQX
RTOS scheduler has started (so will not appear straight after loading the application when the
defaultbreakpointonmain() isreached).Debugworksinstopmode.Inotherwords,ifexecutionof
a user task is halted either through a user action (halt) or a debug event (breakpoint, watchpoint,
fault, etc.), the stopped thread is current and no application thread executes in the background.
The register context for any thread is available in the register window. For suspended or blocked
tasks, the register context is the context in effect when the task was swapped out, regardless of
which task stack level is examined within the traceback window.
In the below example, the MCU is halted in Thread #2, but a backtrace for Thread #9 is also
opened up (and backtrace information for the other threads is also available):
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 3

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
2.2 Required Source Code Changes
MCUXpresso IDE debug is implemented via a GDB remote console application (i.e. a stub). A
“remote debug stub” underneath GDB has access to symbolic information (through GDB), but
has no direct knowledge of symbol data types. Thread aware debug for MQX RTOS requires
some symbols to be present inside the ELF file, more specifically: _mqx_version_number, _mqx_vendor,
_mqx_kernel_data, MQX_init_struct and, optionally, _mqx_debug_config. The optional _mqx_debug_config is
an extra array of configuration data that must be added in the application code and would make
the stub not to rely on hard-coded information, that can be affected by changes in the code and
by various macros and defines. The _mqx_debug_config is described below.
Note 1: MQX thread aware debugging should work without the definition of _mqx_debug_config.
However, this stands true only if the hard-coded information from the GDB stub matches the
actual definitions of data structures found inside the ELF. The assumptions the stub makes are
listed in the “Debug Messages” console, as seen in the screenshot below.
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 4

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
Note 2: The hard-coded information listed in the “Debug Messages” console can be verified by
manually printing real offsets from the ELF, by using GDB’s “print” command. If a mismatch is
identified, MQX RTOS thread awareness will most likely not work and _mqx_debug_config must be
added in the code – more details in the section below.
2.2.1 Modify mqx.c
Asdescribedabove,MCUXpressoIDEMQX RTOSthreadaware debugmightneed thedefinition
of an extra _mqx_debug_config data structure. It must be added inside mqx.c source file. The newly
added code section must look like below:
/* Data used by low-level debuggers to offer task awareness support */
#define MQX_DEBUG_CONFIG_MAJOR_VERSION (1)
#define MQX_DEBUG_CONFIG_MINOR_VERSION (0)
const uint32_t _mqx_debug_config[] =
{
MQX_DEBUG_CONFIG_MAJOR_VERSION,
MQX_DEBUG_CONFIG_MINOR_VERSION,
0xFFFFFFFFUL, // Default initialization value for _mqx_kernel_data
offsetof(struct kernel_data_struct, TD_LIST),
offsetof(struct kernel_data_struct, ACTIVE_PTR),
offsetof(struct kernel_data_struct, FP_ACTIVE_PTR),
offsetof(struct kernel_data_struct, SYSTEM_TD),
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 5

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
offsetof(struct queue_struct, NEXT),
offsetof(struct queue_struct, PREV),
offsetof(struct queue_struct, SIZE),
offsetof(struct td_struct, STATE),
offsetof(struct td_struct, TASK_ID),
offsetof(struct td_struct, STACK_PTR),
offsetof(struct td_struct, FLAGS),
offsetof(struct td_struct, TASK_TEMPLATE_PTR),
offsetof(struct td_struct, TD_LIST_INFO),
offsetof(struct task_template_struct, TASK_NAME)
};
Linker must be also forced to keep the above data structure. The following line must be added:
*(volatile void **)kernel_data = (void *)&_mqx_debug_config;
after:
/* The following assignments are done to force the linker to include
* the symbols, which are required by TAD.
* Note that we should use address of the variable so it is not optimized
* as direct constant assignment when optimization level is high.
* Note that counter will be immediately reset to zero on the subsequent
* _mem_zero call. */
*(volatile void **)kernel_data = (void *)&_mqx_version_number;
*(volatile void **)kernel_data = (void *)&_mqx_version;
*(volatile void **)kernel_data = (void *)&_mqx_vendor;
Note: If _mqx_debug_config is found inside the ELF, a message will be printed inside the “Debug
Messages” console.
2.3 Debugger Messages
LinkServer MQX RTOS Thread Aware Debugging requires a set of symbols to be present inside
the ELF, as mentioned above. It also requires that the debug session is carried out in All-Stop
mode.
If both of these criteria are met, then when you start your debug session, confirmation that
LinkServer MQX RTOS 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)
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 6

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
MQX stack backtrace is enabled
...
as shown in the screenshot below:
IftheimageisdebuggedinNon-Stopmode,thenthelogwillindicatethatthreadawaredebugging
will not be available:
...
GDB nonstop mode enabled
MQX stack backtrace is disabled in Non-stop mode (use All-stop)
...
If the image does not contain expected symbols, at all, then this section of the “Debug Messages”
log will make no reference to MQX RTOS thread awareness:
...
GDB nonstop mode enabled
...
or
...
GDB nonstop mode disabled (using allstop mode)
...
2.4 Switching between all-stop and non-stop debug modes
When debugging a project for the first time using a LinkServer debug connection (or when you
have deleted any existing launch configuration files), you can select whether to debug in Non-
Stop or All-Stop mode (so that you can choose whether or not you wish to use MQX RTOS
thread awareness).
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
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 7

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
Any further debug sessions of your project will now use the newly selected debug mode.
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 8

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
3. Thread Aware Debugging with Other Debug Probes
3.1 PEmicro Probes
MQX RTOS thread aware debugging with PEmicro debug probes is not yet supported.
3.2 SEGGER J-Link Probes
MQX RTOS thread aware debugging with SEGGER J-Link debug probes is not yet supported.
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 9

NXP Semiconductors MCUXpresso IDE MQX RTOS Debug Guide
4. 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,CoreSightareregisteredtrademarksofArmLimited
(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.
© NXP B.V. 2016-2023. All rights reserved.
How To Reach Us:
Home Page: https://www.nxp.com
Web Support: https://www.nxp.com/support
MCUXpresso IDE MQX RTOS Debug Guide -
User Guide All information provided in this document is subject to legal disclaimers Rev. 11.7.0 — 12 January, 2023 © 2023 NXP Semiconductors. All rights reserved. 10