CL-SOM-iMX7: Linux: Getting started

Introduction

This article provides an introduction on how to install the Debian example root filesystem image on the CompuLab CL-SOM-iMX7 System-on-Module / Computer-on-Module eMMC internal storage device.

Preparation steps

• Obtain a PC workstation with a serial communication port.
• For networked installation you need to install a TFTP server on the host PC. For Windows machines we recommend TFTPD32 included in the Linux package for CL-SOM-iMX7 (link below).
• Download the Linux package for CL-SOM-iMX7 from CompuLab website. Unzip the package to a directory on your host workstation.
• All image files mentioned below can be found in the images subdirectory.
• Connect the host PC to the SBC-iMX7 base-board (connector P8) via the serial cable supplied with the evaluation kit.
• Start the terminal emulation software on your PC. Set baud rate to 115200 bps, 8 bit per frame, 1 stop bit, no parity, no flow control.
• Turn on the CL-SOM-iMX7 evaluation system. The U-Boot boot-loader will start and you will get a command prompt.

If the boot settings of your CL-SOM-iMX7 are different than the default, you may need to press and hold Ctrl-C while turning the CL-SOM-iMX7 on, in order to get command prompt.

Preparing installation media

The Linux images can be installed automatically without user intervention. The installation media has to be prepared for Automatic Installation Procedure. Any commercially available MMC/SD card or USB storage device of 1GB (or larger) may be used for the Automatic Installation Procedure.

• Copy the debian-image.tar.bz2 from the Linux package for CL-SOM-iMX7 to the first partition on the installation media (MMC/SD card or USB storage device). The partition can be formatted as either ext2/3/4 or FAT file system.
• Install the installation media of your choice to an appropriate connector:
  • MMC/SD card: SD socket (P9) on the SBC-iMX7
  • USB storage: USB OTG connector (P3) or dual USB host connector (P6) on the SBC-iMX7
• Continue to the Boot into the installation environment section.

Boot into the installation environment (ramdisk)

The next step in CL-SOM-iMX7 Linux installation is starting the installation environment (Linux kernel and Ramdisk image). This can be done using the following media:

• MMC/SD card
• USB storage device
• Network TFTP server

Using installation environment on MMC/SD card

• Copy kernel.img, imx7d-sbc-imx7.dtb, ramdisk.img and bootscr.img from Linux package for CL-SOM-iMX7 to the root directory on the first partition of the MMC/SD card. The partition can be formatted either ext2/3/4 or FAT file system.
• Insert the MMC/SD card into the SD socket (P9) on the SBC-iMX7.
• Use the following U-Boot commands to boot the installation environment on the CL-SOM-iMX7 evaluation system:

CL-SOM-iMX7 # mmc dev 0
CL-SOM-iMX7 # mmc rescan
CL-SOM-iMX7 # load mmc 0 ${loadaddr} bootscr.img
CL-SOM-iMX7 # source ${loadaddr}

• Continue to the Install Kernel and Debian Linux Images section.

Using installation environment on USB storage

• Copy kernel.img, imx7d-sbc-imx7.dtb and ramdisk.img from Linux package for CL-SOM-iMX7 to the root directory on the first partition of the USB storage. The partition can be formatted either ext2/3/4 or FAT file system.
• Insert the USB storage into either port on the dual USB host connector P6 of the SBC-iMX7.

SBC-iMX7 jumper E7 must be open

USB Boot

• Use the following U-Boot commands to boot the installation environment on a CL-SOM-iMX7 evaluation system:

CL-SOM-iMX7 # setenv fdt_file imx7d-sbc-imx7.dtb
CL-SOM-iMX7 # setenv ramdisk_addr 0x82000000
CL-SOM-iMX7 # setenv bootargs 'root=/dev/ram0 ramdisk_size=16384 console=ttymxc0,115200'
CL-SOM-iMX7 # usb start
CL-SOM-iMX7 # load usb 0 ${loadaddr} kernel.img && load usb 0 ${fdt_addr} ${fdt_file} && load usb 0 ${ramdisk_addr} ramdisk.img
CL-SOM-iMX7 # bootz ${loadaddr} ${ramdisk_addr} ${fdt_addr}

USB Boot using boot script

This approach can be used in order to avoid setting boot environment manually as in the example above.

• Use the following U-Boot commands to boot the installation environment on a CL-SOM-iMX7 evaluation system:

CL-SOM-iMX7 # usb start
CL-SOM-iMX7 # load usb 0 ${loadaddr} bootscr.img
CL-SOM-iMX7 # source ${loadaddr}

• Continue to the Install Kernel and Debian Linux Images section.

Using installation environment from TFTP server

• Connect the CL-SOM-iMX7 Ethernet port (connector P21 on the SBC-iMX7) to your local network.
• Put kernel.img, imx7d-sbc-imx7.dtb and ramdisk.img from Linux package for CL-SOM-iMX7 to a location accessible by the TFTP server:

  - On Windows machine: copy kernel.img, imx7d-sbc-imx7.dtb and ramdisk.img to the same folder and point the TFTP server to that folder

  - On Linux machine: copy kernel.img, imx7d-sbc-imx7.dtb and ramdisk.img to the TFTP server root directory, usually /tftpboot or /tftproot.

• You can use U-Boot dhcp command to obtain an IP address or manually set ipaddr environment variable:

CL-SOM-iMX7 # setenv ipaddr <CL-SOM-iMX7 ip address>

• Set the serverip environment variable:

CL-SOM-iMX7 # setenv serverip <tftp server host ip address>

• Use the following U-Boot commands to boot Linux on CL-SOM-iMX7:

CL-SOM-iMX7 # setenv loadaddr 0x80800000
CL-SOM-iMX7 # setenv fdt_addr 0x83000000
CL-SOM-iMX7 # setenv fdt_file imx7d-sbc-imx7.dtb
CL-SOM-iMX7 # setenv ramdisk_addr 0x82000000
CL-SOM-iMX7 # setenv bootargs 'root=/dev/ram0 rw ramdisk_size=16384 console=ttymxc0,115200 ip=dhcp'
CL-SOM-iMX7 # tftpboot ${loadaddr} kernel.img && tftpboot ${fdt_addr} ${fdt_file} && tftpboot ${ramdisk_addr} ramdisk.img
CL-SOM-iMX7 # bootz ${loadaddr} ${ramdisk_addr} ${fdt_addr}

• Continue to the Install Kernel and Debian Linux Images section.

Install Kernel and Debian Linux Images

Automatic Installation Procedure

After the ramdisk image is loaded the Linux command prompt will appear.

    Kernel release : Linux Linux 4.1.15-cl-som-imx7-2.0


login[83]: root login on 'ttymxc0'
root@compulab:~#

Next, the automatic installation script starts and following message appears:

Automatic Installation Procedure starts in 07 seconds. Press any key to terminate

Terminate the Automatic Installation Procedure by pressing any key during the timeout for installing the Linux manually.

Next, the installation script checks all required images on the installation media and installs them onto eMMC storage device.

The Automatic Installation script cleans up the eMMC device during the installation procedure. All data stored on the eMMC device will be lost.

Checking Linux images... OK
Checking destination media... OK
Preparing media for installation... OK
Extracting root file system tarball... 
 162MiB 0:02:37 [1.03MiB/s] [================================>] 100%            
OK
Checking Kernel image... OK
Checking Device Tree blob... OK
Installation complete.

Continue to the After Installation section.

Manual Installation Procedure

The next step is installing the kernel and Debian Linux images. The following media can be used as a source for installation:

• MMC/SD Card
• USB storage device
• NFS drive

Debian Image

The latest Linux package for CL-SOM-iMX7 contain a Debian Sid rootfs image:

• debian-image.tar.bz2

Mount an MMC/SD Card

• Copy the debian-image.tar.bz2, imx7d-sbc-imx7.dtb and the zImage-cl-som-imx7 from the Linux package for CL-SOM-iMX7 to the root directory of any partition on the MMC/SD card. The partition can be formatted as either ext2/3/4 or FAT file system.
• Insert the MMC/SD card into the SD socket (P9) on the SBC-iMX7.
• The MMC/SD card is mounted automatically under /media/mmcblk0pX. Where X is the partition number.
• If for some reason the MMC/SD card hasn't been mounted automatically, use the following mount command:

root@compulab:~# mkdir -p /media/mmcblk0pX && mount /dev/mmcblk0pX /media/mmcblk0pX

• Continue to the Install Images section.

Mount a USB Storage Device

• Copy the debian-image.tar.bz2, imx7d-sbc-imx7.dtb and the zImage-cl-som-imx7 from the Linux package for CL-SOM-iMX7 to the root directory of any partition on the USB storage device. The partition can be formatted as either ext2/3/4 or FAT file system.
• Plug the USB storage device to either port on the dual USB host connector P6 of the SBC-iMX7.

SBC-iMX7 jumper E7 must be open

• The USB device is mounted automatically under /media/sdXY. Where X is the device letter and Y is the partition number.
• If for some reason the USB storage device hasn't been mounted automatically, use the following mount command:

root@compulab:~# mkdir -p /media/sdXY && mount /dev/sdXY /media/sdXY

• Continue to the Install Images section.

Mount an NFS drive

• Connect the CL-SOM-iMX7 Ethernet port (connector P21 on the SBC-iMX7) to your local network.
• Copy the debian-image.tar.bz2, imx7d-sbc-imx7.dtb and the zImage-cl-som-imx7 from the Linux package for CL-SOM-iMX7 to a directory exported through NFS.
• Obtain an IP address for the CL-SOM-iMX7:
  • Using DHCP:

    root@compulab:~# ifup eth0

  • If you do not have a DHCP server, you can set a static IP address using ifconfig:

    root@compulab:~# ifconfig eth0 <ip address>

• Mount the NFS share containing the zImage-cl-som-imx7 and the debian-image.tar.bz2 files:

root@compulab:~# mount -o nolock <host ip>:/path/to/nfs/share /mnt/net

• Continue to Install Images section.

Install Images

• In this subsection the term /mount/point can be:
  • /mnt/net if NFS is used
  • /media/mmcblk0pX if an MMC/SD card is used, where X is the partition number.
  • /media/sdXY if USB storage is used, where X is the USB drive letter and Y is the partition number.

Once the ramdisk image is loaded and the media containing the CL-SOM-iMX7 Kernel and Debian Linux images is mounted, the installation can be done on:

• MMC/SD or eMMC

Install on MMC/SD or eMMC

The below procedure will work on an empty MMC device only. If you have already used the MMC device, please delete all the partitions before proceeding.

• Define an environment variable that describes an MMC/SD device:

MMC/SD

root@compulab:~# export TARGET_DEVICE=mmcblk0

eMMC

root@compulab:~# export TARGET_DEVICE=mmcblk2

• Clean up the on the TARGET_DEVICE:

root@compulab:~# dd if=/dev/zero of=/dev/${TARGET_DEVICE} bs=1M count=1
root@compulab:~# hdparm -z /dev/${TARGET_DEVICE}

• Create two partitions for the Linux kernel (FAT32 100M) and root file system (EXT4 the rest of the disk) on the MMC device:

root@compulab:~# echo -e "n\np\n1\n\n+100M\na\n1\nt\nc\nn\np\n2\n\n\nw\neof\n" | fdisk /dev/${TARGET_DEVICE}

• Adjust the TARGET_DEVICE name:

root@compulab:~# TARGET_DEVICE=$(awk -v device=${TARGET_DEVICE} 'BEGIN {if (device~/mmc/) {part="p"}; print device part}')

• Format the first partition with FAT32 file system:

root@compulab:~# mkfs.vfat -n boot /dev/${TARGET_DEVICE}1

• Format the second partition with EXT4 file system:

root@compulab:~# mkfs.ext4 -L rootfs /dev/${TARGET_DEVICE}2

• Mount both partitions:

root@compulab:~# mkdir -p /media/boot && mount /dev/${TARGET_DEVICE}1 /media/boot
root@compulab:~# mkdir -p /media/rootfs && mount /dev/${TARGET_DEVICE}2 /media/rootfs

• Copy zImage-cl-som-imx7 and imx7d-sbc-imx7.dtb to the first (FAT) partition:

root@compulab:~# cp /mount/point/zImage-cl-som-imx7 /mount/point/imx7d*.dtb /media/boot && sync

• Extract the content of debian-image.tar.bz2 onto the second partition:

root@compulab:~# tar --numeric-owner -xpf /mount/point/debian-image.tar.bz2 -C /media/rootfs && sync

• Unmount both partitions:

root@compulab:~# umount /dev/${TARGET_DEVICE}1
root@compulab:~# umount /dev/${TARGET_DEVICE}2

• Continue to the After Installation section.

After Installation

If the boot settings of the CL-SOM-iMX7 are different than default, you may need to press and hold Ctrl-C while turning the CL-SOM-iMX7 on, in order to get command prompt.

Boot Environment

Common Environment Variables

CL-SOM-iMX7 # setenv bootdelay 3
CL-SOM-iMX7 # setenv image zImage-cl-som-imx7
CL-SOM-iMX7 # setenv loadaddr 0x80800000
CL-SOM-iMX7 # setenv fdt_file imx7d-sbc-imx7.dtb
CL-SOM-iMX7 # setenv fdt_addr 0x83000000

Configuration Dependent Environment Variables

Display options

SBC-iMX7 has an option to connect either an LCD or a DVI display.

Below are examples that show how to change the boot environment in order to set the correct interface timing and geometry and work with either an LCD or a DVI display separately.

• DVI display enable function:

CL-SOM-iMX7 # setenv set_display 'fdt addr ${fdt_addr}; fdt rm lcdif/display/display-timings/lcd'

• LCD display enable function:

CL-SOM-iMX7 # setenv set_display 'fdt addr ${fdt_addr}; fdt rm lcdif/display/display-timings/dvi'

MMC/SD or eMMC

• mmcdev environment variable:

MMC

CL-SOM-iMX7 # setenv mmcdev 0
CL-SOM-iMX7 # setenv mmcblk 0

eMMC

CL-SOM-iMX7 # setenv mmcdev 1
CL-SOM-iMX7 # setenv mmcblk 2

• mmcroot environment variable:

CL-SOM-iMX7 # setenv mmcroot "/dev/mmcblk${mmcblk}p2 rootwait rw"

• Kernel and device tree loaders:

CL-SOM-iMX7 # setenv loadimage 'load mmc ${mmcdev}:${mmcpart} ${loadaddr} ${image}'
CL-SOM-iMX7 # setenv loadfdt 'load mmc ${mmcdev}:${mmcpart} ${fdt_addr} ${fdt_file}'

• bootargs environment variable:

CL-SOM-iMX7 # setenv bootargs "console=ttymxc0,115200 root=${mmcroot}"

Boot command

• Default boot command:

CL-SOM-iMX7 # setenv bootcmd 'run loadimage; run loadfdt; run set_display; bootz ${loadaddr} - ${fdt_addr}'

• To boot Linux, type:

CL-SOM-iMX7 # saveenv
CL-SOM-iMX7 # run bootcmd

See also

• CL-SOM-iMX7: Evaluation Kit: Getting Started
• CL-SOM-iMX7: Evaluation Kit: Hardware Guide
• CL-SOM-iMX7: Linux: Debian
• CL-SOM-iMX7: Linux: Kernel
• Linux Development for ARM modules