Page Comparison

This section is a guideline how to build a Linux image for the i.MX 8X Plus based congatec modules, using the Yocto Project 4.0 (krikstone). The first section contains Linux Host Machine preparation, Yocto obtaining, and Linux image build. The second section describes how to include the software development tools in the target Linux image, and the third section describes how to build a cross-SDK for the Linux Host Machine.
For more information see the i.MX Yocto Project User's Guide

1. Linux image build

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. It is recommended that at least 120 GB is provided, which is enough to compile all backends together. For building machine learning components, at least 250 GB is recommended.

The recommended minimum Ubuntu version is 20.04 or later. The latest release supports Chromium v91, which requires an increase to the ulimit (number of open files) to 4098.

1.1 Linux Host Machine preparation

Ubuntu 20.04 or newer is recommended but other environments are also possible.

1.1.1 Ubuntu 20.04

• The following tools have to be installed

	$ sudo apt-get update
	$  sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio 
		python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 
		libegl1-mesa libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev zstd liblz4-tool rsync curl git-lfs

1.1.2 Configure the local git

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

1.1.3 repo tool

Regarding the repo tool, it may be necessary to use newer version than the one provided via the operating system package above; the following steps are an example how to get access to such a version

$ mkdir -p ~/.bin
$ PATH="${HOME}/.bin:${PATH}"
$ curl <https://storage.googleapis.com/git-repo-downloads/repo> > ~/.bin/repo
$ chmod a+rx ~/.bin/repo

1.2 Obtaining Yocto

The Google's repo tool is used to obtain Yocto sources; the tool downloads all necessary files as defined in the provided manifest file. The manifest file therefore determines, among other things, specific version of boot loader and kernel that will be included in the target image.
The congatec Yocto sources and subsequently the manifest file are derived from a NXP GA release version; the mapping is in the table below, together with information about included boot loader and kernel version. In addition to the the base manifest file may be available manifest files adding specific functionality above the base NXP GA release. They would be also documented in the table.

The repo tool dowloads all files into the working directory, so it is a good idea to create a dedicated directory for the purpose, e.g.

	$ mkdir ~/yocto
	$ cd ~/yocto

1.2a Using the latest available version

	$ repo init -u <https://git.congatec.com/arm-nxp/imx8-family/yocto/manifest-imx8-family.git> -b cgtimx8x__kirkstone_5.15.32-2.0.0 -m cgtsx8x__imx-5.15.32-2.0.0.xml
	$ repo sync

1.3 Configuration of the build directory and environment

The downloaded Yocto sources contain imx-setup-release.sh script that is used in this step to configure the build directory and build environment. The script takes three inputs in this example - machine the build is being made for (variable MACHINE), distribution to use (variable DISTRO) and name of the build directory (the -b parameter).
The Machine Identification is module dependent and is to be determined as per the table below; regarding distribution the options are fsl-imx-xwayland and fsl-imx-wayland

	$ MACHINE='<Machine Identification>' DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b build-dir
	[ ! ] EULA accept needed for next step.

Note: The configured environment is not persistent; it can be re-configured using command source setup-environment build-dir

1.3.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 4GB memory variant is the target, please add the following line into your conf/local.conf file with the correspoding memory size:

    MEMORY_PRESENT = "4GB"

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

1.4. The fsl-image-validation-imx image building

The last step is the image build itself; the bitbake tool does that, taking at least one parameter - the name of the image to build (i.e. the bitbake image name).

	$ bitbake imx-image-core

The available i.MX images are: core-image-minimal, core-image-base, fsl-image-machine-test, imx-image-core, imx-image-multimedia, and imx-image-full.

After the bitbake finishes, the following files can be found in the tmp/deploy/images/\<Machine Identification\> subdirectory of the build folder.

Note that this table does not contain all files in the subdirectory

2. Include SDK in the target image (optional)

Development tools and libraries can be included in the target Linux image, which makes software development on the module itself possible. Yocto's features tools-sdk and dev-pkgs are available for the purpose - after the build directory and environment are configured (i.e. after the step 1.3), the features need to be added to the EXTRA_IMAGE_FEATURES variable in theconf/local.conf file. An example that shows the default variable after the update follows

EXTRA_IMAGE_FEATURES ?= "debug-tweaks tools-sdk dev-pkgs"

The development tools and libraries will be included during the subsequent bitbake run.

3. Build, install, and use the cross-SDK on the Linux Host Machine

The Yocto system is able to build a cross-SDK that can be used for software development on the Linux Host Machine. The command that builds an installation package for the SDK can be invoked after the 1.3 or 1.4 steps.

3.1 Build the cross-SDK installation package

bitbake imx-image-core -c populate_sdk

Note: The installation package is located in the tmp/deploy/sdk subdirectory after the build

3.2 Install the SDK

$ ./tmp/deploy/sdk/fsl-imx-xwayland-glibc-x86_64-imx-image-core-armv8a-<Machine Identification>-toolchain-5.15-kirkstone.sh

3.3 Source the SDK toolchain

To use the cross-SDK on the Linux Host Machine, the SDK setup file needs to be sourced as follows

$ source /opt/fsl-imx-xwayland/5.15-krikstone/environment-setup-armv8a-poky-linux
$ unset LDFLAGS

Note: The /opt/fsl-imx-xwayland is the default destination directory as proposed by the SDK installer

4. 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 imx-image-core-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.

5. Provided Boot Container

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

• bootcontainer__imx8qxp-cgtsx8x_2GB_fspi.bin

This 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

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