• 0

i.MX Linux® User’s Guide For Sabre-SD Board

Category : Blog Post

Following is the list of Supported hardware SoCs and boards covered in this guide:

  • i.MX 6Quad SABRE-SD Board and Platform
  • i.MX 6DualLite SABRE-SD Platform
  • i.MX 6Quad SABRE-AI Platform
  • i.MX 6DualLite SABRE-AI Platform
  • i.MX 6SoloLite EVK
  • i.MX 6SoloX SABRE-SD Platform
  • i.MX 6SoloX SABRE-AI Platform
  • i.MX 6QuadPlus SABRE-AI platform
  • i.MX 6QuadPlus SABRE-SD platform
  • i.MX 6UltraLite EVK platform

Abbreviations used in this article.

  • SABRE-SD refers to the i.MX 6Quad SABRE-SD, i.MX 6DualLite SABRE-SD, i.MX 6QuadPlus SABRE-SD, and i.MX 7Dual SABRE-SD boards.
  • SABRE-AI refers to the i.MX 6Quad SABRE-AI, i.MX 6DualLite SABRE-AI, and i.MX 6QuadPlus SABRE-AI boards.
  • SoloLite refers to the i.MX 6SoloLite Board.
  • SoloX or SX refers to the i.MX 6SoloX SABRE-SD and SABRE-AI boards.
  • UL refers to the i.MX 6UltraLite board


The i.MX Linux BSP is a collection of binary files, source code, and support files that can be used to create a U-Boot bootloader, a Linux kernel image, and a root file system for i.MX development system. The Yocto Project is the framework of choice to build the images although other methods can be used. You can refer “Yocto Project User’s Guide” for all the information on how to set up Linux host machine, how to run and configure a Yocto Project, generate an image, and generate a rootfs.

Basic Terminal Setup

The i.MX boards can communicate with a host server (Windows® OS or Linux OS) using a serial cable. Common serial communication programs such as HyperTerminal, Tera Term, or PuTTY can be used.

USB cable can be connected from PC to Sabre-SD board for debugging. PuTTY can be setup with following configuration on PC.

You can download PuTTY from this link.

Booting Linux OS

Before the Linux OS kernel can boot on an i.MX board, the images (U-Boot, Linux kernel, device tree, and rootfs) need to be copied to a boot device and the boot switches need to be set to boot that device. There are various ways that this can be done for different boards, boot devices, and results desired. This section explains how to prepare a boot device, where files need to be in the memory map, how to set switches for booting, and how to boot Linux OS from U-Boot.

Software overview

To boot a Linux image, four elements are needed:

  • Bootloader (U-Boot)
  • Linux kernel image (zImage)
  • A device tree file (.dtb) for the board being used
  • A root files system (rootfs) for the particular Linux image

The system can be configured for a specific graphical backend. The graphical backend are X11, XWayland, and Frame Buffer.


U-Boot is most recommended tool as bootloader. U-Boot must be loaded onto a device to be able to boot from it. U-Boot images are board-specific and can be configured to support booting from different sources.

Linux kernel image and device tree

This Freescale i.MX BSP contains a pre-built kernel image based on the 4.1.15 version of the Linux kernel and the device tree files associated with each platform. The same kernel image is used for all the i.MX boards. Device trees are kernel configuration files that allow a common kernel to boot with different pin settings for different boards or configurations. Device tree files use the .dtb extension. The configuration for a device tree can be found in the Linux source code under arch/arm/boot/dts in the *.dts files.

Root file system

The root file system package (or rootfs) provides busybox, common libraries, and other fundamental elements.

The i.MX BSP package contains several root file systems. The file system includes Freescale-specific libraries and common Linux utilities. They are named with the following convention: [image recipe]-[backend]-[platform][board].[ext3|sdcard]. The ext3 extension indicates a standard file system. It can be mounted as NFS, or its contents can be stored on a boot media such as an SD/MMC card. The graphical backend to be used is also defined by the rootfs.

Preparing an SD/MMC card to boot

For a Linux image to be able to run, four separate pieces are needed:

Linux kernel image (zImage), device tree file (*.dtb), U-Boot boot loader image, and root file system (*.ext3 or *.ext4).

An “.sdcard” image contains all four images properly configured for an SD card. The release contains a pre-built .sdcard image that is built specifically for the one board configuration. It runs the X11 graphical backend. It does not run on other boards unless U-Boot, device tree, and rootfs are changed.

The Yocto Project build creates an SD card image that can be flashed directly. This is the simplest way to load everything needed onto the card with one command. When more flexibility is desired, the individual components can be loaded separately.

An SD card can be loaded with the individual components one-by-one The rootfs on the default .sdcard image is limited to a bit less than 4 GB, but re-partitioning and re-loading the rootfs can increase that to the size of the card.

The rootfs can also be changed to specify the graphical backend that is used.

The device tree file (.dtb) contains board and configuration-specific changes to the kernel.

The kernel image and DTB move to use the FAT partition without a fixed raw address on the SD card. The users have to change the U-Boot boot environment if the fixed raw address is required.

Image layout

Start address (sectors) Size (sectors) Format Description
0x400 bytes (2) 0x9FFC00 bytes (20478) RAW U-Boot and reserved area
0xa00000 bytes (20480) 500 Mbytes (1024000) FAT Kernel zImage and DTBs
0x25800000 bytes (1228800) Remaining space Ext3/Ext4 Rootfs


Preparing the card

An SD/MMC card reader, such as a USB card reader, is required. SD/MMC card reader is used to transfer the bootloader and kernel images to initialize the partition table and copy the root file system. To simplify the instructions, it is assumed that a 4GB SD/MMC card is used.

Any Linux distribution can be used for the following procedure.

The Linux kernel running on the Linux host assigns a device node to the SD/MMC card reader. The kernel might decide the device node name or udev rules might be used. In the following instructions, it is assumed that udev is not used.

Drive utility can be used to identify SDX.

Copying the full SD card image

The SD card image (with the extension .sdcard) contains U-Boot, the Linux image and device trees, and the rootfs for a 4 GB SD card. The image can be installed on the SD card with one command if flexibility is not required.

$ sudo dd if=<image name>.sdcard of=/dev/sdx bs=1M && sync

Partitioning the SD/MMC card

The full SD card image already contains partitions. This section describes how to set up the partitions manually. This needs to be done to individually load the bootloader, kernel, and rootfs.

There are various ways to partition an SD card. Essentially, the bootloader image needs to be at the beginning of the card, followed by the Linux image and the device tree file. These can either be in separate partitions or not. The root file system does need to be in a partition that starts after the Linux section. Make sure that each section has enough space. The example below creates two partitions.

On most Linux host operating systems, the SD card is mounted automatically upon insertion. Therefore, before running fdisk, make sure that the SD card is unmounted if it was previously mounted (through sudo umount /dev/sdx).

Start by running fdisk with root permissions.

$ sudo fdisk /dev/sdx

Type the following parameters (each followed by <ENTER>):

p [lists the current partitions]
d [To delete existing partitions.  Repeat this until no unnecessary partitions are reported by the ‘p’ command to start fresh.]
n [create a new partition]
p [create a primary partition – use for both partitions]
1 [the first partition]
20480 [starting at offset sector]
1024000 [size for the first partition to be used for the boot images]
P [to check the partitions]
1228800 [starting at offset sector, which leaves enough space for the kernel, the bootloader and its configuration data]
<enter> [using the default value will create a partition that extends to the last sector of the media]
p [to check the partitions]
w [this writes the partition table to the media and fdisk exits]

Copying a bootloader image

Execute the following command to copy the U-Boot image to the SD/MMC card.

$ sudo dd if=<U-Boot image> of=/dev/sdx bs=512 seek=2 conv=fsync

Copying the kernel image and DTB file

This section describes how to load the kernel image and DTB when the full SD card image is not used. The pre-built SD card image uses the VFAT partition for storing kernel image and DTB, which requires a VFAT partition that is mounted as a Linux drive and the files are simply copied into it. This is the preferred method.

Another method that can be used is for users to put the kernel image and DTB to the fixed raw address of the SD card by using the dd command. The later method needs to modify the U-Boot default environment variables for loading the kernel image and DTB.

Format partition 1 on the card as VFAT with this command:

$ sudo mkfs.vfat /dev/sdx1

Mount the formatted partition with this command:

$ mkdir mountpoint

$ sudo mount /dev/sdx1 mountpoint

Copy the zImage and *.dtb files to the mount point by using cp. The device tree names should match the mount point specified by U-Boot. Be sure to un-mount the partition with this command:

$ sudo umount mountpoint

Copying the root file system (rootfs)

Copy the target file system to a partition that only contains the rootfs. This example uses partition 2 for the rootfs. First format the partition. The file system format ext3 or ext4 is a good option for the removable media due to the built-in journaling. Replace sdx with the partition in use in your configuration.

$ sudo mkfs.ext3 /dev/sdx2


$ sudo mkfs.ext4 /dev/sdx2

Copy the target file system to the partition:

$ mkdir /home/user/mountpoint

$ sudo mount /dev/sdx2 /home/user/mountpoint

Extract a rootfs package to a directory: extract fsl-image-gui-imx6qpsabreauto.ext3 to /home/user/rootfs for


$ sudo mount -o loop -t ext3 fsl-image-gui-imx6qpsabreauto.ext3 /home/user/rootfs

The rootfs directory needs to be created manually.

Assume that the root file system files are located in /home/user/rootfs as in the previous step:

$ cd /home/user/rootfs

$ sudo cp -a * /home/user/mountpoint

$ sudo umount /home/user/mountpoint

$ sudo umount /home/user/rootfs

$ sync

  • 0

Freescale Yocto Project for i.MX6 platform

Category : Blog Post


The Yocto Project is an open-source collaboration focused on embedded Linux® OS development. For more information regarding Yocto Project, see the Yocto Project page www.yoctoproject.org/. There are several documents on the Yocto Project homepage that describe in detail how to use the system. The basic Yocto Project, without the latest Freescale release layer, can be used by following instructions in the Yocto Project Quick Start found at http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html.

Freescale i.MX joined the Yocto Project community to provide a release based on the Yocto Project framework. Information specific to FSL community BSP can be found on the community webpage.


Freescale Yocto Project Release layers have the following features:

  1. Linux kernel recipe
    1. The kernel recipe resides in the recipes-kernel folder and integrates a Freescale kernel from the source downloaded from the Freescale git server. This is done automatically by the recipes in the project.
    2. 10.53_1.1.0 is a Linux kernel that Freescale has released only for the Yocto Project. Previous BSP releases based on Linux version 3.0.35 are released with ltib and are provided only from FSL Community BSP in the Yocto Project environment.
    3. Freescale L3.10.53_1.1.0 supports using device trees. Device tree settings are found in the i.MX 6 machine configuration files.
  2. U-Boot recipe
    1. The U-Boot recipe resides in the recipes-bsp folder and integrates a Freescale uboot-imx.git from the source downloaded from the Freescale git server.
    2. Certain i.MX boards use different U-Boot versions.
    3. Freescale release L3.10.53_1.1.0 for the i.MX 6 devices uses an updated v2014.04 Freescale version. This version has not been updated for other i.MX Freescale hardware.
    4. Releases based on Linux version 2.6.35 for imx5qsb uses v2009.08 from meta-fsl-arm.
    5. The Freescale Yocto Project Community BSP uses u-boot-fslc v2013.10 from the mainline but this is only supported by the community 3.0.35 kernel and will probably not work for the L3.10.53 kernel.
    6. Freescale release L3.10.53_1.1.0 requires the Freescale v2014.04 U-Boot release.
    7. The Freescale Yocto Project Community BSP updates U-Boot versions frequently, so the information above might change as new U-Boot versions are integrated to meta-fsl-arm layers and updates from Freescale u-boot-imx releases are integrated into the mainline.
  3. Graphics recipes
    1. Graphics recipes reside in recipes-graphics.
    2. Graphics recipes integrate the Freescale graphics package release. For the i.MX 6 boards, the gpu-viv-bin-mx6q recipes package the graphic components for each backend – X11, frame buffer (fb), Direct Frame Buffer (directfb), Wayland backend and Weston compositor (weston).
    3. Xorg-driver integrates our xserver-xorg.
    4. For i.MX 5, the amd-gpu-bin provides packages for X11 and frame buffer backends.
  4. MX package recipes
    1. imx-lib, imx-test, and firmware-imx reside in recipes-bsp and pull from the Freescale mirror to build and package into image recipes.
  5. Multimedia recipes
    1. Multimedia recipes reside in recipes-multimedia.
    2. Recipes include libfslcodec, libfslparser, libvpuwrap, and gstreamer that pull from the Freescale mirror to build and package into image recipes.
    3. Some recipes are provided for codecs that are restricted. Packages for these are not on the Freescale mirror. These packages are available separately. Contact your Freescale Marketing representative to acquire these.
  6. Core recipes
    1. Some recipes for rules, such as udev, provide updated i.MX rules to be deployed in the system. These recipes are usually updates of policy recipes and are used for customization only. Releases only provide updates if needed.

Host Setup

To get the Yocto Project expected behaviour in a Linux Host Machine, the packages and utilities described below must be installed. An important consideration is the hard disk space required in the host machine. For example, when building on a machine running Ubuntu, the minimum hard disk space required is about 50 GB for the X11 backend. It is recommended that at least 120 GB be provided, which is enough to compile any backend.

The recommended minimum Ubuntu version is 12.04 or later. Earlier versions may cause the Yocto Project build setup to fail, because it requires python versions only available starting with Ubuntu 12.04. See The Yocto Project reference manual for more information.

Host Packages

Essential Yocto Project host packages:

$ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \

build-essential chrpath  socat

i.MX layers host packages for a Ubuntu 12.04 or 14.04 host setup:

$ sudo apt-get install libsdl1.2-dev xterm  sed cvs subversion coreutils texi2html \

docbook-utils python-pysqlite2 help2man make gcc g++ desktop-file-utils \

libgl1-mesa-dev libglu1-mesa-dev mercurial autoconf automake groff curl lzop asciidoc

i.MX layers host packages for a Ubuntu 12.04 host setup only:

$ sudo apt-get install uboot-mkimage

i.MX layers host packages for a Ubuntu 14.04 host setup only:

$ sudo apt-get install u-boot-tools

Setting Up the Repo Utility

Create a bin folder in the home directory.

$ mkdir ~/bin (this step may not be needed if the bin folder already exists)

$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo

$ chmod a+x ~/bin/repo

Add the following line to the .bashrc file to ensure that the ~/bin folder is in your PATH variable.

export PATH=~/bin:$PATH

Yocto Project Setup

Getting Source from GIT:

$ mkdir fsl-release-bsp

$ cd fsl-release-bsp

$ git config –global user.name “Your Name”

$ git config –global user.email “Your Email”

$ git config –list

$ repo init -u git://git.freescale.com/imx/fsl-arm-yocto-bsp.git -b imx-3.10.53-1.1.0_ga

$ repo sync

Image Build


Choosing a Freescale Yocto Project Image

core-image-minimal A small image that only allows a device to boot.
core-image-base A console-only image that fully supports the target device hardware.
core-image-sato An image with Sato, a mobile environment and visual style for mobile devices. The image supports X11 with a Sato theme, Pimlico applications. It contains a terminal, an editor and a file manager.
fsl-image-machine-test An FSL Community i.MX core image with console environment – no GUI interface
fsl-image-gui Builds a Freescale image with a GUI without any QT content. This image recipe works on all backends for X11, DirectFB, Frame Buffer and Wayland
fsl-image-qt5 Builds a QT5 image for X11, Frame Buffer and Wayland Backends


Machine Configurations

In the meta-fsl-bsp-release layer, Freescale provides new or updated machine configurations that overlay the meta-fsl-arm machine configurations. These files are copied into the meta-fsl-arm/conf/machine directory by the fsl-setup-release.sh script.

The following are all the Freescale machine configuration files that can be selected:

  • imx6dlsabreauto
  • imx6dlsabresd
  • imx6qsabreauto
  • imx6qsabresd
  • imx6slevk
  • imx6solosabreauto
  • imx6solosabresd
  • imx6sxsabresd
  • imx6sxsabreauto

Bitbake Options

bitbake  <parameter> <component>

<component> is a desired build package.

Bitbake options
Bitbake paramater Description
-c fetch Fetches if the downloads state is not marked as done.
-c cleanall Cleans the entire component build directory. All the changes in the build directory will be lost. The rootfs and state of the component are also cleared. The component is also removed from the download directory.
-c deploy Deploys an image or component to the rootfs.
-k Continues building components even if a build break occurs.
-c compile -f It is not recommended that the source code under the tmp directory is changed directly, but if it is, the Yocto Project might not rebuild it unless this option is used. Use this option to force a recompile after the image is deployed.
-g Lists a dependency tree for an image or component.
-DDD Turns on debug 3 levels deep. Each D adds another level of debug.


U-Boot Configuration

U-Boot type Build setup Build command
U-Boot EIM-NOR $ echo “UBOOT_CONFIG = \”eimnor\”” >> conf/local.conf $ MACHINE=imx6dlsabreauto bitbake -c deploy u-boot-imx
U-Boot SPI-NOR $ echo “UBOOT_CONFIG = \”spinor\”” >> conf/local.conf $ MACHINE=imx6qsabreauto bitbake -c deploy u-boot-imx
U-Boot NAND $ echo “UBOOT_CONFIG = \”nand\”” >> conf/local.conf $ MACHINE=imx6solosabreauto bitbake -c deploy u-boot-imx
U-Boot SATA $ echo “UBOOT_CONFIG = \”sata\”” >> conf/local.conf $ MACHINE=imx6qsabresd bitbake -c deploy u-boot-imx
U-Boot M4 $ echo “UBOOT_CONFIG = \”m4fastup\”” >> conf/local.conf $ MACHINE=imx6sxsabresd bitbake -c deploy u-boot-imx
U-Boot QSPI1 $ echo “UBOOT_CONFIG = \”qspi1\”” >> conf/local.conf $ MACHINE=imx6sxsabreauto bitbake -c deploy u-boot-imx
U-Boot QSPI2 $ echo “UBOOT_CONFIG = \”qspi2\”” >> conf/local.conf $ MACHINE=imx6sxsabresd bitbake -c deploy u-boot-imx
U-Boot EMMC $ echo “UBOOT_CONFIG = \”emmc\”” >> conf/local.conf $ MACHINE=imx6sxsabresd bitbake -c deploy u-boot-imx
U-Boot m4fastup $ echo “UBOOT_CONFIG = \”m4fastup\”” >> conf/local.conf $ MACHINE=imx6sxsabresd bitbake -c deploy u-boot-imx


Building an Image

The Yocto Project build uses the bitbake command. For example, bitbake <component> builds the named component. Each component build has multiple tasks, such as fetching, configuration, compilation, packaging, and deploying to the target rootfs. The bitbake image build gathers all the components required by the image and build in order of the dependency per task. The first build is the toolchain along with the tools required for the components to build.

The following command is an example on how to build an image:

$ bitbake fsl-image-gui

X-11 Image on i.MX 6Quad Sabre-SD

$ MACHINE=imx6qsabresd source fsl-setup-release.sh -b build-x11 -e x11

$ bitbake fsl-image-gui

This builds an X11 image without QT5. To build with QT5, build fsl-image-qt5.

FB Image on i.MX 6Quad Sabre-AI

$ MACHINE=imx6qsabreauto source fsl-setup-release.sh –b build-fb –e fb

$ bitbake fsl-image-qt5

This builds QT5 on a frame buffer backend. To build without QT5, use image recipe fsl-image-gui.

DFB Image on i.MX 6SoloX Sabre-SD

$ MACHINE=imx6sxsabresd source fsl-setup-release.sh –b build-dfb –e dfb

$ bitbake fsl-image-gui

The fsl-image-gui image works on all backends and, if DirectFB is setup correctly in the build environment, it will enable the

DirectFB components. DirectFB does not support QT5 so only fsl-image-gui can be used with it.

Wayland Image on i.MX 6SoloX Sabre-SD

$ MACHINE=imx6sxsabresd source fsl-setup-release.sh -b build-wayland -e wayland

$ bitbake fsl-image-qt5

This builds a QT5 Weston Wayland image. To build without QT5, build fsl-image-gui.

Chromium Browser on X11 and Wayland

The Yocto Project community has chromium-imx recipes in the dizzy branch for X11 and Wayland. Note that the VPU patches used have problems but GPU patches work. This section describes how to integrate Chromium into your rootfs and enable hardware accelerated rendering of WebGL. The Chromium browser requires additional layers added in the fsl-release-setup.sh script.In local.conf, you can perform the following operations:

  • Add Chromium into your image.


  • Add the commercial white list into local.conf.


This allows proprietary code to be built into your image. Additional license obligations will need to be met for these additions. Make sure you know what they are and are in compliance.

Qt5 and WebKit Browser

Qt5 has both a commercial and an open source license. When building in Yocto Project the open source license is the default. Make sure to understand the differences between these licenses and choose appropriately. Once custom Qt5 development has started on the open source license it can’t be used with the commercial license. Work with a legal representative to understand the differences between these licenses. There are two Qt5 browsers available. Qt5WebKit can be found in /usr/share/qt5/examples/webkitwidgets/browser and WebKit2 can be found in /usr/share/qt5/examples/webkitqml/flickrview.

To run these, after booting up Linux on your device, tell Qt5 which graphics to use but setting the environment variable below. See Section “Qt5” in the i.MX Linux User’s Guide for the information on the graphics for different graphical backends.

$export QT_QPA_PLATFORM=$Graphics

Both browsers can be run by going to the directory above and running the executable found there. Touchscreen can be enabled by adding the parameters -plugin evdevtouch:/dev/input/event0 to the executable. So the command line would look like one of these:

./browser -plugin evdevtouch:/dev/input/event0

.flickrview -plugin evdevtouch:/dev/input/event0

Flashing an SD Card Image

An SD card image provides the full system to boot with U-Boot and kernel. To flash an SD card image, run the following command:

$ sudo dd if=<image name>.sdcard  of=/dev/sd<partition> bs=1M && sync

For more information on flashing, see Section “Preparing an SD/MMC Card to Boot” in the i.MX Linux User’s Guide (IMXLUG).

The Manufacturing Tool, MFGTool

One way to place an image on a device is to use the Manufacturing Tool, MFGTool. The recipes used to build a manufacturing tool image are linux-imx-mfgtool and u-boot-mfgtool. To build a manufacturing image do the following –

$ bitbake fsl-image-mfgtool-initramfs

A manufacturing tool kernel is built using the imx_v7_mfg_defconfig while the default kernel is built by using the imx_v7_defconfig. This is handled automatically by the MFGTool recipes listed above.