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

MCUXpresso IDE MQX RTOS Debug Guide -

User Guide All information provided in this document is subject to legal disclaimers

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

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

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

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

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

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

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

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

...

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

Table of contents

Other NXP Semiconductors Computer Hardware manuals

NXP Semiconductors

NXP Semiconductors AN11211 Troubleshooting guide

NXP Semiconductors

NXP Semiconductors AN12398 User manual

NXP Semiconductors

NXP Semiconductors i.MX 8QuadXPlus User manual

NXP Semiconductors

NXP Semiconductors BFU520 User manual

NXP Semiconductors

NXP Semiconductors OM13506 User manual

NXP Semiconductors

NXP Semiconductors i.MX6ULL User manual

NXP Semiconductors

NXP Semiconductors LPCXpresso54608 User manual

NXP Semiconductors

NXP Semiconductors freescale MCF5225X User manual

NXP Semiconductors

NXP Semiconductors RD710 User manual

NXP Semiconductors

NXP Semiconductors SLN-VIZNLC-IOT User manual

NXP Semiconductors

NXP Semiconductors NavQPlus 8MPNAVQ-8G-G User manual

NXP Semiconductors

NXP Semiconductors WCT1012 User manual

NXP Semiconductors

NXP Semiconductors OM13488 User manual

NXP Semiconductors

NXP Semiconductors QorIQ LX2160A User manual

NXP Semiconductors

NXP Semiconductors AXIOM M52259DEMOCOM Installation manual

NXP Semiconductors

NXP Semiconductors LX2160ARDBGSG User manual

NXP Semiconductors

NXP Semiconductors HRPNUG User manual

NXP Semiconductors

NXP Semiconductors 8MNANOD3L-EVK User manual

NXP Semiconductors

NXP Semiconductors freescale TRK-S12ZVHY64 User manual

NXP Semiconductors

NXP Semiconductors JN5148 User manual

NXP Semiconductors

NXP Semiconductors LPC5536-EVK User manual

NXP Semiconductors

NXP Semiconductors S32G-VNP-EVB User manual

NXP Semiconductors

NXP Semiconductors QorIQ T2080 User manual

NXP Semiconductors

NXP Semiconductors Motorola DSP56602 User manual

Popular Computer Hardware manuals by other brands

EMC2

EMC2 VNX Series Hardware Information Guide

Panasonic

Panasonic DV0PM20105 Operation manual

Mitsubishi Electric

Mitsubishi Electric Q81BD-J61BT11 user manual

Gigabyte

Gigabyte B660M DS3H AX DDR4 user manual

Raidon

Raidon iT2300 Quick installation guide

National Instruments

National Instruments PXI-8186 user manual

Hauppauge

Hauppauge WinTV-HVR-2250 Quick installation guide

Kontron

Kontron CP6002 user guide

Manhattan

Manhattan 702843 user manual

Aphex

Aphex 230 instruction manual

AMD

AMD Phenom II Product data sheet

Intel

Intel NUC 12 Pro user guide

dbx

dbx Zone Pro 1260 user manual

Galaxy

Galaxy GHDX2-2430S-24F4D Installation and hardware reference manual

Intel

Intel AXXRMFBU4 Quick installation user's guide

Kontron

Kontron DIMM-PC/MD product manual

ST X-NUCLEO-SAFEA1B How to use

STEINWAY LYNGDORF

STEINWAY LYNGDORF SP-1 installation manual