Skip to main content

Cortex-M JTAG Debugging

Introduction​

This article describes how to debug firmware running on Cortex-M cores using JTAG and SEGGER J-Link hardware.

The following Toradex hardware platforms are supported:

This article complies with the Typographic Conventions for Toradex Documentation.

Prerequisites​

To install the J-Link Software and GDB Server, follow the steps below:

  1. Install dependency packages:

    Recent operating systems don't include the required Python 3.6 development libraries for the GDB server. To compile it manually, select a folder to install the library and run the following commands:

    $ cd ~
    $ export PREFIX=/home/$USER/python3.6
    $ wget https://www.python.org/ftp/python/3.6.14/Python-3.6.14.tgz
    $ tar xf Python-3.6.14.tgz
    $ mkdir -p $PREFIX && cd $PREFIX
    $ ~/Python-3.6.14/configure --prefix=$PREFIX --enable-shared
    $ make -j$(nproc)
    $ make install

    After the manual installation, run the following command to check if the shared library was compiled successfully:

    $ find . -name libpython3.6m.so.1.0
    ./libpython3.6m.so.1.0
    ./lib/libpython3.6m.so.1.0

    Finally, export the library path:

    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/$USER/python3.6/lib

  2. Download the J-Link Software from Segger website: J-Link Software and Documentation Pack

    info

    This article assumes a Linux host. Other host operating systems may also work as expected, but are not covered here.

  3. Install the J-Link Software:

    $ sudo apt install ./JLink_Linux_<PACKET_VERSION>.deb

JTAG Debug for Cortex-M​

Compiling the firmware image generates the hello_world.elf file, which should be used for debugging instead of the hello_world.bin file. After compiling the firmware image, boot the target module and access the U-Boot terminal to set up the JTAG connection.

Run the Debugger​

  1. Connect the J-Link to your board using the JTAG connector. Refer to the table below for the pinout and connection details for each module:

    Carrier BoardJTAG Connector
    Apalis Evaluation BoardX33
    Colibri Evaluation BoardX13
    Dahlia Carrier BoardX8
    Verdin Development BoardX56
    danger

    Do not use the on-board debugger and an external JTAG debugger at the same time. Before connecting an external JTAG debugger, configure the board as follows:

    Simultaneous use of the on-board debugger and an external JTAG debugger may damage the debuggers or the carrier board.

  2. After connecting the J-Link to the board, run the J-Link GDB Server:

    $ JLinkGDBServer -if JTAG -device MIMX8ML8_M7

  3. After initializing the JLinkGDBServer, connect to the target module and run the hello_world application using the arm-none-eabi-gdb tool from the MCUXpresso SDK:

    $ arm-none-eabi-gdb hello_world.elf

    GNU gdb (GNU Toolchain for the Arm Architecture 11.2-2022.02 (arm-11.14)) 11.2.90.20220202-git
    Copyright (C) 2022 Free Software Foundation, Inc.
    License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    Type "show copying" and "show warranty" for details.
    This GDB was configured as "--host=x86_64-pc-linux-gnu --target=arm-none-eabi".
    Type "show configuration" for configuration details.
    For bug reporting instructions, please see:
    <https://bugs.linaro.org/>.
    Find the GDB manual and other documentation resources online at:
        <http://www.gnu.org/software/gdb/documentation/>.

    For help, type "help".
    Type "apropos word" to search for commands related to "word"...
    Reading symbols from hello_world.elf...
    (gdb)

  4. After loading the GDB server and connecting to the target module, run the following commands to load the firmware and start debugging:

    (gdb) target remote localhost:2331
    (gdb) monitor reset
    (gdb) monitor halt
    (gdb) load

  5. Finally, the application is now downloaded and halted at the reset vector. It is possible to start the demo application by running the monitor go command or to run the firmware step by step using the step command, as shown below:

    (gdb) step
    (gdb) monitor go

    As a result, the "hello world." message successfully appears on the alternative core debug terminal:

    hello world.

Next Steps​

Follow the HMP RPMsg Guide article to learn how to use the Remote Processor Messaging (RPMsg) protocol for communication between the alternative and main cores.

Send Feedback!