Skip to content

Apple's open-source XNU kernel on Android phones: its own loader and drivers, Metal on the Adreno. Runs from RAM; a reboot gives the phone back to Android.

C

tools, devices, docs: run HakiOS from Git Bash on Windows, and on this redwood unit

shimoku2671c88b03e8
diff --git a/devices/poco-x5-pro/pull-firmware-root.sh b/devices/poco-x5-pro/pull-firmware-root.sh
new file mode 100644
index 0000000..3baea8a
--- /dev/null
+++ b/devices/poco-x5-pro/pull-firmware-root.sh
@@ -0,0 +1,36 @@
+#!/bin/bash
+# pull-firmware.sh, through root. On some ROMs of this phone (seen on a redwood unit running a
+# spoofed-brand KernelSU build) /vendor/firmware_mnt is a vfat mount owned by system with
+# fmask=0337, and /vendor/firmware is not readable by the adb shell user either: the plain
+# `adb pull` of pull-firmware.sh gets nothing ("not on the phone" for every file) although every
+# file is there. This does the same pull by way of su: the firmware is copied, under root, to a
+# world-readable staging directory in /data/local/tmp, pulled from there, and the staging directory
+# is removed again. Nothing on the phone is changed. Needs the phone in Android with adb and a root
+# that answers `su -c` (Magisk, KernelSU).
+#
+# The layout it leaves is pull-firmware.sh's: fw-gpu/, fw-wifi/, fw-audio/, fw-haptic/, fw-modem/
+# (modem.* and image/, the modem's own files for TFTP). Camera firmware is not pulled: its files
+# carry the first phone's renamed names and are not needed for the modem or the network.
+set -e
+cd "$(dirname "$0")/../.."
+S=/data/local/tmp/fw
+adb get-state >/dev/null
+adb shell "su -c 'sh -c \"
+S=$S; rm -rf \$S; mkdir -p \$S/gpu \$S/wifi \$S/audio \$S/haptic \$S/modem
+cp /vendor/firmware/a660_gmu.bin /vendor/firmware/a660_sqe.fw /vendor/firmware/a660_zap.* \$S/gpu/ 2>/dev/null
+cp /vendor/firmware_mnt/image/wpss.* \$S/wifi/
+cp /vendor/firmware_mnt/image/adsp.* \$S/audio/
+cp /vendor/firmware/aw8697_haptic.bin \$S/haptic/
+cp /vendor/firmware_mnt/image/modem.* \$S/modem/
+cp -r /vendor/firmware_mnt/image \$S/modem/
+chmod -R a+rX \$S\"'"
+rm -rf fw-stage
+adb pull "$S" fw-stage >/dev/null
+rm -rf fw-gpu fw-wifi fw-audio fw-haptic fw-modem
+mv fw-stage/gpu fw-gpu; mv fw-stage/wifi fw-wifi; mv fw-stage/audio fw-audio
+mv fw-stage/haptic fw-haptic; mv fw-stage/modem fw-modem; rmdir fw-stage
+adb shell "su -c 'rm -rf $S'"
+for d in fw-gpu fw-wifi fw-audio fw-haptic fw-modem fw-modem/image; do
+ echo "pull-firmware-root.sh: $d: $(ls -1 "$d" | wc -l | tr -d ' ') files"
+done
+echo "pull-firmware-root.sh: done; Wi-Fi also wants fw-wifi/mac (the radio's address) and fw-wifi/network (the network's name and passphrase)"
diff --git a/docs/net-review.md b/docs/net-review.md
new file mode 100644
index 0000000..0eb8129
--- /dev/null
+++ b/docs/net-review.md
@@ -0,0 +1,139 @@
+# HakiOS — network stack review
+
+A read-level audit of the networking code: the `en0`/`en1` data paths, the links behind them,
+and the Apple80211 control plane iOS talks to. The goal was to find real correctness bugs and to
+map what is genuinely left to do. No build or device run was part of this pass (done on a Windows
+host); every finding is from reading the source, with file and line references so each can be
+checked.
+
+## Scope
+
+Reviewed in full:
+
+| File | What it is |
+|---|---|
+| `xnu/files/bsd/sys/hakios.net.h` | the link ⇄ interface contract |
+| `xnu/files/bsd/dev/hakios.net.c` | `enN`: the Ethernet-looking interface on the kernel KPI |
+| `xnu/files/bsd/dev/hakios.virtio_net.c` | the QEMU virtio-net link behind `en0` |
+| `xnu/files/bsd/dev/hakios.cell.c` | `en1`: the modem's IP packets as Ethernet (ARP/DHCP in kernel) |
+| `xnu/files/bsd/dev/hakios.ipa.c` | the IPA/GSI data path (rings, endpoints, tables) |
+| `xnu/files/bsd/dev/hakios.apple80211.c` | the Apple80211 ioctl/event surface for `wifid` |
+| `xnu/files/bsd/dev/hakios.sta.c` | the station boundary (scan/join/leave serialization) |
+| `wifi/lx/src/lx_80211.c` | the ath11k port's boundary: beacon parse, scan results, join |
+
+Not reviewed line-by-line this pass: `hakios.wifi.c` (DSP/subsystem bring-up — the radio works
+today), `hakios.mpss.c` and `hakios.qmi.c` (the modem; the in-progress cellular registration lives
+here — see the roadmap below), and the non-network virtio devices.
+
+## Bottom line
+
+**The core data paths are correct and defensively written. No confident, reachable correctness bug
+was found in the reviewed code.** Bounds are checked at the trust boundaries (user space via
+`copyin`/`copyout`, and over-the-air beacon data), ring invariants are maintained correctly, and
+the cache is synchronised around every DMA buffer. The items below are latent portability concerns
+and optional hardening — not live bugs on the POCO X5 Pro.
+
+## What was verified correct (not just "looks fine")
+
+- **virtio-net rings** (`hakios.virtio_net.c`): the split-queue handling is right. The receive
+ queue is primed with all 64 buffers and `avail->idx` seeded to `QUEUE_SIZE` (`queue_make`,
+ line 155); reclaim/refill use `% QUEUE_SIZE` masking with proper `dmb ish` barriers around the
+ `avail->idx` publish (lines 188–192, 213–215). Transmit reclaims completed buffers before
+ grabbing a free one and drops cleanly when full (lines 174–180).
+
+- **IPA GSI receive invariant** (`hakios.ipa.c`): the "at most `slots-1` outstanding" rule is held
+ end to end. Priming posts `slots-1` buffers (line 859), and `receive_event` consumes the buffer
+ at `done % slots`, then posts the *previously free* buffer at `next % slots` (lines 655–695) — so
+ the just-read buffer becomes the new free slot and is never re-posted while still being read. The
+ off-by-one fixed in commit `03a098b` is correctly in place.
+
+- **QMAP de-framing** (`hakios.ipa.c` `receive_event`, lines 671–689): every field is bounded —
+ `at + 4 <= length`, `at + 4 + packet > length` break, and `pad > packet` reject — before handing
+ `packet - pad` bytes up. No over-read.
+
+- **In-kernel ARP/DHCP** (`hakios.cell.c`): the DHCP reply builder stays inside its buffer. Worst
+ case option set is ~42 bytes from `bootp+240`; the 300-byte pad floor keeps the frame ≤ the
+ 346-byte `reply[]` (lines 142–221). The request parser bounds `ihl` and the options loop against
+ the frame end (lines 126–162).
+
+- **Apple80211 user boundary** (`hakios.apple80211.c`): `give()` always clamps `copyout` to
+ `req_len` (line 239); `set_join`/`set_scan` validate `ssid_length` and `key_length` against the
+ destination before `memcpy` (lines 477, 534, 543–549). Join buffers are wiped with `memset_s`
+ before free (lines 560–565) so passphrases don't linger.
+
+- **Beacon parse** (`wifi/lx/src/lx_80211.c`): `element()` (line 525) walks TLVs with both
+ `at + 2 <= length` and `at + 2 + elements[at+1] <= length` guards. The SSID copy clamps to the
+ 32-byte field (`name[1] <= sizeof(network->name)`, line 608) and the elements copy is gated on
+ `length - 36 <= ELEMENTS_MOST` (lines 597, 567). The single caller guards `skb->len >= 36` before
+ calling `heard()` (line 908), so the `length - 36` subtraction cannot underflow in practice.
+
+## Latent concerns (ranked) — not live bugs on the current phone
+
+### 1. IPA event-ring write pointer is read as 32-bit only
+
+`hakios.ipa.c`, `channel_events` (line 478):
+
+```c
+uint32_t wp = gsi_rd(EV_CNTXT(ch->ring_id, 4)), base = (uint32_t)ch->event_ring.phys, ...
+if (wp < base || wp >= base + ch->slots * ELEMENT_SIZE) { ... return 0; }
+```
+
+Both the hardware write pointer and the ring base are truncated to 32 bits. This is correct as long
+as the event ring's physical address — and the whole ring — sit in the low 4 GB, or at least do not
+straddle a 4 GB boundary. On the POCO X5 Pro the data path comes up, so today this holds. On a
+future port whose DDR layout places a GSI event ring above 4 GB, the comparison and the index math
+break silently (the "write pointer outside the ring" path, line 482).
+
+- **Risk:** medium for porting, none for the current device.
+- **Recommendation:** when porting to a new SoC, also read the high word (`EV_CNTXT(ring, 5)`) and
+ compare as 64-bit. **Do not change this blind on the working phone** — verify that reg 5 carries
+ the write-pointer high word on the target GSI revision first, because a wrong assumption here
+ would break a path that currently works. Flagged as a porting checklist item, not a patch.
+
+### 2. Defense-in-depth at the `bss` → user boundary
+
+`hakios.apple80211.c` `give_network` (lines 265–266) copies `bss->ssid_length` into the 32-byte
+`result->ssid` without a local clamp. It is safe **only because** the producer guarantees
+`ssid_length ≤ 32` (`lx_80211.c:608`, and `want_length` via the `:1586` check). That's a real
+invariant today, but it lives in a different module (the ath11k port). A one-line clamp
+(`min(ssid_length, sizeof result->ssid)`) at the consumer would make the kernel robust to a future
+change in the port without relying on it. Same reasoning for `heard()` not trusting its caller's
+`>= 36` guard.
+
+- **Risk:** none today; cheap insurance against future refactors.
+- **Recommendation:** optional hardening; apply with a build + a scan test.
+
+### 3. IPv6 asymmetry on `en1` is by design, worth a note
+
+`hakios.cell.c`: inbound IPv6 is wrapped and passed up (`cell_receive`, version 6 accepted,
+line 267), but outbound IPv6 is dropped (`cell_transmit`, counted as `not_ip4`, line 253). The
+data session is IPv4-only, so this is intentional; just confirming it's not an oversight. If an
+IPv6 PDP type is ever enabled, the transmit side needs the matching branch.
+
+## The real remaining work: cellular registration & data session
+
+This is the part the README marks "in progress," and it is **not** in the reviewed files — it's in
+`hakios.mpss.c` / `hakios.qmi.c` (QMI DPM/WDA/WDS, NAS). The data *plumbing* below it (`en1`, the
+IPA path, ARP/DHCP) is in place and reviewed-correct; what's left is the modem-side handshake that
+brings the session up so `hakios_cell_session(up=true, ...)` gets called with a real address.
+
+From the git history the current frontier is: DPM Open Port → WDA Set Data Format → WDS Bind Mux →
+Set IP Family → Start Network Interface, with registration gating the start (commits `82e0292`,
+`3b146ba`, `150d30f`). Advancing this needs **a live run log from the phone**, not source reading —
+the failures are QMI error codes and timing, visible only at runtime:
+
+```sh
+XL_SB_DELAY=8 XL_SECS=600 \
+XL_CMDLINE="... modem=1 modem_ipa_data_trace=1 net_trace=20 net_names=1" \
+./xl run
+```
+
+Send `logs/` from such a run and the cellular path can be debugged against the actual QMI exchange.
+
+## How to proceed
+
+1. The reviewed data paths are solid — no fixes needed to ship them.
+2. The two optional hardening items (§2) are safe one-liners; say the word and they go in as a
+ small, clearly-scoped patch for you to build and test.
+3. The 32-bit event-pointer item (§1) is a porting note, deliberately not a blind patch.
+4. Cellular registration is the open frontier and is log-driven — a phone run log unblocks it.
diff --git a/docs/port-pkg110.md b/docs/port-pkg110.md
new file mode 100644
index 0000000..2296f38
--- /dev/null
+++ b/docs/port-pkg110.md
@@ -0,0 +1,155 @@
+# Bring-up on the connected device (branded PKG110)
+
+Status of getting HakiOS — and the cellular path — running and debuggable on the phone attached to
+this machine. Everything below was verified on the actual device or the actual files; nothing is
+assumed.
+
+## The decisive finding: it's `redwood` / SM7325, the reference platform
+
+The connected phone reports itself as OnePlus **PKG110**, but that branding is spoofed (KernelSU +
+`rezygisk` + `tricky_store`). The device tree — which the bootloader fills and which is not spoofed
+— tells the truth:
+
+```
+/proc/device-tree/model = "redwood based Qualcomm Technologies, Inc. SM7325"
+compatible = qcom,yupik-idp qcom,yupik qcom,idp
+ro.soc.model = SM7325
+ro.product.board = redwood
+```
+
+**Same SoC (SM7325) and same board codename (`redwood`) HakiOS already targets as the POCO X5 Pro 5G.**
+This is not a new port; it is bring-up of the existing `redwood` support on this unit. No new
+`devices/<name>/` with its own SoC map, UEFI port or driver addresses is required.
+
+### SoC args verified against the hardware
+
+Pulled the phone's own `/sys/firmware/fdt` (via root) and ran `tools/soc-args.py` on it. Every
+address it produced matches the reference `devices/poco-x5-pro/soc.args`:
+
+```
+soc_ipa_base=0x1e40000 soc_gsi_base=0x1e04000 soc_ipcc=0x408000
+soc_rsc=0x18220000 soc_apps_smmu=0x15000000 soc_cmd_db=0x80860000
+soc_mpss_mem=0x8b800000 modem_ipa_fw_at=0x8b710000 soc_smem=0x80900000
+soc_imem=0x14600000 soc_ipa_stream=0x480 soc_ipa_stream_uc=0x482
+soc_pas_mpss=0x4 soc_pas_ipa=0xf soc_ipa_fw=yupik_ipa_fws
+```
+
+Only `soc_aoss` was not emitted (its node is named differently in this unit's DT); that register is
+fixed by the SoC, not the board, so the kernel's built-in SM7325 default (`0xc300000`) applies.
+**No boot-arg overrides are needed on this device.**
+
+## Firmware: pulled — after a real porting fix
+
+The stock `devices/poco-x5-pro/pull-firmware.sh` got **0 files** on this ROM. Not because anything
+is missing: `/vendor/firmware_mnt` is a vfat mount owned by `system` with `fmask=0337`, and
+`/vendor/firmware` is not readable by the adb shell user either, so a plain `adb pull` is refused
+for every file. Under root all of it is there.
+
+Fix: `devices/poco-x5-pro/pull-firmware-root.sh` — the same pull by way of `su`, through a
+world-readable staging directory in `/data/local/tmp` that is removed afterwards. Nothing on the
+phone is changed. Result, verified:
+
+| dir | contents | size |
+|---|---|---|
+| `fw-modem/` | `modem.mdt` + 28 segments, and `image/` (370 files: the modem's own files for TFTP) | 273 MB |
+| `fw-audio/` | `adsp.mdt` + b00–b36 (38) | 21 MB |
+| `fw-wifi/` | `wpss.mdt` + b00–b07 (9) | 7.3 MB |
+| `fw-gpu/` | `a660_gmu.bin`, `a660_sqe.fw`, `a660_zap.*` (7) | 137 KB |
+| `fw-haptic/` | `aw8697_haptic.bin` | 7.5 KB |
+
+(837 files, 313 MB, 10.7 s. Camera firmware is not pulled: its files carry the first phone's renamed
+names and are not needed for the modem or the network.)
+
+## Bootloader
+
+`ro.boot.flash.locked=1`, `verifiedbootstate=green`, `ro.secureboot.lockstate=locked` — but
+`tricky_store` is installed, whose whole job is to report a locked/green state while the device is
+unlocked. KernelSU cannot be installed on a genuinely locked bootloader of this class, so the
+bootloader is almost certainly **unlocked, with its lock state spoofed**. The definitive check is
+the boot test itself: `./xl enter` does a `fastboot boot`, which a truly locked device refuses.
+
+## Running from Windows (Git Bash) — what had to be solved
+
+- **No theos needed for a first boot.** `xl` falls back to `prebuilt/mach.development.bcm2837` and
+ `prebuilt/loader.efi` when nothing is built (`xl:50-53,120`): those are the `redwood` kernel and
+ loader, i.e. for this SoC. The toolchain is only needed to build a *changed* kernel (which the
+ cellular fix eventually is).
+- **The iOS system image IS needed for a modem run** (a correction: the first run proved the
+ earlier assumption wrong). With no ramdisk at all (`XL_RAMDISK=none`) the kernel panics before
+ the modem thread starts -- `Failed to mount root device @IOKitBSDInit.cpp:926` -- because the
+ modem steps run "once the root is there" (`hakios.mpss.c:6256`). And the modem's firmware is read
+ from `/fw` of the system image, which `MODEM=1 userland/build.sh` fills from `fw-modem/`
+ (`hakios.mpss.c:1045-1110`). The modem's own file systems (modemst1/2, fsc, fsg) do come from the
+ phone's UFS (`ufs=2`), but in addition to the image, not instead of it. So the project's standard
+ path applies: `sysimage/fetch.sh` (iOS 16.5 from Apple's public CDN, ~7.4 GB) and
+ `PREBUILT=1 REST=1 MODEM=1 SYSTEM=1 userland/build.sh`.
+- **Build in WSL's own ext4, not on `/mnt/d`.** `fetch.sh` relies on 7z leaving files named
+ `NAME:com.apple.decmpfs` (finished by `unzbm`); `:` is not a legal NTFS file-name character, and
+ drvfs is slow on tens of thousands of small files. A local clone in `~/hakios` plus a copy of
+ `fw-*` is used; the finished `root.apfs`/`system.apfs` are copied back to the D: checkout for `xl`.
+ Verified beforehand: 7-Zip 26 (>= 23 reads APFS), `cc` (builds `unzbm`), `numpy` present and
+ guarded anyway; `lzfse` is not on the build path (`mkapfs.py` is stdlib-only) -- note the PyPI
+ package `pyliblzfse` provides the module `liblzfse`, not `lzfse`; what the scripts import is the
+ PyPI package `lzfse`. `modem_firmware.py` validated this unit's 28 modem segments against the DTB
+ window to the byte (the last segment ends exactly at `0x9ae00000`).
+- **`flock` is absent in Git Bash**, and `xl` wraps every `fastboot` call in it (`xl:60`) and takes a
+ run lock on a file descriptor (`xl:109`). `tools/win-bin/flock` is a shim that drops the lock
+ arguments and runs the command as it is (one `xl` at a time here, so the lock buys nothing).
+ Verified for both forms. WSL2 would have the real `flock` but cannot see USB without usbipd.
+- **`python3` is real** (3.14.7, not the Store stub); `mkpayload.py` and `mkxnuimg.py` are stdlib only.
+- **The modem run payload builds locally** with the exact invocation `xl run` uses:
+ 16 809 392 bytes (the kernel is 16 809 112), the command line embedded. This is what gets staged.
+
+## The build (done, verified)
+
+In WSL's ext4 (`~/hakios`, a local clone plus `fw-*`):
+
+- `sysimage/fetch.sh`: ~9 min. `done: 2.9G rootfs, 26M cryptex, 11M App cryptex, 2.6G dyld shared
+ cache` (5.7 GB in `sysimage/`); `unzbm` built by `cc`, the LZBITMAP files finished, PingFang
+ trimmed 74 -> 26 MB.
+- `PREBUILT=1 REST=1 MODEM=1 SYSTEM=1 userland/build.sh`: ~4 min, exit 0. The small image got
+ `fw/` from `fw-gpu fw-wifi fw-haptic fw-audio` (15 files; camera absent, not needed); the modem's
+ firmware went into `system.apfs` `/fw` (`MODEM=1`, validated first).
+- `root.apfs`: 2371 blocks x 4096 = 9 711 616 bytes. `system.apfs`: 641 948 blocks x 4096 =
+ 2 629 419 008 bytes (2.5 GB). Copied to the D: checkout's `userland/` for `xl`: sizes identical
+ byte for byte, both carry the APFS container magic `NXSB` in block 0.
+
+## The run (the project's own cellular runner)
+
+With `userland/system.apfs` and `root.apfs` in the D: checkout, from the repository root in Git Bash:
+
+```sh
+XL_SB_DELAY=8 XL_END=android \
+tools/modem-cycle-win.sh "modem=1 modem_again=1 modem_buffer=0xa8000000 modem_ipa_data_trace=1 net_trace=20" 600
+```
+
+`modem-cycle-win.sh` is `tools/modem-cycle.sh` with only its PATH lines changed. The original
+prepends `tools/macos-bin`, whose `stat` and `timeout` exec `/opt/local/bin/gstat`/`gtimeout`
+(MacPorts) and whose `flock` is a Python script on `fcntl` -- none of which exist under Git Bash, so
+the original fails there on its first `fastboot` call (`xl:60`). The variant uses Git Bash's own
+GNU `stat` and `timeout` and the `tools/win-bin/flock` shim. It does `./xl enter`, `./xl ramdisk userland/system.apfs` (~80 s), then `./xl run`
+with `debug=0x8 rd=md0 hv_wdt_pet=1 bootcpu=7 cpus=8 cpufreq=1 ufs=2` plus those args, follows the
+log live, prints a modem-only summary of it, and (`XL_END=android`) returns the phone to Android.
+This is the full bring-up through registration and the data session; `modem_ipa_data_trace=1` and
+`net_trace=20` make the QMI exchange and the first frames visible -- the evidence the fix is made from.
+
+### What the first run showed
+
+Booted with no ramdisk at all, the prebuilt kernel came up, then panicked at 56 s on
+`Failed to mount root device` -- before any `mpss:` line. Not a modem failure: a missing root. That
+run did prove the bootloader unlock, the Windows fastboot driver and the whole local pipeline.
+
+## What this does to the phone — read before saying go
+
+`./xl enter` **reboots the phone out of Android** into fastboot and RAM-boots the loader; `./xl run`
+RAM-boots an experimental kernel for the session. **Nothing is flashed**: `./xl reboot` (or a
+power-cycle) brings the phone's own Android back. If the bootloader turns out to be genuinely
+locked, `fastboot boot` is refused and the phone sits in fastboot until `fastboot reboot`. It is
+your daily phone, so this step runs only on your explicit go-ahead.
+
+## After the log
+
+Read `logs/*-run.log` → find where registration / the data session stops (QMI error codes, timing)
+→ make the targeted fix in `hakios.mpss.c` / `hakios.qmi.c` → set up theos to rebuild → re-run →
+iterate. The fix is made and verified only against the real on-device log; nothing here fabricates
+a result.
diff --git a/tools/modem-cycle-win.sh b/tools/modem-cycle-win.sh
new file mode 100644
index 0000000..0dbac5e
--- /dev/null
+++ b/tools/modem-cycle-win.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+# tools/modem-cycle.sh "KERNEL ARGS" [SECS] [LOG]: wait for the phone (up to 6 h), enter the loader, upload the
+# system image, run the kernel with those args, summarize the modem's log, and leave the phone in the loader
+# (or fastboot) for the next run (XL_END=android: back to Android).
+# The phone is never flashed: the kernel is booted with "fastboot boot"-like upload through xl.
+# Windows (Git Bash) variant: identical to modem-cycle.sh except its PATH lines. The macOS shims in
+# tools/macos-bin (flock: a python script on fcntl; stat, timeout: exec /opt/local/bin/gstat, gtimeout)
+# would shadow Git Bash's own GNU stat and timeout and the flock shim in tools/win-bin, and fail.
+cd "$(dirname "$0")/.." || exit 1
+PATH=$PWD/tools/win-bin:/c/platform-tools:$PATH
+ARGS=$1; SECS=${2:-300}
+# A port's SoC addresses (devices/<name>/soc.args, made by devices/<name>/pull-soc.sh): added to the
+# kernel command line so hakios.mpss.c / hakios.ipa.c map that phone's blocks. SOC_ARGS names the file;
+# default is the one device there is. The POCO's values equal the kernel defaults, so this is a no-op there.
+SOC_ARGS=${SOC_ARGS-$(ls devices/*/soc.args 2>/dev/null | head -1)}
+SOC=""; [ -n "$SOC_ARGS" ] && [ -f "$SOC_ARGS" ] && SOC=$(tr '\n' ' ' < "$SOC_ARGS")
+for i in $(seq 1 2160); do s=$(./xl state); [ "$s" != absent ] && break; sleep 10; done
+echo "$(date +%T) phone: $s"; [ "$s" = absent ] && { echo "NO PHONE"; exit 1; }
+./xl enter 2>&1 | tail -1
+./xl ramdisk userland/system.apfs 2>&1 | tail -1
+XL_SB_DELAY=${XL_SB_DELAY:-600} XL_CMDLINE="debug=0x8 rd=md0 hv_wdt_pet=1 bootcpu=7 cpus=8 cpufreq=1 ufs=2 $ARGS $SOC" XL_SECS=$SECS XL_FOLLOW=1 XL_FOLLOW_KEEP=1 ./xl run 2>&1 | tail -2
+echo "$(date +%T) state after run: $(./xl state)"
+L=$(ls -t logs/*-run.log.live | head -1); F=${L%.live}; echo "LOG=$F"
+cat $L $F 2>/dev/null | grep -a "mpss: \(7: \(THE\|the watch\)\|11\|rmtfs\|tftp\|servreg\|dms\|nas\|ipa: \(THE\|from node\|the modem\|a probe\)\|link: \(THE\|tftp\)\|LAST WORDS\|step 1[01]\)\|serving system\|panic(\|ipa: \|cell: \|net: en1\|wda: \|wds: \(THE\|the client\|about\)" | grep -v "about to ask\|about to tell" | sed 's/^\[ *[0-9.]*\]: //' | awk '!seen[$0]++' | cut -c1-230 | head -80
+# Where the phone is left (XL_END): "loader" (default) -- the kernel hands control back to our loader
+# at the end of the run (loader_return_after: the modem, the DSPs and the GPU stopped first), and the
+# phone stays there, in the loader's fastboot-protocol channel, ready for the next run with no reboot
+# at all; if the return failed and the watchdog reset the phone into Android, it is sent back to
+# fastboot, so a phone left alone always sits where it can be recovered. "android": the old way,
+# back to Android after every run.
+case "${XL_END:-loader}" in
+android)
+ echo "== back to Android"
+ case "$(./xl state)" in loader|fastboot) XL_FORCE=1 ./xl reboot >/dev/null 2>&1 ;; esac
+ for i in $(seq 1 40); do s=$(./xl state); [ "$s" = android ] && break; sleep 5; done ;;
+*)
+ echo "== staying in the loader / fastboot"
+ for i in $(seq 1 60); do s=$(./xl state); [ "$s" != absent ] && break; sleep 5; done
+ if [ "$s" = android ]; then
+ adb reboot bootloader >/dev/null 2>&1
+ for i in $(seq 1 30); do s=$(./xl state); [ "$s" = fastboot ] && break; sleep 5; done
+ fi ;;
+esac
+echo "$(date +%T) phone: $s"; echo DONE
diff --git a/tools/win-bin/flock b/tools/win-bin/flock
new file mode 100644
index 0000000..a7ee70b
--- /dev/null
+++ b/tools/win-bin/flock
@@ -0,0 +1,16 @@
+#!/bin/sh
+# flock for Git Bash on Windows, where util-linux's flock does not exist. xl (the loader driver)
+# wraps every fastboot call in `flock -w SECS LOCKFILE timeout SECS fastboot ...` so that two xl
+# invocations (a run in one terminal, a screenshot in another) take turns on the one USB channel.
+# Here one xl runs at a time, so the lock buys nothing: the lock options and the lock file are
+# dropped and the command is run as it is. To use it: PATH=$PWD/tools/win-bin:$PATH ./xl ...
+# (next to C:\platform-tools for fastboot and adb). Not for Linux or macOS, which have the real one.
+while [ $# -gt 0 ]; do
+ case $1 in
+ -w|-E|--timeout|--conflict-exit-code) shift 2 ;; # an option that takes a value
+ -*) shift ;; # -n -s -x -u -o and the rest
+ *) break ;; # the lock file
+ esac
+done
+shift # the lock file itself
+exec "$@"