NXP AN14120 Debugging Cortex-M Software User Guide

NXP AN14120 Debugging Cortex-M Software User Guide

Introduction

This document describes cross-compiling, deploying, and debugging an application for the i.MX 8M Family, i.MX 8ULP, and i.MX 93 Cortex-M processor using Microsoft Visual Studio Code.

Software environment

The solution could be implemented both on the Linux and Windows host. For this application note, a Windows PC is assumed, but not mandatory.
Linux BSP release 6.1.22_2.0.0 is used in this application note. The following prebuild images are used:

• i.MX 8M Mini: imx-image-full-imx8mmevk.wic
• i.MX 8M Nano: imx-image-full-imx8mnevk.wic
• i.MX 8M Plus: imx-image-full-imx8mpevk.wic
• i.MX 8ULP: imx-image-full-imx8ulpevk.wic
• i.MX 93: imx-image-full-imx93evk.wic

For detailed steps on how to build these images, refer to i.MX Linux User’s Guide (document IMXLUG) and i.MX Yocto Project User’s Guide (document IMXLXYOCTOUG).
If a Windows PC is used, write the prebuild image on the SD card using Win32 Disk Imager (https:// win32diskimager.org/) or Balena Etcher (https://etcher.balena.io/). If an Ubuntu PC is used, write the prebuild image on the SD card using the below command:

$ sudo dd if=.wic of=/dev/sd bs=1M status=progress conv=fsync

Note : Check your card reader partition and replace sd with your corresponding partition. 1.2

Hardware setup and equipment

• Development kit:
  • NXP i.MX 8MM EVK LPDDR4
  • NXP i.MX 8MN EVK LPDDR4
  • NXP i.MX 8MP EVK LPDDR4
  • NXP i.MX 93 EVK for 11×11 mm LPDDR4 – NXP i.MX 8ULP EVK LPDDR4
• Micro SD card: SanDisk Ultra 32-GB Micro SDHC I Class 10 is used for the current experiment.
• Micro-USB (i.MX 8M) or Type-C (i.MX 93) cable for debug port.
• SEGGER J-Link debug probe.

Prerequisites

Before starting to debug, several prerequisites must be met to have a properly configured debug environment.
PC Host – i.MX board debug connection
To establish the hardware debug connection, perform the following steps:

1. Connect the i.MX board to the host PC via the DEBUG USB-UART and PC USB connector using a USB cable. The Windows OS finds the serial devices automatically.
2. In Device Manager, under Ports (COM & LPT) find two or four connected USB Serial Port (COM ). One of the ports is used for the debug messages generated by the Cortex-A core, and the other is for the Cortex-M core. Before determining the right port needed, remember:
   • [i.MX 8MP, i.MX 8ULP, i.MX 93]: There are four ports available in Device Manger. The last port is for Cortex-M debug and the second to last port is for Cortex-A debug, counting debug ports in ascending order.
   • [i.MX 8MM, i.MX 8MN]: There are two ports available in Device Manager. The first port is for Cortex-M debug and the second port is for Cortex-A debug, counting debug ports in ascending order.
3. Open the right debug port using your preferred serial terminal emulator (for example PuTTY) by setting the following parameters:
   • Speed to 115200 bps
   • 8 data bits
   • 1 stop bit (115200, 8N1)
   • No parity
4. Connect the SEGGER debug probe USB to the host, then connect the SEGGER JTAG connector to i.MX board JTAG interface. If the i.MX board JTAG interface has no guided connector, the orientation is determined by aligning the red wire to the pin 1, as in Figure 1.
   

VS Code configuration

To download and configure the VS Code, perform the following steps:

1. Download and install the latest version of Microsoft Visual Studio Code from the official website. In case of using Windows as the host OS, choose the “Download for Windows” button from the Visual Studio Code main page.
   

2. After installing Visual Studio Code, open it and choose the “Extensions” tab or press the Ctrl + Shift + X combination.

3. In the dedicated Search bar, type MCUXpresso for VS Code and install the extension. A new tab appears in the left side of VS Code window.
   

MCUXpresso extension configuration

To configure MCUXpresso extension, perform the following steps:

1. Click the MCUXpresso extension dedicated tab from the left side bar. From the QUICKSTART PANEL, click
   Open MCUXpresso Installer and give permission for downloading the installer.

2. The installer window appears in a short time. Click MCUXpresso SDK Developer and on SEGGER JLink then click the Install button. The installer installs the needed software for archives, toolchain, Python support, Git, and debug probe

After all packages are installed, be sure that the J-Link probe is connected to the host PC. Then, check if the probe is also available in the MCUXpresso extension under DEBUG PROBES view, as shown in Figure

Import MCUXpresso SDK

Depending on what board you are running, build and download the specific SDK from NXP official website. For this application note, the following SDKs have been tested:

• SDK_2.14.0_EVK-MIMX8MM
• SDK_2.14.0_EVK-MIMX8MN
• SDK_2.14.0_EVK-MIMX8MP
• SDK_2.14.0_EVK-MIMX8ULP
• SDK_2.14.0_MCIMX93-EVK

To build an example for i.MX 93 EVK, see Figure 7:

1. To import an MCUXpresso SDK repository in VS Code, perform the following steps:

2. After downloading the SDK, open Visual Studio Code. Click the MCUXpresso tab from the left side, and expand the INSTALLED REPOSITORIES and PROJECTS views.

3. Click the Import Repository and select LOCAL ARCHIVE. Click the Browse… corresponding to the Archive field and select the recently downloaded SDK archive.

4. Select the path where the archive is unzipped and fill in the Location field.

5. The Name field can be left by default, or you can choose a custom name.

6. Check or uncheck Create Git repository based on your needs and then click Import.

Import an example application

When the SDK is imported, it appears under the INSTALLED REPOSITORIES view.
To import an example application from the SDK repository, perform the following steps:

1. Click the Import Example from Repository button from the PROJECTS view.

2. Choose a repository from the drop-down list.

3. Choose the toolchain from the drop-down list.

4. Choose the target board.

5. Choose the demo_apps/hello_world example from the Choose a template list.
   

6. Choose a name for the project (the default can be used) and set the path to project Location.

7. Click Create.

8. Perform the following steps for i.MX 8M Family only. Under the PROJECTS view, expand the imported project. Go to the Settings section and click the mcuxpresso-tools.json file.
   a. Add “interface”: “JTAG” under “debug” > “segger”
   b. For i.MX 8MM, add the following configuration: “device”: “MIMX8MM6_M4” under “debug” > “segger”
   c. For i.MX 8MN, add the following configuration: “device”: “MIMX8MN6_M7” under “debug” > “segger”
   d. For i.MX 8MP, add the following configuration:
   
   “device”: “MIMX8ML8_M7” under “debug” > “segger”
   The following code shows an example for i.MX8 MP “debug” section after the above modifications of mcuxpresso-tools.json were performed:

After importing the example application successfully, it must be visible under the PROJECTS view. Also, the project source files are visible in the Explorer (Ctrl + Shift + E) tab.

Building the application

To build the application, press the left Build Selected icon, as shown in Figure 9.

Prepare the board for the debugger

To use the JTAG for debugging Cortex-M applications, there are a few prerequisites depending on the platform:

1. For i.MX 93
   To support i.MX 93, the patch for SEGGER J-Link must be installed: SDK_MX93_3RDPARTY_PATCH.zip.
   Note: This patch must be used, even if it is installed in the past. After the download has finished, unzip the archive and copy the Devices directory and the JLinkDevices.xml file to C:\Program Files\SEGGER\JLink. If a Linux PC is used, the target path is /opt/SEGGER/JLink.

   • Debugging Cortex-M33 while only Cortex-M33 is running
     In this mode, the boot mode switch SW1301[3:0] must be set to [1010]. Then the M33 image can be directly loaded and debugged using the debug button. For more details, see Section 5.
     If Linux running on Cortex-A55 is needed in parallel with Cortex-M33, there are two ways of debugging Cortex-M33:

   • Debugging Cortex-M33 while Cortex-A55 is in U-Boot
     First, copy the sdk20-app.bin file (located in the armgcc/debug directory) generated in Section 3 into the boot partition of the SD card. Boot the board and stop it in U-Boot. When the boot switch is configured to boot Cortex-A, the boot sequence does not start the Cortex-M. It has to be kicked off manually using the commands below. If Cortex-M is not started, JLink fails to connect to the core.
     

   • Note: If the system cannot be debugged normally, try to right-click the project in the MCUXpresso for VS
     Code and choose “Attach to debug the project”.

   • Debugging Cortex-M33 while Cortex-A55 is in Linux
     The Kernel DTS must be modified to disable the UART5, which uses the same pins as the JTAG interface.
     If a Windows PC is used, the easiest is to install WSL + Ubuntu 22.04 LTS, and then to cross-compile the DTS.
     After the WSL + Ubuntu 22.04 LTS installation, open the Ubuntu machine running on WSL and install the required packages:
     
     Now, the Kernel sources can be downloaded:
     
     To disable the UART5 peripheral, search for lpuart5 node in the linux- imx/arch/arm64/boot/ dts/freescale/imx93-11×11-evk.dts file and replace the okay status with disabled:
     Recompile the DTS:
     
     Copy the newly created linux-imx/arch/arm64/boot/dts/freescale/imx93 11×11-evk.dtb file on the boot partition of the SD card. Copy the hello_world.elf file (located in the armgcc/debug directory) generated in Section 3 into the boot partition of the SD card. Boot the board in Linux. Since boot ROM does not kick off the Cortex-M when Cortex-A boots, the CortexM must be manually started.
     
     Note : The hello_ world.elf file must be placed in the /lib/firmware directory.

2. For i.MX 8M
   To support i.MX 8M Plus, the patch for SEGGER J-Link must be installed:
   iar_segger_support_patch_imx8mp.zip.
   After the download has finished, unzip the archive and copy the Devices directory and the
   JLinkDevices.xml file from the JLink directory to C:\Program Files\SEGGER\JLink. If a Linux PC
   is used, the target path is /opt/SEGGER/JLink.

   • Debugging Cortex-M while Cortex-A is in U-Boot
     In this case, nothing special must be done. Boot the board in U  Boot and jump to Section 5.

   • Debugging Cortex-M while Cortex-A is in Linux
     To run and debug the Cortex-M application in parallel with Linux running on Cortex-A, the specific clock must be assigned and reserved for Cortex-M. It is done from within U-Boot. Stop the board in U-Boot and run the below commands:
     

3. For i.MX 8ULP
   To support the i.MX 8ULP, the patch for SEGGER J-Link mustbe installed: SDK_MX8ULP_3RDPARTY_PATCH.zip.
   Note: This patch must be used even if it is installed in the past.
   After the download, unzip the archive and copy the Devices directory and the JLinkDevices.xml file to C:\Program Files\SEGGER\JLink. If a Linux PC is used, the target path is /opt/SEGGER/JLink. For i.MX 8ULP, due to the Upower unit, build the flash.bin using m33_image in our “VSCode” repo first. The M33 image can be found in {CURRENT REPO}\armgcc\debug\sdk20-app.bin. Refer to Section 6 from the Getting Started with MCUX presso SDK for EVK-MIMX8ULP and EVK9-MIMX8ULP in the SDK_2_xx_x_EVK-MIMX8ULP/docs on how to build the flash.bin image.
   Note: Use the M33 image in the active VSCode repo. Otherwise, the program does not attach properly. Right-click and choose “Attach”.
   

Running and debugging

After pressing the debug button, choose the Debug project configuration and the debugging session starts.

When a debugging session starts, a dedicated menu is displayed. The debugging menu has buttons for starting the execution until a breakpoint fires up, pause the execution, step over, step into, step out, restart, and stop.
Also, we can see local variables, register values, watch some expression, and check call stack and breakpoints
in the left-hand navigator. These function regions are under the “Run and Debug” tab, and not in MCUXpresso
for VS Code.

Note about the source code in the document

Example code shown in this document has the following copyright and BSD-3-Clause license:

Copyright 2023 NXP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials must be provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE

Legal information

Definitions

Draft — A draft status on a document indicates that the content is still
under internal review and subject to formal approval, which may result in modifications or additions. NXP Semiconductors does not give any representations or warranties as to the accuracy or completeness of information included in a draft version of a document and shall have no liability for the consequences of use of such information.

Disclaimers

Limited warranty and liability — Information in this document is believed to be accurate and reliable. However, NXP Semiconductors does not give any representations or warranties, expressed or implied, as to the accuracy or completeness of such information and shall have no liability for the consequences of use of such information. NXP Semiconductors takes no responsibility for the content in this document if provided by an information source outside of NXP Semiconductors. In no event shall NXP Semiconductors be liable for any indirect,  incidental, punitive, special or consequential damages (including – without limitation – lost profits, lost savings, business interruption, costs related to the removal or replacement of any products or rework charges) whether or not such damages are based on tort (including negligence), warranty, breach of contract or any other legal theory.
Notwithstanding any damages that customer might incur for any reason whatsoever, NXP Semiconductors’ aggregate and cumulative liability towards customer for the products described herein shall be limited in accordance with the Terms and conditions of commercial sale of NXP Semiconductors.

Right to make changes — NXP Semiconductors reserves the right to make changes to information published in this document, including  without limitation specifications and product descriptions, at any time and without notice. This document supersedes and replaces all information supplied prior to the publication hereof.

Suitability for use — NXP Semiconductors products are not designed, authorized or warranted to be suitable for use in life support, life critical or safety-critical systems or equipment, nor in applications where failure or malfunction of an NXP Semiconductors product can reasonably be expected to result in personal injury, death or severe property or environmental damage. NXP Semiconductors and its suppliers accept no liability for  inclusion and/or use of NXP Semiconductors products in such equipment or applications and therefore such inclusion and/or use is at the customer’s own risk.

Applications — Applications that are described herein for any of these
products are for illustrative purposes only. NXP Semiconductors makes no representation or warranty that such applications will be suitable for the specified use without further testing or modification.
Customers are responsible for the design and operation of their
applications and products using NXP Semiconductors products, and NXP Semiconductors accepts no liability for any assistance with applications or customer product design. It is customer’s sole responsibility  to determine whether the NXP Semiconductors product is suitable and fit for the customer’s applications and products planned, as well as for the planned application and use of customer’s third party customer(s). Customers should provide appropriate design and operating safeguards to minimize the risks associated with their applications and products.
NXP Semiconductors does not accept any liability related to any default, damage, costs or problem which is based on any weakness or default in the customer’s applications or products, or the application or use by customer’s third party customer(s). Customer is responsible for doing all necessary testing for the customer’s applications and products using NXP Semiconductors products in order to avoid a default of the applications and the products or of the application or use by customer’s third party.

Terms and conditions of commercial sale — NXP Semiconductors products are sold subject to the general terms and conditions of commercial sale, as published athttps://www.nxp.com/profile/terms, unless otherwise agreed in a valid written individual agreement. In case an individual agreement is concluded only the terms and conditions of the  respective agreement shall apply. NXP Semiconductors hereby expressly objects to applying the customer’s general terms and conditions with regard to the purchase of NXP Semiconductors products by customer.

Export control — This document as well as the item(s) described herein may be subject to export control regulations. Export might require a prior authorization from competent authorities.

Suitability for use in non automotive qualified products — Unless this document expressly states that this specific NXP Semiconductors
product is automotive qualified, the product is not suitable for automotive use. It is neither qualified nor tested in accordance with automotive testing or application requirements. NXP Semiconductors accepts no liability for inclusion and/or use of non-automotive qualified products in automotive equipment or applications.
In the event that customer uses the product for design-in and use in
automotive applications to automotive specifications and standards,
customer (a) shall use the product without NXP Semiconductors’ warranty of the product for such automotive applications, use and specifications, and (b) whenever customer uses the product for automotive applications beyond NXP Semiconductors’ specifications such use shall be solely at customer’s own risk, and (c) customer fully indemnifies NXP Semiconductors for any liability, damages or failed product claims resulting from customer design and use of the product for automotive applications beyond NXP Semiconductors’ standard warranty and NXP Semiconductors’ product specifications.

Translations — A non-English (translated) version of a document, including the legal information in that document, is for reference only. The English version shall prevail in case of any discrepancy between the translated and English versions.

Security — Customer understands that all NXP products may be subject to unidentified vulnerabilities or may support established security standards or specifications with known limitations. Customer is responsible for the design and operation of its applications and products throughout their lifecycles to reduce the effect of these vulnerabilities on customer’s applications and products. Customer’s responsibility also extends to other open and/or proprietary technologies supported by NXP products for use in customer’s applications. NXP accepts no liability for any vulnerability. Customer should regularly check security updates from NXP and follow up appropriately.
Customer shall select products with security features that best meet rules, regulations, and standards of the intended application and make the ultimate design decisions regarding its products and is solely responsible for compliance with all legal, regulatory, and security related requirements concerning its products, regardless of any information or support that may be provided by NXP. NXP has a Product Security Incident Response Team (PSIRT) (reachable at PSIRT@nxp.com) that manages the investigation, reporting, and solution release to security vulnerabilities of NXP products.
NXP B.V. — NXP B.V. is not an operating company and it does not distribute or sell products.

References

• Win32 Disk Imager - Download [Official Site]
• GitHub - nxp-imx/linux-imx: i.MX Linux kernel

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>