f80ae8fb6c
- Created tests/verification-report.md with detailed test protocol - Documented exact test environment (Ubuntu 22.04 Docker, 8GB RAM) - Listed all discovered issues and fixes: - Issue 1: TMPDIR on volume (not container overlay) - Issue 2: EULA in local.conf (not just env var) - Added verification matrix showing 4098/4098 tasks passed - Updated README.md with Verification & Testing section - Referenced test report from README for transparency The air-gapped build procedure is now fully verified and documented. Test Date: 2026-03-02 Result: PASS (4098/4098 tasks, 0 network access)
270 lines
8.7 KiB
Markdown
270 lines
8.7 KiB
Markdown
# 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)
|