# OreBolt OS v1.4 -- 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 v1.3 workflow of "mine Rockbox for > register definitions" was wrong for our Linux build path. --- ## 1. Why this is the v1.3 -> v1.4 change 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 OreBolt OS is (mostly) proprietary. 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. v1.4 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 ```bash # Clone (or extract the tarball) to /opt/fiio-m3k-linux sudo mkdir -p /opt/fiio-m3k-linux # Either: git clone --depth 1 /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 (``, ``, ``, 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 (``, ``, ``) | | `$(KERNEL_HEADERS)/arch/mips/include/asm/mach-jz4760` | **X1000E SoC headers** -- `` (SoC register definitions), `` (GPIO mux tables), `` (clock generation unit), `` (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 ``). - 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: ```bash 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. v1.4 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 ```bash 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 v1.4 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: ```bash 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. v1.3 -> v1.4 PREREQUISITES.md delta The v1.3 PREREQUISITES.md §3 "Rockbox Headers for Ingenic T31" is **replaced** by this file in v1.4. The v1.4 PREREQUISITES.md §3 now points operators here instead of reproducing the Rockbox workflow.