Skip to end of metadata
Go to start of metadata

Build and Install Linux System for SMARC-iMX8 (QuadMax and QuadPlus Core)

This document provides instructions for advanced users how Embedian offers patches and builds a customized version of u-boot and linux kernel for Embedian's SMARC-iMX8 product platform and how to install the images to bring the evaluation board up and running. 

Our aim is to fully support our hardware through device drivers. We also provide unit tests so that testing a board is easy and custom development can start precisely. The recommended host environment is Ubuntu Ubuntu 16.04 or Ubuntu 18.04.

Availability

SMARC-iMX8 from Embedian

Carrier Board

EVK-STD-CARRIER-S20 (universal carrier board for all SMARC 2.0 modules) from Embedian

Basic Resources

 

ARM Cross Compiler: GCC

To build Embedian’s SMARC-iMX8 u-boot and linux kernel, you will need to install the following ARM GNU aarch64 compiler first: 

For u-boot 2020.04 and Linux 5.4.70, you need to use the following ARM GNU aarch64 coss compilier. 

$ wget -c https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz 

$ sudo tar -C /opt -xJf gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz

$ export CC=/opt/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/bin/aarch64-linux-gnu-

Test:

If this test fails, verify that you have the 32bit libraries installed on your development system.

$ ${CC}gcc --version

aarch64-linux-gnu-gcc (GNU Toolchain for the A-profile Architecture 8.3-2019.03 (arm-rel-8.36)) 8.3.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Generating SSH Keys

We recommend you use SSH keys to establish a secure connection between your computer and Embedian Gitlab server. The steps below will walk you through generating an SSH key and then adding the public key to our Gitlab account.

Step 1. Check for SSH keys

First, we need to check for existing ssh keys on your computer. Open up Git Bash and run:

Check the directory listing to see if you have a file named either id_rsa.pub or id_dsa.pub. If you don't have either of those files go to step 2. Otherwise, you already have an existing keypair, and you can skip to step 3.

Step 2. Generate a new SSH key

To generate a new SSH key, enter the code below. We want the default settings so when asked to enter a file in which to save the key, just press enter.

Now you need to enter a passphrase.

Which should give you something like this:

Step 3. Add your SSH key to Embedian Gitlab Server

Copy the key to your clipboard.

Go to Embedian Git Server. At Profile Setting --> SSH Keys --> Add SSH Key 

Paste your public key and press "Add Key" and your are done.

Setting Up the Tools and Build Environment

To build the latest Freescale i.MX8QM fsl-bsp-release, you first need an Ubuntu 16.04 LTS installation. Since bitbake does not accept building images using root privileges, please do not login as a root user when performing the instructions in this section. 

Once you have Ubuntu 16.04 LTS running, install the additional required support packages using the following console command:

$ sudo apt-get install gawk wget git-core diffstat unzip texinfo build-essential chrpath libsdl1.2-dev xterm python-m2crypto bc libsdl1.2-dev pv srecord cmake

Create a Bootable Image: flash.bin

The bootable image file is called flash.bin. It is is comprised of as minimum the System Controller Firmware (scfw_tcm.bin) and the Security Controller Firmware (mx8qmb0-ahab-container.img), optionally it can contain images for the Cortex M4 cores (if more than one available as in the case of QM devices) and Cortex A cores. 

 

                          

 

This section instruct you how to generate a bootable file flash.bin. 

1. Download the imx-mkimage tool and apply Embedian's patch to accept Embedian's device tree blob.

$ git clone https://source.codeaurora.org/external/imx/imx-mkimage -b imx_5.4.70_2.3.0

$ cd imx-mkimage

$ wget -c ftp://ftp.embedian.com/public/smarcimx8qm/0001-5.4.70_2.3.0-change-uboot-device-tree-name.patch

$ patch -p1 <0001-5.4.70_2.3.0-change-uboot-device-tree-name.patch

$ cd ../

 

2. Get and Build the ARM Trusted firmware and copy bl31.bin to imx-mkimage/iMX8QM directory.

$ git clone https://source.codeaurora.org/external/imx/imx-atf -b imx_5.4.70_2.3.0

$ cd imx-atf

$ make CROSS_COMPILE=${CC} PLAT=imx8qm bl31

$ cp build/imx8qm/release/bl31.bin ../imx-mkimage/iMX8QM/

$ cd ../

 

3. Get and build System Control Firmware

3.1. Setup Cross Compiler

$ sudo mkdir -p /opt/scfw
$ wget -c https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
$ sudo tar xf gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2 -C /opt/scfw

3.2. Get and build System Control Firmware (SCFW)

$ export TOOLS=/opt/scfw/
$ git clone git@git.embedian.com:developer/imx-sc-firmware.git -b 8qm_1.7.0
$ cd imx-sc-firmware
$ make clean-qm
$ make clean
$ make qm B=smarc_8g U=0 D=1 M=1 R=B0
$ cp build_mx8qm_b0/scfw_tcm.bin ../imx-mkimage/iMX8QM/
$ cd ../

For 4GB LPDDR4 variant, use

$ make qm B=smarc_4g U=0 D=1 M=1 R=B0


4. Get and Security Control Firmware (SECO)

$ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-3.7.4.bin
$ chmod a+x imx-seco-3.7.4.bin
$ ./imx-seco-3.7.4.bin
$ cd imx-seco-3.7.4
$ cp firmware/seco/mx8qmb0-ahab-container.img ../imx-mkimage/iMX8QM/
$ cd ../


5. Get and build Cortex-M image (Optional)

$ export ARMGCC_DIR=/opt/scfw/gcc-arm-none-eabi-9-2019-q4-major
$ git clone git@git.embedian.com:developer/freertos-embedian.git freertos -b mcuxpresso_sdk_2.9.0-8qm
$ cd freertos/boards/smarcimx8qm/demo_apps/hello_world/cm4_core0/armgcc
$ ./build_all.sh
$ cd ../../cm4_core1/armgcc/
$ ./build_all.sh
$ cd ../../../../../../
$ cp -v boards/smarcimx8qm/demo_apps/hello_world/cm4_core0/armgcc/release/hello_world_m40.bin ../imx-mkimage/iMX8QM/m4_image.bin
$ cp -v boards/smarcimx8qm/demo_apps/hello_world/cm4_core1/armgcc/release/hello_world_m41.bin ../imx-mkimage/iMX8QM/m4_1_image.bin
$ cd ../


6. Clone the U-Boot source code from Embedian Git Server and copy related files to imx-mkimage/iMX8QM/ directory.

Download:

For u-boot v2020.04: 

$ git clone git@git.embedian.com:developer/smarc-t335x-uboot.git u-boot_v2020.04 -b 8qm-imx_v2020.04_5.4.70_2.3.0

$ cd u-boot_v2020.04

Configure and Build:

$ export CC=/opt/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/bin/aarch64-linux-gnu-

$ make ARCH=arm CROSS_COMPILE=${CC} distclean

$ make ARCH=arm CROSS_COMPILE=${CC} smarcimx8qm_8g_ser3_defconfig

$ make ARCH=arm CROSS_COMPILE=${CC}

Note1:

If the board is 4GB LPDDR4 in commercial or industrial temperature, use
$ make ARCH=arm CROSS_COMPILE=${CC} smarcimx8qm_4g_ser3_defconfig

Note 2:

"ser3" stands for console debug port in SMARC definition. In this example, we uses SER3 as debug port. If user uses SER0 as your debug port, make change to "ser0" instead. Same as SER1 and SER2.

Note 3:

The SMARC-iMX8 module always boot up from the on-module eMMC flash. The factory default will be flash.bin pre-installed with SER3 as console output. In some cases when the eMMC flash is empty or needs to be upgraded. Users can shunt crossed the TEST# to ground. In this way, the SMARC-iMX8 module will boot up to carrier SD card, if TEST# pin is shunt crossed. The flash.bin image are the same, the difference is how you flash flash.bin. This will be explained in the "Setup SD card" section.

Copy u-boot.bin spl/u-boot-spl.bin arch/arm/dts/fsl-smarcimx8qm.dtb to imx-mkimage/iMX8QM directory.

$ cp u-boot.bin spl/u-boot-spl.bin arch/arm/dts/fsl-smarcimx8qm.dtb ../imx-mkimage/iMX8QM/

 

7. Generate flash.bin file.

$ cd ../imx-mkimage

$ make CROSS_COMPILE=${CC} SOC=iMX8QM flash_linux_m4


The flash.bin file will be located at imx-mkimage/iMX8QM directory. Go to "Setup SD Card" section to instruct you how to flash this file into SD card.

Linux Kernel

Download:

For 5.4.70 (Based on Freescale imx_5.4.70_2.3.0 official release):

$ git clone git@git.embedian.com:developer/smarc-fsl-linux-kernel.git linux_v5.4.70 -b 8qm-imx_5.4.70_2.3.0

$ cd linux_v5.4.70

Configure and Build:

$ make ARCH=arm64 CROSS_COMPILE=${CC} distclean

$ make ARCH=arm64 CROSS_COMPILE=${CC} smarcimx8qm_defconfig

$ make ARCH=arm64 CROSS_COMPILE=${CC} Image modules dtbs

 

All available DTB files are listed in the table below.

DTB File NameDescription
imx8qm-smarc.dtbDevice tree blob for no display configuration.
imx8qm-smarc-hdmi.dtbDevice tree blob for HDMI display configuration.
imx8qm-smarc-dp.dtbDevice tree blob for Display Port (DP) display configuration.
imx8qm-smarc-edp.dtbDevice tree blob for embedded Display Port (eDP) display configuration.
imx8qm-smarc-lvds.dtbDevice tree blob for LVDS display configuration.
imx8qm-smarc-rpmsg.dtbDevice tree blob for Cortex-M4 configuration.

Root File System

Ubuntu ARM64 18.04:

UserPassword
rootN/A


Ubuntu 18.04 Download:

$ wget -c ftp://ftp.embedian.com/public/dev/minfs/ubuntu/bionic/ubuntu-minimal-imx8qm-18.04-arm64.tar.gz

Verify:

$ md5sum ubuntu-minimal-imx8qm-18.04-arm64.tar.gz
0d48e9951a7cfb61ac712d5a386e6eb1  ubuntu-minimal-imx8qm-18.04-arm64.tar.gz


Yocto Build Root File System:

UserPassword
rootN/A

Find the yocto zeus pre-built root file systems here at Embedian's ftp site based on your module CPU variants.

Setup SD Card

For these instruction, we are assuming: DISK=/dev/mmcblk0, "lsblk" is very useful for determining the device id.

$ export DISK=/dev/mmcblk0


Erase SD card:

$ sudo dd if=/dev/zero of=${DISK} bs=1M count=160


Create Partition Layout: Leave 2MB offset for flash.bin.

With util-linux v2.26, sfdisk was rewritten and is now based on libfdisk.

sfdisk

$ sudo sfdisk --version
sfdisk from util-linux 2.27.1

Create Partitions:

sfdisk >=2.26.x

Icon
$ sudo sfdisk ${DISK} <<-__EOF__
2M,48M,0x83,*
50M,,,
__EOF__

sfdisk <=2.25

Icon
$ sudo sfdisk --in-order --Linux --unit M ${DISK} <<-__EOF__
2,48,0x83,*
,,,-
__EOF__

Format Partitions:

for: DISK=/dev/mmcblk0
$ sudo mkfs.vfat -F 16 ${DISK}p1 -n boot
$ sudo mkfs.ext4 ${DISK}p2 -L rootfs
 
for: DISK=/dev/sdX
$ sudo mkfs.vfat -F 16 ${DISK}1 -n boot
$ sudo mkfs.ext4 ${DISK}2 -L rootfs

Mount Partitions:

On some systems, these partitions may be auto-mounted...

$ sudo mkdir -p /media/boot/
$ sudo mkdir -p /media/rootfs/
 
for: DISK=/dev/mmcblk0
$ sudo mount ${DISK}p1 /media/boot/
$ sudo mount ${DISK}p2 /media/rootfs/
 
for: DISK=/dev/sdX
$ sudo mount ${DISK}1 /media/boot/
$ sudo mount ${DISK}2 /media/rootfs/

Install Boot File

If on-module eMMC Flash is empty

In some cases, when eMMC flash is erased or the u-boot is under development, we need a way to boot from SD card first. Users need to shunt cross the TEST# pin to ground. In this way, SMARC-iMX8 will always boot up from SD card. 

Fuse flash.bin to the SD card. 

~/imx-mkimage

$ sudo dd if=iMX8QM/flash.bin of=${DISK} bs=1024 seek=32


If on-module eMMC Flash is not empty

The flash.bin is pre-installed in on-module eMMC flash at factory default. SMARC-iMX8 is designed to always boot up from on-module eMMC flash and to load Image, device tree blob and root file systems based on the setting of BOOT_SEL. If users need to fuse your own flash.bin or perform u-boot upgrade. This section will instruct you how to do that.

Copy flash.bin to the second partition home directory of your SD card and boot into SD card. Go to home directory and you should see flash.bin file (The flash.bin file is located at imx-mkimage/iMX8QM/ directory). 

$ sudo cp -v imx-mkimage/iMX8QM/flash.bin /media/rootfs/home/root/

Boot up device and fuse flash.bin to the on-module eMMC flash. (The eMMC flash is emulated as /dev/mmcblk0 in SMARC-iMX8)

home directory

$ sudo dd if=flash.bin of=/dev/mmcblk0 bs=1024 seek=32

Icon
  1. If your u-boot hasn't been finalized and still under development, it is recommended to shunt cross the test pin and boot directly from SD card first. Once your u-boot is fully tested and finalized, you can fuse your flash.bin to eMMC flash.
  2. When TEST# pin of SMARC-iMX8 is not shunt crossed, it will always boot up from on-module eMMC flash. U-boot will read the BOOT_SEL configuration and determine where it should load Image and device tree blob. When TEST# is shunt crossed (pull low), it will always boot up from SD card.

uEnv.txt based bootscript

Create "uEnv.txt" boot script: ($ vim uEnv.txt)

~/uEnv.txt

#optargs="video=HDMI-A-1:1920x1080-32@60 consoleblank=0"
#optargs="video=HDMI-A-1:3840x2160-32@30 consoleblank=0"
#optargs="video=HDMI-A-1:3840x2160-32@60 consoleblank=0"
#console port SER3
console=ttyLP4,115200 earlycon
#console port SER2
#console=ttyLP1,115200 earlycon
#console port SER1
#console=ttyLP3,115200 earlycon
#console port SER0
#console=ttyLP0,115200 earlycon
mmcdev=1
mmcpart=1
image=Image
loadaddr=0x80280000
fdt_addr=0x83000000
mmcroot=/dev/mmcblk1p2 rw
usbroot=/dev/sda2 rw
mmcrootfstype=ext4 rootwait fixrtc
netdev=eth0
ethact=FEC0
ipaddr=192.168.1.150
serverip=192.168.1.53
gatewayip=192.168.1.254
mmcargs=setenv bootargs cma=1280M console=${console} root=${mmcroot} rootfstype=${mmcrootfstype} ${optargs}
# uenvcmd=run loadimage; run loadfdt; run mmcboot
# USB Boot
#usbargs=setenv bootargs console=${console} root=${usbroot} rootfstype=${mmcrootfstype} ${optargs}
#uenvcmd=run loadusbimage; run loadusbfdt; run usbboot

Copy uEnv.txt to the boot partition:

~/

$ sudo cp -v ~/uEnv.txt /media/boot/

Install Kernel Image

Copy Image to the boot partition:

~/linux_v5.4.70

$ sudo cp -v arch/arm64/boot/Image /media/boot

Install Kernel Device Tree Binary

$ sudo mkdir -p /media/boot/dtbs

$ sudo cp -v arch/arm64/boot/dts/embedian/<device tree name> /media/boot/dtbs/imx8qm-smarc.dtb

The device tree name in your SD card has be to imx8qm-smarc.dtb

Install HDMI/DP Firmware (Only if HDMI/DP Display)

$ wget http://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.10.bin

$ chmod a+x firmware-imx-8.10.bin

$ ./firmware-imx-8.10
enter "y" to accept EULA

$ cd firmware-imx-8.10
$ sudo cp -v firmware/hdmi/cadence/hdmitxfw.bin /media/boot/
$ sudo cp -v firmware/hdmi/cadence/hdmirxfw.bin /media/boot/
$ sudo cp -v firmware/hdmi/cadence/dpfw.bin /media/boot/

Install Root File System and Kernel Modules

Copy Root File System:

Yocto Pre-Built Rootfs:

directory where your root file system is

$ sudo tar jxvf <filename.tar.gz> -C /media/rootfs


Ubuntu 18.04:

directory where your root file system is

$ sudo tar xvfz ubuntu-minimal-imx8qm-18.04-arm64.tar.gz -C /media/rootfs

Copy Kernel Modules:

~/linux_v5.4.70

$ sudo make ARCH=arm64 CROSS_COMPILE=${CC} INSTALL_MOD_PATH=/media/rootfs modules_install

Note

Icon
  1. MAC address is factory pre-installed at on board I2C EEPROM at offset 60 bytes). It starts with Embedian's vendor code 10:0D:32. u-boot will read it and pass this parameter to kernel.
  2. If your rootfs is yocto built, the kernel modules will be included in the rootfs. No need to copy again.

Networking:

Edit: /etc/network/interfaces

$ sudo vim /media/rootfs/etc/network/interfaces

Add:

/media/rootfs/etc/network/interfaces

auto lo
iface lo inet loopback
 
auto eth0
iface eth0 inet dhcp

Remove SD card:

$ sync
$ sudo umount /media/boot
$ sudo umount /media/rootfs

Sample Examples Demo

Setting up eMMC usually is the last step at development stage after the development work is done at your SD card or NFS environments. From software point of view, eMMC is nothing but a non-removable SD card on board. For SMARC-iMX8, the SD card is always emulated as /dev/mmcblk1 and on-module eMMC is always emulated as /dev/mmcblk0. Setting up eMMC now is nothing but changing the device descriptor. 

This section gives a step-by-step procedure to setup eMMC flash. Users can write a shell script your own at production to simplify the steps.

First, we need to backup the final firmware from your SD card or NFS.

Prepare for eMMC binaries from SD card (or NFS):

Insert SD card into your Linux PC. For these instructions, we are assuming: DISK=/dev/mmcblk0, "lsblk" is very useful for determining the device id.

For these instruction, we are assuming: DISK=/dev/mmcblk0, "lsblk" is very useful for determining the device id.

$ export DISK=/dev/mmcblk0

Mount Partitions:

On some systems, these partitions may be auto-mounted...

$ sudo mkdir -p /media/boot/
$ sudo mkdir -p /media/rootfs/
 
for: DISK=/dev/mmcblk0
$ sudo mount ${DISK}p1 /media/boot/
$ sudo mount ${DISK}p2 /media/rootfs/
 
for: DISK=/dev/sdX
$ sudo mount ${DISK}1 /media/boot/
$ sudo mount ${DISK}2 /media/rootfs/


Copy Image to rootfs partition:

$ sudo cp -v /media/boot/Image /media/rootfs/home/root

Note

Icon
  1. If your rootfs is Ubuntu 18.04, copy to /media/rootfs/home/ubuntu instead of /media/rootfs/home/root


Copy uEnv.txt to rootfs partition:

Copy and paste the following contents to /media/rootfs/home/root ($ sudo vim /media/rootfs/home/root/uEnv.txt)

#optargs="video=HDMI-A-1:1920x1080-32@60 consoleblank=0"
#optargs="video=HDMI-A-1:3840x2160-32@30 consoleblank=0"
#optargs="video=HDMI-A-1:3840x2160-32@60 consoleblank=0"
#console port SER3
console=ttyLP4,115200 earlycon
#console port SER2
#console=ttyLP1,115200 earlycon
#console port SER1
#console=ttyLP3,115200 earlycon
#console port SER0
#console=ttyLP0,115200 earlycon
mmcdev=0
mmcpart=1
image=Image
loadaddr=0x80280000
fdt_addr=0x83000000
mmcroot=/dev/mmcblk0p2 rw
usbroot=/dev/sda2 rw
mmcrootfstype=ext4 rootwait fixrtc
netdev=eth0
ethact=FEC0
ipaddr=192.168.1.150
serverip=192.168.1.53
gatewayip=192.168.1.254
mmcargs=setenv bootargs cma=1280M console=${console} root=${mmcroot} rootfstype=${mmcrootfstype} ${optargs}
# uenvcmd=run loadimage; run loadfdt; run mmcboot
# USB Boot
#usbargs=setenv bootargs console=${console} root=${usbroot} rootfstype=${mmcrootfstype} ${optargs}
#uenvcmd=run loadusbimage; run loadusbfdt; run usbboot


Copy device tree blob to rootfs partition:

$ sudo cp -v /media/boot/dtbs/imx8qm-smarc.dtb /media/rootfs/home/root/imx8qm-smarc.dtb

Copy real rootfs to rootfs partition:

Yocto Built Root File Systems

$ pushd /media/rootfs

$ sudo tar cvfz ~/smarcimx8qm-emmc-rootfs.tar.gz .

$ sudo mv ~/smarcimx8qm-emmc-rootfs.tar.gz /media/rootfs/home/root

$ popd


Ubuntu 18.04 Root File Systems

$ sudo vim /media/rootfs/etc/udev/rules.d/70-persistent-net.rules

Delete all contents starting with "SUBSYSTEM=="

$ pushd /media/rootfs

$ sudo tar cvfz ~/smarcimx8qm-emmc-rootfs.tar.gz .

$ sudo mv ~/smarcimx8qm-emmc-rootfs.tar.gz /media/rootfs/home/ubuntu

$ popd

Remove SD card:

$ sync
$ sudo umount /media/boot
$ sudo umount /media/rootfs

Copy Binaries to eMMC from SD card:

Insert this SD card into your SMARC-iMX8 device and boot into SD card.

Now it will be almost the same as you did when setup your SD card, but the eMMC device descriptor is /dev/mmcblk0 now.

$ export DISK=/dev/mmcblk0

Erase eMMC:

$ sudo dd if=/dev/zero of=${DISK} bs=2M count=16

Create Partition Layout:

$ sudo sfdisk ${DISK} <<-__EOF__
 2M,48M,0x83,*
 50M,,,
__EOF__

Format Partitions:

$ sudo mkfs.vfat -F 16 ${DISK}p1 -n boot
$ sudo mkfs.ext4 ${DISK}p2 -L rootfs

Mount Partitions:

$ sudo mkdir -p /media/boot/
$ sudo mkdir -p /media/rootfs/
$ sudo mount ${DISK}p1 /media/boot/
$ sudo mount ${DISK}p2 /media/rootfs/

Install binaries for partition 1

Copy uEnv.txt/Image/*.dtb to the boot partition

$ sudo cp -v Image uEnv.txt /media/boot/

Install Kernel Device Tree Binary

$ sudo mkdir -p /media/boot/dtbs

$ sudo cp -v imx8qm-smarc.dtb /media/boot/dtbs/

Setup eMMC

$ sudo tar -zxvf smarcimx8qm-emmc-rootfs.tar.gz -C /media/rootfs

 
Unmount eMMC:

$ sync
$ sudo umount /media/boot
$ sudo umount /media/rootfs

 

Switch your Boot Select to eMMC and you will be able to boot up from eMMC now.

version 1.0a, 6/04/2021

Last updated 2021-06-04

  • No labels