OreBolt-OS/HEADERS.md

OreBolt OS -- Kernel Headers Sourcing Strategy

TL;DR -- vendor the FiiO M3K GPL kernel tree (Linux 3.10.14, Ingenic BSP) as the canonical headers source for the H2. Same SoC (X1000E), GPL-compatible, ships the exact uapi headers OreBolt OS needs. Use the Ingenic XBurst BSP as a fallback for any header FiiO stripped. Rockbox is optional, bare-metal only -- it is not a header set on top of Linux and the original workflow of "mine Rockbox for register definitions" was wrong for our Linux build path.

---

1. Background

v1.3 targeted the wrong SoC (T31 / X2000) and asked the operator to "clone Rockbox for reference and hand-write register definitions" because Rockbox's headers are GPL and the original workflow assumed a proprietary codebase. That workflow was:

• Wrong target. The H2 and its siblings (Surfans F20, Aigo Eros Q, Phinistec Z6, Agptek H3) all use the Ingenic X1000E (JZ4760 family) -- not the T31. See /upload/h2-and-related-devices.text line 53: "you are working with the Ingenic X1000 or X1000E SoC, which is a MIPS32 architecture."
• Wrong tool. Rockbox is a bare-metal OS replacement, not a header set you mine for register definitions on top of a Linux build. v1.3 ships init.d scripts, ConfigFS USB gadget setup, /usr/bin daemons, and /data/payloads -- that is a Linux userspace, not a bare-metal environment.
• Painful workflow. Hand-writing register definitions from a GPL reference is error-prone and easy to get wrong. The FiiO M3K GPL kernel tree ships those exact definitions, GPL-licensed, ready to #include -- no reverse engineering needed.

OreBolt OS corrects this by vendoring the FiiO M3K tree as the canonical headers source.

2. The FiiO M3K GPL kernel tree (primary)

The FiiO M3K is a DAP that uses the exact same Ingenic X1000E SoC as the H2. FiiO released their Linux kernel source under GPL. Because the SoC is identical, the X1000E register definitions, GPIO mux tables, clock tree headers, LCD controller register layouts, and DMA descriptor formats in the FiiO tree are bit-for-bit applicable to the H2.

2.1 Where to get it

GitHub mirrors of the FiiO M3K kernel source are maintained by the DAP hacking community. Common search terms:

github.com  FiiO_M3K_Kernel_Source
github.com  fiio m3k linux

Alternatively, FiiO publishes GPL source bundles as .tar.gz on their official download page -- check fiio.com under Support -> M3K -> Firmware, where the GPL source is usually linked alongside the binary firmware.

2.2 Install it

# Clone (or extract the tarball) to /opt/fiio-m3k-linux
sudo mkdir -p /opt/fiio-m3k-linux
# Either:
git clone --depth 1 <fiio-m3k-mirror-url> /opt/fiio-m3k-linux
# Or:
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

2.3 What OreBolt OS uses from it

The Makefiles add the following -I paths to every cross-compile:

Include path	What it provides
$(KERNEL_HEADERS)/include/uapi	Linux userspace API headers (<linux/kernel.h>, <linux/types.h>, <linux/ioctl.h>, etc.) -- the clean, GPL-2.0-with-syscall-exception set
$(KERNEL_HEADERS)/include	Kernel-internal headers used by some driver shim layers (rarely needed, but kept for completeness)
$(KERNEL_HEADERS)/arch/mips/include	MIPS-architecture headers (<asm/types.h>, <asm/io.h>, <asm/byteorder.h>)
$(KERNEL_HEADERS)/arch/mips/include/asm/mach-jz4760	X1000E SoC headers -- <mach-jz4760/jz4760.h> (SoC register definitions), <mach-jz4760/gpio.h> (GPIO mux tables), <mach-jz4760/cgu.h> (clock generation unit), <mach-jz4760/dmac.h> (DMA descriptor format)

2.4 GPL compliance

The FiiO M3K kernel tree is GPL-2.0. OreBolt OS's hardware library (liborebolt.a and src/modules/*.c) is also GPL-2.0-or-later, so #include-ing FiiO's headers is a clean GPL-to-GPL link. No license boundary issue.

Important: do NOT copy FiiO's .c driver files verbatim into OreBolt OS unless you are prepared to GPL-2.0-only those files (or track the upstream so changes propagate). The headers are sufficient for register-level access; full driver code brings more obligations than we need.

3. Ingenic XBurst BSP (fallback)

If a header you need is missing from the FiiO tree (FiiO sometimes strips headers for peripherals the M3K does not expose), the raw Ingenic XBurst BSP is the next stop. Two known community mirrors:

• YuanhuanLiang/X1000 -- X1000 SDK dump
• acbits/kernel-xburst-bsp -- broader XBurst BSP, useful for JZ47xx family

These are raw SDK dumps from Ingenic, including the kernel/ directory with the 3.10.14 base. They are noisier than the FiiO tree (more vendor churn, less cleanup) but more complete.

3.1 When to use the BSP instead of FiiO

• A header FiiO references is missing (e.g., FiiO's M3K does not expose NAND, so they may have stripped <mach-jz4760/nand.h>).
• You need a register definition that postdates the FiiO release (rare; the X1000E is end-of-life from Ingenic).
• You are debugging a peripheral the M3K does not have but the H2 does (e.g., the H2's Bluetooth chipset).

3.2 How to switch

Override KERNEL_HEADERS at build time:

export KERNEL_HEADERS=/opt/xburst-bsp/kernel
./build.sh

The build system accepts any path that contains include/uapi/linux/kernel.h -- the headers-check target in the master Makefile verifies this.

4. Rockbox (OPTIONAL, bare-metal only)

v1.3 listed Rockbox as the primary header reference. OreBolt OS demotes it to optional and explicitly scopes it to the bare-metal build path -- which OreBolt OS does not currently use, but a future "OreBolt OS Native" port might.

4.1 What Rockbox is actually good for

Rockbox is a complete OS replacement for the H2 and its siblings. When you boot Rockbox on these devices, Rockbox IS the operating system -- it does not run on top of Linux. This makes it useless as a header source for a Linux userspace build, but extremely useful if you ever decide to:

• Replace the H2's stock Linux firmware entirely with Rockbox + OreBolt OS native code (no kernel, no init system, just Rockbox acting as the OS).
• Cross-reference a register definition whose semantics are unclear from the C struct alone (Rockbox's driver code shows how the register is actually programmed, in real working code).

4.2 What Rockbox is NOT good for

• Mining headers for use in a Linux userspace build. Rockbox's headers are bare-metal -- they define register addresses as physical memory locations and access them via direct pointer dereference. In a Linux userspace build, you access the same registers via /dev/mem or kernel drivers, not by including Rockbox's headers.
• Copy-pasting GPL code into a proprietary project. Rockbox is GPL-2.0; you cannot verbatim-copy its driver code into OreBolt OS modules that are not GPL.

4.3 If you still want Rockbox for reference

git clone --depth 1 https://github.com/Rockbox/rockbox.git /opt/rockbox-ref

The relevant tree for the H2 is firmware/target/mips/ingenic/jz4760/ (the closest public match to the X1000E). Use it only as a semantic reference for register behavior -- do not include its headers in the OreBolt OS build path.

5. Decision matrix

Build target	Headers source	Rockbox role
OreBolt OS on stock H2 Linux firmware (current path)	FiiO M3K GPL kernel	None
OreBolt OS on a custom Buildroot Linux rootfs for H2	FiiO M3K GPL kernel	None
OreBolt OS bare-metal on H2 (future "Native" port)	Rockbox jz4760/ headers, FiiO headers as cross-reference	Primary
Any build needing a stripped header	Ingenic XBurst BSP as fallback	None

6. Verification

Run make headers-check after setting KERNEL_HEADERS to verify the tree is correctly installed:

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

The check verifies:

• The path exists.
• include/uapi/linux/kernel.h exists (i.e., this is a Linux kernel tree).
• Warns (does not fail) if arch/mips/include/asm/mach-jz4760/jz4760.h is missing -- this is the JZ4760 SoC header. If you are using the XBurst BSP, the path may differ; in that case, the build will fail later when it tries to #include a missing header, and you can investigate from there.

7. Historical PREREQUISITES.md delta

The v1.3 PREREQUISITES.md section on "Rockbox Headers for Ingenic T31" is replaced by this file. The current PREREQUISITES.md points operators here instead of reproducing the Rockbox workflow.