From 5ce726a12528400aa6c854f89d2349507cd581c8 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Thu, 29 Oct 2026 14:10:29 -0400 Subject: [PATCH] docs/review: lessons from review round 29 Twenty-six lessons (L-318 to L-343) from the round 29 omamobile-reviewer runs, and three corrections: C-20, our kernel #109 advice that the Pixel 7's SPI controller DMAs the touch report (it polls; gs201's spi_0 has no dmas); C-21, asking for FT3658=m in panther's device kernel.config against RELEASES; C-22, a Bluetooth address in kernel #98's thread that the first review missed. Five candidates were dropped as already covered. Co-Authored-By: Claude Opus 5.5 --- docs/review/LESSONS.md | 236 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) diff --git a/docs/review/LESSONS.md b/docs/review/LESSONS.md index 9d09b1214..7cd8bd66f 100644 --- a/docs/review/LESSONS.md +++ b/docs/review/LESSONS.md @@ -18,6 +18,62 @@ never change, so reviews can cite them. ## Safety model (AGENTS.md section 1) +- **L-324. A review reads the PR thread for identifiers, not only the diff.** + A contributor's evidence comments on kernel #98 quoted `bluetoothctl show` + with the phone's public Bluetooth address twice, and `tools/pr-check` sees + commits only. *Check:* every round, run the MAC pattern + (`[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}`) and the serial and IMEI patterns over + `gh pr view N --json comments,reviews` and the inline review comments, and + ask for an edit. Extends L-29; see C-22. *From:* kernel #98, round 29. +- **L-323. A device that drops its forked init for the shared one also changes + its `INITRAMFS_INIT` to an absolute value.** A value without a leading `/` + is relative to `device//`, so #111's unchanged `initramfs/init` + pointed at the file the same push deleted; `tests/boot-method` passed + because `images` stops at "build the kernel first" before the initramfs. + *Check:* `grep INITRAMFS_INIT device//device.conf`, then `git cat-file -e + :device//`, or run `bin/omamobile initramfs` with a scratch + `KERNEL_OUT` (it dies at the init check before any download). Extends L-134. + *From:* #111, round 29. +- **L-322. Accepting a new `BOOT_METHOD` in `bin/omamobile` opens `flash` and + `push` too, and `flash` switches the slot.** On Qualcomm A/B, `fastboot + --set-active` hands slot state to ABL, which (as we understand it) resets + the successful flag; with the GPT mark allowed only by hand under a §3.1 + entry, `flash` forces the next GPT write or a fallback. *Check:* for a new + method, list what each of `images`, `flash` and `push` does on that + bootloader, and refuse the ones whose follow-up isn't approved. Extends + L-284. *From:* #111, round 29. +- **L-321. "The shared init covers this device" is checked against the LUNs on + any non-Pixel UFS.** `initramfs/init` leaves allowlisted partitions writable + only on `sda`, `boot_arch` finds `userdata` only there, and `cmd_push` finds + slot B's images only there. Pixels keep them on LUN 0; multi-LUN Qualcomm + layouts may not. The no-USB-host `sysrq c` fallback is a Tensor-era + assumption too. *Check:* ask for the read-only `PARTNAME` to `sdX` map of + every `UFS_RW` entry from sysfs before accepting "push updates `boot_b`", + and ask what a panic does on that bootloader. Extends L-1 and L-232. *From:* + #111, round 29. +- **L-320. A one-boot helper a PR adds needs install, enable and removal steps + in its runbook.** #136's H5 created the early read's marker, but no step + installed or enabled the unit, so the run's main reading would silently not + happen. *Check:* for each script or unit a PR adds under `device//`, find + the runbook line that copies it and runs `systemctl enable`, and the one + that undoes it. *From:* #136, round 29. +- **L-319. A meter check or stop rule written for one reset applies to every + reset that reaches the same state.** #136's "VBUS still up two minutes after + the reset" was attached to H5's planned `echo b`, but H4's swap timer and a + forced restart with the drive attached are the same crash with host mode on. + *Check:* for each stop rule that depends on hardware state, list the other + ways the runbook can reach that state (timers, dead-man, forced restart) and + state the rule once, at the top. Extends L-296 and L-133. *From:* #136, + round 29. +- **L-318. A step that swaps the cable while no Type-C driver owns the port + can't expect its link back.** #136's H5 boots with a USB drive on the port + and the boost module blacklisted, so the charger and the TCPC defer and + nothing owns the MAX77779, which opens its USB data switch when the drive is + unplugged. The runbook said "put the laptop back in" as if SSH would return. + *Check:* for every step that ends with a cable swap, list which Type-C + driver is bound at that moment; if none, the Expect says "no link" and the + way back is a restart with the laptop attached. Extends L-81 and AGENTS + "USB". *From:* #136, round 29. - **L-298. A retry path is exercised on the phone by holding its dependency down, not by breaking hardware.** #99's screen-on retry can be forced by keeping neard stopped across a screen-on. *Check:* first confirm the daemon @@ -314,6 +370,40 @@ never change, so reviews can cite them. ## Shared code and the reference device +- **L-328. Moving a CPIF watcher from open-per-poll to a held fd changes the + node's open count for the CP's lifetime; read open and release before + calling it neutral.** On our CPIF, `bootdump_open` runs `init_comm` (which + returns at once for SIT), `terminate_comm` is NULL, release purges the rx + queue on cbd's close, and a holder that never reads takes none of cbd's + frames, so #148 is neutral there by source. It still changes every phone's + modem profile, so cheetah gets a maintainer run first. *Check:* the iod's + open, release, poll and rx paths, and every reader of `iod->opened`. Extends + L-206. *From:* #148, round 29. +- **L-327. A new `VENDOR_LIBS` entry in `extract-vendor-chroot` is unverified + until the extractor has run on a real image.** Every entry's NEEDED closure + is walked and any unresolved soname aborts the whole profile, so a GNSS-only + addition could take a phone's modem chroot down with it; #141's libraries + were copied by hand. *Check:* ask for one extractor run (its `==>` lines and + the new MANIFEST paths), or run it on a factory image we have; binder + clients often need `STUB_LIBS`. Extends L-29. *From:* #141, round 29. +- **L-326. A "read-only, no-op on cheetah" `clk_get_rate()` on an ACPM clock + is a firmware call.** clk-acpm registers the gs101, gs201 and zumapro clocks + with `CLK_GET_RATE_NOCACHE`, so kernel #116's MIF restore adds one ACPM DVFS + GET on cheetah at every drop from 120 Hz, though it never writes there (MIF + is already at its top rate). *Check:* before calling a new `clk_get_rate()` + on a shared path free, read the provider's `flags` and `recalc_rate`, and + put the call count in the cheetah table. Extends L-111. *From:* kernel #116, + round 29. +- **L-325. "Shares the register map" isn't "shares the device type": a PMIC + change gated on `device_type` is checked against the reference phone's MFD + data, not its registers.** rtc-s5m gives the S2MPG12 the S2MPG10's + `s2mpg10_rtc_regs`, but sec-acpm's `s2mpg12_data` keeps `device_type = + S2MPG12`, so kernel #132's `== S2MPG10` steps skip cheetah although the + registers are the same; a condition on the regs pointer would have reached + it. *Check:* for each new condition in a shared PMIC driver, read what it + tests (type, regs, compatible), find cheetah's value in the MFD match data + and probe, and confirm with the compare's immediate in the object. Extends + L-206 and L-230. *From:* kernel #132, round 29. - **L-301. A shared-driver branch gated on what callers send counts as match data under CONTRIBUTING §6.2 only if no reference-phone consumer sends it, on the base and on `omamobile-int`.** Kernel #125's DCS-read path runs only @@ -640,6 +730,42 @@ never change, so reviews can cite them. ## Kernel (linux-omarchy-mobile) +- **L-332. A delayed "auto-off" work in a driver is checked for re-arm, cancel + and remove order.** Kernel #126's LHBM timer used `schedule_delayed_work()`, + a no-op while the work is pending, and never cancelled it on off, so an + off-on within 3 s was cut short; its `remove()` cancelled before removing + the sysfs attribute that queues the work, and could leave a lit circle with + no timer. *Check:* off cancels, on uses `mod_delayed_work()`, and remove + goes attributes away, state off, cancel sync, detach. The Pixel 7 Pro's + s6e3hc4 LHBM on `omamobile-int` is the local precedent. *From:* kernel #126, + round 29. +- **L-331. A fixed sleep between NCI commands while the controller resets is + checked against the core's request pairing.** Kernel #131 sends + PROP_NFC_MODE_SET, sleeps 200 ms, then sends CORE_INIT. The core's + `nci_core_reset_ntf_packet()` completes the pending request unconditionally, + so a late CORE_RESET_NTF completes whatever is pending, and every later + request takes the previous one's response; the vendor HAL waits for the + notification, with a 500 ms timer. *Check:* for any `msleep` between NCI + commands, find which notification the vendor HAL waits for there and whether + the core completes requests from it (`ntf.c`, `rsp.c`); prefer leaving the + request pending until the notification arrives. Extends L-61. *From:* kernel + #131, round 29. +- **L-330. A board that reuses a shared pin group for a different part + inherits the reference phone's pulls.** Panther's touch node uses gs201's + `ts_irq` (`PULL_NONE`, cheetah's), while Google's `gs201-panther-touch.dtsi` + overrides `&ts_irq` to pull-up for the FT3658. *Check:* for each shared + pinctrl label a board PR references, `grep -n '&