Skip to content

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

chore: post-virtio-console cleanup — dead code, stale docs, leftovers

ExTv4f3f0d01cc1e
diff --git a/CLAUDE.md b/CLAUDE.md
index 157423b..f954961 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,12 +44,17 @@ The app uses debug build for all releases (release signing not configured). Nati
```
Terminal UI (Compose)
↕ TerminalSession (Termux JNI)
-libpodroid-bridge.so ←→ serial.sock / ctrl.sock ←→ QEMU ←→ ttyAMA0 (Alpine)
+libpodroid-bridge.so ←→ terminal.sock + ctrl.sock ←→ QEMU ←→ hvc0 + hvc1 (Alpine)
+
+PodroidQemu (boot monitor) ←→ serial.sock ←→ QEMU ←→ ttyAMA0 (boot log only)
```
-- **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`
+The terminal layer uses three QEMU Unix sockets, each with a single role:
+
+- **`terminal.sock`** ↔ virtio-console `/dev/hvc0` — primary terminal I/O. getty runs on hvc0; `libpodroid-bridge.so` relays it to a Termux PTY.
+- **`ctrl.sock`** ↔ virtio-console `/dev/hvc1` — resize signal channel. Bridge debounces SIGWINCH bursts (~25 per keyboard slide) and writes a single `RESIZE rows cols\n`; the resize daemon in `init-podroid` stty's hvc0.
+- **`serial.sock`** ↔ PL011 `/dev/ttyAMA0` — boot log sink. `PodroidQemu.monitorBootSerial` connects for the lifetime of the VM, streaming kernel + init output into `console.log` and the boot-stage detector. No bridge handoff.
+- **`qmp.sock`** — runtime control for port forwarding (`QmpClient` sends `netdev_add` / `netdev_remove`).
### Key Components
@@ -57,7 +62,7 @@ libpodroid-bridge.so ←→ serial.sock / ctrl.sock ←→ QEMU ←→ tty
**`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.
+**`podroid-bridge.c`** — native C binary (compiled to `libpodroid-bridge.so`) that Termux runs as a subprocess. Bidirectionally relays PTY ↔ `terminal.sock`, and writes `RESIZE rows cols\n` to `ctrl.sock` after a 200 ms-debounced SIGWINCH burst (so a single keyboard-slide animation produces one shell prompt redraw, not 25).
**`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`.
@@ -76,7 +81,7 @@ Single-activity Compose app: `NavGraph.kt` routes `setup → home → terminal /
| 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) |
+| `libpodroid-bridge.so` | PTY ↔ virtio-console 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) |
@@ -85,8 +90,9 @@ These are executed directly via `ProcessBuilder` / `TerminalSession`, not loaded
## 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`
+- `-serial unix:serial.sock` (boot log) + a virtio-serial-pci bus carrying two virtconsoles: `terminal.sock` (org.podroid.term, hvc0) and `ctrl.sock` (org.podroid.ctrl, hvc1)
+- `-qmp unix:qmp.sock` for runtime port-forward changes
+- RAM, CPU count, and user-editable extras (`-cpu`, `-accel`, RNG, etc.) 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`)
@@ -106,6 +112,17 @@ All tuning applies under software emulation only — KVM is impossible without r
- 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
+- QEMU 11.0.0-rc2 cross-compiled against NDK r27c with three minimum patches:
+ `--disable-plugins` (uftrace.c uses `timespec_get`, absent from Bionic),
+ empty `contrib/ivshmem-{server,client}/meson.build` (use shm_open we don't ship),
+ `-include shm_shim.h` declarations + a `libshm.a` stub implementing
+ `shm_open`/`shm_unlink` via `memfd_create` (NDK API-28 stubs lack them).
+- Custom Linux 6.6.87 kernel: arm64 defconfig + `podroid_kernel.config` (modules)
+ + `forced_builtin.config` (=y for IPV6 / BRIDGE / NF_TABLES / NFT_COMPAT /
+ MASQUERADE family / VETH / TUN / OVERLAY_FS / FUSE_FS).
+- A build-time loop greps the resolved `.config` and **fails the build** if
+ any of those critical options isn't `=y`. This guards against silent
+ Kconfig demotions caused by unmet tristate deps (e.g. CONFIG_BRIDGE caps
+ out at IPV6's strength).
**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 2affb2d..281367a 100644
--- a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt
+++ b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt
@@ -2,19 +2,25 @@
* Podroid - Rootless Podman for Android
* Copyright (C) 2024 Podroid contributors
*
- * QEMU engine for Podroid. Manages the VM lifecycle and exposes two Unix
+ * QEMU engine for Podroid. Manages the VM lifecycle and exposes three Unix
* sockets for the terminal layer:
*
- * serial.sock — QEMU serial chardev (ttyAMA0 in the VM). The podroid-bridge
- * binary connects here for bidirectional terminal I/O.
+ * serial.sock — QEMU -serial (ttyAMA0 in the VM). Boot-log sink only:
+ * PodroidQemu's monitorBootSerial coroutine connects here
+ * for the lifetime of the VM, streaming kernel messages
+ * and init-podroid boot stages into console.log + the
+ * in-memory ring buffer used by detectBootStage().
*
- * ctrl.sock — QEMU virtio-console chardev (hvc0 in the VM). The bridge
- * writes "RESIZE rows cols\n" here on SIGWINCH; the VM daemon
- * calls stty on ttyAMA0 which triggers SIGWINCH in the VM.
+ * terminal.sock — QEMU virtio-console (/dev/hvc0 in the VM). Primary
+ * terminal I/O. getty runs on hvc0; the podroid-bridge
+ * binary connects here for bidirectional shell I/O. Fully
+ * independent of serial.sock, so no socket hand-off.
*
- * Boot monitoring: PodroidQemu connects to serial.sock and reads until the VM
- * reaches the "Ready" stage (or until releaseSerial() is called). The bridge
- * then takes over the connection for interactive terminal use.
+ * ctrl.sock — QEMU virtio-console (/dev/hvc1 in the VM). Resize signal
+ * channel only. Bridge writes "RESIZE rows cols\n" on
+ * SIGWINCH (debounced by RESIZE_DEBOUNCE_MS); the resize
+ * daemon in init-podroid stty's hvc0 to deliver SIGWINCH
+ * to the foreground TUI inside the VM.
*/
package com.excp.podroid.engine
@@ -108,11 +114,13 @@ class PodroidQemu @Inject constructor(
}
/**
- * Release the boot-monitoring serial connection so podroid-bridge can connect.
+ * Close the boot-monitoring serial socket. Called from cleanup() when the
+ * VM stops; not used as a hand-off trigger any more (bridge has its own
+ * socket).
*/
fun releaseSerial() {
val sock = bootSocket ?: return
- Log.d(TAG, "Releasing boot monitor socket")
+ Log.d(TAG, "Closing boot monitor socket")
bootSocket = null
try {
// Signal EOF to the monitor loop
@@ -124,27 +132,6 @@ class PodroidQemu @Inject constructor(
}
}
- /**
- * Replay the portion of boot serial output that arrived after "Ready!" into
- * a freshly created terminal emulator.
- */
- private fun replayBootOutput(sess: TerminalSession) {
- val console = _consoleText.value
- val readyIdx = console.indexOf("Ready!")
- if (readyIdx < 0) return
- val lineEnd = console.indexOf('\n', readyIdx)
- if (lineEnd < 0) return
- val postReady = console.substring(lineEnd + 1)
- if (postReady.isEmpty()) return
- val bytes = postReady.toByteArray(Charsets.UTF_8)
- try {
- sess.emulator?.append(bytes, bytes.size)
- Log.d(TAG, "Replayed ${bytes.size}B of post-Ready output to emulator")
- } catch (e: Exception) {
- Log.w(TAG, "Could not replay boot output: ${e.message}")
- }
- }
-
private fun autoStartBridge() {
android.os.Handler(android.os.Looper.getMainLooper()).post {
if (_terminalSession != null) return@post
@@ -196,7 +183,6 @@ class PodroidQemu @Inject constructor(
)
sess.updateSize(80, 24)
- replayBootOutput(sess)
_terminalSession = sess
_terminalSessionAttached = true
@@ -322,9 +308,12 @@ class PodroidQemu @Inject constructor(
}
/**
- * Connects to serial.sock and reads boot output until:
- * - The "Ready" stage is detected, or
- * - releaseSerial() is called (bootSocket closed externally), or
+ * Connects to serial.sock and streams kernel + init-podroid output for the
+ * lifetime of the VM. Writes the bytes to console.log and pushes the
+ * latest tail into the consoleText flow used by the diagnostic exporter
+ * and the boot-stage detector. Stops when:
+ * - releaseSerial() is called during cleanup() (VM stopping), or
+ * - QEMU itself exits, or
* - The coroutine is cancelled.
*
* Writes all output to console.log for the test-deploy.sh validator and
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt
index 92af110..681210e 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt
@@ -6,15 +6,18 @@
*
* The bridge binary (libpodroid-bridge.so) runs as the TerminalSession
* subprocess. Termux allocates a real PTY for it; the bridge relays that
- * PTY to QEMU's serial Unix socket. Window resize is handled properly:
+ * PTY to QEMU's virtio-console terminal.sock (= /dev/hvc0 in the VM).
+ * Window resize is handled out-of-band over a second virtio-console port:
*
* TerminalSession.updateSize(cols, rows)
* → ioctl(pty_master, TIOCSWINSZ) [Termux JNI]
* → SIGWINCH → bridge process
- * → bridge reads new size via TIOCGWINSZ
- * → writes "RESIZE rows cols\n" to ctrl.sock
- * → VM daemon calls stty on /dev/ttyAMA0
- * → Linux kernel sends SIGWINCH to VM foreground process group
+ * → bridge debounces (RESIZE_DEBOUNCE_MS, currently 200 ms) so a
+ * keyboard-slide animation collapses to one event
+ * → reads final size via TIOCGWINSZ
+ * → writes "RESIZE rows cols\n" to ctrl.sock (= /dev/hvc1 in the VM)
+ * → init-podroid resize daemon calls stty on /dev/hvc0
+ * → Linux sends SIGWINCH to the VM's foreground process group
* → nvim / htop / btop redraws correctly
*
* No reflection, no emulator injection, no sz stdin injection.
diff --git a/init-podroid b/init-podroid
index d934ab8..df5469f 100755
--- a/init-podroid
+++ b/init-podroid
@@ -62,17 +62,15 @@ hostname podroid 2>/dev/null
printf '127.0.0.1\tlocalhost podroid\n::1\tlocalhost ip6-localhost\n' > /etc/hosts
# ── Kernel modules + device nodes ────────────────────────────────────────────
+# Bridge / netfilter / overlay / fuse / virtio are =y in our custom kernel
+# (see Dockerfile forced_builtin.config), so only the few that legitimately
+# remain modular are loaded here. The check on /lib/modules still guards
+# against a kernel built without CONFIG_MODULES.
boot_stage "Loading kernel modules..."
_kver=$(uname -r)
if [ -d "/lib/modules/$_kver" ]; then
depmod -a 2>/dev/null
- for _mod in \
- virtio_net virtio_blk fuse tun veth \
- bridge br_netfilter overlay \
- xt_addrtype xt_conntrack xt_nat xt_mark xt_comment \
- nf_nat nf_conntrack nf_conntrack_netlink nfnetlink \
- ip_tables ip6_tables ip6table_nat \
- 9p 9pnet 9pnet_virtio; do
+ for _mod in 9p 9pnet 9pnet_virtio; do
modprobe "$_mod" 2>/dev/null
done
fi
@@ -188,7 +186,6 @@ export CONTAINERS_STORAGE_CONF=/etc/containers/storage.conf
export CONTAINERS_REGISTRIES_CONF=/etc/containers/registries.conf
dmesg -n 1 2>/dev/null
-stty rows 24 cols 80 -ixon -ixoff -iexten 2>/dev/null
trap 'podman stop -a -t 5 2>/dev/null; podman network prune -f 2>/dev/null; sync' TERM INT HUP
# ── Resize daemon (reads RESIZE msgs from hvc1, applies to hvc0 terminal) ─────
diff --git a/podroid-bridge.c b/podroid-bridge.c
index d464482..3914aa2 100644
--- a/podroid-bridge.c
+++ b/podroid-bridge.c
@@ -18,7 +18,9 @@
* SIGPIPE — ignored; EPIPE on write = EOF, handled in main loop
* SIGINT — graceful shutdown
* SIGTERM — graceful shutdown
- * SIGWINCH — async flag, processed in select() loop; fires send_resize() immediately
+ * SIGWINCH — async flag, debounced in the select() loop. Each signal just
+ * refreshes a timestamp; send_resize() fires once after the
+ * burst has been quiet for RESIZE_DEBOUNCE_MS.
*
* Args: <terminal.sock> <ctrl.sock>
*/
diff --git a/skill.md b/skill.md
index 739d382..0e9376c 100644
--- a/skill.md
+++ b/skill.md
@@ -43,26 +43,25 @@ Android App
├── 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 (port forwarding)
+│ ├── serial.sock — ttyAMA0 boot-log sink; monitor stays connected for VM lifetime
+│ ├── terminal.sock — virtio-console hvc0; primary shell I/O for podroid-bridge
+│ ├── ctrl.sock — virtio-console hvc1; debounced RESIZE messages from bridge
+│ └── qmp.sock — QEMU Machine Protocol for runtime control (port forwarding)
└── Compose UI
└── Screens: Setup → Home → Terminal / Settings
```
-### VM Boot Sequence (critical — read carefully)
-1. QEMU starts, creates `serial.sock` (unix socket, server, single-client)
-2. **Boot monitor** (`PodroidQemu.monitorBootSerial`) connects first to `serial.sock`, streams output to `console.log` and parses `boot_stage` strings for the Android UI
-3. `init-podroid` Phase 1 (running in initramfs): mounts virtio-blk as ext4, creates overlayfs (`lowerdir=/`, `upperdir=/mnt/persist/upper`), `chroot /mnt/overlay /init --main`
-4. `init-podroid` Phase 2 (`--main`): kernel modules → networking → containers → SSH → getty on ttyAMA0
-5. Phase 2 emits `boot_stage "Ready!"` then **sleeps 2 seconds** (critical — lets boot monitor finish reading "Ready!" before bridge steals the single-client socket)
-6. `detectBootStage("Ready!")` fires → `_state = Running` → `autoStartBridge()`
-7. **`releaseSerial()`** closes boot monitor socket (`shutdownInput + shutdownOutput + close`)
-8. **500ms delay** then `TerminalSession` launched with `libpodroid-bridge.so` as subprocess
-9. Bridge binary connects to `serial.sock`, relays PTY ↔ serial bidirectionally
+### VM Boot Sequence
+1. QEMU starts and binds all four sockets (`server,nowait` so it doesn't block on a connection).
+2. **Boot monitor** (`PodroidQemu.monitorBootSerial`) connects to `serial.sock` and streams everything kernel and init-podroid write to ttyAMA0 into `console.log` + the in-memory tail used by `detectBootStage`. Stays connected for the lifetime of the VM (no hand-off).
+3. `init-podroid` Phase 1 (initramfs): mounts virtio-blk as ext4, creates overlayfs (`lowerdir=/`, `upperdir=/mnt/persist/upper`), pivots via `/bin/busybox chroot /mnt/overlay /init --main`.
+4. `init-podroid` Phase 2 (`--main`): kernel modules (just `9p*` now — bridge / netfilter / overlay / fuse / virtio are all built-in) → networking → containers → SSH → starts getty on `/dev/hvc0`. Resize daemon listens on `/dev/hvc1`.
+5. Phase 2 emits `boot_stage "Ready!"` immediately before launching the getty loop — no `sleep 2` is needed any more because the bridge connects to a different socket.
+6. `detectBootStage("Ready!")` fires → `_state = Running` → `autoStartBridge()` posts to the main thread.
+7. `TerminalSession` launches `libpodroid-bridge.so` with `terminal.sock` + `ctrl.sock` as args. Bridge connects directly; no socket hand-off, no 500 ms guard delay.
-### Single-Client Socket Constraint
-`serial.sock` is QEMU `server,nowait` — only ONE client at a time. Boot monitor connects first. `releaseSerial()` frees it. Bridge has a 50×200ms retry loop. The `sleep 2` in init-podroid and the 500ms `postDelayed` in `autoStartBridge()` are both critical timing guards.
+### No socket hand-off
+The old PL011 path used a single-client `serial.sock` shared by the boot monitor and the bridge, which forced a `releaseSerial()` + delay dance. With the virtio-console split that constraint is gone. `releaseSerial()` only runs during `cleanup()` on VM stop now.
---
@@ -81,7 +80,7 @@ All tuning applies under software emulation only — KVM is impossible without r
- 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.
+- Currently `-fPIC -DANDROID` only (no LTO / -O3) — those previously caused link failures with QEMU 11.0.0-rc2 + NDK r27c. Three minimum patches make the build clean: `--disable-plugins`, empty `contrib/ivshmem-{server,client}/meson.build` stubs, and an `-include shm_shim.h` + `libshm.a` (memfd_create-backed) to satisfy `shm_open`/`shm_unlink`.
---
@@ -92,7 +91,7 @@ All tuning applies under software emulation only — KVM is impossible without r
/
├── app/ # Android application module
├── init-podroid # VM init script (baked into initrd.img as /init)
-├── podroid-bridge.c # Native PTY↔serial relay (compiled to libpodroid-bridge.so)
+├── podroid-bridge.c # Native PTY↔virtio-console relay (compiled to libpodroid-bridge.so)
├── Dockerfile # Unified multi-stage: downloader → rootfs-builder → packer → qemu-builder → final
├── build-all.sh # Unified build+deploy script
├── gradle.properties # podroidQemuVersion=11.0.0-rc2
@@ -180,7 +179,7 @@ All tuning applies under software emulation only — KVM is impossible without r
| 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) |
+| `libpodroid-bridge.so` | PTY ↔ virtio-console 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) |
@@ -195,8 +194,9 @@ All tuning applies under software emulation only — KVM is impossible without r
| Kernel | `filesDir/vmlinuz-virt` |
| Initrd | `filesDir/initrd.img` |
| Storage image | `filesDir/storage.img` (ext4, sparse) |
-| serial.sock | `filesDir/serial.sock` — ttyAMA0, single-client, boot monitor then bridge |
-| ctrl.sock | `filesDir/ctrl.sock` — hvc0, bridge writes `RESIZE rows cols\n` |
+| serial.sock | `filesDir/serial.sock` — ttyAMA0, boot-log only; monitor stays connected for VM lifetime |
+| terminal.sock | `filesDir/terminal.sock` — virtio-console hvc0; primary terminal for podroid-bridge |
+| ctrl.sock | `filesDir/ctrl.sock` — virtio-console hvc1; bridge writes debounced `RESIZE rows cols\n` |
| qmp.sock | `filesDir/qmp.sock` |
| VM IP | 10.0.2.15/24 (SLIRP) |
| Gateway | 10.0.2.2 |
@@ -206,8 +206,8 @@ All tuning applies under software emulation only — KVM is impossible without r
| Default CPUs | 1 (range: 1, 2, 4, 6, 8) |
| Default font size | 20sp |
| Default storage | 2 GB (range: 2–64 GB) |
-| QEMU machine | `-M virt,gic-version=3 -cpu max -accel tcg,thread=multi,tb-size=256` |
-| Kernel cmdline | `console=ttyAMA0 loglevel=1 quiet androidip=<ip> [ssh=1]` |
+| QEMU machine | `-M virt,gic-version=3 -smp <cpus> -m <ramMb>`; tunable extras (`-cpu`, `-accel`, RNG, etc.) come from the user-editable Settings field |
+| Kernel cmdline | `console=ttyAMA0 <user-extras> androidip=<ip> [ssh=1]` (default user-extras: `loglevel=1 quiet mitigations=off elevator=mq-deadline`) |
---
@@ -228,7 +228,7 @@ These exact strings are emitted by `init-podroid` and matched by `PodroidQemu.de
Also detected: `Mounting storage...`, `Booting kernel...` (emitted by PodroidQemu itself, not init-podroid).
-**Critical**: After `boot_stage "Ready!"`, init-podroid does `sleep 2` before starting the getty loop. This is intentional — gives the boot monitor time to read "Ready!" before the single-client serial.sock becomes available to the bridge.
+No `sleep 2` after `Ready!` is needed any more — the boot monitor stays on `serial.sock` while the bridge connects to a separate `terminal.sock`, so there's no socket hand-off race to guard.
---
@@ -238,41 +238,38 @@ Also detected: `Mounting storage...`, `Booting kernel...` (emitted by PodroidQem
```bash
# Located AFTER the `if [ "$1" = "--main" ]; then ... fi` block (at end of file)
mount proc/sys/dev
-depmod -a && modprobe virtio_blk # must load virtio_blk to get /dev/vda
+# virtio_blk is built-in to the custom kernel (no need to modprobe).
find /dev/vda or /dev/vdb → PERSIST_DEV
mount -t ext4 PERSIST_DEV /mnt/persist # mkfs.ext4 if needed
mkdir -p /mnt/persist/upper /mnt/persist/work /mnt/overlay
mount -t overlay overlay -o lowerdir=/,upperdir=...,workdir=... /mnt/overlay
-exec chroot /mnt/overlay /init --main
+exec /bin/busybox chroot /mnt/overlay /init --main
# FALLBACK (if overlay failed): exec /init --main ← runs without persistence
```
-**Critical bug to avoid**: The fallback at end of Phase 1 must NOT be `exec chroot /mnt/overlay /init --main` — if overlay failed, `/mnt/overlay` may not exist → kernel panic. Must be `exec /init --main`.
-
-**Critical bug to avoid**: vmlinuz-virt and modules in initrd.img MUST come from the SAME rootfs-builder Docker stage. The Dockerfile copies vmlinuz from `rootfs-builder /boot/vmlinuz-virt` (NOT from the netboot downloader stage). Mismatched kernel/modules = `modprobe virtio_blk` silently skipped = no block device = no storage mount = kernel panic.
+**Critical bug to avoid**: the chroot must use `/bin/busybox chroot` explicitly. Phase 1 runs before busybox applet symlinks are installed, so a bare `chroot` is not in PATH and the script exits with code 127, which the kernel interprets as init dying → panic on every boot.
### Phase 2 (`--main` flag, runs inside chroot overlay)
```bash
boot_stage "Initializing system..."
# mount proc/sys/devtmpfs/devpts/tmpfs/cgroup2
boot_stage "Loading kernel modules..."
-# depmod + modprobe (virtio_net, virtio_blk, fuse, tun, veth, bridge, overlay, ...)
+# Most networking/fs is =y in our custom kernel; only 9p* are still =m.
boot_stage "Waiting for network..."
-# wait for eth0 with IP (loop), set up resolv.conf (8.8.8.8, 1.1.1.1)
-boot_stage "Network found" or boot_stage "Network found" (after timeout)
+# wait for eth0 with IP (loop), set up resolv.conf (10.0.2.3, 8.8.8.8, 1.1.1.1)
+boot_stage "Network found"
boot_stage "Configuring containers..."
# sysctl, /etc/subuid, containers.conf, storage.conf, registries.conf
boot_stage "Starting SSH..." # only if ssh=1 in kernel cmdline
# dropbearkey + dropbear
boot_stage "Almost ready..."
-# MOTD generation with internet check, bash profile + aliases
-# resize daemon: background loop reads RESIZE from /dev/hvc0, calls stty on /dev/ttyAMA0
+# MOTD generation with async internet check, bash profile + aliases
+# resize daemon (background): reads RESIZE from /dev/hvc1, runs stty on /dev/hvc0
# write podroid-login wrapper: #!/bin/bash; cat /etc/motd; exec script -q -c 'exec /bin/bash --login' /dev/null
boot_stage "Ready!"
rm -f /run/boot_stage
-sleep 2 # ← CRITICAL: let boot monitor read "Ready!" before bridge steals socket
while true; do
- /sbin/getty -n -l /usr/local/bin/podroid-login 0 ttyAMA0 xterm-256color
+ /sbin/getty -n -l /usr/local/bin/podroid-login 0 hvc0 xterm-256color
sleep 1
done
```
@@ -295,15 +292,15 @@ Keyboard → TerminalView → TerminalSession.write() → PTY master fd
↓
podroid-bridge stdin (PTY slave)
↓
- serial.sock → ttyAMA0 in VM
-VM output → ttyAMA0 → serial.sock → bridge stdout → PTY slave → TerminalEmulator → TerminalView
+ terminal.sock → /dev/hvc0 in VM
+VM output → /dev/hvc0 → terminal.sock → bridge stdout → PTY slave → TerminalEmulator → TerminalView
Resize → TerminalView.updateSize() → TIOCSWINSZ on PTY → SIGWINCH → bridge
- → bridge reads TIOCGWINSZ
+ → bridge debounces 200 ms → TIOCGWINSZ
→ writes "RESIZE rows cols\n" to ctrl.sock
- → VM daemon reads /dev/hvc0
- → stty rows N cols M < /dev/ttyAMA0
+ → init resize daemon reads /dev/hvc1
+ → stty rows N cols M < /dev/hvc0
→ Linux SIGWINCH to VM fg process group
-Mouse → TerminalView touch handler → PTY → bridge → serial → VM
+Mouse → TerminalView touch handler → PTY → bridge → terminal.sock → VM
```
### PodroidQemu Key Methods
@@ -356,15 +353,16 @@ arrow(final): if mod==1 → "\x1b[$final" else → "\x1b[1;$mod$final"
## podroid-bridge.c
-- **Purpose**: Relay PTY (Termux-allocated) ↔ `serial.sock` (QEMU serial)
-- **Arguments**: `bridge_exe serial_sock_path ctrl_sock_path`
+- **Purpose**: Relay PTY (Termux-allocated) ↔ `terminal.sock` (QEMU virtio-console / hvc0).
+- **Arguments**: `bridge_exe terminal_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 (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).
+- **terminal.sock retry**: 50 attempts × 200 ms = 10 s max.
+- **ctrl.sock retry**: 50 × 100 ms = 5 s max; lazy reconnect on each SIGWINCH if not yet connected.
+- **`send_resize()`**: reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock.
+- **SIGWINCH debounce**: every signal just refreshes a `clock_gettime(CLOCK_MONOTONIC)` timestamp; the actual `send_resize()` only fires once the burst has been quiet for `RESIZE_DEBOUNCE_MS` (200 ms). Collapses the ~25 per-frame layout changes during an Android keyboard slide into a single shell prompt redraw.
+- **select timeout**: 50 ms — wakes the loop frequently enough to fire the debounced resize on schedule.
+- The old `filter_queries()` intercept (`ESC[18t`/`ESC[19t` xterm size queries) is gone — virtio-console reports real `TIOCGWINSZ` inside the guest, so apps don't need the workaround.
---