Initial documentation for TQMa6UL Yocto mirror project
Add comprehensive documentation for 2038-compliant BSP migration: - README.md: Project overview, 2038 compliance verification - 2038-problem-analysis.md: Detailed technical analysis confirming Scarthgap (5.0) provides 64-bit time_t on 32-bit ARM - step-by-step-mirror-creation.md: Complete procedure for creating offline mirror on Ubuntu 22.04 outside corporate network - license-compliance.md: License categories, approval criteria, and table templates for military use approval - corporate-network-deployment.md: Installation and build setup for air-gapped corporate environment Target: TQMa6UL-AB (i.MX6 UltraLite) on MBa6x BSP: TQ scarthgap.TQ.ARM.BSP.0006 2038 Status: Verified compliant (kernel 6.6 + glibc 2.38+) Repo: https://code.gegen.autos/openclaw/tqma6-yocto-mirror
This commit is contained in:
OpenClaw (Siggi)
341
docs/04-deployment/corporate-network-deployment.md
Normal file
341
docs/04-deployment/corporate-network-deployment.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# Corporate Network Deployment Guide
|
||||
|
||||
**Document ID:** DEPLOY-CORP-001
|
||||
**Date:** 2026-03-01
|
||||
**Environment:** Corporate network (potentially air-gapped)
|
||||
**Prerequisites:** Approved software mirror archive
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide describes the deployment of the Yocto mirror and build environment within a corporate network after software approval has been obtained.
|
||||
|
||||
**Assumptions:**
|
||||
- Software approval has been granted
|
||||
- Mirror archive has been transferred securely to corporate network
|
||||
- Target system: Ubuntu 22.04 LTS (or approved corporate Linux)
|
||||
- Internet access: May be restricted or unavailable
|
||||
|
||||
---
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
Before starting deployment:
|
||||
|
||||
- [ ] Software approval documentation received
|
||||
- [ ] Mirror archive transferred (USB/secure file transfer)
|
||||
- [ ] Checksum verified: `sha256sum -c archive.tar.gz.sha256`
|
||||
- [ ] Sufficient disk space available (200GB+)
|
||||
- [ ] Corporate Ubuntu 22.04 system ready
|
||||
- [ ] User has sudo privileges
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Extract Mirror Archive
|
||||
|
||||
```bash
|
||||
# Create base directory
|
||||
export CORP_BASE=/opt/tqma6-yocto
|
||||
sudo mkdir -p ${CORP_BASE}
|
||||
sudo chown $(whoami):$(whoami) ${CORP_BASE}
|
||||
|
||||
# Extract mirror archive
|
||||
cd ${CORP_BASE}
|
||||
tar xzf /path/to/transfer/tqma6-yocto-mirror-scarthgap-*.tar.gz
|
||||
|
||||
# Verify structure
|
||||
ls -la mirror-package/
|
||||
# Should show: sources/, licenses/, downloads/, build-instructions/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Install Build Dependencies
|
||||
|
||||
### 2.1 From Corporate Repository
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
sudo apt update
|
||||
|
||||
# Install required packages (from approved corporate repos)
|
||||
sudo apt install -y \
|
||||
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 xterm \
|
||||
locales lz4 zstd rpcsvc-proto
|
||||
```
|
||||
|
||||
**Note:** If packages are not available, request them from IT department.
|
||||
|
||||
### 2.2 Locale Configuration
|
||||
|
||||
```bash
|
||||
sudo locale-gen en_US.UTF-8
|
||||
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
|
||||
export LC_ALL=en_US.UTF-8
|
||||
export LANG=en_US.UTF-8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Setup Yocto Build Environment
|
||||
|
||||
### 3.1 Create Directory Structure
|
||||
|
||||
```bash
|
||||
cd ${CORP_BASE}
|
||||
|
||||
# Create working directories
|
||||
mkdir -p build
|
||||
mkdir -p mirror
|
||||
|
||||
# Copy sources
|
||||
cp -r mirror-package/sources/* ./
|
||||
|
||||
# Setup downloads directory (offline)
|
||||
mkdir -p downloads
|
||||
cp -r mirror-package/downloads/* downloads/ 2>/dev/null || true
|
||||
```
|
||||
|
||||
### 3.2 Initialize Build
|
||||
|
||||
```bash
|
||||
# Source the build environment
|
||||
cd ${CORP_BASE}/poky-scarthgap
|
||||
source oe-init-build-env ${CORP_BASE}/build
|
||||
|
||||
# You are now in ${CORP_BASE}/build
|
||||
```
|
||||
|
||||
### 3.3 Configure for Offline Build
|
||||
|
||||
Edit `${CORP_BASE}/build/conf/local.conf`:
|
||||
|
||||
```conf
|
||||
# Machine selection
|
||||
MACHINE ??= "tqma6ulx-mba6ulx"
|
||||
|
||||
# Offline/Premirror configuration
|
||||
BB_NO_NETWORK = "1"
|
||||
|
||||
# Use local mirror for all sources
|
||||
PREMIRRORS:prepend = " \
|
||||
git://.*/.* file://${CORP_BASE}/downloads/ \
|
||||
ftp://.*/.* file://${CORP_BASE}/downloads/ \
|
||||
http://.*/.* file://${CORP_BASE}/downloads/ \
|
||||
https://.*/.* file://${CORP_BASE}/downloads/ \
|
||||
"
|
||||
|
||||
# Don't check for updates
|
||||
BB_FETCH_PREMIRRORONLY = "1"
|
||||
|
||||
# Parallelism
|
||||
BB_NUMBER_THREADS ?= "8"
|
||||
PARALLEL_MAKE ?= "-j8"
|
||||
|
||||
# DL directory
|
||||
DL_DIR = "${CORP_BASE}/downloads"
|
||||
|
||||
# SSTATE (optional, for faster rebuilds)
|
||||
SSTATE_DIR = "${CORP_BASE}/sstate-cache"
|
||||
|
||||
# Archive settings for compliance
|
||||
INHERIT += "archiver"
|
||||
ARCHIVER_MODE[src] = "original"
|
||||
COPY_LIC_MANIFEST = "1"
|
||||
COPY_LIC_DIRS = "1"
|
||||
```
|
||||
|
||||
### 3.4 Configure Layers
|
||||
|
||||
Edit `${CORP_BASE}/build/conf/bblayers.conf`:
|
||||
|
||||
```conf
|
||||
BBLAYERS ?= " \
|
||||
${CORP_BASE}/poky-scarthgap/meta \
|
||||
${CORP_BASE}/poky-scarthgap/meta-poky \
|
||||
${CORP_BASE}/poky-scarthgap/meta-yocto-bsp \
|
||||
${CORP_BASE}/meta-openembedded/meta-oe \
|
||||
${CORP_BASE}/meta-openembedded/meta-python \
|
||||
${CORP_BASE}/meta-openembedded/meta-networking \
|
||||
${CORP_BASE}/meta-openembedded/meta-filesystems \
|
||||
${CORP_BASE}/meta-tq/meta-tq \
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Build Image
|
||||
|
||||
### 4.1 First Build (Offline)
|
||||
|
||||
```bash
|
||||
cd ${CORP_BASE}/build
|
||||
|
||||
# Ensure we're in the build environment
|
||||
source ${CORP_BASE}/poky-scarthgap/oe-init-build-env ${CORP_BASE}/build
|
||||
|
||||
# Start build (all sources should be local)
|
||||
bitbake core-image-minimal
|
||||
```
|
||||
|
||||
**Expected:** Build completes without network access.
|
||||
|
||||
### 4.2 Verify 2038 Compliance
|
||||
|
||||
After successful build:
|
||||
|
||||
```bash
|
||||
# Check time_t size in generated toolchain
|
||||
${CORP_BASE}/build/tmp/sysroots/x86_64-linux/usr/bin/arm-poky-linux-gnueabi-gcc -dM -E - < /dev/null | grep TIME_BITS
|
||||
# Expected: #define __TIME_BITS 64
|
||||
|
||||
# Check kernel config
|
||||
bitbake -e virtual/kernel | grep CONFIG_COMPAT_32BIT_TIME
|
||||
# Expected: CONFIG_COMPAT_32BIT_TIME=y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Development Workflow
|
||||
|
||||
### 5.1 Daily Use
|
||||
|
||||
```bash
|
||||
# Enter build environment
|
||||
cd ${CORP_BASE}
|
||||
source poky-scarthgap/oe-init-build-env build
|
||||
|
||||
# Build target
|
||||
bitbake core-image-minimal
|
||||
|
||||
# Deploy to target (SD card / eMMC)
|
||||
# See TQ documentation for deployment methods
|
||||
```
|
||||
|
||||
### 5.2 Adding Custom Layers
|
||||
|
||||
If custom corporate layers are required:
|
||||
|
||||
```bash
|
||||
# Add to bblayers.conf
|
||||
vim ${CORP_BASE}/build/conf/bblayers.conf
|
||||
|
||||
# Add path to custom layer
|
||||
# ${CORP_BASE}/meta-custom \
|
||||
```
|
||||
|
||||
### 5.3 SDK Generation
|
||||
|
||||
For application development:
|
||||
|
||||
```bash
|
||||
# Generate SDK
|
||||
bitbake core-image-minimal -c populate_sdk
|
||||
|
||||
# Install SDK
|
||||
${CORP_BASE}/build/tmp/deploy/sdk/*.sh
|
||||
|
||||
# Source SDK environment
|
||||
source /opt/poky/.../environment-setup-arm-poky-linux-gnueabi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updating the Mirror
|
||||
|
||||
When new TQ BSP versions are approved:
|
||||
|
||||
1. Request updated mirror from external system
|
||||
2. Verify checksums
|
||||
3. Extract to separate directory
|
||||
4. Compare with current deployment
|
||||
5. Test build in isolation
|
||||
6. Switch over after validation
|
||||
|
||||
### Build Cache Management
|
||||
|
||||
```bash
|
||||
# Clean build (keep downloads)
|
||||
bitbake -c cleanall core-image-minimal
|
||||
|
||||
# Full clean (careful!)
|
||||
rm -rf ${CORP_BASE}/build/tmp/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Network timeout errors
|
||||
|
||||
**Cause:** BitBake trying to fetch from internet
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Verify BB_NO_NETWORK is set
|
||||
grep BB_NO_NETWORK ${CORP_BASE}/build/conf/local.conf
|
||||
|
||||
# Should show: BB_NO_NETWORK = "1"
|
||||
```
|
||||
|
||||
### Issue: Missing source files
|
||||
|
||||
**Cause:** Incomplete mirror transfer
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check downloads directory
|
||||
ls ${CORP_BASE}/downloads | wc -l
|
||||
# Compare with external mirror
|
||||
|
||||
# Re-transfer missing files
|
||||
```
|
||||
|
||||
### Issue: Permission denied
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Fix ownership
|
||||
sudo chown -R $(whoami):$(whoami) ${CORP_BASE}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **No Internet Access:** Build must complete without network
|
||||
2. **Audit Trail:** All sources archived and version-controlled
|
||||
3. **License Compliance:** License manifest generated for every build
|
||||
4. **User Permissions:** Build as regular user, not root
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] Mirror extracted and verified
|
||||
- [ ] Offline build successful
|
||||
- [ ] 2038 compliance verified (64-bit time_t)
|
||||
- [ ] License manifest generated
|
||||
- [ ] Image deploys to target hardware
|
||||
- [ ] SDK functional for application development
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues:
|
||||
1. Check [TQ BSP Documentation](https://github.com/tq-systems/meta-tq)
|
||||
2. Review Yocto Project manuals (included in mirror)
|
||||
3. Consult internal engineering team
|
||||
|
||||
---
|
||||
|
||||
**Author:** Siggi ⚙️
|
||||
**Date:** 2026-03-01
|
||||
**Classification:** Internal Use
|
||||
Reference in New Issue
Block a user