212 lines
8.7 KiB
Markdown
Executable File
212 lines
8.7 KiB
Markdown
Executable File
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```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. 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
|
|
|
|
```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 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. 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.
|