Mcuxpresso IDE Azure RTOS Threadx Debug Guide Rev

MCUXpresso IDE Azure RTOS ThreadX Debug Guide Rev. 11.4.1 — 15 September, 2021 User guide NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

15 September, 2021

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 ii NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

1. Introduction ...... 1 2. LinkServer Azure RTOS ThreadX Thread Aware Debugging ...... 2 2.1. Behavior when thread aware debugging ...... 4 2.2. Debugger Messages ...... 5 2.3. Switching between all-stop and non-stop debug modes ...... 6 3. Azure RTOS ThreadX Thread Aware Debug Views ...... 7 3.1. Showing the Azure RTOS ThreadX TAD Views ...... 7 3.2. Threads View ...... 8 3.3. Message Queues View ...... 8 3.4. Semaphores View ...... 9 3.5. Mutexes View ...... 9 3.6. Event Flags View ...... 10 3.7. Timers View ...... 10 3.8. Memory Block Pools View ...... 10 3.9. Memory Byte Pools View ...... 11 3.10. Timeouts ...... 11 4. Thread Aware Debugging with Other Debug Probes ...... 12 4.1. PEmicro Probes ...... 12 4.2. SEGGER J-Link Probes ...... 12 5. Exporting Azure RTOS ThreadX Trace ...... 13 5.1. Enabling Trace Inside the Application ...... 13 5.1.1. Add required preprocessor symbols ...... 13 5.1.2. Declare the trace buffer ...... 14 5.1.3. Enable trace ...... 14 5.2. Exporting Trace ...... 15 5.2.1. Configuration of Trace Export feature ...... 15 5.2.2. Trace Export button ...... 15 5.2.3. Exporting Trace ...... 16 6. Legal information ...... 17

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 iii NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

1. Introduction

Azure RTOS is one of the real-time operating systems (RTOS) that is delivered with some of the MCUXpresso SDK packages. It is an advanced real-time OS designed for embedded applications 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 MCUXpresso SDK packages.

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

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

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 1 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

2. LinkServer Azure RTOS ThreadX Thread Aware Debugging

When debugging via LinkServer debug probes, the MCUXpresso IDE debugger can provide Azure RTOS ThreadX thread aware debug if : 1. 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.

2. No changes are made inside TX_THREAD_STRUCT data structure that could impact debugger’s ability to determine available threads from the ThreadX sub-system.

Note: 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 Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 2 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 3 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

2.1 Behavior when thread aware debugging

MCUXpresso IDE LinkServer Azure RTOS ThreadX thread aware debugging is available once the ThreadX scheduler has started (so will not appear straight after loading the application when the default breakpoint on main() is reached). Debug works in stop mode. In other words, if execution 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 the background. The register context for any thread is available in the Registers view. For suspended or blocked threads, the register context is the context in effect when the thread was swapped out, 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 is also available:

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 4 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

2.2 Debugger Messages

LinkServer Azure RTOS ThreadX Thread Aware Debugging requires that the debug session is carried out in All-Stop mode. If this precondition is met, then when you start your debug session, confirmation that LinkServer Azure RTOS ThreadX 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) Azure RTOS ThreadX stack backtrace is enabled ...

as shown in the screenshot below:

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 5 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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 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 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 Azure RTOS ThreadX 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

Any further debug sessions of your project will now use the newly selected debug mode.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 6 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

3. Azure RTOS ThreadX Thread Aware Debug Views

MCUXpresso IDE includes several additional Views to further simplify Azure RTOS application debugging, known collectively as the Azure RTOS ThreadX TAD (Thread Aware Debugger for GDB): • 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 GDB commands 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 the MCUXpresso IDE.

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.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 7 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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:

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 8 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 9 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

• 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.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 10 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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 shown below:

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 11 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

4. Thread Aware Debugging with Other Debug Probes

4.1 PEmicro Probes

Azure RTOS ThreadX thread aware debugging with PEmicro probes is not yet supported but planned to be incorporated in a forthcoming PEmicro release.

4.2 SEGGER J-Link Probes

Azure RTOS ThreadX thread aware debugging with JLink probes is not yet supported but planned to be incorporated in a forthcoming MCUXpresso IDE release. Support will be delivered as a separate plugin extension for the JLink GDB server.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 12 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

5. Exporting Azure RTOS ThreadX Trace

The Azure RTOS ThreadX offers support for collecting system and application events that occur during run-time. Data is initially stored in the target memory and then must be transferred on the host machine for inspection. Decoding of trace data is done using Microsoft’s Azure RTOS TraceX 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 data can 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. Current procedure 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 the Preprocessor section of the compiler. This must be done for the application itself and for the linked libraries (e.g. ThreadX library).

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 13 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

5.1.2 Declare the trace buffer

A buffer area for storing the trace events occurring at run-time must be specified and then further instruct the ThreadX trace sub-system to use it. Buffer can be a global variable, just like in the example 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 be achieved 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

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 14 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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 further modified via Window -> Preferences page. These preferences were added for being able to adapt the feature to any custom setup but in most of the situations the default values can be safely used. 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.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 15 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

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

Enablement of the button depends on the existence of some clearly defined symbols inside the executable – 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 the preferences' values mentioned above and allow one-time change for any of them. Note that any change 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 be imported in Azure RTOS TraceX tool afterwards.

MCUXpresso IDE Azure RTOS ThreadX Debug Guide - All information provided in this document is subject to legal disclaimers © 2021 NXP Semiconductors. All rights reserved. User Guide Rev. 11.4.1 — 15 September, 2021 16 NXP Semiconductors MCUXpresso IDE Azure RTOS ThreadX Debug Guide

6. 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: http:// 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. FreeRTOSTM and FreeRTOS.orgTM 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.

How To Reach Us:

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

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