Setup ===== References ---------- This guide is based on the *NXP/Freescale Yocto Project User's Guide* (IMXLXYOCTOUG) The instructions for setting up and building Linux in the Yocto Project were adopted to our products and the ARMSDK environment. Documentation is available online at nxp.com. `i.MX Software and Development Tools `_ A list of helpful bitbake commands can be found here: `NXP/Freescale - Useful bitbake commands `_ A cheat sheet for bitbake: `Bitbake Cheat Sheet `_ Requirements -------------------- For Yocto a Linux Host Machine is needed. .. hint:: The list of supported machines for your Build Host is available here: https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#detailed-supported-distros For this purpose Ka-Ro used to offer a Virtual Appliance, called ARMSDK VM, while this can still be used it's not recommended anymore. We now recommend to grab a solution from a provider of for virtual appliances like `osboxes.org `_. Like these (recommended: devuan): `https://www.osboxes.org/devuan-linux/ `_ `https://www.osboxes.org/debian/ `_ `https://www.osboxes.org/ubuntu-mate/ `_ An important consideration is the hard disk space required for the virtual appliance. It is recommended that **at least** 120 GiB is provided, if not 500 GiB. Should there be not enough space in the VA solution it can always be extended by adding a new HDD to the VM and mounting from a general mount point into the directory structure of development user in the VA, e.g. `here `_. Host packages ------------- The Yocto framework requires (build) dependencies, packages that need to be installed/available on the host system for the builds like documented herein to pass successfully. Example for Debian based (e.g. Devuan / Debian / Ubuntu) distribution: First of all update your local repository: .. code-block:: shell sudo apt-get update Install essential Yocto Project host packages: .. code-block:: shell sudo apt-get install gawk wget git-core diffstat unzip \ texinfo gcc-multilib build-essential chrpath socat i.MX layers host packages: .. code-block:: shell 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 u-boot-tools Upgrade git version ------------------- A `git `_ version of ≤ 1.8.3.1 has bugs which will break builds. Please ensure a current version of git is installed. Check installed version: .. code-block:: shell git --version Update your local repository if not already just done before: .. code-block:: shell sudo apt-get update Hereafter an upgrade example for users of a VA's with an older Debian (>Wheezy) like the the one Ka-Ro offered. Upgrade to git version 1.9.1 on ARMSDK-VM v7 - Debian Wheezy: .. code-block:: shell sudo apt-get remove git sudo apt-get install git-man/wheezy-backports git/wheezy-backports Setting up git -------------- After making sure the most recent *git* version (at least > 1.8.3.1) is available, as described above, the tool should also be configured. The (non-root) user working directly with the sources needs to be defined. If not defined, either the *git* tool or the hereafter mentioned repo tool will call this irregularity to the attention of the user. A proper setup is a requirement for the handling of the sources as governed by the *git* `VCS `_, as git uses these information in conjunction with its source management features. Setup git with the commands below: .. code-block:: shell git config --global user.name "Your Name" git config --global user.email "Your Email" git config --list Setting up the repo utility --------------------------- Thus does the *repo tool* complement very well the layered nature of the Yocto Project, making it among other things easier for customers to either just generally expand or add their own layers to the BSP. To install the *repo utility*, perform these steps: .. code-block:: shell mkdir ~/bin PATH=${PATH}:~/bin curl 'http://commondatastorage.googleapis.com/git-repo-downloads/repo' > ~/bin/repo chmod a+x ~/bin/repo Yocto Project Setup ------------------- The 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. 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 BSP recipe layers. For this example, a directory called karo-yocto-rocko is created for the project (usually under a directory like ``$HOME/projects/`` is recommend). Use the stable branch ``rocko``: .. code-block:: shell mkdir karo-yocto-rocko cd karo-yocto-rocko repo init -u https://github.com/karo-electronics/karo-bsp -b rocko repo sync When this process is completed, the source code is checked out into the directory ``sources`` under the working directory (in example above ``karo-yocto-rocko``). .. note:: The above given ``repo`` command deviates from the standard command as to overcome an error (specifically a http 404 error) when using ``repo init``. The standard command would be: .. code-block:: shell repo init -u https://github.com/karo-electronics/karo-bsp -b rocko User should update the codebase periodically, which can be performed via the following command: .. code-block:: shell repo sync After a prolonged timespan an update is **strongly** recommended. If errors occur during repo initialization, try deleting the ``.repo`` directory and running the repo initialization command again. Choosing a machine ------------------ This release supports the following machines. Depending on the target to be compiled choose the machine configuration that matches your TXCOM module. .. note:: The user has to differentiate between payload software, like the operating system (GNU/Linux), and the bootloader (U-Boot), thus there are in below given table two different settings for ``MACHINE=``. .. note:: This is an effect for the BSP as the U-Boot bootloader requires a different toolchain to be compiled with. +------------------+---------------------+------------------+-----------------------------+ | ``MACHINE=`` | U-Boot ``MACHINE=`` | TXCOM number | TXCOM name | +==================+=====================+==================+=============================+ | **TX6Q** | +------------------+---------------------+------------------+-----------------------------+ | NAND Modules | +------------------+---------------------+------------------+-----------------------------+ | | | *TX6Q-1010* | *(Legacy)* | | +---------------------+------------------+-----------------------------+ | | tx6q-1030 | TX6Q-1030 | TX6Q/1000/1024S/128F | | imx6q-tx6-nand +---------------------+------------------+-----------------------------+ | | | *TX6Q-1110* | *(Legacy)* | | +---------------------+------------------+-----------------------------+ | | tx6q-1130 | TX6Q-1130 | TX6Q/1000/1024S/128F/LVDS | +------------------+---------------------+------------------+-----------------------------+ | eMMC Modules | +------------------+---------------------+------------------+-----------------------------+ | imx6q-tx6-emmc | tx6q-1036 | TX6Q-1036 | TX6Q/1000/1024S/8GF | +------------------+---------------------+------------------+-----------------------------+ | **TX6QP** | +------------------+---------------------+------------------+-----------------------------+ | eMMC Modules | +------------------+---------------------+------------------+-----------------------------+ | | tx6q-8037 | TX6Q-8037 | TX6QP/800/1GS/8GF/I | | imx6qp-tx6-emmc +---------------------+------------------+-----------------------------+ | | tx6q-8137 | TX6Q-8137 | TX6QP/800/1GS/8GF/LVDS | +------------------+---------------------+------------------+-----------------------------+ | **TX6DL** | +------------------+---------------------+------------------+-----------------------------+ | NAND Modules | +------------------+---------------------+------------------+-----------------------------+ | | | *TX6U-8010* | *(Legacy)* | | +---------------------+------------------+-----------------------------+ | | tx6u-8030 | TX6U-8030 | TX6DL/800/1024S/128F/I | | imx6dl-tx6-nand +---------------------+------------------+-----------------------------+ | | | *TX6U-8110* | *(Legacy)* | | +---------------------+------------------+-----------------------------+ | | tx6u-8130 | TX6U-8130 | TX6DL/800/1024S/128F/I/LVDS | +------------------+---------------------+------------------+-----------------------------+ | eMMC Modules | +------------------+---------------------+------------------+-----------------------------+ | | tx6u-8033 | TX6U-8033 | TX6DL/800/1024S/4GF/E85 | | imx6dl-tx6-emmc +---------------------+------------------+-----------------------------+ | | tx6u-8133 | TX6U-8133 | TX6DL/800/1024S/4GF/E85/LVDS| +------------------+---------------------+------------------+-----------------------------+ | **TX6S** | +------------------+---------------------+------------------+-----------------------------+ | NAND Modules | +------------------+---------------------+------------------+-----------------------------+ | | tx6s-8034 | TX6S-8034 | TX6S/800/256S/128F/I | | imx6dl-tx6-nand +---------------------+------------------+-----------------------------+ | | tx6s-8134 | TX6S-8134 | TX6S/800/256S/128F/I/LVDS | +------------------+---------------------+------------------+-----------------------------+ | eMMC Modules | +------------------+---------------------+------------------+-----------------------------+ | | tx6s-8035 | TX6S-8035 | TX6S/800/512S/4GF/E85 | | imx6dl-tx6-emmc +---------------------+------------------+-----------------------------+ | | tx6s-8135 | TX6S-8135 | TX6S/800/512S/4GF/E85/LVDS | +------------------+---------------------+------------------+-----------------------------+ | **TX6UL** | +------------------+---------------------+------------------+-----------------------------+ | NAND Modules | +------------------+---------------------+------------------+-----------------------------+ | | | *TXUL-0010* | *(Legacy)* | | imx6ul-txul-nand | txul-5010 +------------------+-----------------------------+ | | | TXUL-5010 | TX6UL/528/256S/128F/I | +------------------+---------------------+------------------+-----------------------------+ | eMMC Modules | +------------------+---------------------+------------------+-----------------------------+ | | | *TXUL-0011* | *(Legacy)* | | imx6ul-txul-emmc | txul-5011 +------------------+-----------------------------+ | | | TXUL-5011 | TX6UL/528/256S/4GF/E85 | +------------------+---------------------+------------------+-----------------------------+ | **TX6ULL** | +------------------+---------------------+------------------+-----------------------------+ | eMMC Modules | +------------------+---------------------+------------------+-----------------------------+ | imx6ull-txul-emmc| txul-8013 | TXUL-8013 | TX6ULL/800/512S/4GF/E85 | +------------------+---------------------+------------------+-----------------------------+ Set the above given, depending on your intended workload, as value in the machine configuration variable: .. code-block:: shell MACHINE= Set up the environment ---------------------- The command to setup the Yocto environment in its general form looks like the following: .. code-block:: shell MACHINE= source ./setup-environment Where the user has to insert a value, fitting the desired target TXCOM and software target, from the above table, and choose a name for the build directory to be created by the "setup-environment" script, to look like such: **GNU/Linux:** .. code-block:: shell MACHINE=imx6dl-tx6-emmc source ./setup-environment build-gnulinux U-Boot --------- .. code-block:: shell MACHINE=tx6u-8033 source ./setup-environment build-bootloader .. note:: The user has to differentiate between payload software, like the operating system (GNU/Linux), and the bootloader (U-Boot), thus there are in above given table two different settings for ``MACHINE=``. .. note:: This is an effect for the BSP as the U-Boot bootloader requires a different toolchain to be compiled with. Choosing an image target ------------------------ Choose an image target to build, e.g. (for more see below): .. topic:: ``karo-image-minimal`` This builds a minimal image consisting of: * Kernel (Linux) incl. DTB (**D** \evice **T** \ree **B** \lob) * RFS (GNU) .. topic:: ``u-boot`` This builds an minimal image consisting of: * Bootloader (U-Boot) The RFS (short for: root file system, also: rootfs) in this instance is a low key file system generally intended for either first steps and/or headless systems. It includes all the general standard tools of a GNU/Linux distribution, but misses features like a X11 server, etc. Additional packages ------------------- In Yocto *layers* provide *recipes* that provide *packages*, which themselves can either be specific programs (e.g. bash) or a suite of programs (e.g. Qt SDK). The before mentioned *recipes* define how these *packages* are baked (hence: ``bit **bake**``) into the *image*. Additional *packages* can therefore be added to *images* by providing an appropriate *layer*. A comprehensive listing of available, predefined *layers* can be found (e.g.) here: `https://layers.openembedded.org `_ Building an image target ------------------------ .. code-block:: shell bitbake Examples: * For building core-image-minimal: .. code-block:: shell bitbake karo-image-minimal * For building Linux kernel and kernel modules only: .. code-block:: shell bitbake linux-karo * For building U-Boot only: .. code-block:: shell bitbake u-boot * A BSP with X server and GUI can be configured and built using: .. code-block:: shell MACHINE=imx6q-tx6-emmc DISTRO=karo-x11 source ./setup-environment build-imx6q-tx6-emmc bitbake karo-image-x11 .. note:: To re-initialize the build environment when the session was exited, run the following command in the directory above the build directory: .. code-block:: shell source ./setup-environment Image Deployment ---------------- After a build is complete, the created image resides in the ``tmp/deploy/images`` sub-directory. An image is, for the most part, specific to the machine set in the environment setup. Each image build creates a U-Boot, a kernel, and an image type based on the ``IMAGE_FSTYPES`` defined in the machine configuration file. The following files are created for Ka-Ro TX modules: +----------------------------------+--------------------+ | Filename | Content | +==================================+====================+ | u-boot---.bin | U-Boot binaries | +----------------------------------+--------------------+ | uImage | Kernel image | +----------------------------------+--------------------+ | modules-.tgz | Kernel modules | +----------------------------------+--------------------+ | -.tar.bz2 | RFS | +----------------------------------+--------------------+