MIPS XIP Kernel

# Ubuntu/Debian
sudo apt update
sudo apt install -y clang lld llvm binutils-mipsel-linux-gnu \
  qemu-system-mips flex bison bc libelf-dev libssl-dev \
  python3 python3-pip texinfo

# Verify toolchain
clang --version
mipsel-linux-gnu-ld --version
qemu-system-mips --version

# Clone the repository
git clone https://github.com/user/mips-xip-kernel.git
cd mips-xip-kernel

# Full build: download + patch + compile + assemble
make

# Static layout verification
make verify

# Boot test in QEMU
make test

# Interactive QEMU session
make run

build/
├── linux-6.12.34/          # Patched kernel source tree
│   ├── vmlinux             # ELF kernel image
│   └── System.map          # Symbol map
├── out/
│   ├── xip-bios.bin        # Final flash image (shim + kernel ROM)
│   ├── shim.elf            # Boot shim ELF
│   ├── shim.bin            # Boot shim raw binary
│   └── kernel.bin          # Kernel ROM blob (objcopy -O binary)
└── boot.log                # QEMU serial output (if make test/run)

┌─────────────────────────────────────────────────┐
│  U-Boot Header (64 bytes)                       │
├─────────────────────────────────────────────────┤
│  Kernel (compressed or XIP)                     │
│  ├── Entry point                                │
│  ├── Device Tree Blob (DTB)                     │
│  └── Initramfs                                  │
├─────────────────────────────────────────────────┤
│  Root Filesystem (SquashFS + JFFS2 overlay)     │
├─────────────────────────────────────────────────┤
│  Bootloader (U-Boot / Breed)                    │
└─────────────────────────────────────────────────┘

#!/bin/bash
set -euo pipefail

KVER=6.12.34
WORK=build
KDIR=$WORK/linux-$KVER
OUT=$WORK/out

# Which defconfig to build. Defaults to the bare XIP boot-test config; the
# LWRT image build overrides it with DEFCONFIG=lwrt_qemu_malta_defconfig.
DEFCONFIG="${DEFCONFIG:-xip_qemu_malta_defconfig}"

# 1. Fetch kernel tarball
curl -fSL "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-${KVER}.tar.xz" \
  -o "$WORK/linux-${KVER}.tar.xz"

# 2. Extract
tar -xf "$WORK/linux-${KVER}.tar.xz" -C "$WORK"

# 3. Apply XIP patches
for p in patches/*.patch; do
  patch -p1 -d "$KDIR" < "$p"
done

# 4. Build the initramfs userspace. With no arguments this builds the tiny
#    freestanding demo PID 1; if LWRT_ROOTFS points at a staged rootfs, the
#    script instead emits a gen_init_cpio list describing it (this is how the
#    LWRT binary is baked in). Either way it writes $OUT/initramfs.list.
bash scripts/build-userspace.sh "$OUT"

# 5. Configure kernel from the selected defconfig, then point the embedded
#    initramfs at the generated list.
cp "configs/$DEFCONFIG" "$KDIR/arch/mips/configs/"
make -C "$KDIR" CC=clang ARCH=mips CROSS_COMPILE=mipsel-linux-gnu- "$DEFCONFIG"
"$KDIR/scripts/config" --file "$KDIR/.config" \
  --set-str INITRAMFS_SOURCE "$OUT/initramfs.list"
make -C "$KDIR" CC=clang ARCH=mips olddefconfig

# 6. Compile
make -C "$KDIR" CC=clang ARCH=mips \
  CROSS_COMPILE=mipsel-linux-gnu- \
  -j$(nproc) vmlinux

# Architecture
CONFIG_MIPS=y
CONFIG_32BIT=y
CONFIG_CPU_MIPS32_R2=y
CONFIG_CPU_LITTLE_ENDIAN=y

# XIP (the core feature)
CONFIG_XIP_KERNEL=y
CONFIG_XIP_PHYS_ADDR=0x1fc01000

# Optimization
CONFIG_CC_OPTIMIZE_FOR_SIZE=y
CONFIG_EXPERT=y
CONFIG_SLUB_TINY=y
CONFIG_KALLSYMS=n

# Boot
CONFIG_BLK_DEV_INITRD=y
CONFIG_INITRAMFS_SOURCE=""

# Hardware
CONFIG_MIPS_MALTA=y
CONFIG_PCI=y
CONFIG_SERIAL_8250=y
CONFIG_SERIAL_8250_CONSOLE=y

# Power management
CONFIG_POWER_RESET_PIIX4_POWEROFF=y

# Disabled subsystems
CONFIG_SMP=n
CONFIG_FPU=n
CONFIG_BLOCK=n
CONFIG_PROC_FS=n
CONFIG_SYSFS=n
CONFIG_NET=n
CONFIG_USB=n
CONFIG_DEBUG_INFO=n

# Networking core (lean: dhcp client / dns / httpd)
CONFIG_NET=y
CONFIG_PACKET=y
CONFIG_UNIX=y
CONFIG_INET=y
# CONFIG_IPV6 is not set

# Network driver (QEMU malta NIC)
CONFIG_NETDEVICES=y
CONFIG_ETHERNET=y
CONFIG_NET_VENDOR_AMD=y
CONFIG_PCNET32=y

# VFS the LWRT init needs
CONFIG_PROC_FS=y
CONFIG_PROC_SYSCTL=y
CONFIG_SYSFS=y
CONFIG_TMPFS=y
CONFIG_DEVTMPFS=y
CONFIG_DEVTMPFS_MOUNT=y

# IPC / syscalls the Rust std runtime expects
CONFIG_FUTEX=y
CONFIG_EPOLL=y
CONFIG_SIGNALFD=y
CONFIG_TIMERFD=y
CONFIG_EVENTFD=y
CONFIG_SHMEM=y
CONFIG_SYSCTL=y

# Compress the embedded initramfs to fit the malta byteswap window
CONFIG_RD_GZIP=y
CONFIG_INITRAMFS_COMPRESSION_GZIP=y

#!/bin/bash
set -euo pipefail

WORK=build
KDIR=$WORK/linux-6.12.34
OUT=$WORK/out
mkdir -p "$OUT"

# 1. Extract kernel_entry address from System.map
ENTRY=$(awk '$3 == "kernel_entry" {print "0x"$1}' "$KDIR/System.map")

# 2. Build boot shim (4 KiB at reset vector)
mipsel-linux-gnu-gcc -c -o shim.o shim/shim.S \
  -mips32r2 -EL -mno-abicalls -fno-pic -nostdlib
mipsel-linux-gnu-ld -o shim.elf shim.o \
  -T shim/shim.ld --defsym kernel_entry="$ENTRY" \
  -nostdlib --no-dynamic-linker
mipsel-linux-gnu-objcopy -O binary shim.elf shim.bin

# 3. Extract kernel ROM blob
mipsel-linux-gnu-objcopy -O binary -j .text -j .rodata \
  -j .init.text -j .data -j .init.data \
  "$KDIR/vmlinux" kernel.bin

# 4. Concatenate: shim + kernel → flash image
cat shim.bin kernel.bin > xip-flash.bin

# 5. Word-swap for QEMU malta (big-endian BIOS on mipsel)
python3 -c "
import sys
data = open('xip-flash.bin','rb').read()
swapped = b''
for i in range(0, len(data), 4):
    word = data[i:i+4]
    if len(word) == 4:
        swapped += bytes([word[3],word[2],word[1],word[0]])
    else:
        swapped += word
open('$OUT/xip-bios.bin','wb').write(swapped)
"

echo "Flash image: $OUT/xip-bios.bin ($(stat -c%s $OUT/xip-bios.bin) bytes)"

MIPS Virtual Address Space (32-bit)
┌────────────────────────────────────────────────┐ 0xFFFFFFFF
│  KSEG3 (0xBFC00000) — Cached, mapped           │
│  └── Reset vector: 0xBFC00000                  │
├────────────────────────────────────────────────┤ 0xA0000000
│  KSEG1 (0xA0000000) — Uncached, unmapped       │
│  └── I/O registers, flash if > 512 MiB         │
├────────────────────────────────────────────────┤ 0x80000000
│  KSEG0 (0x80000000) — Cached, unmapped         │
│  └── RAM: 0x80000000 – 0x8FFFFFFF              │
│  └── XIP virt: 0x80000000 + phys_addr         │
├────────────────────────────────────────────────┤ 0x00000000
│  USEG (0x00000000) — User space (mapped)       │
└────────────────────────────────────────────────┘

# Install cross-compilation toolchain
sudo apt install -y \
  clang lld llvm \
  binutils-mipsel-linux-gnu \
  gcc-mipsel-linux-gnu \
  qemu-system-mips

# Verify
clang --version
mipsel-linux-gnu-ld --version
qemu-system-mips --version

# Kernel build dependencies
sudo apt install -y \
  flex bison bc libelf-dev libssl-dev \
  libncurses-dev cpio wget xz-utils \
  python3 python3-pip

// Freestanding PID 1 — no libc, raw MIPS o32 syscalls
#include <stddef.h>

#define SYS_exit    4001
#define SYS_write   4004
#define SYS_pause   4029
#define SYS_sync    4036
#define SYS_reboot  4088

static void syscall1(int n, int a0) {
    register int v0 __asm__("v0") = n;
    register int a0r __asm__("a0") = a0;
    __asm__ volatile("syscall" : "+r"(v0) : "r"(a0r) : "memory");
}

static void write_str(const char *s, int len) {
    register int v0 __asm__("v0") = SYS_write;
    register int fd __asm__("a0") = 1;  // stdout
    register const char *buf __asm__("a1") = s;
    register int sz __asm__("a2") = len;
    __asm__ volatile("syscall" : "+r"(v0) : "r"(fd), "r"(buf), "r"(sz) : "memory");
}

void _start(void) {
    write_str("XIP-USERSPACE-OK\n", 17);
    write_str("XIP-POWEROFF: requesting power off\n", 35);
    syscall1(SYS_sync, 0);
    // reboot(LINUX_REBOOT_CMD_POWER_OFF = 0x4321fedc)
    register int v0 __asm__("v0") = SYS_reboot;
    register int a0 __asm__("a0") = 0xfee1dead;
    register int a1 __asm__("a1") = 672274793;
    register int a2 __asm__("a2") = 0x4321fedc;
    __asm__ volatile("syscall" : "+r"(v0) : "r"(a0), "r"(a1), "r"(a2) : "memory");
    while(1); // should never reach here
}

/* XIP virtual address = KSEG0 + physical offset */
XIP_VIRT_ADDR = 0x80000000 + CONFIG_XIP_PHYS_ADDR;

/* ROM region — executes directly from flash */
SECTIONS {
    .text XIP_VIRT_ADDR : AT(CONFIG_XIP_PHYS_ADDR) {
        _text = .;
        /* ... code sections ... */
        _etext = .;
    }

    /* RAM region — writable data */
    .data LINKER_LOAD_ADDRESS : {
        _sdata = .;
        /* ... data sections ... */
        _edata = .;
    }

    .bss : {
        _sbss = .;
        /* ... BSS sections ... */
        _ebss = .;
    }

    /* Special section for uasm-generated TLB handlers */
    .data..xip_patchable_text : {
        /* RAM buffers that kernel writes at boot */
    }
}

/* Custom macro to override asm-generic AT() */
#define XIP_AT(addr) (addr) - LOAD_OFFSET + XIP_PHYS_OFFSET

/* ROM trampoline in .text (original symbol location) */
handle_tlbl:
    PTR_LA  t9, xip_handle_tlbmiss_handler_setup_pgd
    jr      t9
    nop

/* RAM buffer in .data..xip_patchable_text */
xip_handle_tlbmiss_handler_setup_pgd:
    /* uasm-generated code lives here — writable RAM */

Physical Address Space
┌────────────────────────────────────────────┐ 0x20000000 (512 MiB)
│  End of KSEG0/KSEG1 direct-mapped region   │
├────────────────────────────────────────────┤
│  ...                                       │
├────────────────────────────────────────────┤ 0x1FC00000
│  SPI-NOR Flash (16 MiB)                    │
│  ├── 0x1FC00000: Boot Shim (4 KiB)         │
│  ├── 0x1FC01000: Kernel .text (XIP)        │
│  ├── 0x1FDxxxxx: Kernel .rodata (XIP)      │
│  ├── 0x1FExxxxx: Kernel .init.text (XIP)   │
│  └── 0x1FFxxxxx: Data LMA (copied to RAM)  │
├────────────────────────────────────────────┤ 0x1E000000
│  RAM (8–16 MiB)                            │
│  ├── 0x80000000: Kernel .data              │
│  ├── 0x800xxxxx: Kernel .bss               │
│  ├── 0x801xxxxx: TLB handlers (RAM)        │
│  ├── 0x802xxxxx: Free memory               │
│  └── 0x81FFFFFF: End of 32 MiB window      │
└────────────────────────────────────────────┘

# Standard OpenWrt build (for reference)
git clone https://git.openwrt.org/openwrt/openwrt.git
cd openwrt
./scripts/feeds update -a
./scripts/feeds install -a
make menuconfig  # Select Target → MediaTek Ralink → MT76x8
make -j$(nproc)  # Builds full firmware image

# Output: bin/targets/ramips/mt76x8/openwrt-ramips-mt76x8-*.bin

# Connection tracking
CONFIG_NF_CONNTRACK=y

# NAT
CONFIG_NF_NAT=y
CONFIG_NF_NAT_MASQUERADE=y

# nftables framework
CONFIG_NF_TABLES=y
CONFIG_NFT_CT=y          # Connection tracking in nftables
CONFIG_NFT_NAT=y         # NAT in nftables
CONFIG_NFT_MASQ=y        # Masquerading in nftables

#!/usr/sbin/nft -f
flush ruleset

table inet filter {
    chain input {
        type filter hook input priority 0; policy drop;
        iif lo accept
        ct state established,related accept
        tcp dport 22 accept           # SSH
        icmp type echo-request accept # Ping
    }

    chain forward {
        type filter hook forward priority 0; policy drop;
        ct state established,related accept
        iif "lan" oif "wan" accept    # LAN → WAN
    }

    chain output {
        type filter hook output priority 0; policy accept;
    }
}

table inet nat {
    chain prerouting {
        type nat hook prerouting priority -100;
    }

    chain postrouting {
        type nat hook postrouting priority 100;
        oif "wan" masquerade          # NAT for LAN clients
    }
}

Offset    Size      Partition
0x000000  128 KiB   Bootloader (U-Boot / Breed)
0x020000  64 KiB    Config (factory defaults)
0x030000  64 KiB    Config (user settings)
0x040000  128 KiB   Bootloader (backup)
0x060000  14.75 MiB Firmware (kernel + rootfs)
  ├── 0x060000  4 KiB    Boot Shim (XIP)
  ├── 0x061000  ~900 KiB Kernel .text (XIP)
  ├── 0x101000  ~200 KiB Kernel data (copied to RAM)
  └── 0x111000  ~14 MiB  Root filesystem (SquashFS)
0xFE0000  128 KiB   Board config (MAC, region)
0xFF0000  64 KiB    Boot countdown

qemu-system-mipsel \
  -M malta \
  -m 256M \
  -nographic \
  -bios build/out/xip-bios.bin \
  -serial mon:stdio \
  -no-reboot \
  -device pci-testdev 2>&1 | tee build/boot.log

Linux version 6.12.34 (builder@x86) (clang 18.0) #1 SMP ...
...
Memory: 245760K/262144K available (1024K kernel code, ...)
...
Freeing unused kernel image(s): 32K freed
XIP-USERSPACE-OK
XIP-POWEROFF: requesting power off

# Connect USB-to-serial adapter to router UART pins
# TX → RX, RX → TX, GND → GND

# Linux
sudo screen /dev/ttyUSB0 115200

# Or with minicom
sudo minicom -D /dev/ttyUSB0 -b 115200

# Or with picocom
sudo picocom -b 115200 /dev/ttyUSB0

#!/usr/bin/env python3
"""QEMU boot smoke test for XIP kernel."""
import subprocess, sys, time

MARKERS = [
    "Linux version",        # kernel alive
    "Memory:",              # memblock accounting sane
    "Freeing unused kernel",# init memory reclaim worked
    "XIP-USERSPACE-OK",     # PID 1 ELF executed
    "XIP-POWEROFF:",        # userspace reached poweroff
]

def test():
    proc = subprocess.Popen(
        ["qemu-system-mipsel", "-M", "malta", "-m", "256M",
         "-nographic", "-bios", "build/out/xip-bios.bin",
         "-no-reboot", "-serial", "mon:stdio"],
        stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
        text=True
    )
    output = []
    found = 0
    deadline = time.time() + 30

    while time.time() < deadline:
        line = proc.stdout.readline()
        if not line:
            break
        output.append(line)
        if found < len(MARKERS) and MARKERS[found] in line:
            found += 1
        if "XIP-POWEROFF" in line:
            break

    proc.wait(timeout=10)
    output_text = "".join(output)

    if found == len(MARKERS) and proc.returncode == 0:
        print("PASS: all markers found, clean poweroff")
        sys.exit(0)
    else:
        print(f"FAIL: found {found}/{len(MARKERS)} markers")
        sys.exit(1)

name: Build & Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          sudo apt update
          sudo apt install -y clang lld llvm \
            binutils-mipsel-linux-gnu \
            qemu-system-mips flex bison bc

      - name: Cache kernel tarball
        uses: actions/cache@v4
        with:
          path: build/linux-*.tar.xz
          key: kernel-${{ hashFiles('patches/*') }}

      - name: Build
        run: make

      - name: Verify layout
        run: make verify

      - name: Boot test
        run: make test

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: xip-kernel
          path: |
            build/out/xip-bios.bin
            build/boot.log