docs: record the QEMU clock-dilation lead for the FGS video

Chasing the video on the emulator found one lever that actually attacks the failure, and it is
worth writing down even though it did not hold:

  emulator -avd phone ... -qemu -icount shift=1,sleep=off

Without -icount the guest clock is tied to the host's wall clock, so Android's five-second
startForegroundService() deadline means five real seconds however slowly TCG executes - which is
what kills the app here every time. With -icount the guest clock advances per executed
instruction, and it measured 2.30x slow (30.9 s host to 13.4 s guest uptime). On that boot a scan
start succeeded: the app's notification appeared five seconds after the tap and there was no
am_crash, the only success recorded on this machine.

It then stopped reproducing - later attempts produced neither a notification nor a crash. Two
possibilities, and the second is an app-side diagnosability gap: either the tap never reached the
app, or ScanService.start() swallowed a ForegroundServiceStartNotAllowedException, which it does
silently (it catches IllegalStateException and does nothing with it, so logcat shows nothing at
all). Notes say so, and point at SETTLE_SECONDS / WARM_SECONDS for scaling the waits, because a
dilated guest is slower at everything - uiautomator dumps included.

The script also retries a tap (up to three times, re-reading the coordinates) before falling back
to a cold restart, since on a slow emulator the window can still be settling while the
accessibility tree already lists the button - and a restart costs another cold start. The
recommendation stands: record the take on the phone.
This commit is contained in:
2026-10-14 12:25:02 +02:00
parent 179bc2cc33
commit ddc7fb44b0
2 changed files with 40 additions and 9 deletions
+14 -6
View File
@@ -308,12 +308,20 @@ action except the items marked **[code]**.
`startForeground()` inside Android's budget — while on the phone this app scans a
5,363-photo library in 20 s with the notification up throughout.
An earlier version of this note claimed a second, unexplained mid-scan death. That was
this same failure misread: the script's old "is a scan running?" check matched the
service *record*, which exists from the moment `startForegroundService()` is called, so
it reported success on runs that were already dying. `tools/record-fgs-demo.sh` now waits
for the app's notification instead, which is the only honest proof the service started,
and reports the `am_crash` line when it never does.
One emulator-side lever is worth knowing, because it is the only thing that ever got this
app's foreground service started on this machine: QEMU's virtual instruction counter
dilates the **guest** clock, so Android's deadline is measured against time that passes
more slowly than the host's. Booting with `-qemu -icount shift=1,sleep=off` made the guest
clock run **2.30× slow** (measured: 30.9 s of host time to 13.4 s of guest uptime), and on
that boot a scan start *worked* — the app's notification appeared five seconds after the
tap, with no `am_crash`, the only success recorded here. It then stopped working: later
attempts produced neither a notification nor a crash, which means the tap never reached
the app, or `ScanService.start()` silently swallowed a
`ForegroundServiceStartNotAllowedException` (it catches `IllegalStateException` and does
nothing with it, so that path leaves no trace in logcat at all — a diagnosability gap
worth a log line if this is ever chased further). So treat `-icount` as a lead to retry
with patience rather than a recipe to rely on, and use `SETTLE_SECONDS` / `WARM_SECONDS`
to scale this script's waits for a dilated clock.
The declaration is **per type**: if a new foreground-service type is ever added to
the manifest, it has to be declared here too.