NXP Semiconductors
User's Guide
Document Number: IMXLXYOCTOUG
Rev. L4.9.88_2.0.0-ga, 05/2018
i.MX Yocto Project User's Guide
Contents
1
2
3
4
5
6
7
Overview................................. ................................. 1
Features.....................................................................3
Host Setup................................................................. 4
Yocto Project Setup....................... ...........................5
Image Build...............................................................6
Image Deployment.................................................. 13
Customization........................... .............................. 13
A Frequently Asked Questions............ .......................15
B
C
References...............................................................19
Revision History......................... ............................ 19
1 Overview
This document describes how to build an image for an i.MX
board by using a Yocto Project build environment. It describes
the i.MX release layer and i.MX-specific usage.
The Yocto Project is an open-source collaboration focused on
embedded Linux® OS development. For more information on
Yocto Project, see the Yocto Project page:
www.yoctoproject.org/. There are several documents on the
Yocto Project home page that describe in detail how to use the
system. To use the basic Yocto Project without the i.MX
release layer, follow the instructions in the Yocto Project
Quick Start found at www.yoctoproject.org/docs/current/
yocto-project-qs/yocto-project-qs.html.
The FSL Yocto Project Community BSP (found at
freescale.github.io ) is a development community outside NXP
providing support for i.MX boards in the Yocto Project
environment. i.MX joined the Yocto Project community
providing a release based on the Yocto Project framework.
Information specific to FSL community BSP use is available
on the community web page. This document is an extension of
the community BSP documentation.
Files used to build an image are stored in layers. Layers
contain different types of customizations and come from
different sources. Some of the files in a layer are called
recipes. Yocto Project recipes contain the mechanism to
retrieve source code, build and package a component. The
following lists show the layers used in this release.
Overview
i.MX release layer
• meta-fsl-bsp-release
• meta-bsp - updates for meta-freescale, poky, and meta-openembedded layers
• meta-sdk - updates for meta-freescale-distros
Yocto Project community layers
• meta-freescale: provides support for the base and for i.MX Arm® reference boards.
• meta-freescale-3rdparty: provides support for 3rd party and partner boards.
• meta-freescale-distro: additional items to aid in development and exercise board capabilities.
• fsl-community-bsp-base: often renamed to base. Provides base configuration for FSL Community BSP.
• meta-openembedded: Collection of layers for the OE-core universe. See layers.openembedded.org/.
• poky: basic Yocto Project items in Poky. See the Poky README for details.
• meta-browser: provides several browsers.
• meta-qt5: provides Qt5.
References to community layers in this document are for all the layers in Yocto Project except meta-fsl-bsp-release. i.MX
boards are configured in the meta-fsl-bsp-release and meta-freescale layers. This includes U-Boot, the Linux kernel, and
reference board-specific details.
i.MX provides an additional layer called the i.MX BSP Release, named meta-fsl-bsp-release, to integrate a new i.MX release
with the FSL Yocto Project Community BSP. The meta-fsl-bsp-release layer aims to release the updated and new Yocto
Project recipes and machine configurations for new releases that are not yet available on the existing meta-freescale and
meta-freescale-distro layers in the Yocto Project. The contents of the i.MX BSP Release layer are recipes and machine
configurations. In many test cases, other layers implement recipes or include files and the i.MX release layer provides
updates to the recipes by either appending to a current recipe, or including a component and updating with patches or source
locations. Most i.MX release layer recipes are very small because they use what the community has provided and update
what is needed for each new package version that is unavailable in the other layers.
The i.MX BSP Release layer also provides image recipes that include all the components needed for a system image to boot,
making it easier for the user. Components can be built individually or through an image recipe, which pulls in all the
components required in an image into one build process.
The i.MX kernel and U-Boot releases are accessed through i.MX public git servers. However, several components are
released as packages on the i.MX mirror. The package-based recipes pull files from the i.MX mirror instead of a git location
and generate the package needed.
All packages which are released as binary are built with hardware floating point enabled as specified by the
DEFAULTTUNE defined in each machine configuration file. Software floating point packages are not provided starting with
the jethro releases.
Release L4.9.88_2.0.0-ga is released for Yocto Project 2.4 (Rocko). The same recipes for Yocto Project 2.4 are going to be
upstreamed and made available on the next release of the Yocto Project release. The Yocto Project release cycle lasts roughly
six months.
The recipes and patches in meta-fsl-bsp-release are upstreamed to the community layers. After that is done for a particular
component, the files in meta-fsl-bsp-release are no longer needed and the FSL Yocto Project Community BSP will provide
support. The community supports i.MX reference boards, community boards, and third-party boards. A complete list can be
found at freescale.github.io/doc/release-notes/2.2/index.html#document-bsp-scope. All board references in this document are
related to the i.MX machine configuration files only.
1.1 End user license agreement
During the setup environment process of the Freescale Yocto Project Community BSP, the NXP End User License
Agreement (EULA) is displayed. To continue to use the i.MX Proprietary software, users must agree to the conditions of this
license. The agreement to the terms allows the Yocto Project build to untar packages from the i.MX mirror.
2
NXP Semiconductors
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018
Read this license agreement carefully during the setup process, because once accepted, all
further work in the i.MX Yocto Project environment is tied to this accepted agreement.
NOTE
Features
1.2 References
This release includes the following references and additional information.
• i.MX Linux® Release Notes (IMXLXRN) - Provides the release information.
• i.MX Linux® User's Guide (IMXLUG) - Contains the information on installing U-Boot and Linux OS and using i.MX-
specific features.
• i.MX Yocto Project User's Guide (IMXLXYOCTOUG) - Contains the instructions for setting up and building Linux
OS in the Yocto Project.
• i.MX Reference Manual (IMXLXRM) - Contains the information on Linux drivers for i.MX.
• i.MX Graphics User's Guide (IMXGRAPHICUG) - Describes the graphics features.
• i.MX BSP Porting Guide (IMXXBSPPG) - Contains the instructions on porting the BSP to a new board.
• i.MX VPU Application Programming Interface Linux® Reference Manual (IMXVPUAPI) - Provides the reference
information on the VPU API.
The quick start guides contain basic information on the board and setting it up. They are on the NXP website.
• SABRE Platform Quick Start Guide (IMX6QSDPQSG)
• SABRE Board Quick Start Guide (IMX6QSDBQSG)
• i.MX 6UltraLite EVK Quick Start Guide (IMX6ULTRALITEQSG)
• i.MX 6ULL EVK Quick Start Guide (IMX6ULLQSG)
• SABRE Automotive Infotainment Quick Start Guide (IMX6SABREINFOQSG)
• i.MX 6SoloLite Evaluation Kit Quick Start Guide (IMX6SLEVKQSG)
• i.MX 7Dual SABRE-SD Quick Start Guide (SABRESDBIMX7DUALQSG)
• i.MX 8MQuad Evaluation Kit Quick Start Guide (IMX8MQUADEVKQSG)
Documentation is available online at nxp.com.
• i.MX 6 information is at nxp.com/iMX6series
• i.MX SABRE information is at nxp.com/imxSABRE
• i.MX 6SoloLite EVK information is at nxp.com/6SLEVK
• i.MX 6UltraLite information is at nxp.com/iMX6UL
• i.MX 6ULL information is at nxp.com/iMX6ULL
• i.MX 7Dual information is at nxp.com/iMX7D
• i.MX 7ULP information is at nxp.com/imx7ulp
• i.MX 8 information is at nxp.com/imx8
2 Features
i.MX Yocto Project Release layers have the following features:
• Linux kernel recipe
• The kernel recipe resides in the recipes-kernel folder and integrates a i.MX kernel from the source downloaded
from the i.MX git server. This is done automatically by the recipes in the project.
• L4.9.88_2.0.0-ga is a Linux kernel released for the Yocto Project.
• U-Boot recipe
• The U-Boot recipe resides in the recipes-bsp folder and integrates a i.MX uboot-imx.git from the source
downloaded from the i.MX git server.
NXP Semiconductors
3
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018
Host Setup
• Certain i.MX boards use different U-Boot versions.
• i.MX release L4.9.88_2.0.0-ga for the i.MX 6, i.MX 7, i.MX 8 devices uses an updated v2017.03 i.MX U-Boot
version. This version has not been updated for all i.MX hardware.
• The i.MX Yocto Project Community BSP uses u-boot-fslc from the mainline, but this is only supported by the U-
Boot community and is not supported with the L4.9.88 kernel.
• The i.MX Yocto Project Community BSP updates U-Boot versions frequently, so the information above might
change as new U-Boot versions are integrated to meta-freescale layers and updates from i.MX u-boot-imx
releases are integrated into the mainline.
• Graphics recipes
• Graphics recipes reside in recipes-graphics folder.
• Graphics recipes integrate the i.MX graphics package release. For the i.MX boards that have a GPU, the imx-
gpu-viv recipes package the graphic components for each DISTRO – X11, frame buffer (FB), XWayland,
Wayland backend, and Weston compositor (Weston). Only i.MX 6 and i.MX 7 support X11 and Frame Buffer.
• Xorg-driver integrates the xserver-xorg.
• i.MX package recipes
imx-lib, imx-test, and firmware-imx reside in recipes-bsp and pull from the i.MX mirror to build and package into
image recipes.
• Multimedia recipes
• Multimedia recipes reside in recipes-multimedia.
• Recipes include imx-codec, imx-parser, libvpuwrap, and imx-gstreamer-plugins that pull from the i.MX mirror to
build and package into image recipes.
• Some recipes are provided for codecs that are restricted. Packages for these are not on the i.MX mirror. These
packages are available separately. Contact your i.MX Marketing representative to acquire these.
• Core recipes
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 and are used for customization only. Releases only provide updates if needed.
• Demo recipes
Demonstration recipes reside in the meta-sdk directory. This layer contains image recipes and recipes for
customization, such as touch calibration, or recipes for demonstration applications.
3 Host Setup
To get the Yocto Project expected behavior 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 is provided, which is enough to compile all backends together.
The recommended minimum Ubuntu version is 14.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.
Ubuntu 16.04 users have commented on errors during build for SDL. To fix this comment out in local.conf the following
lines as such adding # character
#PACKAGECONFIG_append_pn-qemu-native = " sdl"
#PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
4
NXP Semiconductors
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018
3.1 Host packages
A Yocto Project build requires that some packages be installed for the build that are documented under the Yocto Project. Go
to Yocto Project Quick Start and check for the packages that must be installed for your build machine.
Essential Yocto Project host packages are:
Yocto Project Setup
$ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat libsdl1.2-dev
i.MX layers host packages for a Ubuntu 12.04 or 14.04 host setup are:
$ 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 are:
$ sudo apt-get install uboot-mkimage
i.MX layers host packages for a Ubuntu 14.04 host setup only are:
$ sudo apt-get install u-boot-tools
The configuration tool uses the default version of grep that is on your build machine. If there is a different version of grep in
your path, it may cause builds to fail. One workaround is to rename the special version to something not containing "grep".
3.2 Setting up the repo utility
Repo is a tool built on top of Git that makes it easier to manage projects that contain multiple repositories, which do not need
to be on the same server. Repo complements very well the layered nature of the Yocto Project, making it easier for users to
add their own layers to the BSP.
To install the “repo” utility, perform these steps:
1. Create a bin folder in the home directory.
$ mkdir ~/bin (this step may not be needed if the bin folder already exists)
$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
2. Add the following line to the .bashrc file to ensure that the ~/bin folder is in your PATH variable.
export PATH=~/bin:$PATH
4 Yocto Project Setup
First make sure that git is set up properly with the commands below.
$ git config --global user.name "Your Name"
$ git config --global user.email "Your Email"
$ git config --list
The i.MX Yocto Project BSP Release directory contains a sources directory, which contains the recipes used to build one
or more build directories, and a set of scripts used to set up the environment.
NXP Semiconductors
5
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018
Image Build
The recipes used to build the project come from both the community and i.MX. The Yocto Project layers are downloaded to
the sources directory. This sets up the recipes that are used to build the project.
The following example shows how to download the i.MX Yocto Project Community BSP recipe layers. For this example, a
directory called imx-yocto-bsp is created for the project. Any name can be used instead of this.
$ mkdir imx-yocto-bsp
$ cd imx-yocto-bsp
$ repo init -u https://source.codeaurora.org/external/imx/imx-manifest -b imx-linux-rocko -
m imx-4.9.88-2.0.0_ga.xml
$ repo sync
https://source.codeaurora.org/external/imx/imx-manifest/tree/?h=imx-linux-rocko has a
list of all manifest files supported in this release.
NOTE
When this process is completed, the source code is checked out into the directory imx-yocto-bsp/sources.
You can perform repo synchronization, with the command repo sync, periodically to update to the latest code.
If errors occur during repo initialization, try deleting the .repo directory and running the repo initialization command again.
The repo init is configured for the latest patches in the line. Follow the instructions in index: imx-manifest.git to retrieve
the original GA. Otherwise, GA plus patches are picked up by default. To pick up previous releases from rocko base add -m
(release manifest name) at the end of repo init line and it will retrieve previous releases. Examples are provided in the
README in the link provided above.
5 Image Build
This section provides the detailed information along with the process for building an image.
5.1 Build configurations
i.MX provideds a script, fsl-setup-release.sh, that simplifies the setup for i.MX machines. To use the script, the name
of the specific machine to be built for needs to be specified as well as the desired graphical backend. The script sets up a
directory and the configuration files for the specified machine and backend.
In the meta-fsl-bsp-release layer, i.MX provides new or updated machine configurations that overlay the meta-
freescale machine configurations. These files are copied into the meta-freescale/conf/machine directory by the
fsl-setup-release.sh script. The following are i.MX machine configuration files that can be selected. Check either the
release notes or the machine directory for the latest additions.
• imx6qpsabreauto
• imx6qpsabresd
• imx6ulevk
• imx6ull14x14evk
• imx6ull9x9evk
• imx6dlsabreauto
• imx6dlsabresd
• imx6qsabreauto
• imx6qsabresd
• imx6slevk
• imx6solosabreauto
• imx6solosabresd
• imx6sxsabresd
6
NXP Semiconductors
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018
Image Build
• imx6sxsabreauto
• imx6sllevk
• imx7dsabresd
• imx7ulpevk
• imx8mqevk
Each build folder must be configured in such way that they only use one distro. Each time the variable DISTRO_FEATURES
is changed, a clean build folder is needed. Each graphical backend Frame Buffer, Wayland, XWayland, and X11 each have a
distro configuration. If no DISTRO file is specified, the xwayland distro is set up as default. Distro configurations are saved
in the local.conf in the DISTRO setting and are displayed when the bitbake is running. In past releases, we used the poky
distro and customized versions and providers in our layer.conf but a custom distro is a better solution. When the default poky
distro is used, the default community configuration is used. As a i.MX release, we prefer to have a set of configurations that
NXP supports and has been testing.
Here are the list of DISTRO configurations. Note that DirectFB is no longer supported and fsl-imx-wayland and fsl-imx-fb
are not validated in our test cycle.
• fsl-imx-x11 - X11 graphics are not supported on i.MX 8.
• fsl-imx-wayland - Wayland weston graphics.
• fsl-imx-xwayland - Wayland graphics and X11. X11 applications using EGL are not supported.
• fsl-imx-fb - Frame Buffer graphics - no X11 or Wayland. Frame Buffer is not supported on i.MX 8.
Users are welcome to create their own distro file based on one of these to customize their environment without updating the
local.conf to set preferred versions and providers.
The syntax for the fsl-setup-release.sh script is shown below.
$ DISTRO= MACHINE= source fsl-setup-release.sh -b
DISTRO= is the distro, which configures the build environment and it is stored in meta-fsl-
bsp-release/imx/meta-sdk/conf/distro.
MACHINE= is the machine name which points to the configuration file in conf/machine in
meta-freescale and meta-fsl-bsp-release.
-b specifies the name of the build directory created by the fsl-setup-release.sh script.
When the script is run, it prompts the user to accept the EULA. Once the EULA is accepted, the acceptance is stored in
local.conf inside each build folder and the EULA acceptance query is no longer displayed for that build folder.
After the script runs, the working directory is the one just created by the script, specified with the -b option. A conf folder is
created containing the files bblayers.conf and local.conf.
The /conf/bblayers.conf file contains all the metalayers used in the i.MX Yocto Project release.
The local.conf file contains the machine and distro specifications:
MACHINE ??= 'imx7ulpevk'
DISTRO ?= 'fsl-imx-x11'
ACCEPT_FSL_EULA = "1"
The MACHINE configuration can be changed by editing this file, if necessary.
ACCEPT_FSL_EULA in the local.conf file indicates that you have accepted the conditions of the EULA.
In the meta-fsl-bsp-release layer, consolidated machine configurations (imx6qpdlsolox.conf and imx6ul7d.conf) are provided
for i.MX 6 and i.MX 7 machines. i.MX uses these to build a common image with all the device trees in one image for testing.
Do not use these machines for anything other than testing.
NXP Semiconductors
7
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018
Image Build
5.2 Choosing an i.MX Yocto project image
The Yocto Project provides some images which are available on different layers. Poky provides some images, meta-
freescale and meta-freescale-distro provide others, and additional image recipes are provided in the meta-fsl-
bsp-release layer. The following table lists various key images, their contents, and the layers that provide the image
recipes.
Image name
core-image-minimal
core-image-base
core-image-sato
fsl-image-machine-test
Poky
Poky
Poky
Table 1.
i.MX Yocto project images
Target
Provided by layer
A small image that only allows a device to boot.
A console-only image that fully supports the target device
hardware.
An image with Sato, a mobile environment and visual style
for mobile devices. The image supports X11 with a Sato
theme and uses Pimlico applications. It contains a
terminal, an editor and a file manager.
An FSL Community i.MX core image with console
environment - no GUI interface.
Builds an i.MX image with a GUI without any Qt content. meta-fsl-bsp-release/imx/meta-sdk
meta-fsl-bsp-release/imx/meta-sdk
meta-freescale-distro
fsl-image-validation-imx
fsl-image-qt5-validation-imx Builds an opensource Qt 5 image. These images are only
supported for i.MX SoC with hardware graphics. They are
not supported on the i.MX 6UltraLite, i.MX 6UltraLiteLite,
and i.MX 7Dual.
5.3 Building an image
The Yocto Project build uses the bitbake command. For example, bitbake
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-validation-imx
5.4 Bitbake options
The bitbake command used to build an image is bitbake . Additional parameters can be used for specific
activities described below. Bitbake provides various useful options for developing a single component. To run with a bitbake
parameter, the command looks like this:
bitbake
is a desired build package.
The following table provides some bitbake options.
8
NXP Semiconductors
i.MX Yocto Project User's Guide, Rev. L4.9.88_2.0.0-ga, 05/2018