OreBolt-OS/PREREQUISITES.md

# OreBolt OS v1.4 -- Host & Toolchain Prerequisites

Everything you need to set up on your Arch Linux build machine **before**
running `./build.sh`.  This guide covers the host OS, cross-compiler
toolchain, **kernel headers sourcing** (new in v1.4 -- see
[HEADERS.md](HEADERS.md)), optional Buildroot environment, and SD card
preparation.

> **v1.4 change**: the target SoC is now correctly identified as the
> **Ingenic X1000E** (JZ4760 family), not the T31/X2000.  The headers
> source is now the **FiiO M3K GPL kernel tree** (same SoC as the H2),
> not Rockbox.  Rockbox is now optional and scoped to bare-metal only.
> See [HEADERS.md](HEADERS.md) for the full strategy.

---

## Table of Contents

1. [Arch Linux Host Setup](#1-arch-linux-host-setup)
2. [Cross-Compiler Toolchain](#2-cross-compiler-toolchain)
3. [Kernel Headers (v1.4 -- FiiO M3K GPL tree)](#3-kernel-headers-v14--fiio-m3k-gpl-tree)
4. [Optional: Buildroot for X1000E Full Image](#4-optional-buildroot-for-x1000e-full-image)
5. [Workspace Clone & Verify](#5-workspace-clone--verify)
6. [SD Card Preparation](#6-sd-card-preparation)
7. [Environment Variables Reference](#7-environment-variables-reference)
8. [Troubleshooting](#8-troubleshooting)
9. [Licensing](#9-licensing)
10. [What `build.sh` Handles Automatically](#10-what-buildsh-handles-automatically)

---

## 1. Arch Linux Host Setup

OreBolt OS targets the HiFiWalker H2 (Ingenic **X1000E**, MIPS32r2,
mipsel) but builds entirely on a stock Arch Linux x86_64 workstation.
Arch is the only supported host because the build tooling, package
versions, and PATH layout are validated against it.  Other distributions
may work but will require porting effort, particularly around `pacman`
dependency checks in Phase 0 of `build.sh`.

### 1.1 Install Base Build Toolchain

```bash
sudo pacman -Syu --needed base-devel git make python3
```

This pulls in `gcc`, `binutils`, `make`, `patch`, `tar`, `gzip`, `bzip2`,
`xz`, `sed`, `gawk`, `file`, and `which` -- the minimal set required by
both the host-side tools and the cross-compilation pipeline.  The
`build.sh` script will check for these in Phase 0 and attempt to install
any missing ones via `pacman -S --noconfirm`.

### 1.2 Install SD Card Utilities

```bash
sudo pacman -S --needed rsync dosfstools e2fsprogs parted file
```

Required for partitioning, formatting, and verifying the SD card used to
deploy OreBolt OS to the H2 (see Section 6).  `file` is also used by
`build.sh` Phase 7 to verify that produced binaries are MIPS
little-endian ELF.

### 1.3 Keep Arch Updated

```bash
sudo pacman -Syu
```

Arch Linux rolling release means you will always have a recent GCC,
binutils, and glibc.  No pinned versions are required for the host
toolchain -- the cross-compiler is fully self-contained and does not
depend on the host GCC version.

### 1.4 User Permissions

You need `sudo` access for package installation and SD card mount
operations.  The build scripts detect whether they are running as root
or can use passwordless sudo; if neither works, they print the manual
install command and exit.

```bash
sudo -n true 2>/dev/null && echo "passwordless sudo: OK" || echo "passwordless sudo: NO (will prompt)"
```

---

## 2. Cross-Compiler Toolchain

The build requires a `mipsel-linux-musl` cross-compiler targeting
MIPS32r2 little-endian with hard-float ABI and musl libc.  The `build.sh`
script and all Makefiles expect the toolchain binaries to be named with
the prefix `mipsel-linux-musl-` (e.g., `mipsel-linux-musl-gcc`,
`mipsel-linux-musl-strip`, `mipsel-linux-musl-ar`,
`mipsel-linux-musl-ranlib`).

### 2.1 Toolchain Source: Rockbox (Recommended)

Rockbox maintains a tested MIPS cross-compiler specifically for Ingenic
JZ47xx and X1000-family SoCs.  Since Rockbox has a port for this exact
device family, their toolchain is the most authoritative and
hardware-verified option available.

**Option A: Use Rockbox's prebuilt toolchain**

1. Visit the Rockbox toolchain downloads page:
   `https://www.rockbox.org/wiki/CrossCompile`
2. Download the MIPS toolchain tarball.
3. Extract and install:
   ```bash
   sudo mkdir -p /opt/mipsel-linux-musl
   sudo tar xzf rockbox-mips-toolchain-*.tar.gz -C /opt/mipsel-linux-musl --strip-components=1
   ```
4. Add to PATH (see Section 2.4).

**Option B: Build the Rockbox toolchain from source**

```bash
git clone https://github.com/Rockbox/rockbox.git
cd rockbox/tools
# Follow instructions at https://www.rockbox.org/wiki/CrossCompile
```

> **v1.4 note**: Rockbox's toolchain is still the recommended
> cross-compiler even though Rockbox is no longer the recommended
> headers source.  The toolchain (compiler + binutils + libc) is
> SoC-agnostic enough that it works for any MIPS32r2 target; the
> headers source is what was wrong in v1.3.

### 2.2 Toolchain Source: musl.cc (Fallback)

If the Rockbox toolchain is unavailable, musl.cc provides
community-built musl cross-compiler binaries.  These are generic and not
tuned for Ingenic specifically.

```bash
wget https://musl.cc/mipsel-linux-musl-cross.tgz -O /tmp/mipsel-toolchain.tgz
sudo mkdir -p /opt/mipsel-linux-musl
sudo tar xzf /tmp/mipsel-toolchain.tgz -C /opt/mipsel-linux-musl --strip-components=1
```

**Caveat**: musl.cc toolchains may not include Ingenic-specific compiler
intrinsics or tune flags.  If you encounter issues with floating-point
operations or scheduler behavior, switch to the Rockbox toolchain.

### 2.3 Toolchain Source: Buildroot Self-Build (Advanced)

Buildroot can generate a complete cross-compiler toolchain from source.
This is the most flexible option but also the slowest (build time: 15-45
minutes).  See Section 4.

### 2.4 Add Toolchain to PATH

```bash
export PATH="/opt/mipsel-linux-musl/bin:$PATH"
mipsel-linux-musl-gcc --version
mipsel-linux-musl-gcc -dumpmachine   # Should print: mipsel-linux-musl
```

If your toolchain uses a different prefix, set `CROSS_COMPILE`:

```bash
export CROSS_COMPILE=mips-linux-gnu-
./build.sh
```

### 2.5 Verify the Toolchain Works

```bash
echo '#include <stdio.h>
int main(void) { printf("hello mipsel\\n"); return 0; }' > /tmp/test.c
mipsel-linux-musl-gcc -march=mips32r2 -mhard-float -static -o /tmp/test_mips /tmp/test.c
file /tmp/test_mips
# Expected: ELF 32-bit LSB executable, MIPS, MIPS32 version 1 ...
```

---

## 3. Kernel Headers (v1.4 -- FiiO M3K GPL tree)

> **Read [HEADERS.md](HEADERS.md) for the full strategy.**  This section
> is a quick-start summary.

v1.4 sources kernel headers from the **FiiO M3K GPL kernel tree** (Linux
3.10.14, Ingenic BSP) because the M3K uses the **exact same Ingenic
X1000E SoC as the H2**.  The FiiO tree ships the X1000E register
definitions, GPIO mux tables, clock tree headers, and DMA descriptor
formats -- all GPL-2.0, all directly `#include`-able, no reverse
engineering needed.

### 3.1 Install the FiiO M3K kernel tree

```bash
sudo mkdir -p /opt/fiio-m3k-linux
# Clone from a community mirror, or extract FiiO's official GPL tarball:
sudo tar xzf fiio_m3k_kernel_*.tar.gz -C /opt/fiio-m3k-linux --strip-components=1

# Verify
ls /opt/fiio-m3k-linux/include/uapi/linux/kernel.h
ls /opt/fiio-m3k-linux/arch/mips/include/asm/mach-jz4760/jz4760.h
```

### 3.2 Verify with `make headers-check`

```bash
make headers-check KERNEL_HEADERS=/opt/fiio-m3k-linux
# Expected:
# [OK] kernel headers root: /opt/fiio-m3k-linux
```

### 3.3 Fallback: Ingenic XBurst BSP

If a header is missing from the FiiO tree, use the raw Ingenic XBurst
BSP.  See [HEADERS.md §3](HEADERS.md#3-ingenic-xburst-bsp-fallback).

### 3.4 What about Rockbox?

Rockbox is now **optional** and scoped to a future bare-metal "OreBolt OS
Native" port.  The current Linux userspace build path does not use
Rockbox at all.  See [HEADERS.md §4](HEADERS.md#4-rockbox-optional-bare-metal-only).

---

## 4. Optional: Buildroot for X1000E Full Image

Buildroot is not required for the module-level cross-compilation that
`build.sh` performs.  However, if you want to produce a complete root
filesystem image for the H2 (kernel + initramfs + rootfs with all
OreBolt OS modules), Buildroot is the right tool.

### 4.1 Clone Buildroot

```bash
git clone https://github.com/buildroot/buildroot.git
cd buildroot
git checkout 2024.02   # or current stable
```

### 4.2 Configure for Ingenic X1000E

```bash
make menuconfig
```

**Target options:**
```
Target Architecture = MIPS (little endian)
Target Architecture Variant = mips32r2
Target ABI = 32 (soft-float)     # override below for hard-float
```

**Toolchain:**
```
Toolchain type = External toolchain
Toolchain = Custom toolchain
Toolchain path = /opt/mipsel-linux-musl
Toolchain prefix = $(ARCH)-linux-musl-
```

**Hard-float note**: the X1000E has a hardware FPU.  OreBolt OS compiles
with `-mhard-float`.  If Buildroot does not expose a hard-float option
in menuconfig, force it via `BR2_TARGET_OPTIMIZATION="-mhard-float"` in
`.config`.

**System configuration:**
```
System hostname = h2-hifiwalker
System banner = Welcome to OreBolt OS
/dev management = Dynamic using devtmpfs
Init system = BusyBox init (SysVinit)
```

### 4.3 Integrate the OreBolt OS Overlay

In menuconfig: System configuration -> Root filesystem overlay directories
Add: `/path/to/h2-workspace/overlay`

Or edit `.config` directly:
```
BR2_ROOTFS_OVERLAY="/path/to/h2-workspace/overlay"
```

### 4.4 Build and Flash

```bash
make
# Output: output/images/{rootfs.ext4, zImage, sdcard.img}

sudo dd if=output/images/sdcard.img of=/dev/sdX bs=4M status=progress
sync
sudo eject /dev/sdX
```

---

## 5. Workspace Clone & Verify

```bash
git clone <repo-url> h2-workspace
cd h2-workspace
```

### 5.1 Verify Workspace Integrity

`build.sh` Phase 2 does this automatically, but you can check manually:

```bash
# Required top-level files
ls -1 Makefile Makefile.h2-core-v6.1 Makefile.orebolt-v1.4 \
       build.sh inject_payloads.sh \
       main.c include/h2_ui.h include/log_manager.h lv_conf.h.dist \
       src/modules/panic_purge_api.h \
       PREREQUISITES.md HEADERS.md LICENSE.md CHANGELOG.md \
       ARCHITECTURE.md README.md BUILD_MANIFEST.txt SHA256SUMS

# All 16 module source files (v1.4: reconciled count)
ls -1 modules/orebolt-vault/vault.c \
       modules/orebolt-nettap/scalpel.c \
       modules/orebolt-deploy/deploy.c \
       modules/orebolt-studio/studio.c \
       modules/orebolt-probe/probe.c \
       modules/orebolt-vterm/vterm.c \
       modules/orebolt-radar/noise_radar.c \
       modules/orebolt-ducky/ducky.c \
       modules/orebolt-extract/extract.c \
       modules/orebolt-noise/noise.c \
       modules/orebolt-reset/reset.c \
       modules/orebolt-emulate/emulator.c \
       modules/orebolt-emulate/emulator_input_mapper.c \
       modules/orebolt-rfid/rfid.c \
       modules/orebolt-wifi/wifi.c \
       modules/orebolt-glitch/glitch.c \
       modules/orebolt-pwdb/pwdb.c \
       modules/orebolt-bitchat/bitchat.c

# Init scripts
ls -1 overlay/etc/init.d/S98emulator-input \
       overlay/etc/init.d/S99broker \
       overlay/etc/init.d/bt_input_daemon.sh

# Hardware library sources (7 files in v1.4)
ls -1 src/modules/
```

### 5.2 Verify Toolchain

```bash
mipsel-linux-musl-gcc --version
mipsel-linux-musl-gcc -dumpmachine    # Must contain "mips"
```

---

## 6. SD Card Preparation

The HiFiWalker H2 boots from an SD card.  Minimum: a single FAT32
partition holding the firmware files.

### 6.1 Identify the SD Card

```bash
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT
```

**WARNING**: Be absolutely certain you have identified the correct
device.  `/dev/sda` is typically your system disk.

### 6.2 Single-Partition Layout

```bash
sudo umount /dev/sdX1 2>/dev/null || true
sudo parted /dev/sdX --script mklabel msdos
sudo parted /dev/sdX --script mkpart primary fat32 1MiB 100%
sudo parted /dev/sdX --script set 1 boot on
sudo mkfs.vfat -F 32 -n OREBOLT /dev/sdX1
```

### 6.3 Dual-Partition Layout (Full Rootfs)

```bash
sudo parted /dev/sdX --script mklabel msdos
sudo parted /dev/sdX --script mkpart primary fat32 1MiB 129MiB
sudo parted /dev/sdX --script set 1 boot on
sudo parted /dev/sdX --script mkpart primary ext4 129MiB 100%
sudo mkfs.vfat -F 32 -n H2_BOOT /dev/sdX1
sudo mkfs.ext4 -L H2_ROOT /dev/sdX2
```

### 6.4 Deploy

```bash
SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy
```

---

## 7. Environment Variables Reference

| Variable | Default | Description |
|---|---|---|
| `CROSS_COMPILE` | `mipsel-linux-musl-` | Toolchain binary prefix |
| `KERNEL_HEADERS` | `/opt/fiio-m3k-linux` | **v1.4 NEW**: FiiO M3K GPL kernel tree path |
| `HARDWARE_GPIO` | `0` | **v1.4 default flipped**: set to `1` only on real H2 hardware to compile real GPIO panic purge |
| `SD_CARD_MOUNT` | `/mnt/h2-sd` | SD card mount point for `--deploy` |
| `NO_COLOR` | (unset) | Set to `1` to disable ANSI color in build scripts |
| `PATH` | (system) | Must include `/opt/mipsel-linux-musl/bin` |

Recommended `~/.bashrc` additions:

```bash
export PATH="/opt/mipsel-linux-musl/bin:$PATH"
export KERNEL_HEADERS="/opt/fiio-m3k-linux"
# export SD_CARD_MOUNT="/run/media/$USER/OREBOLT"
# export HARDWARE_GPIO=0  # explicit on dev host; set to 1 on hardware
```

---

## 8. Troubleshooting

### Toolchain not found
```
[-] Missing toolchain binaries: mipsel-linux-musl-gcc
```
Verify `/opt/mipsel-linux-musl/bin/` is in `$PATH`.  If your toolchain
uses a different prefix, set `CROSS_COMPILE`.

### Compiler target is not MIPS
```
[!] Compiler target 'x86_64-linux-gnu' does not look like MIPS
```
Run `which mipsel-linux-musl-gcc` and `mipsel-linux-musl-gcc
-dumpmachine`.  Ensure the cross-compiler's `bin/` appears before
`/usr/bin/` in `$PATH`.

### KERNEL_HEADERS not found (v1.4 NEW)
```
[-] CRITICAL: KERNEL_HEADERS not found at /opt/fiio-m3k-linux
```
Install the FiiO M3K GPL kernel tree (Section 3.1) or set
`KERNEL_HEADERS` to point at the XBurst BSP fallback (HEADERS.md §3).

### musl.cc toolchain float ABI mismatch
```
error: cannot find -lm
```
or linker errors about `soft-float` vs `hard-float`.  Switch to the
Rockbox toolchain (Section 2.1) which is configured for Ingenic's
hard-float ABI.

### LVGL clone fails
```
[*] Cloning LVGL v8.3.11 + lv_drivers v8.3.0...
fatal: unable to access 'https://github.com/lvgl/lvgl.git'
```
Pre-clone LVGL manually:
```bash
git clone --depth 1 -b v8.3.11 https://github.com/lvgl/lvgl.git
git clone --depth 1 -b v8.3.0 https://github.com/lvgl/lv_drivers.git
cp lv_conf.h.dist lv_conf.h
cp lv_drivers/lv_drv_conf_template.h lv_drv_conf.h
sed -i 's/#if 0/#if 1/' lv_drv_conf.h
sed -i 's/USE_FBDEV 0/USE_FBDEV 1/' lv_drv_conf.h
sed -i 's/USE_EVDEV 0/USE_EVDEV 1/' lv_drv_conf.h
```
`build.sh` Phase 5 will detect the existing `lvgl/src/` and skip
cloning.

### bitchat.mod missing AGPL_BITCHAT marker (v1.4 NEW)
```
[-] bitchat.mod missing AGPL_BITCHAT marker (license violation)
```
`mod_bitchat_mesh.c` was compiled without `-DAGPL_BITCHAT`.  This
should not happen if you build via `make` or `./build.sh` (both set
the define in `Makefile.orebolt-v1.4`).  If you are building
manually, add `-DAGPL_BITCHAT` to `CFLAGS`.

### Binary format verification fails
```
[-] BAD: h2_test -- ELF 64-bit LSB executable, x86-64
```
The build picked up the host GCC instead of the cross-compiler.  Run
`./build.sh --clean && ./build.sh`.

---

## 9. Licensing

v1.4 introduces a multi-tier licensing strategy.  See
[LICENSE.md](LICENSE.md) for the full strategy.

- **bitchat mesh module**: AGPL-3.0-only
- **All other OreBolt OS modules**: GPL-2.0-or-later
- **LVGL/lv_drivers**: MIT (upstream)

If you modify and deploy bitchat, you MUST make your modified source
available to anyone who interacts with your modified node over the mesh
(AGPL v3 §13).  Replace the `BITCHAT_SOURCE_URL` placeholder in
`mod_bitchat_mesh.c` with your real Written Offer URL before deploying.

---

## 10. What `build.sh` Handles Automatically

| Phase | What It Does | You Need To... |
|---|---|---|
| 0 | Checks for `base-devel`, `git`, `make`, `python3`, SD utils; probes for `KERNEL_HEADERS` | Install host deps + FiiO M3K kernel tree (Sections 1, 3) |
| 1 | Verifies `mipsel-linux-musl-{gcc,strip,ar,ranlib}` exist and target MIPS | Install the toolchain (Section 2) |
| 2 | Validates all 16 module source files, init scripts, and required top-level files | Clone the workspace (Section 5) |
| 3 | Creates the `overlay/` directory tree (apps/, usr/lib/, usr/bin/, etc.) | Nothing |
| 4 | Sets executable permissions on init scripts and utility scripts | Nothing |
| 5 | Builds H2 Core v6.1: clones LVGL/lv_drivers, compiles liblvgl.so, h2_test launcher, 16 modules, input mapper | Have network access (or pre-clone LVGL) |
| 6 | Builds OreBolt OS v1.4: compiles liborebolt.a and generates 150-payload matrix | Nothing |
| 7 | Verifies all artifacts exist, checks MIPS LE ELF, verifies bitchat AGPL marker | Nothing |
| 8 | Copies everything to SD card mount point, creates ROM directories | Mount SD card (Section 6) |

**In summary, you only need to do Sections 1, 2, 3, 5, and 6 before
running `./build.sh`.**  Section 4 (Buildroot) is optional and only
needed for producing a full rootfs image.

---

## Quick Reference Checklist

```
[ ] Arch Linux host up to date (pacman -Syu)
[ ] base-devel, git, make, python3, rsync, dosfstools, e2fsprogs, parted, file installed
[ ] mipsel-linux-musl toolchain installed at /opt/mipsel-linux-musl/
[ ] Toolchain in PATH: mipsel-linux-musl-gcc --version works
[ ] Test compile produces MIPS LE ELF binary
[ ] v1.4 NEW: FiiO M3K GPL kernel tree at /opt/fiio-m3k-linux/
[ ] v1.4 NEW: make headers-check passes
[ ] Workspace cloned into h2-workspace/
[ ] All 16 module source files present
[ ] v1.4 NEW: LICENSE.md reviewed (bitchat = AGPL-3.0-only)
[ ] SD card formatted (FAT32) and mounted at /mnt/h2-sd/
[ ] Ready to run: ./build.sh
```