Page Comparison

A x86 based Linux system with installed cross compile toolchain is required to develop Yocto based software for i.MX 8-based designs. It is possible to use a virtual machine that runs Linux but a dedicated system with Ubuntu is preferrable. Furthermore, the host should have a serial port to access the debug console and an SD card reader.

For more information see the i.MX Yocto Project User's Guide. Ubuntu 18.04 or newer is recommended but it is possible to build on 16.04 (with additional packages) too. Also have a look at the Sample Images SectionSampleImages) at the end of this document.

This guide shows the procedure for Yocto Project 3.0 (Zeus) on an Ubuntu 20.04 (16.04 at the bottomSettinguptheBuildhostonUbuntu16.04)).

1. Setting up and building Yocto

1.1. Installation in Ubuntu 20.04 64 bit (Clean install)

Setup a clean (X)Ubuntu 20.04 64bit system installation on your preferred devlopment workstation.
Ensure that at least 24GiB Ram are availale if a image with Qt should be built.

1.2. Additional Packages

Install additional packages that are required for building Yocto successfully:

1.2.1 Build Tools

	$ sudo apt update
	$ sudo apt install gawk wget git-core diffstat unzip texinfo gcc-multilib \
	build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
	xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
	pylint3 xterm \
	curl git-lfs

1.2.2 Repo-Tool

Now get repo tool and store it in ~/bin folder. Also add this folder to PATH.

	$ mkdir ~/bin
	$ curl <https://storage.googleapis.com/git-repo-downloads/repo> > ~/bin/repo
	$ chmod a+x ~/bin/repo
	$ echo "export PATH=~/bin:$PATH" >> ~/.bashrc

1.3. Configure development workstation

1.3.1 Configure the local git

	$ git config --global user.email "youremail"
	$ git config --global user.name "Your name"
	$ git lfs install

1.4. Fetch the yocto recipes

Now fetch BSP manifest and get sources

    $ mkdir ~/yocto
    $ cd ~/yocto
    $ repo init -u <https://git.congatec.com/arm-nxp/imx8-family/yocto/manifest-imx8-family.git> -b cgtimx8x__zeus_5.4.70_2.3.3
    $ repo sync

1.5. Configure the build environment for the target module

	$ DISTRO=fsl-imx-xwayland MACHINE=imx8qxp-cgtsx8x source cgt-setup-release.sh -b build-xwayland
	# [ ! ] EULA accept needed for next step.

1.5.1 Memory selection

The Yocto variable MEMORY_PRESENT is included to select the different memory configurations for the different variants

Possible values of MEMORY_PRESENT are:

• "1GB"

• "2GB"

• "4GB"

The default is set to 2GB. If the 1GB memory variant is the target, please add the following line into your conf/local.conf file with the correspoding memory size:

    MEMORY_PRESENT = "1GB"

The variable is used in u-boot and imx-sc-firmware to select consistenly the memory present on the target hardware.

1.6. Build an image

1.6.1 fsl-image-machine-test

	$ bitbake fsl-image-machine-test

Depending on the performance of the development system, this process might take hours.

When it finishes the image will be located under the build folder: tmp/deploy/images/imx8qxp-cgtsx8x

1.6.2 imx-image-full

On Ubuntu 20.04 a build error rises on fsl-image-full image. This is due to the pybind11 package which uses Python system path instead of receipe build-sysroot path.

Apply the following patch before you build the image:

diff --git a/meta-ml/recipes-devtools/python/python3-pybind11_2.5.0.bb b/meta-ml/recipes-devtools/python/python3-pybind11_2.5.0.bb
index 06300a58a..8e86db047 100644
--- a/meta-ml/recipes-devtools/python/python3-pybind11_2.5.0.bb
+++ b/meta-ml/recipes-devtools/python/python3-pybind11_2.5.0.bb
@@ -15,7 +15,9 @@ S = "${WORKDIR}/git"

 BBCLASSEXTEND = "native"

-EXTRA_OECMAKE =  "-DPYBIND11_TEST=OFF"
+EXTRA_OECMAKE =  "-DPYBIND11_TEST=OFF \
+                  -DPYTHON_EXECUTABLE=${RECIPE_SYSROOT_NATIVE}/usr/bin/python3-native/python3.7 \
+"

 inherit cmake setuptools3backport python3native

After this patch is applied, build the image with:

	$ bitbake imx-image-full

Ensure that at least 24GiB RAM are available on build host.

2. Transfering the BSP image to uSD card

In order to transfer the image to a uSD card, follow the next steps changing sdX for your detected device.

	$ cd ~/yocto/build-sx8x/tmp/deploy/images/imx8qxp-cgtsx8x/
	$ bzcat fsl-image-machine-test-imx8qxp-cgtsx8x.wic.bz2 | sudo dd of=/dev/sdX bs=1M conv=fsync && sync

The root partition on u-SD card does exactly fit to the data used and does not have many extra space. It could be expanded up to the end of the available sdcard space with a graphical tool like gparted or on command line with parted (install it if needed).

	$ DISK=/dev/sdX
	$ sudo parted -s ${DISK} resizepart 2 '100%'
	$ sync
	$ sudo resize2fs ${DISK}2
	$ sudo fdisk -l | grep ${DISK}
	$ sync

Attention:

The only booting option which is supported by congatec is boot from SPI flash.
Therefore, the image does not have a valid bootcontainer to boot from SD-Card.

See next section for details.

3. Provided Boot Container

The yocto build process also builds the bootcontainer (that incorporates the bootloader). In the deploy folder there are two bootcontainer files for a 2GB module:

• bootcontainer__imx8qxp-cgtsx8x_2GB_fspi.bin

• bootcontainer__imx8qxp-cgtsx8x_2GB_sd.bin

The first one is the default bootcontainer which has to be burned into the onboard SPI flash with uuu-tool. Example for Windows machine:

	$ .\uuu.exe -b qspi bootcontainer__imx8qxp-cgtsx8x_2GB_fspi.bin

The second one could be used to do a recovery boot from u-SD if the SPI flash is empty. To write the bootcontainer for a 2GB conga-SMX8-X module to the u-SD use (replace sdX with detected device):

	$ sudo dd if=bootcontainer__imx8qxp-cgtsx8x_2GB_sd.bin of=/dev/sdX bs=1k seek=32

Be aware, that the onboard flash have to be empty to boot from u-SD card. Erase it with uuu tool or on bootloader level with:

	> sf probe
	> sf erase 0 1000
	> reset

Then power off the board completely, rearrange the boot swithces accordingly and start again afterwards to take the erase process effect.

4. Device tree blob (*.dtb)

The default devicetree blob configured in the bootloader is "imx8qxp-cgtsx8x.dtb" (defined in the environment variable "fdt_file" of the bootloader).

There are additional devicetree blobs provided for special use cases:

• imx8qxp-cgtsx8x.dtb: LVDS graphical output (default)

• imx8qxp-cgtsx8x-adv7533.dtb: HDMI graphical (Only PN 651105)

Changing the device tree blob

In order to change the device tree configuration, power-on the board and stop the boot process on bootloader level. Then specify the desired .dtb file in the variable fdt_file, e.g.:

	$ setenv fdt_file imx8qxp-cgtsx8x-adv7533.dtb
	$ savee
	$ boot

5. Setting up the Build host on Ubuntu 16.04

This section describe only the differences according to Ubuntu 20.04.

5.1. Installation in Ubuntu 16.04 64 bit (Clean install)

Setup a clean (X)Ubuntu 16.04 64bit system installation on your preferred devlopment workstation.

5.2. Additional Packages

Install additional packages that are required for building Yocto successfully:

5.2.1 Update ca-certificates

This is necessary on Ubuntu 16.04 to access public congatec git server

	$ sudo apt-get install apt-transport-https ca-certificates -y
	$ sudo update-ca-certificates

5.2.2 Build Tools

	$ sudo apt update
	$ sudo apt install gawk wget git-core diffstat unzip texinfo gcc-multilib \
	build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
	xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
	pylint3 xterm curl libncursesw5* libncurses-dev

5.2.3 Python 3.6

Also install Python 3.6 as it is needed for current versions of repo tool and current yocto builds

	$ sudo apt install libzstd1-dev libzstd1 zstd libssl-dev libsqlite3-dev sqlite3 libncurses-dev libncursesw5*

	$ cd ~
	$ wget <https://www.python.org/ftp/python/3.6.9/Python-3.6.9.tgz>
	$ tar xzf Python-3.6.9.tgz
	$ cd Python-3.6.9
	$ ./configure --enable-loadable-sqlite-extensions
	$ make -j8
	$ sudo make install

This sets python3.6 as default python interpreter. If this is not wanted, use "sudo make altinstall"

5.2.4 GIT-LFS

Install git-lfs for git repositories that contain large binary files. See also: https://github.com/git-lfs/git-lfs/wiki/Installation

	$ curl -s <https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh> | sudo bash
	$ sudo apt-get install git-lfs

5.2.5 Further Steps

Continue with section 2.2 from Ubuntu 20.04

6. Sample Images

Sample images are available for download at conga-SMX8-X product page. Goto "Software" tab and then select "\[yocto\]". Then write this image to an SD-card as it is described in Transfering the BSP image to uSD cardTransferingtheBSPimagetouSDcard)

Please observe that these images does not have a valid bootcontainer (they are suitable for all variants). This is no problem because our modules are shipped with a preinstalled bootcontainer in SPI flash. But if a newer version of the BSP should be used or on errors a new bootcontainer is also needed.

You can get a bootcontainer from:

• yocto BSP (it is automatically built when building an image)

• build one with cgtbcbe tool

Have a look at the Boot ContainerProvidedBootContainer) section for details and how to flash it to the SD-card.