Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

perf: QEMU TCG tuning for container-heavy workloads

ExTvd620f20055bb
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..157423b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What Is This
+
+Podroid is an Android app that runs a rootless Alpine Linux VM via QEMU (ARM64) to provide a Podman container runtime without root. It embeds a Termux-based VT100 terminal emulator and communicates with the VM over QEMU serial/unix sockets.
+
+## Build Commands
+
+All components are coordinated by `build-all.sh`:
+
+```bash
+./build-all.sh kernel # Build custom kernel only (podroid_kernel.config, ~5–10 min)
+./build-all.sh initramfs # Build custom kernel + Alpine initramfs (~10–15 min total)
+./build-all.sh qemu # Build QEMU + podroid-bridge via Docker (~30 min first time)
+./build-all.sh termux # Build libtermux.so via local NDK (16KB page alignment)
+./build-all.sh apk # Build Android APK via Gradle
+./build-all.sh all # Build everything
+./build-all.sh deploy # Full deploy workflow
+./build-all.sh test # Boot validation: deploys APK, polls console.log for "Ready!"
+```
+
+`podroidKernelVersion` in `gradle.properties` controls the Linux version downloaded. Docker layer-caches the kernel build; only rebuilds if `podroid_kernel.config` or the version changes.
+
+**APK only:**
+```bash
+./gradlew assembleDebug
+./gradlew installDebug
+```
+
+**Monitor VM boot:**
+```bash
+adb logcat -s PodroidQemu
+adb shell run-as com.excp.podroid.debug cat files/console.log
+```
+
+The app uses debug build for all releases (release signing not configured). Native binaries require 16KB page alignment (`-Wl,-z,max-page-size=16384`) — mandatory on Android 13+.
+
+## Architecture
+
+### Data Flow
+
+```
+Terminal UI (Compose)
+ ↕ TerminalSession (Termux JNI)
+libpodroid-bridge.so ←→ serial.sock / ctrl.sock ←→ QEMU ←→ ttyAMA0 (Alpine)
+```
+
+- **Terminal I/O:** TerminalSession runs `libpodroid-bridge.so` as a process; the bridge connects `serial.sock` (I/O relay) and `ctrl.sock` (SIGWINCH / resize signaling)
+- **Port forwarding:** `QmpClient` sends `netdev_add`/`netdev_remove` commands to `qmp.sock` at runtime
+- **Boot monitoring:** `PodroidQemu` reads `serial.sock` until it detects the "Ready!" marker, logging all output to `console.log`
+
+### Key Components
+
+**`engine/PodroidQemu.kt`** — the core singleton. Builds and launches the QEMU process, monitors boot output from serial, manages `TerminalSession` lifecycle, and auto-starts `podroid-bridge` after boot. State machine: `Idle → Starting → Running → Stopped` (see `VmState.kt`).
+
+**`service/PodroidService.kt`** — foreground service that owns the QEMU process. Holds a `WakeLock`, updates the persistent notification with boot stages, and handles graceful stop when the app is swiped from recents.
+
+**`podroid-bridge.c`** — native C binary (compiled to `libpodroid-bridge.so`) that Termux runs as a subprocess. Bidirectionally relays PTY ↔ `serial.sock`, answers ESC window-size queries locally, and sends `RESIZE rows cols\n` to `ctrl.sock` on SIGWINCH.
+
+**`init-podroid`** — two-phase Alpine init script embedded as an asset. Phase 1 mounts overlayfs over `storage.img`; Phase 2 sets up cgroup v2, SLIRP networking, Podman, and Dropbear SSH, then prints the boot stage markers consumed by `PodroidQemu`.
+
+**`data/repository/`** — `SettingsRepository` (RAM, CPUs, storage size, theme, SSH toggle) and `PortForwardRepository` (persistent rules) both use Jetpack DataStore. No database.
+
+### Asset Extraction
+
+`PodroidApplication.kt` copies `qemu/`, `vmlinuz-virt`, and `initrd.img` from APK assets to `filesDir` on startup (size-checked to skip if unchanged). All native binaries in `jniLibs/arm64-v8a/` are extracted automatically by Android.
+
+### Navigation
+
+Single-activity Compose app: `NavGraph.kt` routes `setup → home → terminal / settings`. The setup screen only appears until setup is marked complete in DataStore.
+
+## Native Binaries in `jniLibs/arm64-v8a/`
+
+| File | What it is |
+|---|---|
+| `libqemu-system-aarch64.so` | QEMU TCG emulator (PIE executable, 16KB aligned) |
+| `libpodroid-bridge.so` | PTY ↔ serial relay (PIE executable, 16KB aligned) |
+| `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16KB pages) |
+| `libslirp.so` | SLIRP user-mode networking (statically linked into QEMU) |
+
+These are executed directly via `ProcessBuilder` / `TerminalSession`, not loaded as JNI libraries despite the `.so` extension.
+
+## QEMU Command Construction
+
+`PodroidQemu.buildCommand()` constructs the full QEMU cmdline including:
+- `-serial unix:serial.sock` / `-chardev socket,path=ctrl.sock` / `-qmp unix:qmp.sock`
+- RAM and CPU count from `SettingsRepository`
+- Virtio block device backed by `storage.img` (resized on first boot to configured size)
+- SLIRP networking with runtime port forwards via `QmpClient` (`netdev_add`/`netdev_remove` over `qmp.sock`)
+
+All socket and image paths are under `context.filesDir`.
+
+## Performance Tuning (TCG, no KVM)
+
+All tuning applies under software emulation only — KVM is impossible without root.
+
+**In `PodroidQemu.buildCommand()`:**
+- `tcg,thread=multi` — one host thread per vCPU (already enabled)
+- `tb-size`: 256 MB for <2 GB RAM, 512 MB for ≥2 GB — larger TB cache reduces re-translation for JIT-heavy workloads (Node, JVM in containers)
+- `iothread=iothread0` on `virtio-blk-pci` — dedicated I/O thread decoupled from vCPU threads; biggest single win for container image pull/extraction
+- `mitigations=off` in guest kernel cmdline — safe inside TCG VM (speculative execution attacks can't cross the emulated ISA boundary); 5–15% CPU gain
+- `elevator=mq-deadline` in guest kernel cmdline — request merging for virtio-blk random writes (Podman overlay graph driver)
+**In `init-podroid`:**
+- ZRAM swap at half physical RAM using lz4 — gives 1.5–2× effective memory with near-zero I/O cost; swapon at priority 100 so it's preferred over any file swap
+
+**In `Dockerfile` (QEMU build):**
+- `-O3 -flto=thin` in `--extra-cflags` / `--extra-ldflags` — LLVM thin LTO optimises across QEMU's translation units including the TCG hot path; deps are built separately without LTO so mixed linking is intentional
+
+**What won't work without root:** `io_uring` (Android 12+ seccomp block), CPU affinity/taskset, KSM memory dedup, TAP networking, huge pages on the host.
diff --git a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt
index d69027b..ce2224a 100644
--- a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt
+++ b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt
@@ -469,7 +469,8 @@ class PodroidQemu @Inject constructor(
args += "-cpu"; args += "max"
args += "-smp"; args += "$cpus"
args += "-m"; args += "$ramMb"
- args += "-accel"; args += "tcg,thread=multi,tb-size=256"
+ val tbSize = if (ramMb >= 2048) 512 else 256
+ args += "-accel"; args += "tcg,thread=multi,tb-size=$tbSize"
val kernelPath = File(context.filesDir, "vmlinuz-virt")
val initrdPath = File(context.filesDir, "initrd.img")
@@ -477,7 +478,7 @@ class PodroidQemu @Inject constructor(
if (kernelPath.exists()) {
args += "-kernel"; args += kernelPath.absolutePath
val cmdline = buildString {
- append("console=ttyAMA0 loglevel=1 quiet")
+ append("console=ttyAMA0 loglevel=1 quiet mitigations=off elevator=mq-deadline")
append(" androidip=$androidIp")
if (sshEnabled) append(" ssh=1")
}
@@ -494,7 +495,8 @@ class PodroidQemu @Inject constructor(
val storagePath = File(context.filesDir, "storage.img")
if (storagePath.exists()) {
- args += "-device"; args += "virtio-blk-pci,drive=drive1,num-queues=$cpus"
+ args += "-object"; args += "iothread,id=iothread0"
+ args += "-device"; args += "virtio-blk-pci,drive=drive1,num-queues=$cpus,iothread=iothread0"
args += "-drive"; args += "file=${storagePath.absolutePath},if=none,id=drive1,format=raw,cache=writeback,aio=threads"
}
diff --git a/skill.md b/skill.md
index 0568026..739d382 100644
--- a/skill.md
+++ b/skill.md
@@ -1,6 +1,6 @@
# Podroid AI Context
-> **Last updated:** 2026-04-22
+> **Last updated:** 2026-04-23
> **Purpose:** Complete project context for AI-assisted development. Read this before touching any file.
---
@@ -39,13 +39,13 @@
### High-Level Flow
```
Android App
-├── PodroidApplication — extracts assets (vmlinuz, initrd, qemu/) on first run
-├── PodroidService (foreground) — hosts QEMU, holds WakeLock
+├── PodroidApplication — extracts assets (vmlinuz, initrd, qemu/) on first run (size-checked to skip if unchanged)
+├── PodroidService (foreground) — hosts QEMU, holds WakeLock, updates notification with boot stages
├── PodroidQemu (singleton)
│ ├── QEMU process (libqemu-system-aarch64.so — ELF binary renamed .so for APK)
│ ├── serial.sock — boot monitor reads until "Ready!", then bridge connects
│ ├── ctrl.sock — virtio-console for RESIZE signals from bridge
-│ └── qmp.sock — QEMU Machine Protocol for runtime control
+│ └── qmp.sock — QEMU Machine Protocol for runtime control (port forwarding)
└── Compose UI
└── Screens: Setup → Home → Terminal / Settings
```
@@ -66,6 +66,25 @@ Android App
---
+## Performance Tuning (TCG, no KVM)
+
+All tuning applies under software emulation only — KVM is impossible without root.
+
+**In `PodroidQemu.buildCommand()`:**
+- `tcg,thread=multi` — one host thread per vCPU.
+- `tb-size`: 256 MB for <2 GB RAM, 512 MB for ≥2 GB — larger Translation Block cache reduces re-translation for JIT-heavy workloads (Node, JVM in containers).
+- `iothread=iothread0` on `virtio-blk-pci` — dedicated I/O thread decoupled from vCPU threads; biggest win for container image pull/extraction.
+- `mitigations=off` in guest kernel cmdline — safe inside TCG VM (speculative execution attacks can't cross the emulated ISA boundary); 5–15% CPU gain.
+- `elevator=mq-deadline` in guest kernel cmdline — request merging for virtio-blk random writes (Podman overlay graph driver).
+
+**In `init-podroid`:**
+- ZRAM swap at half physical RAM using lz4 — gives 1.5–2× effective memory with near-zero I/O cost; swapon at priority 100 so it's preferred over any file swap.
+
+**In `Dockerfile` (QEMU build):**
+- `-O3 -flto=thin` in `--extra-cflags` / `--extra-ldflags` — LLVM thin LTO optimises across QEMU's translation units including the TCG hot path.
+
+---
+
## Project Structure
### Root Level
@@ -155,12 +174,15 @@ Android App
```
### Native Libs (app/src/main/jniLibs/arm64-v8a/)
-```
-├── libqemu-system-aarch64.so # QEMU binary renamed .so for APK packaging
-├── libslirp.so # SLIRP networking (soname patched from .so.0 via patchelf)
-├── libpodroid-bridge.so # PTY↔serial bridge binary renamed .so for APK packaging
-└── libtermux.so # Termux terminal JNI (custom-built with 16KB page alignment)
-```
+
+**Note:** All native binaries require 16KB page alignment (`-Wl,-z,max-page-size=16384`) — mandatory on Android 13+.
+
+| File | What it is |
+|---|---|
+| `libqemu-system-aarch64.so` | QEMU TCG emulator (PIE executable, 16KB aligned) |
+| `libpodroid-bridge.so` | PTY ↔ serial relay (PIE executable, 16KB aligned) |
+| `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16KB pages) |
+| `libslirp.so` | SLIRP user-mode networking (statically linked into QEMU) |
---
@@ -168,6 +190,7 @@ Android App
| Item | Value |
|------|-------|
+| podroidKernelVersion | Set in `gradle.properties` (controls kernel source version) |
| QEMU binary | `libqemu-system-aarch64.so` in `nativeLibraryDir` |
| Kernel | `filesDir/vmlinuz-virt` |
| Initrd | `filesDir/initrd.img` |
@@ -335,13 +358,13 @@ arrow(final): if mod==1 → "\x1b[$final" else → "\x1b[1;$mod$final"
- **Purpose**: Relay PTY (Termux-allocated) ↔ `serial.sock` (QEMU serial)
- **Arguments**: `bridge_exe serial_sock_path ctrl_sock_path`
-- **STDERR silenced** immediately via `dup2(/dev/null, STDERR_FILENO)` — bridge runs as TerminalSession subprocess so stderr IS the PTY
-- **`cfmakeraw()`** on own stdin (VM's getty handles echo/line editing)
-- **serial.sock retry**: 50 attempts × 200ms = 10s max
-- **ctrl.sock retry**: 50 × 100ms = 5s max; lazy reconnect on each SIGWINCH if not yet connected
-- **`filter_queries()`**: Intercepts `ESC[18t` / `ESC[19t` (xterm window size queries from busybox `less`), responds locally with fake size, strips bytes — prevents garbage in terminal output
-- **`send_resize()`**: On SIGWINCH, reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock
-- **select timeout**: 50ms (allows SIGWINCH handling without blocking)
+- **STDERR silenced** immediately via `dup2(/dev/null, STDERR_FILENO)` — bridge runs as TerminalSession subprocess so stderr IS the PTY.
+- **`cfmakeraw()`** on own stdin (VM's getty handles echo/line editing).
+- **serial.sock retry**: 50 attempts × 200ms = 10s max.
+- **ctrl.sock retry**: 50 × 100ms = 5s max; lazy reconnect on each SIGWINCH if not yet connected.
+- **`filter_queries()`**: Intercepts `ESC[18t` / `ESC[19t` (xterm window size queries from busybox `less`), responds locally with fake size (using `TIOCGWINSZ`), strips bytes — prevents garbage in terminal output.
+- **`send_resize()`**: On SIGWINCH, reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock.
+- **select timeout**: 50ms (allows SIGWINCH handling without blocking).
---
@@ -383,40 +406,39 @@ dropbear ncurses-terminfo-base musl-locales
## Build Commands
-```bash
-# Build initramfs (Docker required, ~3min first time, cached after)
-./build-all.sh initramfs
-# → app/src/main/assets/vmlinuz-virt + initrd.img
+All components are coordinated by `build-all.sh`:
-# Build QEMU + bridge (Docker, ~30min first time)
-./build-all.sh qemu
-# → app/src/main/jniLibs/arm64-v8a/{libqemu-system-aarch64.so,libslirp.so,libpodroid-bridge.so}
-# → app/src/main/assets/qemu/
-
-# Build Termux JNI lib (local NDK)
-./build-all.sh termux
-# → app/src/main/jniLibs/arm64-v8a/libtermux.so
+```bash
+./build-all.sh kernel # Build custom kernel only (podroid_kernel.config, ~5–10 min)
+./build-all.sh initramfs # Build custom kernel + Alpine initramfs (~10–15 min total)
+./build-all.sh qemu # Build QEMU + podroid-bridge via Docker (~30 min first time)
+./build-all.sh termux # Build libtermux.so via local NDK (16KB page alignment)
+./build-all.sh apk # Build Android APK via Gradle
+./build-all.sh all # Build everything
+./build-all.sh deploy # Full deploy workflow
+./build-all.sh test # Boot validation: deploys APK, polls console.log for "Ready!"
+```
-# Build APK
+**APK only:**
+```bash
./gradlew assembleDebug
+./gradlew installDebug
+```
-# Uninstall + install (debug package)
-adb uninstall com.excp.podroid.debug
-adb install -r app/build/outputs/apk/debug/app-debug.apk
-
-# Fast bridge rebuild (without full Docker QEMU build)
+**Fast bridge rebuild (without full Docker QEMU build):**
+```bash
NDK=$HOME/Android/Sdk/ndk/$(ls ~/Android/Sdk/ndk/ | tail -1)
CC=$NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android28-clang
$CC --sysroot=$NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
-target aarch64-linux-android28 -fPIE -pie -Wl,-z,max-page-size=16384 \
podroid-bridge.c -o app/src/main/jniLibs/arm64-v8a/libpodroid-bridge.so
./gradlew :app:installDebug
+```
-# Full rebuild + deploy
-./build-all.sh all
-
-# Automated boot test
-./build-all.sh test
+**Monitor VM boot:**
+```bash
+adb logcat -s PodroidQemu
+adb shell run-as com.excp.podroid.debug cat files/console.log
```
**Workflow**: