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

This is an add-on product that installs on top of the Linux BSP for the NXP i.MX RT1050/1060 EVK board. It must be purchased separately from the Linux BSP product.

1. Overview

This document describes the exact steps that need to be performed to install U-Boot and Linux to the QSPI Flash on the i.MX RT1050/1060 EVK board and then to boot Linux from the QSPI Flash.

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 IMXRT1050/IMXRT1060 Serial Downloader feature.
- Rationale: Explicit customer requirement.
  Implementation: Section: "Design: Install U-Boot an Linux Images to the QSPI Flash using Serial Downloader".
  Test: Section: "Test Plan: Install U-boot and Linux 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: Update Linux Images to the QSPI Flash using U-Boot command line interface".
  Test: Section: "Test Plan: Update Linux Images (JFFS2 variant) to QSPI Flash", Section: "Test Plan: Update 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 IMXRT1050-EVKB/IMXRT1060-EVKB 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:

imxrt1050-evk-qspi_defconfig - the NXP IMXRT1050-EVKB board
imxrt1060-evk-qspi_defconfig - the NXP IMXRT1060-EVKB board

will be added to U-Boot to support booting from the QSPI Flash on the boards. 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 the resultant binaries from the make command for U-Boot will be SPL.flexspi and u-boot.img images:

$ make imxrt1050-evk-qspi_defconfig
$ make
$ ls SPL.flexspi u-boot.img
SPL.flexspi u-boot.img

or for the NXP IMXRT1060-EVKB board:

$ make imxrt1060-evk-qspi_defconfig
$ make
$ ls SPL.flexspi u-boot.img
SPL.flexspi u-boot.img

The SPL.flexspi image must be programmed to the QPSI flash on the NXP IMXRT1050-EVKB/IMXRT1060-EVKB board at offset 0. The image consists of the U-Boot SPL and two i.MX RT10XX-specific headers required by the internal boot ROM code to correctly boot:

Image Vector Table (IVT). It is generated by mkimage using the board/freescale/imxrt1050-evk/imximage.cfg configuration file.
The FlexSPI Configuration Block. It is compiled from the board/freescale/imxrt1050-evk/flexspi_cb.c file. This file contains the FlexSPI Configuration Block parameters, as per the corresponding Processor Reference Manual. The default configuration will be set up to support the ISSI QSPI Flash is25wp064 installed on the NXP IMXRT10XX-EVK(B) boards.

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

SPL in linked to the addresses in the internal OCRAM memory of i.MXRT10XX. So during booting the internal i.MXRT boot ROM code will copy the SPL image from the QSPI flash to OCRAM and execute from there. Addresses from 0x20208000 to 0x20209000 are utilized by U-Boot SPL right after the area reserved for the boot code. SPL started address is 0x2020a000 (0x2000 bytes before are reserved for the IVT header, which the boot code can also copy from the QSPI flash), stack for SPL is initialized at 0x20209000. Then SPL will initialize external SDRAM and copy and start the main U-Boot from there.

3.2. Design: U-Boot sf Commands

The spi/nxp_fspi.c driver in U-Boot will be updated to support the i.MXRT10XX variant of the FlexSPI controller. The driver along with the required clocks, pinmux and QSPI flash will be configured in the board config and DTS.

The standard U-Boot sf commands will be enabled in the U-Boot configuration to provide user API to the QSPI Flash.

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 an Linux 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 - 0x480000 - Kernel Image (multi image including the kernel and the device tree blob)
0x480000 - 0x800000 - Root File System

The IMXRT1050 or IMXRT1060 Serial Downloder feature can be used to write the SPL and TPL images to U-Boot section of the QSPI Flash on the IMXRT1050-EVKB or IMXRT1060-EVKB 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. For user convenience, the dedicated installation script imxrt_install.sh will be provided:

$ imxrt_install.sh [-p project] [-t fstype] [options]

The script supports options that allow to install certain system components separately or together:

-S - install the bootable U-Boot SPL image SPL.flexspi to the U-Boot partition;
-U - install the main U-Boot image u-boot.imgto the U-Boot partition;
-I - install the uImage to the Kernel partition;
-R - install the flash file system image to the Root File System partition.

The script looks for the images to install in the currently activated distribution, these are u-boot/SPL.flexspi, u-boot/u-boot.img, projects/rootfs_flash/rootfs_flash.uImage and projects/rootfs_flash/rootfs_flash.jffs2. If a custom project is to be installed, the default rootfs_flash project name can be overridden with the option -p project_name. The default type of the flash file system jffs2 can be changed with the -t fstype option to either ubi for the UBI FS based project or to none for the project without flash file system (initramfs based projects for example). Also there are the -s, -u, -i, -r options provided to install image(s) from an arbitrary location not tied to a distribution.

The script requires the blhost and sdphost utilities and the flashloader binary provided by NXP Flashloader_i.MXRT10xx package to operate with the IMXRT over SDP. It is expected that the package is unpacked in to the tools directory of the linux-cm- distribution. If not, the -f, -b and -d options can to used to override the default location.

Also refer to imxrt_install.sh -h for the help at runtime.

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

As an alternative to installing the kernel and file system images to the QSPI Flash via the Serial Downloader feature, one can install or update the images using the U-Boot command monitor, if U-Boot is already installed.

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 - 0x480000 - Kernel Image (multi image including the kernel and the device tree blob)
0x480000 - 0x800000 - 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 IMXRT1050 BSP or IMXRT1060 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.MXTRT1050/i.MXTRT1060 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 RT1050 BSP (release 3.0.4):

https://www.emcraft.com/imxrtaddon/imxrt1050/qspi/

The page is protected as follows:

Login: CONTACT EMCRAFT

Password: CONTACT EMCRAFT

For the i.MX RT1050 BSP (release 3.1.0):

https://www.emcraft.com/imxrtaddon/imxrt1050-3.1.0/qspi/

The page is protected as follows:

Login: CONTACT EMCRAFT

Password: CONTACT EMCRAFT

For the i.MX RT1060 BSP (release 3.1.0):

https://www.emcraft.com/imxrtaddon/imxrt1060-3.1.0/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 IMXRT1050-EVKB or IMXRT1060-EVKB board.
The following hardware reworks are required on the NXP iMXRT1050-EVKB board to enable the QSPI Flash, as described in section 2.7 of the NXP IMXRT1050-EVKB Board Hardware User’s Guide:
- Remove resistors: R356, R361 - R366
- Weld 0Ω resistors: R153 - R158.
The NXP IMXRT1050-EVKB or IMXRT1060-EVKB Board is connected to LAN using the J19 100M ENET connector.
The NXP IMXRT1050-EVKB Board is connected to the development host via the J28 micro-USB connector to provide Serial Console. The NXP IMXRT1060-EVKB Board is connected to the development host via the J1 micro-USB connector to provide Serial Console.
The NXP IMXRT1050-EVKB Board is connected to the development host via the J9 micro-USB connector for Serial Downloader. The NXP IMXRT1060-EVKB Board is connected to the development host via the J48 micro-USB connector for Serial Downloader.

4.3.2. Software Set-Up

4.3.2.1. Flashloader

Download the archive with Flashloader and the host tools for the Serial Downloader from the nxp.com site Search | NXP Semiconductors .
Unzip the Flashloader archive to the tools directory on the top of the linux-cm-<bsp> installation:
$ cd linux-cm-<bsp> $ cd tools $ unzip ~/Downloads/<Flashloader_image>.zip
Enable permissions to execute the blhost and sdphost utilities from the Flashloader_i.MXRT1050_GA or from Flashloader_RT106x_1.0_GA package:
$ chmod +x Flashloader_i.MXRT1050_GA/Flashloader_RT1050_1.1/Tools/sdphost/linux/i386/sdphost Flashloader_i.MXRT1050_GA/Flashloader_RT1050_1.1/Tools/blhost/linux/i386/blhost
or
$ chmod +x Flashloader_RT106x_1.0_GA/Tools/sdphost/linux/i386/sdphost Flashloader_RT106x_1.0_GA/Tools/blhost/linux/i386/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 IMXRT1050 EVKB board:
    $ make mrproper $ make imxrt1050-evk-qspi_defconfig $ make
  - for the IMXRT1060 EVKB board:
    $ make mrproper $ make imxrt1060-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/

4.3.2.4. Prebuilt Binaries

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