1 1. Overview
2 2. Requirements
- 2.1 2.1. Detailed Requirements
- 2.2 2.2. Detailed Non-Requirements
3 3. Design
4 4. Test Plan

1. Overview

The following is a high-level overview of the problem being resolved by this project:

This project develops support for booting from QSPI Flash in the Linux i.MX RT1170 BSP.

Note: This project is developed for MIXMRT1170-EVK board only. Since the MIXMRT1170-EVKB uses a different type of QSPI Flash, this AN does not apply to the EVKB boards.

2. Requirements

2.1.
Detailed Requirements

The following are the requirements for this project:

Support booting of U-Boot from QSPI Flash, with no reliance on presence of SD Card or any other storage devices.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: U-Boot Boot from QSPI Flash".
  Test: Section: "Test Plan: U-Boot Boot from QSPI Flash".
Support the U-Boot standard SPI Flash commands (the sf commands family) for QSPI Flash.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: U-Boot sf Commands".
  Test: Section: "Test Plan: U-Boot sf Commands".
Store the U-Boot environment in QSPI Flash.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: U-Boot Environment in QSPI Flash".
  Test: Section: "Test Plan: U-Boot Environment in QSPI Flash".
Support installation of the U-Boot images to the QSPI Flash using the IMXRT1170 Serial Downloader feature.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: Install U-Boot Images to the QSPI Flash using Serial Downloader".
  Test: Section: "Test Plan: Install U-boot Images to QSPI Flash".
Support installation of the Linux images to QSPI Flash from the networking from the U-Boot command line interface.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: Install Linux Images to the QSPI Flash using U-Boot command line interface".
  Test: Section: "Test Plan: Install Linux Images (JFFS2 variant) to QSPI Flash", Section: "Test Plan: Install Linux Images (UBIFS variant) to QSPI Flash".
Support Linux boot from QSPI Flash, in the following configuration:
- multiimage including kernel and DTB loaded from QSPI Flash to RAM for execution;
- root file system mounted in QSPI Flash as the read-write Flash file system (JFFS2 or UBIFS optionally).
  Rationale: Explicit customer requirement.
  Implementation: Section: "Design: Linux Boot from QSPI Flash".
  Test: Section: "Test Plan: Linux Boot from QSPI Flash (JFFS2 variant)", Section: "Test Plan: Linux Boot from QSPI Flash (UBIFS variant)".
Support QSPI Flash in Linux. This must include support for Linux Flash file system.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: Linux Device Driver for QSPI Flash and Flash File System".
  Test: Section: "Test Plan: Linux Device Driver for QSPI Flash and Flash File System (JFFS2 variant)", Section: "Test Plan: Linux Device Driver for QSPI Flash and Flash File System (UBIFS variant)".

2.2. Detailed Non-Requirements

The following are the non-requirements for this project that may otherwise not be obvious:

Support for any Flash devices other than the QSPI Flash device present on the NXP IMXRT1170-EVK boards is not required.
- Rationale: Costs reduction measure.
Support for Linux boot scenarios other than the one listed in Section: "Detailed Requirements" is not required.
- Rationale: Costs reduction measure.

3. Design

3.1.
Design: U-Boot Boot from QSPI Flash

A dedicated configuration file imxrt1170-evk-qspi_defconfig will be added to U-Boot to support booting from the QSPI Flash on the NXP IMXRT1170-EVK board. The standard build procedure will be used to generate the bootable SPL and TPL images. The Makefile in the U-Boot source tree will be updated to generate the special header and prepend it to the general SPL image in order to make it bootable from the QSPI Flash if the corresponding option is enabled in the config file, the resulting file will be saved with the ".flexspi" extension in the filename. So in case of the imxrt1170-evk-qspi configuration the resultunt binaries from the make command for U-Boot will be SPL.flexspi and u-boot.img images:

make imxrt1170-evk-qspi_defconfig
make
ls SPL.flexspi u-boot.img

The SPL.flexspi image must be programmed to the QPSI flash on the NXP IMXRT1170-EVK board at offset 0. The image consists of the U-Boot SPL and two i.MXRT1170-specific headers:

Image Vector Table (IVT);
The FlexSPI Configuration Block.

The Image Vector Table is generated by mkimage using the board/freescale/imxrt1170-evk/imximage.cfg configuration file.

The The FlexSPI Configuration Block is compiled from the board/freescale/imxrt1170-evk/flexspi_cb.c file. This file contains the FlexSPI Configuration Block parameters, as per the corresponding Processor Reference Manual.

The u-boot.img image is the U-Boot TPL itself. It must be programmed to the QPSI flash on the NXP IMXRT1170-EVK board at offset 0x10000.

The default configuration will be set up to support the ISSI QSPI Flash installed on the EVK board.

3.2.
Design: U-Boot sf Commands

The standard U-Boot sf commands will be enabled in the U-Boot configuration to support the SPI Flash read, erase and write operations.

3.3.
Design: U-Boot Environment in QSPI Flash

Whenever the corresponding configuration described above is selected in U-Boot, the U-Boot environment will be stored in the QSPI Flash.

The environment, along with the redundant environment copy, will be placed at the address range 0x60000 - 0x80000 in the QSPI Flash.

3.4.
Design: Install U-Boot Images to the QSPI Flash using Serial Downloader

The QSPI Flash device will be logically divided into 4 sections to store the software components of the system:

0x000000 - 0x060000 - U-Boot (both SPL + TPL images)
0x060000 - 0x080000 - U-Boot Environment
0x080000 - 0x880000 - Kernel Image (multi image including the kernel and the device tree blob)
0x880000 - 0x1000000 - Root File System

The IMXRT1170 Serial Downloader feature can be used to write the SPL and TPL images to U-Boot section of the QSPI Flash on the IMXRT1170-EVK board. The SPL.flexspi image must be installed at offset 0 of the QSPI Flash, the u-boot.img image must be installed at offset 0x10000 of the QSPI Flash.

The NXPs MCUXpresso Secure Provisioning Tool (actual version for Nov 2024 is v10) can be used to install the SPL and TPL image to the QSPI Flash. The tool is available for download at NXP's web site: MCUXpresso Secure Provisioning Tool This tool provides graphical user interface to program images to the on board mass storage for various NXP's EVK boards.

For user convenience, the dedicated installation script imxtr1170_install_uboot.sh will be provided for installing U-Boot using the command line interface. The script will invoke only the blhost utility from the Secure Provisioning Tool, so running the whole tool set is not necessary. The flashloader binary required by blhost will be provide along with the installation script. The script and the flashloader is part of the linux-cm-imxrt117x-x.x.x installation (starting from linux-cm-imxrt117x-3.0.7 and are available in the tools/bin.

Script usage is as foolows:

$ imxrt1170_install_uboot.sh -h

     imxrt1170_install_uboot.sh - script to install the bootable U-Boot and Linux images to external
     QSPI Flash memory on the IMXRT1170-based board using SDP over USB

     Usage: imxrt1170_install_uboot.sh [options]

     Options:
        -f flashloader.bin      specify alternative path to the flashloader.bin file;
                                default is tools/bin/unsigned_MIMXRT1176_flashloader.bin
                                in linux-cm-imxrt-3.0.x distribution:
                                /home/user/linux-cm-imxrt117x-3.0.7/tools/bin/unsigned_MIMXRT1176_flashloader.bin

        -b blhost               specify alternative path to the blhost utility; default
                                is one from the MCUXpresso Secure Provisioning Tool v10 installation:
                                /opt/nxp/MCUX_Provi_v10/bin/_internal/tools/spsdk/blhost

        -S                      install the SPL image from current distribution:
                                /home/user/linux-cm-imxrt117x-3.0.7/u-boot/SPL.flexspi

        -s SPL.flexspi          install the SPL image from an alternative location

        -U                      install the main U-Boot image from current distribution:
                                /home/user/linux-cm-imxrt117x-3.0.7/u-boot/u-boot.img

        -u u-boot.img           install the main U-Boot image from an alternative location

        -I                      install the Linux uImage from current distribution:
                                /home/user/linux-cm-imxrt117x-3.0.7/projects/rootfs/rootfs.uImage

        -i uImage               install the Linux uImage from an alternative location

        -a                      install all - short alias for the -SUI options

        -v                      enable verbose

        -h                      display this help

3.5.
Design: Install Linux Images to the QSPI Flash using U-Boot Command Line Interface

The QSPI Flash device will be logically divided into 4 sections to store the software components of the system:

0x000000 - 0x060000 - U-Boot (both SPL + TPL images)
0x060000 - 0x080000 - U-Boot Environment
0x080000 - 0x880000 - Kernel Image (multi image including the kernel and the device tree blob)
0x880000 - 0x1000000 - Root File System

The following commands will be defined in the U-Boot environment to update the kernel and rootfs components:

sf_kernel_update - Update the Kernel section
sf_rootfs_update - Update the RootFS section

For the NXP i.MXRT1170 BSP the sf_*_update commands will download images from the TFTP server via networking and install them to the corresponding section in the QSPI Flash. The names of the images to download will be constructed automatically using the following U-Boot environment variables:

project - is the project name, default is rootfs_flash
fstype - is the type of the flash file system image : jffs2 or ubi, default is jffs2

The name of the kernel multiimage in the sf_kernel_update command is ${project}.uImage, i.e. rootfs_flash.uImage in the default settings. The name of the rootfs image in the sf_rootfs_update command is ${project}.${fstype}, i.e. rootfs_flash.jffs2 in the default settings.

3.6.
Design: Linux Boot from QSPI Flash

The separate project projects/rootfs_flash will be created to demonstrate booting Linux from QSPI flash. The following main feature will be enabled in the new project:

Support for the QSPI Flash will be enabled in the kernel configuration.
initramfs will be disabled in the kernel configuration. Instead the root filesystem will be mounted on JFSS2 or alternatively on an UBIFS file system in the QSPI Flash.
The kernel and the DTB images will be built in a single multi-part image.

To implement these features the following options will be added to the common build rules and will be used in Makefile for the rootfs_flash project:

RFS_BUILD_DIR - temporary directory to build the root file system image
FLASHFS_TYPE - to select certain file system image to build: jffs2 or ubi
MKFSUBIFS_FLAGS - Flash-specific flags for the mkfs.ubifs utility (if FLASHFS_TYPE is ubi)
UBINIZE_FLAGS - Flash-specific flags for the ubinize utility (if FLASHFS_TYPE is ubi)
SEPARATE_DTB - tells the make either build the multi-part image or save the DTB separately.

3.7.
Design: Linux Device Driver for QSPI Flash and Flash File System

The existing nxp-fspi driver from the common NXP's codebase will be used to provide support for the FlexSPI controller. The driver will be updated to support the i.MXTRT1170 SoC.

The MTD, SPI_MEM, MTD_SPI_NOR kernel features will be enabled in the rootfs_flash project's configurations, so that the QSPI Flash will be available in Linux as a standard MTD device.

The UBI, UBIFS and JFFS2 related options will be enabled to support for Linux Flash file systems.

4. Test Plan

4.1.
Secure Download Area

The downloadable materials developed by this project are available from a secure Web page on the Emcraft Systems web site. Specifically, proceed to the following URL to download the software materials.

for the i.MX RT1170 BSP:

https://www.emcraft.com/imxrtaddon/imxrt1170-3.0.7/qspi/

The page is protected as follows:

Login: CONTACT EMCRAFT
Password: CONTACT EMCRAFT

4.2.
Downloadable Files

The following files are available from the secure download area for this release:

SPL.flexspi - Bootable U-Boot SPL image to be installed to the QSPI Flash.
u-boot.img - U-Boot TPL image to be installed to the QSPI Flash.
rootfs_flash.uImage - Multiimage with Linux kernel and DTB.
rootfs_flash.jffs2 - JFFS2 image with Linux rootfs.
rootfs_flash.ubi - UBIFS image with Linux rootfs.
u-boot.patch - Source code patch to U-Boot.
linux.patch - Source code patch to Linux.
projects.patch - Source code patch to projects/.

4.3. Test Set-Up

4.3.1. Hardware Set-Up

The following hardware set-up is required for execution of the test plan in this project:

A development host Linux PC.
The NXP IMXRT1170-EVK board.
The NXP IMXRT1170-EVK Board is connected to LAN using the J3 100M ENET connector.
The NXP IMXRT1170-EVK Board is connected to the development host via the J11 micro-USB connector to provide Serial Console.
The NXP IMXRT1170-EVK Board is connected to the development host via the J20 micro-USB connector for Serial Downloader.

4.3.2. Software Set-Up

4.3.2.1. MCUXpresso Secure Provisioning Tool

Download and install the MCUXpresso Secure Provisioning Tool from MCUXpresso Secure Provisioning Tool
Make sure the blhost utility is available from the standard destination of the MCUXpresso Secure Provisioning Tool installation:
$ ls /opt/nxp/MCUX_Provi_v10/bin/_internal/tools/spsdk/blhost /opt/nxp/MCUX_Provi_v10/bin/_internal/tools/spsdk/blhost

4.3.2.2. U-Boot Build:

Apply the U-Boot patch from the top of the fresh linux-cortexm installation:
$ cd u-boot $ patch -p1 < ../u-boot.patch
Build the U-Boot images bootable from QSPI Flash
1. Configure and build U-Boot for QSPI Flash
  - for the IMXRT1170 EVK board:
    $ make mrproper $ make imxrt1170-evk-qspi_defconfig $ make

4.3.2.3. Linux Build:

Apply the Linux and projects/ patches:
$ cd linux $ patch -p1 < ../linux.patch $ cd ../projects $ patch -p1 < ../projects.patch
Build the rootfs_flash project in the default jffs2 configuration:
$ cd rootfs_flash $ make
Redefine FLASHFS_TYPE as ubi to build the rootfs_flash project in the ubi configuration:
$ cd rootfs_flash $ make FLASHFS_TYPE=ubi
Copy the resultant images to a TFTP server:
$ sudo cp rootfs_flash.uImage rootfs_flash.jffs2 rootfs_flash.ubi ~/tmp/

Prebuilt Binaries: For convenience, the prebuilt binaries resulting from the above build procedure are available in the area documented in Section: "Downloadable Files".