tqma6-yocto-mirror/README.md

# TQMa6UL Yocto BSP – Mirror & Build Documentation

**Project ID:** TQMA6-YOCTO-2038
**Date:** 2026-03-01
**Target Hardware:** TQMa6UL-AB (i.MX6 UltraLite) on MBa6ULx Carrier
**Yocto Version:** Scarthgap (5.0.11) LTS
**Objective:** Create offline mirror for software approval, ensure 2038 compliance

---

## Overview

This project addresses the requirement to migrate from legacy PTXdist-based BSP
to Yocto Project for TQMa6UL hardware. The primary drivers are Year 2038
compliance for military/long-term deployments and support for Qt-based
graphical applications.

### 2038 Problem Context

The Year 2038 Problem (Y2K38) affects 32-bit systems using signed 32-bit time_t:
- Maximum representable time: 03:14:07 UTC on 19 January 2038
- Systems will overflow and behave unpredictably after this date
- Critical for military/aerospace systems with 15+ year service life

### Solution

Yocto Scarthgap (5.0 LTS) provides 2038 compliance with both C libraries:
- **glibc 2.39**: 64-bit `time_t` on 32-bit ARM (default since glibc 2.34 in Yocto)
- **musl 1.2+**: 64-bit `time_t` unconditionally since 2020

## Board Identification

| Field | Value |
|-------|-------|
| **SoM** | TQMa6UL (sticker: `TQMA6U-AB`) |
| **SoC** | NXP i.MX6 UltraLite (Cortex-A7, single core) |
| **Carrier** | MBa6ULx |
| **Machine** | `tqma6ul-multi-mba6ulx` |
| **BSP Config** | `mainline` (**not** `imx`!) |

> ⚠️ **Critical:** The TQMa6UL machines are **only** available in the `mainline`
> config template. The `imx` config does NOT include this board.

## Distro Selection

The BSP provides two main distribution families:

| Distro | C Library | Init | Qt | Use Case |
|--------|-----------|------|----|----------|
| **`dumpling-wayland`** | glibc | systemd | Qt6 ✅ | **Recommended** – full-featured, Qt/GUI support |
| `spaetzle` | musl | busybox | ❌ blocked | Minimal/headless only |
| `poky` | glibc | sysvinit | configurable | Yocto upstream default |

### Recommendation: `dumpling-wayland`

**Use `dumpling-wayland`** if you need:
- Qt5/Qt6 graphical applications
- glibc compatibility for third-party software
- systemd, Wayland, WiFi, Bluetooth, OpenGL
- Full `tq-image-qt6` support

> **Note:** `spaetzle` explicitly blocks Qt images:
> `SKIP_RECIPE[tq-image-qt6] = "not buildable with spaetzle"`
>
> Qt5 is not included in the BSP layers. If needed, add `meta-qt5` manually.

### Both distros are 2038-safe

| Distro | C Library | time_t | 2038-safe? |
|--------|-----------|--------|-----------|
| `dumpling-wayland` | glibc 2.39 | 64-bit | ✅ |
| `spaetzle` | musl 1.2+ | 64-bit | ✅ |

## Verified Build Configuration

*Tested 2026-03-01 on Debian 13 (Python 3.13):*

### spaetzle (minimal, musl)

```
TARGET_SYS           = arm-tq-linux-musleabi
MACHINE              = tqma6ul-multi-mba6ulx
DISTRO               = spaetzle
DISTRO_VERSION       = 5.0.11
TUNE_FEATURES        = arm vfp cortexa7 neon thumb callconvention-hard
```

### dumpling-wayland (full, glibc) – recommended

```bash
# Setup with dumpling-wayland instead:
export ACCEPT_FSL_EULA=1
export MACHINE=tqma6ul-multi-mba6ulx
. ./setup-environment build_ut mainline
# Edit conf/local.conf:
#   DISTRO = "dumpling-wayland"
#   ACCEPT_FSL_EULA = "1"
```

Expected output:
```
TARGET_SYS           = arm-tq-linux-gnueabi
DISTRO               = dumpling-wayland
```

## Quick Start

### 1. Prerequisites (Debian 13 / Ubuntu 22.04+)

```bash
sudo apt install -y \
  git python3 jq bash grep gawk wget diffstat \
  chrpath cpio texinfo gcc g++ make file tar \
  bzip2 gzip xz-utils zstd lz4 patch perl \
  python3-pexpect socat unzip rsync bc \
  libsdl1.2-dev xterm
```

### 2. Clone & Setup

```bash
mkdir -p ~/UT && cd ~/UT
git clone --recurse-submodules https://github.com/tq-systems/ci-meta-tq.git
cd ci-meta-tq

export ACCEPT_FSL_EULA=1
export MACHINE=tqma6ul-multi-mba6ulx
. ./setup-environment build_ut mainline
echo 'ACCEPT_FSL_EULA = "1"' >> build_ut/conf/local.conf

# For Qt/GUI applications, switch to dumpling-wayland:
# echo 'DISTRO = "dumpling-wayland"' >> build_ut/conf/local.conf
```

### 3. Optional: Redirect Storage

```bash
mkdir -p ~/.yocto
cat > ~/.yocto/site.conf << 'EOF'
DL_DIR ?= "/srv/yocto/downloads"
SSTATE_DIR ?= "/srv/yocto/sstate-cache"
EOF
```

### 4. Fetch & Build

```bash
# Fetch all sources (for mirror creation)
bitbake tq-image-small-debug --runall=fetch

# Build
bitbake tq-image-small-debug

# Or with dumpling-wayland: build Qt6 image
# bitbake tq-image-qt6
```

## Available Images

| Image | spaetzle | dumpling-wayland | Description |
|-------|----------|------------------|-------------|
| `tq-image-small` | ✅ | ✅ | Minimal |
| `tq-image-small-debug` | ✅ | ✅ | Minimal + debug |
| `tq-image-generic` | ❌ | ✅ | Full-featured |
| `tq-image-weston` | ❌ | ✅ | Wayland compositor |
| `tq-image-qt6` | ❌ | ✅ | Qt6 demo image |
| `core-image-minimal` | ✅ | ✅ | Yocto bare minimum |

## Documentation

| Document | Description |
|----------|-------------|
| [2038 Compliance Analysis](docs/01-analysis/2038-problem-analysis.md) | Detailed 2038 risk assessment |
| [Mirror Creation Guide](docs/02-mirror-creation/step-by-step-mirror-creation.md) | Step-by-step build instructions |
| [License Summary](docs/03-license-analysis/license-summary.md) | License overview and compliance |
| [License Table (CSV)](docs/03-license-analysis/UT-license-table.csv) | For import into spreadsheets |
| [Air-Gapped Deployment](docs/04-deployment/corporate-network-deployment.md) | Offline build setup |

## Verification & Testing

This documentation has been **fully tested** in a controlled environment.

| Test Scenario | Date | Result | Details |
|---------------|------|--------|---------|
| **Air-Gap Full Build** | 2026-03-02 | ✅ **VERIFIED** | [Test Report](tests/verification-report.md) |
| Mirror creation (510 fetches) | 2026-03-02 | ✅ PASS | All downloads successful |
| License extraction (264 pkgs) | 2026-03-02 | ✅ PASS | CSV generated |
| Complete build (4098 tasks) | 2026-03-02 | ✅ PASS | tq-image-small-debug |

**Test Environment:**
- Ubuntu 22.04 LTS (Docker container)
- 8GB RAM, 4 vCPUs
- 63GB volume for TMPDIR/DL_DIR
- `BB_NO_NETWORK = "1"` enforced

See [`tests/verification-report.md`](tests/verification-report.md) for complete
test protocol, discovered issues, and fixes applied to documentation.

---

## Air-Gapped / Offline Deployment

```bash
# 1. On connected machine: fetch all sources
bitbake tq-image-qt6 --runall=fetch   # or tq-image-small-debug

# 2. Package the mirror
tar czf yocto-mirror-tqma6ul.tar.gz -C /srv/yocto downloads/

# 3. On air-gapped machine: extract + configure
tar xzf yocto-mirror-tqma6ul.tar.gz -C /srv/yocto/
# Add to local.conf:
#   SOURCE_MIRROR_URL = "file:///srv/yocto/downloads/"
#   INHERIT += "own-mirrors"
#   BB_NO_NETWORK = "1"
```



## Softwarefreigabeantrag (PDF)

The complete approval document is available as PDF:
**[`docs/softwarefreigabe.pdf`](docs/softwarefreigabe.pdf)** (13 pages, LaTeX source: [`docs/softwarefreigabe.tex`](docs/softwarefreigabe.tex))

Contents: title page, build configuration, complete 264-package license table,
proprietary component assessment, military use evaluation, compliance checklist.

## Complete License & Source Table

The file [`docs/03-license-analysis/UT-license-table.csv`](docs/03-license-analysis/UT-license-table.csv)
contains the **complete inventory of all 264 source packages** in the build graph,
extracted via `bitbake -e` with fully resolved download URLs.

| Metric | Value |
|--------|-------|
| **Total packages** | 264 |
| **Download URLs resolved** | 224 (85%) |
| **Packages without URL** | 40 (meta-packages, virtual providers) |
| **Extraction method** | `bitbake -e <recipe>` per package |

### License Distribution

| License | Count | Military Use |
|---------|-------|-------------|
| MIT | 41 | Approved |
| GPL-2.0-only | 32 | Approved (source required) |
| GPL-2.0-or-later | 22 | Approved (source required) |
| BSD-3-Clause | 19 | Approved |
| GPL-3.0-or-later | 13 | Review (anti-tivoization) |
| GPL-3.0-only | 11 | Review (anti-tivoization) |
| Proprietary | 2 | Review required |

See [`docs/03-license-analysis/UT-license-table-excel.md`](docs/03-license-analysis/UT-license-table-excel.md) for import instructions.

## Known Issues

| Issue | Severity | Notes |
|-------|----------|-------|
| Python 3.13 fork() warnings | Cosmetic | Does not affect build |
| Debian 13 not validated | Cosmetic | Build works correctly |
| `spaetzle` blocks Qt/Weston images | By design | Use `dumpling-wayland` |

## References

- [TQ-Systems ci-meta-tq](https://github.com/tq-systems/ci-meta-tq)
- [TQMa6UL Product Page](https://www.tq-group.com/en/products/tq-embedded/arm-architecture/tqma6ul/)
- [Yocto Scarthgap Docs](https://docs.yoctoproject.org/5.0/)
- [musl 64-bit time_t](https://musl.libc.org/time64.html)
- [glibc Y2038 Design](https://sourceware.org/glibc/wiki/Y2038ProofnessDesign)