conga-SMX8-Plus Yocto 3.0 (Zeus)

This section is a guideline how to build a Linux image for the i.MX 8M Plus based congatec modules, using the Yocto Project 3.0 (Zeus). 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 18.04 or later. The Chromium version 74 requires Ubuntu 18.04. The latest release supports Chromium V74, which requires an increase to the ulimit (number of open files) to 4098. If Chromium is not used, 16.04 should work. Earlier versions before 16.04 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.

#### 1.1 Linux Host Machine preparation
Ubuntu 18.04 or newer is recommended but other environments are also possible. Tested build environments are:

* Ubuntu 18.04
* Ubuntu 20.04
* Linux Mint 19
* Linux Mint 20

##### 1.1.1 Linux Mint 19
* The following tools have to be installed

```bash
$ sudo apt-get update
$ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential \
chrpath socat 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 repo python3-pip device-tree-compiler \
libssl-dev
```
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

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

##### 1.1.2 Linux Mint 20
Additional to Mint 19 setup:

1. The package *python* needs to be installed using *apt-get install* in addition to the packages mentioned above
2. The package *repo* is no longer available, so the direct download as described in the previous paragraph is necessary

##### 1.1.3 Ubuntu 20.04
Same setup as Ubuntu 18.04 but 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
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


```


#### 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.

| Kernel Version | U-boot Version | NXP Release Suffix | Repo Manifest File | Derived congatec Releases | Notes |
|:----------------:|:-------:|:----------------:|:----------------:|:-------------:|:--------|
| 5.4.70-2.3.0 | 2020.4 | 2.3.0 | cgtimx8mp__imx-5.4.70-2.3.0.xml | NA | *The base manifest file for early adopters only ** SX8P & QX8P X hardware revision** of the modules* |
| 5.4.70-2.3.0 | 2020.4 | 2.3.2 | cgtsx8p__imx-5.4.70-2.3.0__ea.xml | NA | *The base manifest file for **SX8P A hardware revision** of the modules* |
| 5.4.70-2.3.0 | 2020.4 | 2.3.2 | cgtqx8p__imx-5.4.70-2.3.2__ea.xml | NA | *The base manifest file for **QX8P A hardware revision** of the modules* |

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.
```bash
$ mkdir ~/yocto
$ cd ~/yocto
```

All manifest files for early adopters reside on the *cgtimx8mp__imx-linux-zeus* branch of the *manifest-imx8m-ea* repository; the *repo init* command can be instructed to use either the latest version of the provided manifest file (subsection 1.2a) or a specific version (subsection 1.2b).

##### 1.2a Using the latest available version
```bash
$ repo init -u git@git.congatec.com:arm-nxp/imx8-family-ea/imx8m/manifest-imx8m-ea \
-b cgtimx8mp__imx-linux-zeus \
-m <Repo Manifest File>
$ repo sync
```

##### 1.2b Using a specific version
```bash
$ repo init -u git@git.congatec.com:arm-nxp/imx8-family-ea/imx8m/manifest-imx8m-ea \
-b <Git Commit SHA String> \
-m <Repo Manifest File>
$ repo sync
```
The *Git Commit SHA String* is SHA of the commit that contains the desired version of *Repo Manifest File*

#### 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*

```bash
$ MACHINE='<Machine Identification>' DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b build-dir
[ ! ] EULA accept needed for next step.
```
| Module | Machine Identification |
|:---------------:|:--------------------:|
| conga-SMX8-Plus | imx8mp-cgt-sx8p |
| conga-QMX8-Plus | imx8mp-cgtqx8p |

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

#### 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).

```bash
$ 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.

| File Name | Description |
| --------------------- | ------------------------ |
| *\<bitbake image name\>*-*\<Machine Identification\>*.wic.bz2 | the complete Linux SD card image |
| Image | Linux kernel image |
| *\<Kernel Default DTB\>* | the default device tree file |
| imx-boot-*\<Machine Identification\>*-sd.bin | boot container for a SD card |

*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 the*conf/local.conf* file. An example that shows the default variable after the update follows

```bash
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
```bash
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
```bash
$ ./tmp/deploy/sdk/fsl-imx-xwayland-glibc-x86_64-imx-image-core-aarch64-imx8mp-cgt-sx8p-toolchain-5.4-zeus.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
```bash
$ source /opt/fsl-imx-xwayland/5.4-zeus/environment-setup-aarch64-poky-linux
$ unset LDFLAGS
```
*Note: The /opt/fsl-imx-xwayland is the default destination directory as proposed by the SDK installer*


### 4. Boot from QSPI
With the above created system image the system boots from SD-Card. It is possible to boot from QSPI if the bootcontainer is flashed inside first SPI partition.
A valid bootcontainer with the current bootloader is built during the image build process with yocto. It is also inside the yocto deploy folder.
For QSPI we have to use the file:
- bootcontainer__imx8mp-cgtqx8p__fspi.bin

Then flashing to QSPI could be done in different ways:

#### 4.1 Update bootcontainer from running Linux on module
1. Copy the bootcontainer to the SD-card to boot from
2. Boot the system
3. Erase bootloader partition of SPI-Flash:
```bash
$ flash_erase /dev/mtd0 0 0
```
4. Copy bootcontainer to flash
```bash
$ dd if=bootcontainer__imx8mp-cgtqx8p__fspi.bin of=/dev/mtd0
```

#### 4.2 Update bootcontainer with UUU tool

##### 4.2.1 Module setup
Use the USB-OTG port of conga-QX8P/conga-SX8P to update the bootcontainer. The procedure is the same, but the bootmode switches differ on the different platforms:

###### 4.2.1.1 Bootmode switches conga-QX8P

| DIP-Switches 1-4 | Description |
| --------------------- | ------------------------ |
| 0000 | Boot from fuses |
| 1000 | USB Serial Download |
| 0100 | eMMC boot |
| 1100 | onboard SD-card slot |
| 0110 | FlexSPI - 3B Read (QSPI) |

So use **1000** for firmware-updates via UUU tool

###### 4.2.1.2 Bootmode switches conga-SX8P
The SMARC module itself does not have any boot switches. Check the backplane manual for details.

##### 4.2.2 Flash
1. Connect the host system with an USB OTG cable to module
2. Start uuu tool
```bash
$ .\uuu.exe -b qspi bootcontainer__imx8mp-cgtqx8p__fspi.bin
```
3. Power up module and wait until flash has finished
4. Power off module
5. Set boot mode switches to boot from QSPI (eg. **0110** on conga-QX8P)
6. Power up and check uboot version