Skip to content
Merged
122 changes: 120 additions & 2 deletions device/tegu/FINGERPRINT-PLAN.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- SPDX-License-Identifier: MIT -->
# Fingerprint plan (tegu / zumapro): fingerprint unlock on the palmtop

Status (2026-10-27, night): **F0, F2, F6a and F6b passed; F3-F5 and F6c wait for D1.** Earlier: **research and plan only, nothing run on the palmtop for
Status (2026-10-28): **F0 and F2-F5 passed (F4, the first RPMB write, on 2026-10-27 under D1 = A); F6a and F6b passed; F6c waits for the factory calibration, which the owner fetched on 2026-10-28.** Earlier: **research and plan only, nothing run on the palmtop for
fingerprint.** Stage 16 of ALL-HARDWARE-PLAN (private). The
Pixel 7 Pro stack works ([cheetah FINGERPRINT-PLAN](../cheetah/FINGERPRINT-PLAN.md),
opt-in); this plan says what carries over to the Pixel 9a and what is new.
Expand Down Expand Up @@ -202,6 +202,10 @@ New for tegu:
(`dd` from the node found by `PARTNAME`), and `persist` is read from the
off-phone backup image, not mounted on the palmtop (f2fs: a read-only
mount can still run recovery). Never add them to `UFS_RW`.
- `fastboot oem udfps update-cal`, or any other `oem` command that writes,
doesn't run without Derek's explicit go and a named exception: it writes
`mfg_data`, outside slot B and `userdata`. Every `fastboot oem` step in a
runbook pins the serial with `-s`.
- `sg` stays blacklisted from autoload; the runner loads it and binds only
the RPMB LUN's node.
- `gpp1` is shared with the touchscreen reset (`gpp1-1`): the fingerprint pin
Expand Down Expand Up @@ -232,7 +236,14 @@ New for tegu:
Neither choice can roll back the RPMB: its write counter and superblocks move
at the first run either way.

**Decision:** _not taken yet._
**Decision (2026-10-27): A, with the stores as block devices.** Taken by
the owner (W4HO) at the console on 2026-10-27, evening: he never runs
stock Android, so nothing is written outside `userdata` and stock on slot A
is left to need a factory reset if it's ever booted. Within A, the stores
are loop devices of Linux-owned images in `/var/lib/omamobile-fp`
(`td.img`, `tdp.img`; step F4b), so storageproxyd gets its `-m` limit from
a block device and maps `0` and `persist/0` the way stock does, but onto
those images, never onto `trusty_userdata` or `trusty_persist`.

## 7. Runbook

Expand Down Expand Up @@ -321,6 +332,33 @@ requests, `fs_ready`, Trusty's log mounting its stores (TD new under A).
retry loop, collect the logs. Rollback: stop the unit; the RPMB cannot be
rolled back. Risk: irreversible for the RPMB; low for the running system.

### F4b: the store images (TD and TDP as block devices; risk: low)

Only on the 9a (the runner maps them only there, and only when the files
exist). Both live in `/var/lib/omamobile-fp` (0700, root), are made on the
palmtop and are **never committed or copied off it** (they hold Trusty's
secure-storage state):

```sh
# TD: a fresh, empty 128 MiB store; storageproxyd takes its -m limit from it
truncate -s 128M /var/lib/omamobile-fp/td.img && chmod 600 /var/lib/omamobile-fp/td.img
# TDP: the F3 copy of trusty_persist (read-only copy, same size). Before the
# first mapped run it is persist-ss/0; after it, that path is the link and the
# copy is persist-ss/0.before-map.<time>.
install -m 600 /var/lib/omamobile-fp/persist-ss/0 /var/lib/omamobile-fp/tdp.img
```

The runner then maps each to a loop device bound to `/dev/block/ss-td` and
`/dev/block/ss-tdp` in the chroot, links `data/vendor/ss/0` and
`persist-ss/0` to them before storageproxyd starts (an existing store there
is moved aside with a timestamp, never deleted), and passes `-f 0:...`,
`-f persist/0:...` and `-m`. Expect "secure storage ready" with "Using
0x8000000 as max file size". Rollback: stop the runner, `losetup -d` both,
delete the two images (Trusty's state in them is lost; the RPMB is not
rolled back), then remove the two links (`data/vendor/ss/0`,
`persist-ss/0`) and move any `*.before-map.*` file back to its own name, so
the next unmapped run doesn't find links to nothing.

### F5: the TA (risk low)

`start apploader`: "g7a.app loaded" within seconds, the `goodix` test port
Expand Down Expand Up @@ -415,3 +453,83 @@ needs them.
reads it over SPI would. Touch, keys and haptics unaffected.
- F6c (the HAL) needs the TA, which needs secure storage (F4), so it waits
for D1 like F3-F5.

## F3-F6c results (2026-10-27, evening, `7.3.0-rc6-omamobile-tegu-s2mpg15-m1-g991042e2eff3-dirty`)

- **F3 passed.** `mfg_data`, `trusty_persist` and `persist` read with the
sha256 of the 10-27 backup. Stock's `persist/ss` holds only `0` (a link to
`trusty_persist`) and an empty `nsp`. **`mfg_data` is all zeros** on this
palmtop; `persist` has no fingerprint files.
- **F4 ran (irreversible, D1 = A).** storageproxyd without `-f`/`-m`:
"secure storage ready" (fs_ready and fs_ready_rw), no RPMB errors.
- **F5 passed.** g7a.app loaded; `com.goodix.fingerprint.test` open.
- **F6c, sensor.** With LDO15S off (not described), the TA read chip id 0
("SENSOR_NOT_AVAILABLE"). LDO15S is off at hand-off, as on cheetah: round
fp2 describes it (`S2MPG15_PMIC_L15S_CTRL` 0x3d in the regmap table, an
`ldo15s` descriptor, DT always on; reads 3.3 V). Then the sensor answers
and the HAL reports sensor0 at (540, 1769), radius 113.
- **F6c, still failing: secure objects and calibration.** Every TA write
fails ("transaction would leave fs too full, abort", WRITE_SECURE_OBJECT),
the calibration objects (`GHBM_*`, `autoCalibrationParams`) don't open on
TD or TDP, and the TA says "spmt is not pass": no factory calibration, so
init ends in CALIBRATION_NOT_READY. Tried: `-m` (needs a block device:
TD now on a loop device of a 128 MiB Linux image, `0 -> /dev/block/ss-td`,
max 0x8000000; Trusty reads it, writes nothing); TDP mapped to a loop
device of the F3 copy (fs_ready never came); TD seeded from a copy of
stock's `trusty_userdata` (fs_ready never came: Trusty refuses it, so the
first F4 run moved its anchor). Back on the empty 128 MiB TD; the runner
with the loop store is `/root/omamobile-fp-chroot.td-loop` on the palmtop.
- Open question: where the 9a's factory fingerprint calibration lives. It
isn't in `mfg_data` (zeros) or `persist`; stock's TD (`trusty_userdata`,
intact, read-only copy in `td.img.stock-copy`) is the likely place, now
unreadable to Trusty after F4. Next: find which file system is "too full"
(TP on the RPMB is the suspect), and whether the HAL can run SPMT-free
calibration (Google's `gf_cali` "default cali data" is disabled by the TA).
- 2026-10-27, night: with TD and TDP both mapped as stock maps them
(`-f 0:` and `-f persist/0:` on loop devices of `td.img` and `tdp.img`,
`-m` the TD device) storageproxyd reports fs_ready; it first answered
"Pending symlink: forcing read result 0" for both (Trusty saw them empty)
until the symlinks `ss/0` and `ss/persist/0` existed, as on stock. Then
the "too full" commits stop, but every TA object open fails
(OPEN_SECURE_OBJECT, 1035), on TDP too: Trusty reads both devices (about
100 reads each) and finds no objects. The calibration (`GHBM_*`,
`autoCalibrationParams`) is the open question; Trusty's storage service
logs nothing at this log level. Runner copies on the palmtop:
`/root/omamobile-fp-chroot.td-loop` and the live one (TD+TDP maps).
- 2026-10-27, night, later: with the symlinks in place, a copy of stock's
`trusty_userdata` as TD mounts too (fs_ready; it failed earlier only
because storageproxyd's pending-symlink reads showed Trusty an empty TD).
Trusty then wrote 13 blocks to the TDP copy and none to TD. The TA still
finds no calibration: "so(autoCalibrationParams.so_0_0) not exist", and
the `GHBM_*` bases don't open on TD or TDP. So the 9a's fingerprint
calibration isn't in `mfg_data` (zeros), `persist` (an empty `ss/nsp`),
stock's TD or the TDP. The HAL also names `/data/device_cali/` and
`/data/vendor_de/0/fpdata`, both on stock's userdata, which Arch replaced:
the likely home, and gone. Without it the TA refuses enrollment ("spmt is
not pass": the factory sensor test). Open: whether the TA can run on
default calibration (it logs "disable using default cali data") and what
enables that. The live runner maps TD (`td.img`, now the stock copy) and
TDP (`tdp.img`) as block devices with the symlinks.
- 2026-10-28: the calibration's home is in ABL. Its strings carry
`oem udfps status`, `oem udfps get-cal-url`, `oem udfps update-cal`,
"udfps data is not valid", "Calibration signature matches/mismatch",
`udfps` next to `mfg_data`, and the URL template
`https://storage.googleapis.com/hardware-mfg-data-ext-sacal/%s.signed.cal`.
So Google keeps each sensor's factory calibration as a signed file on its
manufacturing bucket, and `update-cal` writes it into `mfg_data`; the zeros
there mean this palmtop's calibration was never written (or was wiped).
Next (needs the owner's hands at fastboot, Volume Down + Power: reaching
fastboot from Linux can fall back to stock on slot A): `fastboot oem udfps
status` and `get-cal-url` (read-only), fetch the file, then feed it to the TA from Linux (no partition write;
`update-cal` writes `mfg_data` and is under the rule in section 5). The URL's `%s` is presumably the device serial, so fetching it
sends the serial to Google: the owner's call.
With the owner's go, the URL with the serial (either case) answers 404,
so the id is something else, presumably the sensor's own id that ABL
reads at `udfps_init`. `fastboot oem udfps get-cal-url` will name it.
- 2026-10-28, morning: at fastboot by the buttons, `fastboot oem udfps
status` answers "invalid sentinel 0x0" (no calibration stored) and
`get-cal-url` names the file on Google's bucket; its id isn't the serial.
With the owner's go the file was fetched (472,368 bytes, HTTP 200). It
and its id stay in the owner's private reference folder, never in the
repository or a log. Next: hand it to the TA from Linux, without writing
`mfg_data`.
14 changes: 10 additions & 4 deletions packages/omamobile-audio/lib/speaker_dsp.py
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,14 @@ def _load(self):
except (OSError, ValueError):
return {}

def _save(self, state):
# rename over the file, so the fake mixer reading it at the same
# moment never sees half of it
tmp = f'{self.path}.{os.getpid()}'
with open(tmp, 'w') as f:
json.dump(state, f)
os.replace(tmp, self.path)

def names(self):
return list(self._load())

Expand All @@ -238,8 +246,7 @@ def read(self, name):
if name.endswith('HALO_HEARTBEAT') and os.environ.get('FAKE_HB_STUCK') != '1' and not frozen:
v += 1 # the firmware's heartbeat moves while it runs
c['v'] = list(v.to_bytes(4, 'big'))
with open(self.path, 'w') as f:
json.dump(state, f)
self._save(state)
return v
if t == 'ENUMERATED':
return c['items'][c['v']]
Expand Down Expand Up @@ -274,8 +281,7 @@ def write_bytes(self, name, data):
if log_path:
with open(log_path, 'a') as f:
f.write(name + '\n')
with open(self.path, 'w') as f:
json.dump(state, f)
self._save(state)
return True


Expand Down
8 changes: 6 additions & 2 deletions packages/omamobile-audio/test/all
Original file line number Diff line number Diff line change
Expand Up @@ -351,8 +351,12 @@ pass "watchdog: mutes on DSP errors, bypass, levels, runtime PM, a stuck heartbe
# level drop, so a jump there must not mute; OMAMOBILE_SPK_TEMP_JUMP brings it back.
jump() { # name [wprep...]: watchdog on a running stream; the bottom's estimate goes 25 -> 40 C a moment in
local n=$1; shift; echo 'state: RUNNING' > "$r/asound/card0/pcm5p/sub0/status"; wprep=("$@")
( sleep 0.4; amx cset "name=Bottom DSP1 Protection cd CSPL_TEMPERATURE" 0x00,0x0a,0x00,0x00 >/dev/null ) &
watchrun; wait
# the jump comes once the watchdog has its first reading (its start line,
# then a few intervals), not at a fixed time: a slow runner started it late
rm -f "$r/watch.out"
( for _ in $(seq 1 100); do grep -c 'watchdog: watching' "$r/watch.out" >/dev/null 2>&1 && break; sleep 0.05; done
sleep 0.3; amx cset "name=Bottom DSP1 Protection cd CSPL_TEMPERATURE" 0x00,0x0a,0x00,0x00 >/dev/null ) &
WATCH_N=60 watchrun; wait
}
startok w-jump8; jump w-jump8
((rc == 0)) && ! muted && grep -c 'jump rule off' "$r/watch.out" >/dev/null || { cat "$r/watch.out" >&2; fail "watchdog: at analog 10 or below a 15 C jump of the estimate does not mute (C9j)"; }
Expand Down
6 changes: 5 additions & 1 deletion packages/omamobile-audio/test/fake-amixer
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,12 @@ def load():


def save(c):
with open(state_path, 'w') as f:
# write and rename, so a reader running at the same moment (the
# watchdog while a test changes a control) never sees half a file
tmp = f'{state_path}.{os.getpid()}'
with open(tmp, 'w') as f:
json.dump(c, f)
os.replace(tmp, state_path)


def show(name, ctl):
Expand Down
4 changes: 3 additions & 1 deletion packages/omamobile-audio/test/fake-pw
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,10 @@ if me == 'pw-cli':
if k not in vals or os.environ.get('FAKE_PW_IGNORE') == '1':
continue # the filter ignores unknown controls
vals[k] = float(v)
with open(state, 'w') as f:
tmp = f'{state}.{os.getpid()}'
with open(tmp, 'w') as f:
json.dump(vals, f)
os.replace(tmp, state)
log(args[3])
sys.exit(0)
if me == 'wpctl':
Expand Down
2 changes: 1 addition & 1 deletion packages/omamobile-audio/version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.5.4
0.5.5
51 changes: 47 additions & 4 deletions packages/omamobile-fingerprint/lib/omamobile-fp-chroot
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,17 @@ case $DEVICE in
cheetah)
TA=g7.app
KEYMINT=/vendor/bin/hw/android.hardware.security.keymint-service.trusty
PANEL=1440x3120 ;;
PANEL=1440x3120 PANEL_NAME=sdc-s6e3hc4 MAP_STORES=0 ;;
tegu)
TA=g7a.app
KEYMINT=/vendor/bin/hw/android.hardware.security.keymint-service.rust.trusty
PANEL=1080x2424 ;;
# Google's panel_name is the DSI device's name, from the bootloader's
# "google-tg4c" panel; OMAMOBILE_FP_PANEL_NAME overrides it.
# the 9a's Trusty stores as block devices (FINGERPRINT-PLAN D1, F4b)
PANEL=1080x2424 PANEL_NAME=google-tg4c MAP_STORES=1 ;;
*) echo "omamobile-fp: unknown device '$DEVICE' (cheetah, tegu)" >&2; exit 1 ;;
esac
PANEL_NAME=${OMAMOBILE_FP_PANEL_NAME:-$PANEL_NAME}
PROPS_DEVICE=${OMAMOBILE_FP_PROPS_DEVICE:-/usr/lib/omamobile-fp/props-$DEVICE.conf}
STATE=${OMAMOBILE_FP_STATE:-/var/lib/omamobile-fp}
RUN=/run/omamobile-fp
Expand Down Expand Up @@ -177,7 +181,7 @@ setup_sys() {
[[ -d /sys/module/$m ]] && bind "/sys/module/$m" "$sys/module/$m"
done
mkdir -p "$sys/devices/platform/exynos-drm/primary-panel"
echo sdc-s6e3hc4 > "$sys/devices/platform/exynos-drm/primary-panel/panel_name"
echo "$PANEL_NAME" > "$sys/devices/platform/exynos-drm/primary-panel/panel_name"
echo 60 > "$sys/devices/platform/exynos-drm/primary-panel/op_hz"
# The panel driver's backlight device carries local_hbm_mode and
# local_hbm_max_timeout; expose it under Google's name.
Expand Down Expand Up @@ -230,12 +234,38 @@ setup_dev() {
install -m 0600 "$STATE/mfg_data.img" /run/omamobile-fp/mfg_data.img
bind /run/omamobile-fp/mfg_data.img "$dev/block/by-name/mfg_data"
fi
# Trusty's tamper-detect stores as block devices, as stock maps them
# (td: trusty_userdata, tdp: trusty_persist), each a loop device of a
# Linux-owned image in $STATE: storageproxyd takes its size limit (-m)
# only from a block device. Absent images keep the files in /data.
local name img loop
for name in td tdp; do
img=$STATE/$name.img
((MAP_STORES)) && [[ -f $img ]] || continue
loop=$(losetup -j "$img" | cut -d: -f1 | head -1)
[[ -n $loop ]] || loop=$(losetup -f --show "$img")
bind "$loop" "$dev/block/ss-$name"
done
# the target lives in the tmpfs just mounted on dev: create it first
mkdir -p "$dev/__omamobile_props__"
mount -t tmpfs -o mode=0755,nosuid,nodev,noexec props "$dev/__omamobile_props__"
write_props "$dev/__omamobile_props__"
}

# Link a store path to its block device. A store already there (a file from
# an earlier unmapped run, or the 7 Pro's restored copy) is moved aside with
# a timestamp, never deleted: losing Trusty's state is never a side effect.
link_store() {
local dev=$1 path=$2 aside
[[ -L $path && $(readlink "$path") == "$dev" ]] && return 0
if [[ -e $path || -L $path ]]; then
aside=$path.before-map.$(date +%Y%m%d%H%M%S)
mv -- "$path" "$aside" || die "can't move $path aside"
say "moved the existing $path to $aside"
fi
ln -s "$dev" "$path"
}

setup_data() {
mkdir -p "$STATE/data/vendor/ss" "$STATE/data/vendor/fingerprint" \
"$STATE/data/vendor_de/0/fpdata" "$STATE/data/vendor/goodix" \
Expand All @@ -248,6 +278,14 @@ setup_data() {
# Linux-owned copy; FINGERPRINT-RESEARCH.md section 6 explains why.
mkdir -p "$ROOT/data/vendor/ss/persist"
mount --bind "$STATE/persist-ss" "$ROOT/data/vendor/ss/persist"
# A mapped store needs its link in place before storageproxyd starts, as
# on stock: without it storageproxyd answers "pending symlink" and Trusty
# reads the store as empty.
if ((MAP_STORES)); then
[[ -f $STATE/td.img ]] && link_store /dev/block/ss-td "$STATE/data/vendor/ss/0"
[[ -f $STATE/tdp.img ]] && link_store /dev/block/ss-tdp "$STATE/persist-ss/0"
fi
return 0
}

# Build the chroot in the current (private) mount namespace.
Expand Down Expand Up @@ -335,8 +373,13 @@ start() {
sleep 1
# storageproxyd sets ro.vendor.trusty.storage.fs_ready=1 once Trusty's
# storage is mounted; trusty_apploader blocks until it runs.
local maps=()
if ((MAP_STORES)); then
[[ -f $STATE/td.img ]] && maps+=(-f 0:/dev/block/ss-td -m /dev/block/ss-td)
[[ -f $STATE/tdp.img ]] && maps+=(-f persist/0:/dev/block/ss-tdp)
fi
spawn storageproxyd vendor /vendor/bin/storageproxyd -d /dev/trusty-ipc-dev0 \
-r /dev/sg-rpmb -p /data/vendor/ss -t ufs
-r /dev/sg-rpmb -p /data/vendor/ss -t ufs "${maps[@]}"
wait_prop ro.vendor.trusty.storage.fs_ready 1 60 ||
die "storageproxyd did not report fs_ready in 60 s"
say "secure storage ready"
Expand Down
12 changes: 12 additions & 0 deletions packages/omamobile-fingerprint/test/all
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,18 @@ for f in lib/omamobile-fp-chroot install; do bash -n "$f" || fail "syntax: $f";
grep -c 'TA=g7.app' lib/omamobile-fp-chroot >/dev/null || fail "cheetah loads g7.app"
grep -c 'TA=g7a.app' lib/omamobile-fp-chroot >/dev/null || fail "tegu loads g7a.app"
grep -c 'keymint-service.rust.trusty' lib/omamobile-fp-chroot >/dev/null || fail "tegu runs the Rust KeyMint"
# Each phone's panel name, overridable; Trusty's stores mapped only when their images exist.
grep -c 'PANEL_NAME=sdc-s6e3hc4' lib/omamobile-fp-chroot >/dev/null || fail "cheetah's panel name"
grep -c 'PANEL_NAME=google-tg4c' lib/omamobile-fp-chroot >/dev/null || fail "tegu's panel name"
grep -c 'OMAMOBILE_FP_PANEL_NAME' lib/omamobile-fp-chroot >/dev/null || fail "panel name override"
grep -c 'sdc-s6e3hc4 >' lib/omamobile-fp-chroot >/dev/null && fail "a fixed panel name is written"
grep -c 'PANEL_NAME=google-tg4c MAP_STORES=1' lib/omamobile-fp-chroot >/dev/null || fail "the 9a maps its stores"
grep -c 'PANEL_NAME=sdc-s6e3hc4 MAP_STORES=0' lib/omamobile-fp-chroot >/dev/null || fail "the 7 Pro never maps its stores"
grep -c 'ln -sfn' lib/omamobile-fp-chroot >/dev/null && fail "no forced link over a store"
grep -c '\[\[ -f \$STATE/td.img \]\] && maps+=(-f 0:/dev/block/ss-td -m /dev/block/ss-td)' lib/omamobile-fp-chroot >/dev/null ||
fail "TD maps only with its image"
grep -c '\[\[ -f \$STATE/tdp.img \]\] && maps+=(-f persist/0:/dev/block/ss-tdp)' lib/omamobile-fp-chroot >/dev/null ||
fail "TDP maps only with its image"
grep -c '^ro.hardware=tegu$' lib/props-tegu.conf >/dev/null || fail "props-tegu.conf"
grep -c '^ro.hardware=cheetah$' lib/props-cheetah.conf >/dev/null || fail "props-cheetah.conf"
grep -c '^ro.hardware=' lib/props.conf >/dev/null && fail "props.conf keeps a phone's ro.hardware"
Expand Down
2 changes: 1 addition & 1 deletion packages/omamobile-fingerprint/version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.1.9
0.1.10