<!---
SPDX-License-Identifier: CC-BY-4.0

Copyright (c) 2018-2024 TQ-Systems GmbH <oss@ew.tq-group.com>,
D-82229 Seefeld, Germany.
--->

# OpenEmbedded / Yocto Project evaluation BSP layer for TQ-Systems ARM SOM

This README file contains information on the content of the meta-dumpling layer.

Please see the corresponding sections below for details.

[[_TOC_]]

## Overview

### Abstract

This layer provides recipes to generate images to help evaluation of
TQ-Systems CPU modules and Starterkits. This layer additionally contains
optional fixes and extensions for other layers as far as is needed / useful
for TQ-Systems SOM and some initial example distro support.

### Dependencies

This layer in the checked out branch depends on:

URI: https://git.yoctoproject.org/poky  
branch: scarthgap  
layers: meta  

URI: https://github.com/openembedded/meta-openembedded.git
branch: scarthgap  
layers: meta-oe  

URI: https://github.com/tq-systems/meta-tq.git  
branch: scarthgap  
layers: meta-tq  

When using one of the distros definded in this layer you need
additionally the `meta-poky` layer from the poky repo that defines
`poky` which the distros defined in this layer depend on.
**Note** Recipes and bbappends in this layer do not depend on `meta-poky`

URI: https://git.yoctoproject.org/poky  
branch: scarthgap  
layers: meta-poky  

This layer additionally contains optional fixes and extensions for other layers
as far as needed or useful for TQ-Systems SOM. Most of these bbappends
are implemented under dynamic-layers and are only visible, if the original
layer is in your bblayer.conf. For details look for `BBFILES_DYNAMIC` in
Yocto Project documentation.

### Coding style

It is recommended to use the [Format_Guidelines](https://www.openembedded.org/wiki/Styleguide#Format_Guidelines)
from openembedded.

### Patches

Please submit patches against the meta-dumpling layer via github's collaboration
features.

Additionally, you can send patches to the maintenance team by email:
<oss@ew.tq-group.com>

## Usage

### Adding the meta-dumpling layer to your build

Run 'bitbake-layers add-layer <path-to-meta-dumpling>/meta-dumpling'

Assuming the tq layer exists in subdir sources at the top-level of your
yocto build tree, you can add it to the build system by adding the
location of the tq layer to bblayers.conf, along with any
other layers needed. e.g.:

```
BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"

BBLAYERS ?= "\
...
    ${BSPDIR}/sources/poky/meta \
    ${BSPDIR}/sources/poky/meta-poky \
    ${BSPDIR}/sources/poky/meta-openembedded/meta-oe \
    ${BSPDIR}/sources/meta-tq \
    ...
"
```

### Image recipes

The meta-dumpling layer defines images recipes for test / evaluation of
TQ-Systems SOM:

| image                     | intended use                                                     |
| ------------------------- | ---------------------------------------------------------------- |
| tq-image-small            | based on poky core-image-minimal, usable for UBI rootfs          |
| tq-image-small-debug      | based on poky tq-image-small, added debug features               |
| tq-image-generic          | based on poky core-image-minimal                                 |
| tq-image-generic-debug    | based on tq-image-generic, added debug features and packages     |
| tq-image-generic-rt       | based on poky core-image-minimal, PREEMPT_RT kernel              |
| tq-image-generic-rt-debug | based on tq-image-generic-rt, added debug features and packages  |
| tq-image-weston           | based on poky core-image-weston                                  |
| tq-image-weston-debug     | based on tq-image-weston, added debug features and packages      |
| tq-image-qt6              | based on tq-image-weston, added Qt6 support                      |
| tq-image-qt6-debug        | based on tq-image-qt6, added debug features and examples         |

**Attention:** These image recipes can be used as a starting point for own customization.
Every recipe comes in two flavours. The images suffixed with `debug` add `debug-tweaks` to
the `IMAGE_FEATURES` to have an open root login for console and ssh for ease of development
and testing. The non suffixed images simply define a base feature set for the use case
and contain a lot of test utils, to evaluate and test TQ-Systems starterkits.
Because of the intended use case, these image recipes are intended as a starting point
for development but should not be used directly for production images.
Depending on the actual project, security must be taken in account.

**Note:** Out of the box (without `debug-tweaks` in `IMAGE_FEATURES`) the images
without `-debug` suffix do not allow user login. This should be default for the vast
majority of embedded systems. If one need an user that can login, see poky documentation
for `extrausers.bbclass` and following example:

```
# add user <username> with password <passwd> and force password change at first login
IMAGE_CLASSES += "extrausers"
USERADDEXTENSION = "useradd-staticids"
USERADD_UID_TABLES = "files/passwd"
USERADD_GID_TABLES = "files/group"

EXTRA_USERS_PARAMS = "\
    useradd <username> ; \
    usermod -P <passwd> <username>; \
    passwd-expire <username>; \
"
```

### Example distros

The meta-dumpling layer defines distros as starting point for own customization.
These distros are also available for usage together with vendor based kernel /
vendor hardware support layer.

| distro name          | purpose                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| spaetzle             | size optimized for \[Q\]SPI-NOR, kernel based on linux-stable           |
| spaetzle-ls          | size optimized for \[Q\]SPI-NOR for Layerscape ARM                      |
| spaetzle-nxp         | size optimized for \[Q\]SPI-NOR, packages based on meta-freescale + NXP |
| spaetzle-ti          | size optimized for \[Q\]SPI-NOR, packages based on meta-ti-bsp          |
| dumpling-ls          | systemd, features depends on machine settings for Layerscape ARM        |
| dumpling-wayland     | systemd, wayland / weston, kernel based on linux-stable                 |
| dumpling-wayland-nxp | systemd, wayland / weston, packages based on meta-freescale + NXP       |
| dumpling-wayland-ti  | systemd, wayland / weston, packages based on meta-ti-bsp                |

**Attention:** These distro configs can be used as a starting point for own
customization. Because of the intended usage, they are focused on demonstration.
These configs should not go into a production usage without thorough review.
Depending on the actual project, security must be taken in account.

### SDK usage

For each of the distros an SDK can be built. The SDK contains everything
needed for cross application development for the target hardware. To build
the SDK along with the image, run

```
bitbake <image> -c populate_sdk
```

After building the SDK, an installation script can be found in
`${TMPDIR}/deploy/sdk`. Simply run the script to install the SDK on your
development host. The script will provide you with a default install path,
but it can be customized when needed. Depending on your installation path
you will possibly need root access to install the SDK.

#### Developing in SDK environment

Source the bash script located inside your chosen installation path, starting
with `environment-setup` followed by some architecture specifications. For
example:

```
source <path/to/sdk/installation>/environment-setup-cortexa53-crypto-tq-linux
```

Inside the SDK environment you can now develop your application using the
cross compiler tools. To verify the environment run `env` or display the
value of `CC`:

```
echo ${CC}
```

#### Direct usage of SDK cross toolchain

You can also invoke the cross compile tools directly. They are
located in the SDK installation path in the `sysroots` folder. In this
folder you will find two more folders. One sysroot for your target
hardware, containing cross compiled libraries and headers among others
and one sysroot for your development host architecture (typically
x86_64). This second sysroot contains the cross compile tools in
`<path/to/sdk/installation>/sysroots/<host_architecture>/usr/bin/<target_architecture>`.

### Known issues

* tq-image-small\[-debug\]:
  * DHCP is not working
  * restricted support for hardware
  * some warnings from init scripts