Tool catalogue

164 tools, generated from their own headers.

needs is the device state a tool requires: - host-only, BOOTED, FASTBOOT, on-device (it runs on the device), or any (it probes and handles several).

`generic`

tool	needs	what it does
`bootimg-cmdline.py`	-	Read/patch the kernel cmdline of an Android boot image, in place or to a copy.
`bootimg-repack-dtb.py`	-	Swap the appended DTB inside an Android boot image, fixing up the header.
`bootimg-verify.py`	-	Verify a boot.img actually carries the kernel/DTB you just built.
`dtbo-split.py`	-	Split an Android DTBO image into its individual .dtb entries.
`fdtdump.py`	-	Minimal flattened-devicetree dumper (no dtc on this host).
`gen-tools-doc.py`	-	Generate docs/TOOLS.md from the tool headers. Run via `make tools-doc`.
`mtstall.py`	on-device; /proc	mtstall.py SECONDS [COMM] – is the WebKit main thread computing, or blocked?
`ph-acoustic.py`	BOOTED	ph-acoustic.py – decide “does audio actually come out / go in” with no human.
`ph-afk.sh`	BOOTED	ph-afk.sh – stop the phone suspending itself while nobody is at the keyboard.
`ph-alsa-stage.py`	BOOTED	Walk the ALSA PCM lifecycle one call at a time, marking /dev/kmsg before each.
`ph-applaunch-bench.sh`	on-device	ph-applaunch-bench.sh – cold/warm application launch latency under phosh.
`ph-autologin.sh`	BOOTED	Enable or disable greetd auto-login, which is the ONLY reliable way to get an
`ph-blankwatch.py`	on-device as the session user; grim; a screen that is ON	Sample how much of the screen is BLANK while something is happening.
`ph-build-lock.sh`	-	Serialise KERNEL BUILDS across parallel agents.
`ph-build.sh`	-	shellcheck shell=bash
`ph-camstream.sh`	-	ph-camstream.sh – one capture attempt on the IMX179 front camera, with the
`ph-capture-userspace.sh`	BOOTED	Capture the device’s locally-built package set, so a from-scratch install
`ph-capture.sh`	BOOTED	ph-capture.sh – arm every log channel this device has, from the HOST, and
`ph-chromium-videoarm.sh`	on-device as the session user; /tmp/sess.sh; chromium; grim; v4l2-ctl;	ph-chromium-videoarm.sh LABEL [CHROMIUM_FLAGS…] – one PLAYBACK arm.
`ph-compass-check.py`	-	Check the compass maths in qcom_smgr.c against floating point.
`ph-crosstax.py`	-	ph-crosstax.py [SECONDS] – how much of a cross build runs under qemu.
`ph-cycle.sh`	any	One display bring-up experiment: bootloader -> RAM boot -> modprobe -> capture.
`ph-decode-killstorm.sh`	on-device	ph-decode-killstorm.sh – SIGKILL a hardware decode mid-flight, N times,
`ph-device-test.sh`	BOOTED	One check: two concurrent ph-device.sh callers must not interleave.
`ph-device.sh`	any	Serialise access to the ONE physical phone across parallel agents.
`ph-dpu-regs.sh`	BOOTED	Dump and decode the DPU registers that matter for a stuck display.
`ph-dumpdiff.py`	-	Diff a stock-Android TKDUMP capture against our camss port’s register state.
`ph-egl-dmabuf-probe.py`	on-device	What dmabuf modifiers does EGL really advertise, per platform?
`ph-evtest.py`	-	Dump multitouch events from an evdev node. Run ON THE DEVICE, as root.
`ph-firstpaint.sh`	-	ph-firstpaint.sh – what the user actually waits for: launch -> first frame.
`ph-flash-boot.sh`	FASTBOOT	Flash a boot image to slot b and come back up in pmOS, end to end, unattended.
`ph-gap.py`	BOOTED	Measure the capture gating (HANDOFF-audio.md 2.5) as a number, per config.
`ph-gesture-bench.py`	-	Measure how smooth the phosh session actually is. Run ON THE DEVICE as root.
`ph-greetd-login.py`	on-device as root	Log a user into the graphical session through greetd’s IPC, from ssh.
`ph-i2c-probe.py`	-	Scan the taimen touch i2c bus (QUP5) for the STM FTM4 at 0x49.
`ph-irq-floor.py`	BOOTED	What is waking the CPU while nobody is using the phone?
`ph-key.py`	-	Inject a key press through /dev/uinput. Run ON THE DEVICE as root.
`ph-kmsglog.py`	-	Follow /dev/kmsg into a file, fsync’d per record, so the kernel log tail
`ph-lte-load.py`	-	Generate sustained traffic that REALLY goes out over LTE. Run ON THE DEVICE.
`ph-mempressure.sh`	on-device	ph-mempressure.sh – one line per second of the memory-ceiling vital signs.
`ph-mic-check.sh`	BOOTED	ph-mic-check.sh – is the microphone producing AUDIO, or just a noise floor?
`ph-mic-test.sh`	BOOTED	ph-mic-test.sh [DMIC0..DMIC5] [seconds] [rate] – runs ON THE PHONE.
`ph-mic-watch.sh`	BOOTED	ph-mic-watch.sh [seconds] – runs ON THE PHONE.
`ph-micwatch.sh`	BOOTED	ph-micwatch.sh – sample whether anything is holding the microphone open.
`ph-modcrc.py`	BOOTED	Compare the __versions (modversions) sections of two .ko files.
`ph-modstack.sh`	on-device	Reading the module stack, for tkmod’s reload path. SOURCED, never run:
`ph-mount-cal.py`	BOOTED	Measure the accelerometer mount matrix from four guided poses.
`ph-mt-doctor.py`	on-device as root	Diagnose and clear phantom touch contacts.
`ph-mtstate.py`	-	Print the CURRENT multitouch slot state of an evdev node, without waiting.
`ph-nfc-portal-probe.py`	on-device	Assert what an app on the NFC portal’s fd can and cannot do.
`ph-perf-ab.sh`	-	ph-perf-ab.sh – interleaved A/B of a tuning knob against real frame timings.
`ph-phy-reinit.py`	-	Re-run the CSIPHY v5.0.1 init sequence by hand, WHILE the sensor is already
`ph-phy-settle-sweep.py`	-	Sweep the CSIPHY settle count over its whole 0..255 range against a LIVE
`ph-phy-sweep.py`	-	Sweep CSIPHY CMN_CTRL5 (the lane-enable mask) against a LIVE transmitting
`ph-phystat.py`	-	Read (and optionally poke) the SoC CSIPHY common block live.
`ph-prox-check.py`	BOOTED	Check that qcom_smgr suppresses the proximity IR crosstalk in the ALS.
`ph-push-module.sh`	BOOTED	Install a freshly built kernel module onto the running phone, no reflash.
`ph-rangehttp.py`	on-device	Serve a directory over HTTP with byte-range support, for
`ph-reboot.sh`	any	Reboot the phone and return the INSTANT ssh answers again.
`ph-recover.sh`	any	ph-recover.sh – one command to get taimen back after the 2026-08-01 incident,
`ph-regdump.py`	-	Dump an MMIO range via /dev/mem, one mmap’d process.
`ph-ringdump.py`	-	Decode the ringbuffer out of an adreno devcoredump into CP packets.
`ph-scrollarm.sh`	on-device as the session user	ph-scrollarm.sh LABEL [ENV…] – one PURE-SCROLL arm, with no video playing.
`ph-sensor-poke.py`	-	Live 16-bit-register I2C access to the IMX179, for use WHILE camss holds the
`ph-sensorstream.sh`	-	ph-sensorstream.sh – stream the REAL sensor path, imx179 -> CSIPHY -> CSID ->
`ph-session-cpu.sh`	on-device	ph-session-cpu.sh – rank a graphical session’s user units by cumulative CPU.
`ph-soak.sh`	on-device	ph-soak.sh – the on-device half of the D2 / 72 h stability soak.
`ph-stallcatch.py`	on-device as root	ph-stallcatch.py SECONDS COMM THREAD_SUBSTR [IDLE_MS] – when THREAD of the
`ph-stream.sh`	BOOTED	Stream a command’s output from the phone to a host file, across reboots.
`ph-strip-btf.py`	-	Make a kernel module’s .BTF section invisible to the module loader.
`ph-supervise.sh`	any	ph-supervise.sh – keep the phone alive during unattended work.
`ph-suspend-guard-check.sh`	BOOTED	ph-suspend-guard-check.sh – prove the suspend guard actually blocks, WITHOUT
`ph-sysstate.sh`	on-device	Print one compact line of system state per second, forever.
`ph-tgstream.sh`	-	ph-tgstream.sh – capture from the CSID’s own test generator.
`ph-thermal-ramp.sh`	-	ph-thermal-ramp.sh – the six-phase thermal ramp, with an abort that works.
`ph-thermal.sh`	BOOTED	Keep a phone from being cooked by back-to-back measurement arms.
`ph-threadcpus.py`	on-device; a running process to watch	Which CPU does each of a process’s threads actually run on, and at what clock.
`ph-tone.py`	-	Generate an acoustic probe signal, to be played on the HOST while the phone
`ph-touch.py`	-	Inject touch gestures through /dev/uinput. Run ON THE DEVICE as root.
`ph-uclamp.py`	on-device; CONFIG_UCLAMP_TASK=y; same uid as the target	Raise the scheduler’s utilization floor for a running app’s threads.
`ph-ui.py`	on-device	Drive and inspect the phosh session deterministically. Run ON THE DEVICE.
`ph-vibrate.py`	-	Play a rumble effect through the force-feedback API. Run ON THE DEVICE.
`ph-videoarm.sh`	on-device as the session user	ph-videoarm.sh LABEL [ENV…] – one PLAYBACK arm on a LOCAL clip.
`ph-wake-cycle.py`	on-device	Press the power key on a loop and count the blank/unblank transitions that
`ph-wav-verdict.py`	-	Decide whether a capture contains real microphone audio.
`ph-webarm.sh`	on-device as the session user	ph-webarm.sh LABEL [ENV…] – one YouTube arm with the page state PROVEN
`ph-webbench.sh`	on-device as the session user	ph-webbench.sh – browser smoothness A/B on a deterministic heavy page.
`ph-webdraws.sh`	on-device with passwordless sudo; perf; CONFIG_UPROBE_EVENTS; a running	ph-webdraws.sh [SECONDS] – the compositor’s draw census per frame.
`ph-webeval.py`	on-device; ph-webvq.py beside it; browser launched with WEBKIT_INSPECTOR_HTTP_SERVER=127.0.0.1:9222	Evaluate JavaScript in the current page through WebKit’s remote inspector.
`ph-webframe.sh`	on-device with passwordless sudo; perf; CONFIG_UPROBE_EVENTS;	ph-webframe.sh [SECONDS] – where each compositor frame’s period goes.
`ph-weblayers.py`	on-device; ph-webvq.py beside it; browser launched with WEBKIT_INSPECTOR_HTTP_SERVER=127.0.0.1:9222	Dump the composited layer tree of the current page through the remote inspector.
`ph-webvq.py`	on-device; Epiphany launched with WEBKIT_INSPECTOR_HTTP_SERVER=127.0.0.1:9222	Poll a
`ph-wifi-audit.sh`	-	ph-wifi-audit.sh – end-to-end WiFi stack audit for taimen (ath10k/WCN3990).
`ph-wifi-soak.sh`	on-device	ph-wifi-soak.sh – watch a WiFi link for the two ways it fails quietly.
`ph-wkoffsets.sh`	BOOTED – to name the build under test; falls back to the newest apk,	ph-wkoffsets.sh [SYMBOL…] – uprobe offsets for WebKit phase entry points,
`ph-wkphase.sh`	on-device with passwordless sudo; CONFIG_UPROBE_EVENTS. Offsets come	ph-wkphase.sh arm\|measure [SECONDS]\|off – where the WebKit MAIN THREAD’s
`ph-wlgaps.py`	-	Where a client’s late frames actually are, from a WAYLAND_DEBUG=1 log.
`ph-wol.py`	any	Wake a sleeping phone over wifi with a WoWLAN magic packet, without hands.
`powerhintd.py`	on-device	powerhintd – Android’s power hints for a mainline phone.
`rootfs-uuid.py`	-	Read the filesystem UUIDs out of a pmOS rootfs image, without mounting it.
`stallwatch.sh`	BOOTED	stallwatch.sh – detect the taimen PID-1 freeze from the HOST.
`threadcpu.py`	on-device; /proc	threadcpu.py [SECONDS] [PROC-MATCH] – per-thread CPU of a multithreaded app.
`tsh.py`	INITRAMFS	Run a command on the pmOS initramfs debug shell (busybox telnetd, $HOST:23).
`wkbuckets.py`	-	wkbuckets.py PERF-REPORT-FILE – what phase of WebKit owns the main thread,

`device:google-taimen`

tool	needs	what it does
`ph-awb-invert.py`	-	Invert the SoftwareIsp pipeline over a crop to recover raw (black-subtracted,
`ph-battery-log.sh`	on-device	Log real battery drain, and the state needed to explain it.
`ph-chromatix-awb-locus.py`	-	Extract the AWB colour-temperature locus from a vendor chromatix 3a blob.
`ph-chromium-conf-check.sh`	-	ph-chromium-conf-check.sh [confdir] – runs ON THE HOST.
`ph-cmp-vendor-regs.py`	-	Compare a live WCD934X register dump against downstream’s init tables.
`ph-dmic-sweep.sh`	on-device	ph-dmic-sweep.sh [seconds] – runs ON THE PHONE.
`ph-dt2w-probe.py`	on-device	The device half of ph-dt2w-test.sh: wait for a finger, arm, watch for a tap.
`ph-dt2w-test.sh`	BOOTED	Prove double-tap-to-wake at the CONTROLLER, without a suspend and without
`ph-easel-iatu.py`	-	Program Easel’s inbound iATU so BAR2 maps its peripheral window, then read
`ph-easel-poke.py`	-	Poke Easel registers live through BAR2 (HANDOFF §42b).
`ph-easel-poll.py`	-	Poll Easel RX PHY_STOPSTATE / PHY_RX fast, to catch HS data bursts.
`ph-easel-pon.py`	-	Power on Easel’s BCM15602 PMIC by hand and see if it answers on i2c.
`ph-easel-power.py`	-	Bring Easel (Pixel Visual Core) all the way up from userspace, then retrain
`ph-easel-rx.py`	-	Read Easel’s MIPI RX/TOP state through BAR2 – a third, independent
`ph-easel-txpoll.py`	-	Poll Easel TX PHY_STATUS to see whether the bypass forwards data bursts.“””
`ph-easel-vpg.py`	-	Drive Easel’s TX video pattern generator – sensor and bypass mux out of the
`ph-framprobe.py`	on-device, inside the graphical session	What frame interval does the compositor actually give a client?
`ph-ftm4-log.py`	-	Passively log the whole touch chain so a failure can be read off afterwards.
`ph-ftm4-poke.py`	-	Interrogate the FTM4 touch controller behind the back of a bound ftm4 driver.
`ph-mic-ab.sh`	BOOTED	ph-mic-ab.sh [seconds] – runs ON THE PHONE.
`ph-mic-clean.sh`	BOOTED	ph-mic-clean.sh [mic] [seconds] [stray] – runs ON THE PHONE.
`ph-mic-split.sh`	BOOTED	ph-mic-split.sh – runs ON THE PHONE. Three captures, one question each.
`ph-session.sh`	BOOTED; ph-key.py and ph-touch.py in /tmp on the device; magick on the host	Wake, unlock and blank the phosh session, reliably enough to drive the phone
`ph-skin-burn.sh`	on-device	Drive skin temperature up under CPU load and record which rungs of the
`ph-slpi-dt2w-probe.py`	on-device as root	Does the SLPI report a double tap once it owns the touch i2c?
`ph-tas-fw.py`	-	Parse a TAS2557 uCDSP firmware image and report what is inside it.
`ph-vfe-wrote.py`	-	Does the VFE write ANY byte to the capture buffer?
`ph-voicecall.py`	BOOTED	Drive an ADSP voice-call session over the q6voice debugfs bridge.
`ph-voicehold.py`	BOOTED	Hold the voice PCM open for the duration of a call.

`soc:msm8998`

tool	needs	what it does
`boot-probe.sh`	FASTBOOT	Boot an image and time the USB transitions, distinguishing a real reboot from noise.
`ph-allphy.py`	-	Hand-configure ALL THREE msm8998 CSIPHYs and watch every status register.
`ph-audio-cycle.sh`	BOOTED	ph-audio-cycle.sh [–dtb] [–kernel] – one command from “make finished” to
`ph-cpufreq-verify.sh`	-	ph-cpufreq-verify.sh – does a requested CPU frequency actually get delivered?
`ph-daily-audit.sh`	on-device	Daily-driver readiness audit. Run ON THE DEVICE.
`ph-deadman.sh`	BOOTED	ph-deadman.sh – arm/disarm a self-reboot on the PHONE before a risky test.
`ph-display-watch.py`	-	Log the display pipeline so a frozen screen can be read off afterwards.
`ph-dtc.sh`	-	ph-dtc.sh [board.dts] – compile a board DTS on the HOST, before asking for a
`ph-fp-morning.sh`	BOOTED	One-command fingerprint capture test: run this, touch the sensor
`ph-fp-ta.sh`	on-device	ph-fp-ta.sh – what does the TrustZone say about the fingerprint trustlet?
`ph-fps.py`	-	Sample the display/GPU pipeline once a second. Run ON THE DEVICE.
`ph-hang-matrix.sh`	BOOTED	ph-hang-matrix.sh – the 2x2 attribution matrix for defect #3.
`ph-lab.py`	BOOTED	ph-lab.py – unattended audio experiment harness for taimen.
`ph-osm-probe.py`	-	Read what the msm8998 OSM actually delivered.
`ph-pins.py`	-	Sample TLMM GPIO input levels on the phone – runs ON THE DEVICE.
`ph-pkgcheck.sh`	BOOTED	ph-pkgcheck.sh – is the thing that SHIPS the thing you EDITED?
`ph-reconcile.sh`	-	ph-reconcile.sh – does the aport series and the linux/ tree contain the same code?
`ph-spi-probe.py`	-	Poke the taimen touch controller (LG SW49408) over spidev.
`pil-squash.py`	-	Reassemble a split Qualcomm PIL image (foo.mdt + foo.b00..bNN) into one foo.mbn.

`soc:qcom`

tool	needs	what it does
`dtb-grep.py`	-	Print nodes matching a name pattern out of a flattened device tree.
`ph-compass-cal.py`	BOOTED	Calibrate the magnetometer’s hard-iron offset, and persist it.
`ph-iio-events.py`	-	Enable an IIO event and print events as they arrive. Runs ON the device.
`ph-iio-read.py`	-	Read samples from a buffer-only IIO device (no in__raw), e.g. qcom-smgr-.
`ph-lifeline`	on-device	ph-lifeline: if this boot cannot reach the USB host, return to the bootloader.
`ph-sensor-chain.sh`	BOOTED	ph-sensor-chain.sh – watch the WHOLE ambient-light / proximity chain at once:
`ph-sns-groups.py`	-	Extract the SSC sensor-registry group table from Android’s sensors.qcom.
`ph-storage-bench.sh`	on-device	UFS / block / swap measurement for taimen. Run ON THE DEVICE as root:
`ph-suspend-cycle.sh`	BOOTED	One real s2idle cycle, driven from the host, with evidence that survives the
`ph-to-fastboot.sh`	any	Get the phone INTO the bootloader, and return the instant it lands (~9s).
`ph-usb-wake.py`	any	Wake a taimen that is wedged in suspend, from the host, without hands.
`qrtr-lookup.py`	-	Minimal qrtr-lookup: list QMI services on the QRTR bus. No deps.“””