Overview

In a development environment the EVK board may be programmed via a JTAG/SWD interface or via RedBoot loaded from boot memory.

When debugging via JTAG, you may need to disable the default HAL idle thread action, otherwise there may be issues where the target fails to halt and the debugging session is unreliable. More details can be found in the Cortex-M architectural HAL. If you are debugging via SWD this should not be necessary. When using hardware debug we recommend that the board SW7 DIP switches (1234) are used to select SD card boot (ON OFF ON OFF). Without an SD card installed, this will have the useful side effect of causing the processor to pause in the ROM loader. It avoids potential issues caused by any pre-installed firmware re-configuring the SoC as part of the ROM Bootloader process.

For debugging, applications are loaded and then executed on the board via the debugger arm-eabi-gdb, or via the Eclipse IDE. The following describes setting up to use OpenOCD with GDB.

OpenOCD

	Note
	As mentioned in the Overview section, if there is unknown firmware already installed in the bootable QSPI then it is worth ensuring that it does not interfere with the H/W debug session by changing the SW7 bootstrap selection to disable QSPI execution, until a known eCos application has been installed in the bootable flash.

To debug via OpenOCD the etc/openocd.cfg from the build install directory should be used. Running OpenOCD on a host connected to the board via a suitable cable should produce something similar to the following:

$ openocd -f openocd.cfg
Open On-Chip Debugger 0.11.0-2 (eCosCentric 2021-06-15)
Licensed under GNU GPL v2
For bug reports, read
  http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 1.10
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : clock speed 1000 kHz
Info : SWD DPIDR 0x0bd11477
Info : imxrt1050.cpu: hardware has 8 breakpoints, 4 watchpoints
Info : starting gdb server for imxrt1050.cpu on 3333
Info : Listening on port 3333 for gdb connections

When subsequently connecting via GDB, the output similar to the following will be seen from the OpenOCD session:

Info : accepting 'gdb' connection on tcp/3333

Initialising CPU...
target halted due to debug-request, current mode: Thread
xPSR: 0x21000000 pc: 0x2020e3a8 psp: 0x2023f728
force hard breakpoints
Note: Breakpoints limited to 8 hardware breakpoints
Disable Caches
Initialising SDRAM

semihosting is enabled

As can be see from the “Initialising SDRAM” above, the default CDL behaviour is to install the SDRAM initialising OpenOCD configuration script. This ensures that applications configured for the JSDRAM or RBRAM startup types can be loaded directly via GDB and OpenOCD for debugging, without requiring staging via a second-level boot loader.

See OpenOCD scripts for notes regarding the OpenOCD scripts.

PEEDI

For the Ronetix PEEDI, the peedi.mimxrt1064_evk.cfg or peedi.imxrt1050_evkb.cfg file respectively should be used to setup and configure the MIMXRT1064-EVK and IMXRT1050-EVKB hardware to an appropriate state to load programs. These files only perform basic initialization by default, leaving application code to initialize PLLs and other clocks. However, these files do include an initialization section to configure SDRAM.

The configuration files also contains an option to define whether hardware or software breakpoints are used by default, using the CORE0_BREAKMODE directive in the [PLATFORM_Cortex-M_SWD] section. Edit this file if you wish to use hardware break points, and remember to restart the PEEDI to make the changes take effect.

Note

Normally, when shipped, the EVK platforms are configured to use the on-board CMSIS-DAP H/W debug interface via the micro-USB connector. If an external H/W debugger is being attached via the standard ARM 20-pin 2.54mm IDC debug connector (labelled J21 on RevA1 boards) then the corresponding H/W debug signal jumpers need to be adjusted accordingly. Please refer to the schematic or board documentation. For example, on the RevA1 MIMXRT1064-EVK board jumpers J47 through J50 control access to the external H/W debug signals.

On the PEEDI, debugging can be performed either via the telnet interface or using arm-eabi-gdb and the GDB interface. In the case of the latter, arm-eabi-gdb needs to connect to TCP port 9000 on the PEEDI's IP address. For example:

(gdb) target remote 111.222.333.444:9000

By default when the PEEDI is powered up, the target will always run the initialization section of the configuration file, and halts the target. This behaviour is repeated with the PEEDI reset command.

If the board is reset (either with the 'reset', or by pressing the reset button) and the 'go' command is then given, then the board will boot as normal and run from the contents of the flash.

Consult the PEEDI documentation for information on other features.

H/W Debugging

Currently the standalone startup types, where H/W debug can be used, default to outputting all diagnostics information via LPUART1. The default communications parameters are 115200 baud, no parity, 1 stop bit. It is recommended that LPUART1 be accessed via the virtual CDC-ACM communication device presented by the CMSIS-DAP port.

It is possible to arrange for diagnostics to be output via the H/W debug GDB connection and appear on the gdb console. This requires the configuration option CYGFUN_HAL_GDB_FILEIO in the common HAL package to be enabled. This has two sub-options, CYGSEM_HAL_DIAG_TO_GDBFILEIO_CHAN and CYGSEM_HAL_DIAG_VIA_GDB_FILEIO_IMMEDIATE, that are enabled by default when CYGFUN_HAL_GDB_FILEIO is enabled and both should remain enabled. In this case, when arm-eabi-gdb is attached to the PEEDI, the following gdb command must be issued:

(gdb) set hwdebug on

Eclipse users can do this by creating a GDB command file with the contents:

define preload
  set hwdebug on
end

This will be referenced from their Eclipse debug launch configuration. Using GDB command files is described in more detail in the "Eclipse/CDT for eCos application development" manual.

Installing RedBoot

RedBoot allows for S/W based debugging of applications over the LPUART1 diagnostic channel, or an Ethernet connection, via the GDB stubs support built into RedBoot. RedBoot is normally used to load+debug applications when a H/W debugger interface is not available. Since the IMX EVK boards provide an on-board CMSIS-DAP then RedBoot is not strictly required for debugging since a H/W debugger is always present. However, RedBoot also provides some functionality that may be required for the target use case (e.g. RBL (CYGPKG_RBL)).

	Warning
	The default RedBoot configuration enables Ethernet support to allow debug sessions over Ethernet. See the Supported Hardware warning about powering the board from an external PSU if RedBoot-with-Ethernet is being installed.

The following RedBoot installation process uses a H/W debug session with a RBSRAM RedBoot image to provide the flash access support for updating the bootable QSPI device. This approach of using a on-chip SRAM based RedBoot to provide flash write capability is applicable to any binary data that the developer wishes to install in flash (and in the case of the MIMXRT1064-EVK target the SiP QSPI as well as the external QSPI). For example, the SRAM based RedBoot can be used to write the BootUp bootable QSPI image as well as the binary (JSDRAM) application that BootUp will start.

Prebuilt RedBoot binaries are provided in the loaders/mimxrt1xxx_evk subdirectory of the eCosPro release installation. The host directory within this subdirectory includes the openocd.cfg OpenOCD configuration file used to load and execute RedBoot such that the QSPI flash boot image can be programmed into the bootable FlexSPI QSPI flash memory of the i.MX RT10XX boards.

Notes:

The IMXRT1050-EVKB hardware must be modified from its default (as shipped) HyperFlash configuration to enable QSPI access. This is documented in the relevant "MIMXRT1050-EVK Board Hardware User Guide". It involves removing and moving some 0 Ω resistors on the underside of the board. The MIMXRT1064-EVK requires no such modification since the external QSPI is already the default, and the RT1064 boots from the internal SiP flash anyway. Detailed instructions for rebuilding and programming your own version of RedBoot may be found in the section called “Rebuilding and Installing RedBoot” below.

In one shell window, start OpenOCD as described in the section called “OpenOCD” above, replacing openocd.cfg with the OpenOCD configuration file loaders/mimxrt1xxx_evk/host/openocd.cfg provided within the eCosPro installation directory.

Within a second shell window, open a suitable terminal application and connect to the CDC-ACM device provided by the CMSIS-DAP debug USB interface.

Within a third shell window, as illustrated in the figure below, change to the loaders/mimxrt1xxx_evk subdirectory of the eCosPro release installation, run cksum to note the checksum and size of the QSPI boot image, and load the (RBSRAM) RedBoot ELF prebuilt image into the target using OpenOCD and GDB.

$ cd eCos-4.x.y/loaders/mimxrt1050_evk
$ cksum qspi_boot.bin
2434204827 111164 qspi_boot.bin
$ arm-eabi-gdb redboot_RBSRAM.elf
GNU gdb (eCosCentric GNU tools 7.3.0e) 8.1
Copyright (C) 2018 Free Software Foundation, Inc.
... elided ...
Reading symbols from redboot_RBSRAM.elf...done.
(gdb) tar extended-rem localhost:3333
Remote debugging using localhost:3333
0x2020c330 in hal_delay_us (us=100) at .../packages/hal/cortexm/arch/current/src/hal_misc.c:609
(gdb) load
Loading section .rom_vectors, size 0x8 lma 0x20209020
Loading section .text, size 0xc080 lma 0x20209028
Loading section .rodata, size 0x36f8 lma 0x202150a8
Loading section .data, size 0x634 lma 0x202187a0
Start address 0x20209028, load size 64948
Transfer rate: 42 KB/sec, 9278 bytes/write.
(gdb) cont
Continuing.

From the cksum result above you can see the checksum and size of the QSPI boot image which are 2434204827 and 111164 respectively. On the second shell window running the terminal application, RedBoot output similar to the following should appear.

RedBoot(tm) bootstrap and debug environment [RBSRAM]
eCosCentric certified release, version 4.6.6 - built 15:15:21, Mar 17 2022

Copyright (C) 2000-2009 Free Software Foundation, Inc.
Copyright (C) 2003-2022 eCosCentric Limited
The RedBoot bootloader is a component of the eCos real-time operating system.
Want to know more? Visit www.ecoscentric.com for everything eCos & RedBoot related.
This is free software, covered by the eCosPro Non-Commercial Public License
and eCos Public License. You are welcome to change it and/or distribute copies
of it under certain conditions. Under the license terms, RedBoot's source code
and full license terms must have been made available to you.
Redboot comes with ABSOLUTELY NO WARRANTY.

Platform: NXP MIMXRT1050-EVK (Cortex-M7)
RAM: 0x20200000-0x2023f000 [0x20220b40-0x2023b000 available]
     0x20240000-0x20280000 [0x20240000-0x20280000 available]
     0x80000000-0x82000000 [0x80000000-0x82000000 available]
FLASH: 0x60000000-0x607fffff, 2048 x 0x1000 blocks
RedBoot>

The naming and RAM and FLASH areas reported will depend on the target board.

RedBoot is now running on the NXP EVK and may be interacted with through the terminal application. The RedBoot output shows the available RAM that can be used as a temporary load buffer for the RedBoot QSPI boot image. In the example above the spaces 0x20240000-0x20280000 and 0x80000000-0x82000000 are available. The flash can now be initialised using RedBoot with the following flash initialisation issued at the RedBoot> prompt within the terminal application.

	Note
	Change your responses below accordingly if using DHCP/BOOTP or provide your own IP addresses and netmask for the gateway, server and local address of NXP EVK.

RedBoot> fconfig -i
Initialize non-volatile configuration - continue (y/n)? y
Run script at boot: false
Use BOOTP for network configuration: false
Gateway IP address: 192.168.1.1
Local IP address: 192.168.1.5
Local IP address mask: 255.255.255.0
Default server IP address: 192.168.1.2
Console baud rate: 115200
GDB connection port: 9000
Force console for special debug messages: false
Network debug at boot time: false
Default network device: enet0_eth
Update RedBoot non-volatile configuration - continue (y/n)? y
... Erase from 0x607fe000-0x607fefff: .
... Program from 0x20231000-0x20232000 to 0x607fe000: .
RedBoot>

Once the flash is initialised perform the following actions, as illustrated in Figure 313.12, “Loading RedBoot QSPI boot image into memory”:

The steps above are just a simple mechanism to use the GDB debug connection to load an arbitrary binary from the host machine into the target board memory.

...
(gdb) cont
Continuing.
^C
Program received signal SIGINT, Interrupt.
0x2020c330 in hal_delay_us (us=76) at .../packages/hal/cortexm/arch/current/src/hal_misc.c:609
(gdb) restore qspi_boot.bin binary 0x20240000
Restoring binary file qspi_boot.bin into memory (0x20240000 to 0x202524ac)
(gdb) cont
Continuing.

Within the RedBoot terminal, confirm the image has been loaded correctly into memory by performing a checksum of the memory region into which the QSPI boot image was loaded by GDB and compare these results with the results from the cksum application as illustrated in Figure 313.9, “Checksum of QSPI image and Execution of RedBoot”. The RedBoot cksum command requires the base address of the memory region (0x20240000 as used above) as well as the size of the region (111164 in our example).

RedBoot> cksum -b 0x20240000 -l 111164
POSIX cksum = 2434204827 111164 (0x9117049b 0x000124ac)

As you can see the checksum values 2434204827 from both sources match. Instruct RedBoot to program the bootable QSPI flash with the image in memory as shown below.

	Note
	For the IMXRT1050-EVKB external QSPI the bootable flash base address is 0x60000000. For the MIMXRT1064-EVK SiP flash the base address is 0x70000000.

RedBoot> fis write -f 0x60000000 -b 0x20240000 -l 111164
* CAUTION * about to program FLASH
            at 0x60000000..0x60012fff from 0x20240000 - continue (y/n)? y
... Erase from 0x60000000-0x60012fff: ...................
... Program from 0x20240000-0x20253000 to 0x60000000: ...................

At this point RedBoot has been programmed into the QSPI flash. The GDB session as well as OpenOCD must now be terminated using the ctrl-C keystroke combination in each window to interrupt and terminate the application. Assuming the SW7 is set to OFF, OFF, ON, OFF for QSPI boot selection then on the next hardware reset the system will boot (the RBSRAM) RedBoot from the QSPI copy automatically. The output illustrated in Figure 313.10, “RedBoot Output” will again be seen in the window executing the terminal application and normal interaction with RedBoot may again occur.

Finally, terminate the terminal application to release the CDC-ACM interface and enable both GDB and Eclipse to make use of the interface to download and debug user applications.

Rebuilding and Installing RedBoot

The following process is actually applicable to any standalone application that needs to be programmed into the FlexSPI QSPI flash memory and started from CPU reset, not just the special RBSRAM RedBoot startup type. For example, a different second-level boot loader or the final standalone (SRAM) application. The RBSRAM is for RedBoot configurations that execute from SRAM and can be directly started by the i.MX RT ROM bootloader, with RBRAM being used for RedBoot configurations that execute from SDRAM and are started via a second-level boot loader (e.g. BootUp, a RBSRAM RedBoot or a customer specific boot loader application). See the section called “Startup” for an overview of the different application startup types.

See the Notes: from the previous section with regards to IMXRT1050-EVKB QSPI support.

RedBoot can be configured to reside+execute from SRAM (OCRAM) or the external SDRAM. A RBSRAM RedBoot application should be configured and built using the redboot_RBSRAM.ecm file provided in the packages/hal/cortexm/imx/mimxrt1xxx_evk/current/misc subdirectory of the eCosPro installation. Correspondingly a SDRAM resident RedBoot application should be configured and built using the redboot_RBRAM.ecm configuration fragment.

However, since the decision to keep a single RAM startup type for applications loaded into SDRAM and executed under RedBoot regardless of whether a SRAM or SDRAM RedBoot is active means that the RedBoot SRAM allocation is always set aside. This means that there is no substantive benefit from an SDRAM based RedBoot currently. So the following example just documents the RBSRAM case.

Should it prove necessary to rebuild a RedBoot binary, this is done most conveniently at the command line. The steps needed to rebuild the SRAM version of RedBoot are:

$ mkdir redboot_rbsram
$ cd redboot_rbsram
$ ecosconfig new mimxrt1050_evk redboot
[ … ecosconfig output elided … ]
$ ecosconfig import $ECOS_REPOSITORY/hal/cortexm/imx/mimxrt1xxx_evk/VERSION/misc/redboot_RBSRAM.ecm
$ ecosconfig tree
$ make

The standard make build process will create a binary version of the RedBoot application alongside the ELF version used for debugging. The install/bin subdirectory should contain the file redboot.bin which will be used when building the boot image. The example above targets the mimxrt1050_evk platform, but the same process can be used by replacing with the mimxrt1064_evk platform name.

Create a QSPI boot image from this RBSRAM RedBoot binary as follows:

$ flashimg_rt10 --qspi install/bin/redboot.bin install/bin/qspi_boot.bin

Notes:

Prebuilt host executables of the flashimg_rt10 are located in the loaders/mimxrt1050_evk/host subdirectory of the eCosPro installation directory. Ensure these executables are either in the host's PATH or provide the full or relative path to the executable relevant to your host's operating system when executing the above command. The --qspi parameter is required to ensure the correct layout and contents of boot ROM descriptor structures to allow the application to be booted from the QSPI device. If using the prebuilt RedBoot images provided in the release, the filenames redboot_RBSRAM.elf, redboot_RBSRAM.bin and its flashimg_rt10 derivative qspi_boot.bin within the loaders/mimxrt1050_evk subdirectory should be referenced in place of the files install/bin/redboot.elf, install/bin/redboot.bin and install/bin/qspi_boot.bin respectively in the examples below.

The simplest approach for installing the boot image is to use the onboard CMSIS-DAP debug interface and GDB to load the boot image into memory and use the RBSRAM RedBoot itself to initialise the flash. See the OpenOCD section for an overview of starting the necessary GDB server, and the Installing RedBoot section for an example of using RedBoot to flash an image.

Further application installation examples

The following are just examples of some possible use cases that may helpful in providing an overview for developers.

$ arm-eabi-objcopy -O binary app.elf app.bin

$ flashimg_rt10 --qspi app.bin qspi_boot.bin

$ arm-eabi-objcopy -O binary sdramapp.elf sdramapp.bin