dcosnet
/
OreBolt-OS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OreBolt-OS/PREREQUISITES.md

17 KiB
Executable File
Raw Permalink Blame History

OreBolt OS v1.7 -- 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 (see HEADERS.md), optional Buildroot environment, and SD card preparation.

SoC note: The target SoC is the Ingenic X1000E (JZ4760 family), not the T31/X2000. The headers source is 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 for the full strategy.

Table of Contents

  1. Arch Linux Host Setup
  2. Cross-Compiler Toolchain
  3. Kernel Headers (FiiO M3K GPL tree)
  4. Optional: Buildroot for X1000E Full Image
  5. Workspace Clone & Verify
  6. SD Card Preparation
  7. Environment Variables Reference
  8. Troubleshooting
  9. Licensing
  10. What build.sh 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

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

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

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.

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: 
    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

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

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.

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.

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

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:

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

2.5 Verify the Toolchain Works

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 (FiiO M3K GPL tree)

Read HEADERS.md for the full strategy. This section is a quick-start summary.

OreBolt OS 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

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

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.

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.

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

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

4.2 Configure for Ingenic X1000E

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

make
# Output: output/images/{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

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:

# Required top-level files
ls -1 Makefile Makefile.h2-core-v6.2 Makefile.orebolt-v1.5 \
       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 18 module source files
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-pauto/pauto.c \
       modules/orebolt-extract/extract.c \
       modules/orebolt-noise/noise.c \
       modules/orebolt-reset/reset.c \
       modules/orebolt-retro/retro.c \
       modules/orebolt-retro/retro_input_mapper.c \
       modules/orebolt-rfid/rfid.c \
       modules/orebolt-glitch/glitch.c \
       modules/orebolt-pwdb/pwdb.c \
       modules/orebolt-proxalarm/bledsp.c \
       modules/orebolt-proxalarm/proxvec.c \
       modules/orebolt-proxalarm/radar_ui.c \
       modules/orebolt-proxalarm/proxalarm.c \
       modules/orebolt-bitchat/bitchat.c

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

# Hardware library sources (7 files)
ls -1 src/modules/

5.2 Verify Toolchain

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

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

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 First Deploy with Stock Backup

If this is the first time deploying OreBolt OS to this SD card, use --backup-stock to snapshot the stock Hiby Player firmware before any OreBolt files are written. This enables the "Restore Hiby Player" option in System Tools.

SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy --backup-stock

6.4 Subsequent Deploys

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 FiiO M3K GPL kernel tree path
HARDWARE_GPIO 0 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:

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

[-] 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:

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

[-] 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.5). 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

OreBolt OS uses a multi-tier licensing strategy. See 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 18 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.2: clones LVGL/lv_drivers, compiles liblvgl.so, h2_test launcher, 18 modules, input mapper Have network access (or pre-clone LVGL)
6 Builds OreBolt OS: 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
[ ] FiiO M3K GPL kernel tree at /opt/fiio-m3k-linux/
[ ] make headers-check passes
[ ] Workspace cloned into h2-workspace/
[ ] All 18 module source files present
[ ] LICENSE.md reviewed (bitchat = AGPL-3.0-only)
[ ] SD card formatted (FAT32) and mounted at /mnt/h2-sd/
[ ] Ready to run: ./build.sh