mcuxpresso ide azure rtos threadx debug guide - nxp

MCUXpresso IDE Azure RTOSThreadX Debug GuideRev. 11.6.0 — 13 July, 2022 User guide

NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

13 July, 2022

Copyright © 2022 NXP Semiconductors

All rights reserved.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide -

User GuideAll information provided in this document is subject to legal disclaimers

Rev. 11.6.0 — 13 July, 2022© 2022 NXP Semiconductors. All rights reserved.

ii


1. Introduction .................................................................................................................. 12. LinkServer Azure RTOS ThreadX Thread Aware Debugging ........................................... 2

2.1. Behavior when thread aware debugging ............................................................. 42.2. Debugger Messages .......................................................................................... 52.3. Switching between all-stop and non-stop debug modes ....................................... 6

3. Azure RTOS ThreadX Thread Aware Debug Views ........................................................ 73.1. Showing the Azure RTOS ThreadX TAD Views ................................................... 73.2. Threads View .................................................................................................... 83.3. Message Queues View ...................................................................................... 83.4. Semaphores View ............................................................................................. 93.5. Mutexes View .................................................................................................... 93.6. Event Flags View ............................................................................................. 103.7. Timers View .................................................................................................... 103.8. Memory Block Pools View ................................................................................ 103.9. Memory Byte Pools View ................................................................................. 113.10. Timeouts ....................................................................................................... 11

4. Thread Aware Debugging with Other Debug Probes ..................................................... 124.1. PEmicro Probes ............................................................................................... 124.2. SEGGER J-Link Probes ................................................................................... 12

5. Exporting Azure RTOS ThreadX Trace ........................................................................ 135.1. Enabling Trace Inside the Application ............................................................... 13

5.1.1. Add required preprocessor symbols ....................................................... 135.1.2. Declare the trace buffer ......................................................................... 145.1.3. Enable trace ......................................................................................... 14

5.2. Exporting Trace ............................................................................................... 155.2.1. Configuration of Trace Export feature ..................................................... 155.2.2. Trace Export button .............................................................................. 155.2.3. Exporting Trace .................................................................................... 16

6. Legal information ........................................................................................................ 17




iii


1. IntroductionAzure RTOS is one of the real-time operating systems (RTOS) that is delivered with someof the MCUXpresso SDK packages. It is an advanced real-time OS designed for embeddedapplications and offers advanced scheduling facilities, message passing, interrupt management,and messaging services. Azure RTOS consists of several components (i.e. ThreadX, FileX,USBX) that can be exercised using demo applications available in board-specific MCUXpressoSDK packages.

This guide is intended to highlight debugging capabilities of the MCUXpresso IDE when dealingwith an Azure RTOS based application. It does not provide any information on Azure RTOS itselfor on developing applications that use Azure RTOS.

For more information on Azure RTOS please visit https://docs.microsoft.com/en-us/azure/rtos/




1

https://docs.microsoft.com/en-us/azure/rtos/


2. LinkServer Azure RTOS ThreadX Thread AwareDebugging

When debugging via LinkServer debug probes, the MCUXpresso IDE debugger can provideAzure RTOS ThreadX thread aware debug if :

1. Debugging is carried out in All-Stop mode (rather than the default Non-Stop mode). Thisselection is made when first making a debug connection for a particular project (or afterdeleting an existing launch configuration). For more details, please see the MCUXpresso IDEUser Guide.

2. No changes are made inside TX_THREAD_STRUCT and TX_TIMER_INTERNAL_STRUCT data structures thatcould impact debugger’s ability to determine available threads from the ThreadX kernel.Definitions of the two data structures can be controlled through various defines. In order for thedebugger’s thread awareness feature to work, TX_TIMER_INTERNAL_EXTENSION, TX_THREAD_EXTENSION_0and TX_THREAD_EXTENSION_1 must not inject extra fields inside the mentioned structures. Someof the members the debugger uses from TX_THREAD_STRUCT are: tx_thread_id, tx_thread_stack_ptr,tx_thread_name, tx_thread_state and tx_thread_created_next.

Note 1: Initial development of the GDB thread awareness feature was done usingAzure RTOS ThreadX version 6.1.2, and implicitly, the definitions of TX_THREAD_STRUCT andTX_TIMER_INTERNAL_STRUCT from the associated code base were used as references.




2


Note 2: Debugger performs sanity checks on the thread ID field from the thread control block.The ID of each thread must be equal to 0x54485244 (see TX_THREAD_ID), otherwise an appropriatemessage will be printed in the Debug Messages console.

Note 3: If Non-Stop debug mode is used, only the current thread will be seen in the Debug View,as shown in the below screenshot:

However, once all the necessary preconditions are met, the Debug View will display each threadindividually, as shown in the next screenshot:




3


2.1 Behavior when thread aware debugging

MCUXpresso IDE LinkServer Azure RTOS ThreadX thread aware debugging is available oncethe ThreadX scheduler has started (so will not appear straight after loading the applicationwhen the default breakpoint on main() is reached). Debug works in stop mode. In other words, ifexecution of 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 thebackground. The register context for any thread is available in the Registers view. For suspendedor blocked threads, the register context is the context in effect when the thread was swappedout, regardless of which thread stack level is examined within the traceback window.

In the below example, the MCU is halted in Thread #7, but a backtrace for the other threads isalso available:




4


2.2 Debugger Messages

LinkServer Azure RTOS ThreadX Thread Aware Debugging requires that the debug sessionis carried out in All-Stop mode. If this precondition is met, then when you start your debugsession, confirmation that LinkServer Azure RTOS ThreadX Thread Aware Debugging is activeis recorded in the “Debug Messages” log inside the IDE’s Console view:

...

GDB nonstop mode disabled (using allstop mode)

Azure RTOS ThreadX stack backtrace is enabled

...

as shown in the screenshot below:




5


If the image is debugged in Non-Stop mode, then the log will indicate that thread aware debuggingwill not be available:

...

GDB nonstop mode enabled

Azure RTOS ThreadX stack backtrace is disabled in Non-stop mode (use All-stop)

...

2.3 Switching between all-stop and non-stop debug modes

When debugging a project for the first time using a LinkServer debug connection (or when youhave 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 Azure RTOSThreadX 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 launchconfiguration 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.




6


3. Azure RTOS ThreadX Thread Aware Debug ViewsMCUXpresso IDE includes several additional Views to further simplify Azure RTOS applicationdebugging, known collectively as the Azure RTOS ThreadX TAD (Thread Aware Debugger forGDB):

• Threads : shows the list of threads with status information• Message Queues : shows currently active queues with the available messages decoded• Semaphores : shows the list of semaphores used inside the application• Mutexes : shows the list of mutexes used inside the application• Event Flags : shows the event flags• Timers : lists the active timers used inside the application• Memory Block Pools : shows detailed information about memory allocation within memory

block pools• Memory Byte Pools : shows detailed information about memory allocation within memory

byte pools

Note: These views are independent of the debug probe being used, as they just use GDBcommands to query information from the target.

3.1 Showing the Azure RTOS ThreadX TAD Views

The Azure RTOS ThreadX views can be opened using the common “RTOS” main menu in theMCUXpresso IDE.

The Views are “stop mode” Views: with the target halted or stopped, the Views will query thedevice under debug and read the necessary information through the debug connection.




7


This will also happen during single stepping, so to improve stepping performance it is advisableto:

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.

3.2 Threads View

This View shows the threads in a table:

• # - Thread Control Block index.• Name - Name of the thread.• Handle - Address of the thread handle.• Priority - Priority of the thread (0 – 1023).• State - Current task state (e.g. running, ready, completed, etc.). See tx_api.h for all the possible

states.• Stack Usage - Graphical view of current stack usage, with current allocation and stack size

available to the thread.

Unfolding a thread line item shows the following items:

• Entry - Entry function for current thread.• Run count - Run count for current thread.• Time slice - Time-slice associated to current thread.• Owned mutex count - Number of owned mutexes.• Stack start - Stack start address.• Stack end - Stack end address.• Stack size - Size of stack.• Stack ptr - Thread’s current stack pointer.

3.3 Message Queues View

This View shows the message queues in a table:




8


The meanings of the columns are as follows.

• # - Index of queue• Name - Name of queue.• Address - Address of queue handle• Used - Number of items in use.• Capacity - Maximum capacity of the message queue.• Message Size - Size of an individual element in the queue. According the the Azure RTOS

ThreadX specification, size is word-size multiple.• Suspended - Threads that are suspended and waiting for access to current resource.

Unfolding a queue line item shows the following information:

• Start - Address of queue head item (first item in the queue).• End - Address of queue tail item (last item in the queue).• Read from - Address of current reading element.• Write to - Address of next empty item in the queue.

Clicking on an element in the queue shows details about it.

3.4 Semaphores View

This View shows the semaphores in a table:

• # - Index of semaphore.• Name - Name of semaphore.• Count - The actual semaphore count.• Suspended - Threads that are suspended and waiting for access to current resource.

3.5 Mutexes View

This View provides information about mutexes used inside the application:

• # - Index of mutex.




9


• Name - Name of mutex.• Owner - Current thread that owns the mutex.• Owner count - Mutex ownership count.• Suspended - Threads that are suspended and waiting for access to current resource.

3.6 Event Flags View

This View shows the event flags in a table:

• # - Index of event flag.• Name - Name of event flag.• Flags - Value associated with current event flag.• Suspended - Threads that are suspended and waiting for access to current resource

3.7 Timers View

This View shows the timers in a table:

• # - Index of timer.• Name - Name of the timer.• Remaining - Remaining number of ticks.• Re-init - Number of ticks used as re-initialization value.• Function - Timeout function.

3.8 Memory Block Pools View

This View shows the memory block pools in a table:

• # - Index of memory block pool.• Name - Name of memory block pool.• Block size - Number of used bytes in the memory byte pool.• Pool size - Memory block pool’s size in bytes.• Address - Start address of the memory block pool’s memory area.• Used - Number of used memory blocks.• Free - Number of available memory blocks.• Total - Total number of memory blocks.• Suspended - Threads that are suspended and waiting for access to current resource.




10


3.9 Memory Byte Pools View

This View shows the memory byte pools in a table:

• # - Index of memory byte pool.• Name - Name of memory byte pool.• Address - Address of the head of the byte pool.• Used - Number of used bytes in the memory byte pool.• Free - Number of free bytes in the memory byte pool.• Size - Capacity of the memory byte pool.• Fragments - Number of fragments allocated inside the memory byte pool.• Suspended - Threads that are suspended and waiting for access to current resource.

3.10 Timeouts

When using slow debug probes, 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 shownbelow:




11


4. Thread Aware Debugging with Other Debug Probes

4.1 PEmicro Probes

Azure RTOS ThreadX thread aware debugging with PEmicro debug probes is automaticallysupported without any special option.

However, on odd occasions this can cause problems and it is possible to turn it off using thelaunch configuration server parameter:

-kernel=none

4.2 SEGGER J-Link Probes

Azure RTOS ThreadX thread aware debugging for SEGGER J-Link debug probes is disabledby default.

To turn it on, enable the “Select RTOS plugin” option for “GDBServer/RTOSPlugin_Azure” in theJ-Link Launch Configuration for your project:

Note: J-Link’s GDB thread awareness feature relies on the prerequisites and on the samedata structures as described in LinkServer Azure RTOS ThreadX Thread Aware Debugging [2]section.




12


5. Exporting Azure RTOS ThreadX Trace

The Azure RTOS ThreadX offers support for collecting system and application events that occurduring run-time. Data is initially stored in the target memory and then must be transferred onthe host machine for inspection. Decoding of trace data is done using Microsoft’s Azure RTOSTraceX host-based analysis tool that allows graphical visualization of the traced events.

Note: Functionality described in this section is debug probe agnostic. This means that trace datacan be exported regardless of the underlying debug probe used.

5.1 Enabling Trace Inside the Application

Trace must be explicitly enabled inside the application at compile-time and run-time. Currentprocedure that allows enabling trace inside the application is summarized below.

5.1.1 Add required preprocessor symbols

Trace-dependent code is activated using TX_ENABLE_EVENT_TRACE define. It must be added in thePreprocessor section of the compiler. This must be done for the application itself and for thelinked libraries (e.g. ThreadX library).




13


5.1.2 Declare the trace buffer

A buffer area for storing the trace events occurring at run-time must be specified and then furtherinstruct the ThreadX trace sub-system to use it. Buffer can be a global variable, just like in theexample below:

/* Trace buffer */

#ifdef TX_ENABLE_EVENT_TRACE

UCHAR trace_buffer[64000];

#endif

5.1.3 Enable trace

Trace must be explicitly enabled inside the application by calling tx_trace_enable(). This can beachieved by adding the code like in the screenshot below:

#ifdef TX_ENABLE_EVENT_TRACE

/*

* Enable event tracing using the global "trace_buffer".

* Allow a maximum of 30 ThreadX objects in the registry.

*/

UINT status = tx_trace_enable(&trace_buffer, sizeof(trace_buffer), 30);

if (status != TX_SUCCESS ) {

for (;;) { }

}

#endif




14


Note It is recommended to enable trace inside tx_application_define().

5.2 Exporting Trace

5.2.1 Configuration of Trace Export feature

Trace Export feature is controlled by a list of preferences that can be accessed and furthermodified via Window -> Preferences page. These preferences were added for being able to adaptthe feature to any custom setup but in most of the situations the default values can be safelyused. The available preferences are depicted in the picture below.

5.2.2 Trace Export button

Trace Export button is located in the Debug view’s toolbar, as illustrated in the screenshot below.




15


Its visibility depends on the type/nature of the project. It is designed to be visible when debuggingan Azure RTOS project from an MCUXpresso SDK package.

Enablement of the button depends on the existence of some clearly defined symbols inside theexecutable – see Configuration of Trace Export feature [15].

5.2.3 Exporting Trace

Once the Trace Export button is clicked, a modal dialog window will be presented. It will pick thepreferences' values mentioned above and allow one-time change for any of them. Note that anychange will not be persisted inside the workspace area.

A file path must be specified and then click the Export trace button. The exported file can beimported in Azure RTOS TraceX tool afterwards.




16


6. Legal informationInformation in this document is provided solely to enable system and software implementers touse NXP products. There are no express or implied copyright licenses granted hereunder todesign or fabricate any integrated circuits or integrated circuits based on the information in thisdocument.

NXP makes no warranty, representation, or guarantee regarding the suitability of its products forany particular purpose, nor does NXP assume any liability arising out of the application or use ofany product or circuit, and specifically disclaims any and all liability, including without limitationconsequential or incidental damages. “Typical” parameters that may be provided in NXP datasheets and/or specifications can and do vary in different applications, and actual performancemay vary over time. All operating parameters, including “Typicals”, must be validated foreach customer application by customer’s technical experts. NXP does not convey any licenseunder its patent rights nor the rights of others. NXP sells products pursuant to standard termsand 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 tounidentified vulnerabilities. Customers are responsible for the design and operation of theirapplications and products to reduce the effect of these vulnerabilities on customer’s applicationsand products, and NXP accepts no liability for any vulnerability that is discovered. Customersshould implement appropriate design and operating safeguards to minimize the risks associatedwith their applications and products.

NXP, the NXP logo, Freescale, the Freescale logo, Kinetis and Tower are trademarks of NXPB.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 theMicrosoft group of companies. FreeRTOS™ and FreeRTOS.org™ are trade marks of AmazonWeb Services, Inc. SEGGER Embedded Studio is a trademark of SEGGER MicrocontrollerGmbH. J-Link is a trademark of SEGGER MICROCONTROLLER GMBH & CO. KG IARtrademark is owned by IAR Systems AB. Java and all Java-based trademarks are trademarksof Oracle Corporation in the United States, other countries, or both. Linux is the registeredtrademark of Linus Torvalds in the U.S. and other countries. UNIX is a registered trademarkof The Open Group in the United States and other countries. Eclipse, CDT are trademarks ofEclipse Foundation, Inc.

© NXP B.V. 2016-2022. All rights reserved.

How To Reach Us:

Home Page: https://www.nxp.com

Web Support: https://www.nxp.com/support




17

https://www.nxp.com/SalesTermsandConditions

https://www.nxp.com/SalesTermsandConditions

https://www.nxp.com

https://www.nxp.com/support

mcuxpresso ide azure rtos threadx debug guide - nxp

Documents