Skip to content

Building a Linux Distro with Yocto for the Variscite MX7

This guide is based heavily on the official guide from Variscite, with some additional info i found useful while learning this.

1 Dependencies

1.1 Ubuntu 16.04 LTS & 18.04 LTS

This tutorial was made with a machine running Ubuntu 18.04 LTS 64-bit, which worked almost flawless, though Variscite's original tutorial is based on Ubuntu 16.04 64-bit.

sudo apt-get install gawk wget git diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping libsdl1.2-dev xterm

sudo apt-get install autoconf libtool libglib2.0-dev libarchive-dev python-git \
sed cvs subversion coreutils texi2html docbook-utils python-pysqlite2 \
help2man make gcc g++ desktop-file-utils libgl1-mesa-dev libglu1-mesa-dev \
mercurial automake groff curl lzop asciidoc u-boot-tools dos2unix mtd-utils pv \
libncurses5 libncurses5-dev libncursesw5-dev libelf-dev zlib1g-dev

1.2 Ubuntu 20.04 LTS

Compiling Yocto thud does not work on Ubuntu 20.04 LTS 64-bit. The GNU C library, or short glibc, is version 2.30 in Ubuntu 20.04, which is incompatible to glibc 2.29, which the bitbake command expects. This patch from OCtober 2019 in the OpenEmbedded Core Layer fixes this, but it hasn't been implemented into the Variscite BSP for Yocto thud. The last update for the thud-fslc-4.14.78-mx7-v1.0 tag was in May 2019, so it probably won't be updated anymore. Downgrading the glibc is not recommended, so you should compile it in a virtual machine or with docker.

2 Download Yocto Thud based on Freescale Community BSP

First we set up our git username and email. If you already set up git, you can skip this.

git config --global user.name "Your Name"
git config --global user.email "Your Email"

Next we are going to Download repo. repo is a layer on top of git to simplify some tasks.

curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > /usr/local/bin/repo
chmod a+x /usr/local/bin/repo

or sudo apt install repo (This version could be older than the one you would download via curl)

Then we are going to make our folder where all our development files will be located and switch to that folder.

mkdir ~/dev/var-fslc-yocto

Next you can either choose a specific release tag:

repo init -u https://github.com/varigit/variscite-bsp-platform.git -b refs/tags/TAG_NAME

For example:
repo init -u https://github.com/varigit/variscite-bsp-platform.git -b refs/tags/thud-fslc-4.14.78-mx7-v1.0
repo sync -j4

Or you choose the latest release, which is recommended:

repo init -u https://github.com/varigit/variscite-bsp-platform.git -b thud
repo sync -j4

3 Setup and build Yocto

3.1 Supported images

The following images are provided by Variscite for evaluation purpose: - fsl-image-gui: Default Variscite demo image with GUI and without any Qt5 content. This image recipe works on all backends for X11, Frame Buffer and Wayland and the content is optimized to fit 512MB NAND flash. - fsl-image-qt5: Extends fsl-image-gui image with Qt5 support and various Qt samples for X11, Frame Buffer and Wayland backends.

Note: Will result in image size greater than 512 MB, which will not fit into NAND flash. Use SD card or eMMC to test.

The following images are provided by FSL Community BSP:

  • fsl-image-machine-test: A console-only image that includes gstreamer packages and test and benchmark applications.
  • fsl-image-mfgtool-initramfs: Small image to be used with Manufacturing Tool (mfg-tool) in a production environment.

See the list of Yocto Project’s reference images in Yocto Project Reference Manual.

3.2 Supported distros

The following distros can be used:

  • fslc-x11: Distro for X11 without wayland. This distro include x11 feature and doesn’ has wayland support.
  • fslc-framebuffer: Distro for Framebuffer graphical backend. This distro doesn’t include X11 and wayland features.
  • fslc-wayland: Distro for Wayland without X11. This distro includes wayland feature but doesn’t have x11 support.
  • fslc-xwayland: Distro for Wayland with X11. This distro includes both wayland and X11 features.

Note: Also standard Poky distros can be used

3.3 Build X11 GUI demo image

cd ~/var-fslc-yocto
MACHINE=imx7-var-som DISTRO=fslc-x11 . setup-environment build_x11

The above command is only mandatory for the very first build setup: whenever restarting a newer build session (from a different terminal or in a different time), you can skip the full setup and just run:

cd ~/var-fslc-yocto
source setup-environment build_x11

Optionally you can customize the local.conf. See chapter 4

launch bitbake:

Without Qt content:

bitbake fsl-image-gui

Or with Qt content:

bitbake fsl-image-qt5

3.4 Build console-only demo image

cd ~/var-fslc-yocto
MACHINE=imx7-var-som DISTRO=fslc-framebuffer . setup-environment build_fb

Optionally you can customize the local.conf. See chapter 4

Without Qt content:

bitbake fsl-image-gui

Or with Qt content:

bitbake fsl-image-qt5

3.5 Forcing Clean Build

In order to update the kernel, U-Boot and rootfs:

bitbake -c cleanall u-boot-variscite linux-variscite kernel-module-imx-gpu-viv ti-compat-wireless-wl18xx wl18xx-firmware cryptodev-module

for GUI image

bitbake -c clean fsl-image-gui

for Qt5 image

bitbake -c clean fsl-image-qt5

4 Customization

4.1 Customize the Linux Kernel

To customize the Linux Kernel, first, source the setup-environment script, f.e.:

source setup-environment build_x11

Then run menuconfig and configure the Kernel to your needs:

bitbake -c menuconfig virtual/kernel

When finished, save and exit.

The .config file is saved to ~/dev/var-fslc-yocto/build_x11/tmp/work/imx7_var_som-fslc-linux-gnueabi/linux-variscite/4.14.78-r0/build/.config

  • At this point, you can continue following the rest of step 4 of the Yocto Build Release page to build your image with the newly configured kernel, or just build the kernel by running "bitbake virtual/kernel", or, you can follow the next steps to use this configuration permanently.

To save the configuration in a defconfig format:

bitbake -c savedefconfig virtual/kernel

The defconfig file is saved to ~/dev/var-fslc-yocto/build_x11/tmp/work/imx7_var_som-fslc-linux-gnueabi/linux-variscite/4.14.78-r0/build/defconfig

To make the Kernel recipe use this configuration permanently, you copy it to another location and create a .bbappend file, which links the defconfig to the kernel recipe.

Copy your defconfig:

cd ~/dev/var-fslc-yocto/sources/meta-variscite-fslc/recipes-kernel/linux/
mkdir -p files
cp ~/dev/var-fslc-yocto/build_x11/tmp/work/imx7_var_som-fslc-linux-gnueabi/linux-variscite/4.14.78-r0/build/defconfig  files/my_defconfig

Create a linux-variscite_4.14.78.bbappend file:

gedit linux-variscite_4.14.78.bbappend

and append the following to it:

SRC_URI += "file://my_defconfig"
KERNEL_DEFCONFIG_imx7-var-som = "${WORKDIR}/my_defconfig"

4.1 Use systemd instead of SysV init

Append the following to the conf/local.conf file in your Yocto build directory, to use systemd instead of SysV init in your images:

DISTRO_FEATURES_append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_initscripts = ""
IMX_DEFAULT_DISTRO_FEATURES_append = " systemd"

4.2 Add additional packages

4.2.1 General

Packages and package groups can be added to image recipes. See the Yocto Development manual for how to customize an image: http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#usingpoky-extend-customimage-imagefeatures

4.2.2 Adding a package to the local build of the BSP

Search for the corresponding recipe and which layer the recipe is in. This link is a useful tool for doing so: http://layers.openembedded.org/layerindex/branch/morty/layers/

If the package is in the meta-openembedded layer, the recipe is already available in your build tree.

Add the following line to YOCTO_DIR/BUILD_DIR/conf/local.conf:

IMAGE_INSTALL_append = " "

Note: The leading white-space between the " and the package name is necessary for the append command.

If you need to add a layer to the BSP, clone or extract it to the YOCTO_DIR/sources/ directory. Then, modify YOCTO_DIR/BUILD_DIR/conf/bblayers.conf to include this new layer in BBLAYERS:

BBLAYERS += "${BSPDIR}/sources/"

3 Webserver support

Recipes in meta-openembedded/meta-webserver/recipes-httpd: - apache2 - cherokee - hiawatha - monkey - nginx - nostromo - sthttpd Recipes in poky/meta/recipes-extended/lighttpd: - lighttpd

Although full of capabilities and features, Apache is commonly considered quite heavy, so is not generally used for embedded devices. Nostromo and sthttpd are commonly considered ultralight webserver, with a very small set of capabilities and features, with very limited resource requirements. The usual choice is usually between the following 5: - cherokee - hiawatha - monkey - nginx - lighttpd Here you can find an article comparing the above 5 webserver: https://www.linux.com/news/which-light-weight-open-source-web-server-right-you

4 Accelerated browsers support

Yocto build system allow integrating browsers that support iMX6 GPU accelerations.

The common used browsers are:

qtwebkit based browsers: QtWebKit is the WebKit porting to QT. WebKit is an open source web browser engine. QT5 provide some demo implementations in webkitwidgets examples.
qtwebengine based browsers: QtWebEngine integrates chromium's fast moving web capabilities into QT. QT5 provide some demo implementations in webenginewidgets examples.
chromium based browsers: Chromium is an open-source browser project.

Till 2016, FSLC community maintained chromium-imx project: customized Chromium versions (up to v48) providing GPU and VPU integration for iMX6 CPUs.

Much more updated Chromium versions are available from meta-browser, only providing GPU integration.

The minimum requirements to use chromium browsers is X11 or Wayland.

QT based browsers directly rely on QT integration with iMX6 accelerations.

QtWebKit has been superseded by QtWebEngine, mainly because QtWebKit has not been actively synchronized with the upstream WebKit code since Qt 5.2 and has been deprecated in Qt 5.5. Further details are available in Qt WebEngine Overview

QT team provides a QtWebEngine browser for embedded touch devices and related recipes hase been integrated in our BSP starting from Sumo.

The performance of each browser is strictly related to the features to be used, so different html applications can provide better performance with different browsers.

The following table try to summarize some benchmark for Wayland backend: website QtWebKit QtWebEngine Chromium http://peacekeeper.futuremark.com crash 623 n/a http://www.kevs3d.co.uk/dev/canvasmark n/a 4796 3780 http://webglsamples.org/blob/blob.html 2 fps 32 fps 34 fps 4.1 Add QtWebKit examples to the build

Add the following line to YOCTO_DIR/BUILD_DIR/conf/local.conf:

IMAGE_INSTALL_append = " qtwebkit-examples-examples"

The demo browser used for the above tests is available as

/usr/share/qt5/examples/webkitwidgets/fancybrowser/fancybrowser

4.2 Add QtWebEngine examples to the build

Add the following line to YOCTO_DIR/BUILD_DIR/conf/local.conf:

IMAGE_INSTALL_append = " qtwebengine-examples"

The demo browser used for the above tests is available as

/usr/share/qt5/examples/webenginewidgets/fancybrowser/fancybrowser

4.3 Add Chromium to the build

Add the following line to YOCTO_DIR/BUILD_DIR/conf/local.conf:

IMAGE_INSTALL_append = " chromium" LICENSE_FLAGS_WHITELIST += "commercial_libav commercial_x264"

If you plan to use Chromium, please take care of the specific requirements for commercial license of libav and x264 packages.

The demo browser used for the above tests is available as

/usr/bin/google-chrome

5 Create a bootable SD card

5.1 Yocto pre-built SD card

The Yocto build products contains many files. For example, fsl-image-gui-imx7-var-som.wic.gz, depending on your build. This is a complete image to be flashed directly to an SD card.

Example usage:

sudo umount /dev/sdX*

# For GUI-X11 & Qt5-X11
cd ~/var-fslc-yocto/build_x11
# Or
# For Qt5-FB
cd ~/var-fslc-yocto/build_fb

# For fsl-image-gui image (GUI-X11)
zcat tmp/deploy/images/imx7-var-som/fsl-image-gui-imx7-var-som.wic.gz | sudo dd of=/dev/sdX bs=1M && sync
# Or
# For fsl-image-qt5 image (Qt5-X11 & Qt5-FB)
zcat tmp/deploy/images/imx7-var-som/fsl-image-qt5-imx7-var-som.wic.gz | sudo dd of=/dev/sdX bs=1M && sync

Replace sdX with the right device name. This can be obtained by "dmesg" command on your host Linux PC, after the SD card reader is inserted.

Note: Booting your system from an SD card requires pressing the boot-select button, or switching the relevant DIP switch to "Boot from SD card", according to the relevant start-up guide of your system.

Drawbacks of the native .wic.gz yocto-built image, (relative to the Recovery/Extended SD card): - The rootfs partition doesn't use the entire SD card. - The rootfs partition is not labeled as rootfs. - The NAND flash and eMMC installation scripts and images are not included.