diff --git a/docs/review/LESSONS.md b/docs/review/LESSONS.md index 4dcb36b45..8e9f64405 100644 --- a/docs/review/LESSONS.md +++ b/docs/review/LESSONS.md @@ -18,6 +18,39 @@ never change, so reviews can cite them. ## Safety model (AGENTS.md section 1) +- **L-223. An installer step that writes the phone runs after the typed + codename and is listed in the "only these commands" banner.** #111's + `install-phone` RAM-booted a bootloader copy straight after `getvar`, before + the questions and the banner. *Check:* list every command that can write + (including ones a helper runs over SSH) and its line relative to the + codename prompt; a dry-run test that skips the helper proves nothing about + the order. Extends L-2 and L-5. *From:* #111, round 24. +- **L-224. A policy exception written by the PR that needs it is a finding, + however well specified.** #111 added its own CONTRIBUTING §3.1 entry and + AGENTS line for a 33-partition firmware copy. *Check:* `git diff base head + -- CONTRIBUTING.md AGENTS.md` on every device PR; a new exception goes to the + maintainer and out of the PR. Extends L-2 and L-31. *From:* #111, round 24. +- **L-225. A pinned AVB rollback index is held to the oldest stock any owner + runs.** #104 pinned a newer build's index for every cheetah, above the + maintainer's slot A; rollback locations are device-wide, and libavb stores + any higher non-zero index once a slot is marked successful, which + `omamobile-boot-success` does. *Check:* `avbtool info_image` on each + owner's stock `boot.img` (or ask for the build) against + `AVB_ROLLBACK_INDEX`, `AVB_SECURITY_PATCH` and `OS_PATCH_LEVEL`; prefer the + oldest, or 0 where a phone has shown it boots (#74). Extends L-169. + *From:* #104, round 24. +- **L-226. `fastboot-info.txt` syntax isn't fastboot command-line + syntax.** Told to follow felix's file exactly, #35 copied `flash + --apply-vbmeta vbmeta` into a CLI line that fastboot rejects, mid-way + through a slot A write. *Check:* every hand-written `fastboot` line in a + runbook uses only options in `fastboot --help`. Extends L-205 and C-13. + *From:* #35, round 24. +- **L-227. `ln -sf` or `mv -f` onto a state path is a delete; in Trusty or + calibration code it's a finding.** #101's `ln -sfn` over `persist-ss/0` + would remove cheetah's provisioned copy if one existed. *Check:* grep the + diff for `ln -sf`, `mv -f`, `rm` and `>` onto the package's state + directory, and find who creates those files (`tools/phone-provision`, the + plans). Extends L-2. *From:* #101, round 24. - **L-1. Shared boot code runs under busybox, not util-linux.** The Pixel initramfs has busybox only: `blkid -s LABEL -o value` prints the whole `LABEL=… UUID=…` line there, so a label check that works on a device whose @@ -218,6 +251,56 @@ never change, so reviews can cite them. ## Shared code and the reference device +- **L-228. A board DT property that only the contributor's board sets counts + as its match data under CONTRIBUTING §6.2.** It holds when no base DTS, + cheetah overlay in `DTB_OVERLAYS` or open PR sets it, and the object diff + shows every new instruction behind the field it fills; for board wiring + (#94's REG_ON flip-flop) it's stricter than the compatible. *Check:* `git + grep ''` on the base's `arch/` and `device/*/overlays/`, then the + per-function object diff. Extends L-206 and L-49. *From:* kernel #94, #95, + round 23; confirmed by the maintainer. +- **L-229. An alternative we offer in a draft is held to CONTRIBUTING like + the main request.** Round 22 offered kernel #88 "or keep the shared lookup + and I'll run it on my phone"; §6.2 lets a Pixel 7 Pro run stand in only for + a deliberate cheetah change with a cheetah reason, and the contributor took + the offer. *Check:* every "or, if you prefer, …" against §6.2 before + posting; if the rule doesn't cover the case, fix the rule first. Extends + L-31. *From:* kernel #88, round 23; confirmed by the maintainer. +- **L-230. Inserting into the middle of a shared struct or enum changes + cheetah's objects outside the touched function.** #62's hook in `struct + exynos_pmu_data` shifted later fields by 8 bytes; #101's new + `sec_device_type` renumbered every later type. *Check:* read each flagged + function's changed instructions (offset-only loads; compares only against + values after the insertion), confirm the reference phone's values sit + before it, and compare data symbols' bytes and relocations base vs head. + Extends L-110, L-111 and L-153. *From:* kernel #62, round 23; kernel #101, + round 24. +- **L-231. A registration that opts out is not a no-op when the core's + default is "needed unless everyone opts out".** gs-decon's + `pm_vt_switch_required(dev, false)` turns the suspend VT switch off on + cheetah, because the PM core switches only while its list is empty or one + entry requires it. *Check:* for a new opt-out registration in a shared + driver, read the core's aggregate rule and list what else registers on the + reference phone. Extends L-206. *From:* kernel #116, round 24. +- **L-232. Before calling a forked guard's behaviour a defect, diff it + against the shared original.** dodge's watcher skips disks with a + `/run/ufs-ro` marker, which looked like a gap; `initramfs/init` does the + same by design. *Check:* `diff` the fork's function against + `initramfs/init` before naming a gap. Extends L-134 and C-1. *From:* #111, + round 24 (a near miss). +- **L-233. A device package's workaround for an Omarchy service is checked + against Omarchy's package list before it stays device-local.** #74 + disables `linux-modules-cleanup` for tegu, but the service comes from + `omarchy-base.packages` and is enabled by Omarchy's installer, so it likely + runs on every phone. *Check:* grep the unit's package in + `/usr/share/omarchy/install/omarchy-base.packages`, `enable-services.sh` and + `rootfs/packages.omarchy-skip`, then ask for one read on cheetah. Extends + L-11 and L-32. *From:* #74, round 24. +- **L-234. A shared script that branches on `/proc/device-tree` makes its + package test host-dependent.** #117's test passes on CI and the laptop, + fails in `makepkg check` on the Pixel 9a it's for, and never runs that + branch. *Check:* every new DT read in a package script has an override the + test uses, and the test runs each branch. *From:* #117, round 24. - **L-8. "Nothing changes for cheetah" is checked by building it.** For any change to `bin/omamobile`, `initramfs/`, `rootfs/`, `tools/` or a shared package: build cheetah's images with main's tool and the PR's, in separate @@ -365,6 +448,12 @@ never change, so reviews can cite them. ## Shell and scripts +- **L-235. An edge-triggered "stop when X" is undone by every other actor + that restarts the thing.** #99 stops neard polling once on the lit-to-dark + transition; the sleep hook, its own unblock path and a neard restart all + start polling again while dark. *Check:* list every writer of the state + (AGENTS gotchas, device packages) and prefer a level check. *From:* #99, + round 24. - **L-14. `$(ls … | tail)` at the top level under `set -euo pipefail` exits the script** silently (status 2) when nothing matches, before any argument is parsed. *Check:* glob-and-pick at the top level of any script @@ -409,6 +498,63 @@ never change, so reviews can cite them. ## Kernel (linux-omarchy-mobile) +- **L-236. A binding's numeric constraints are checked against the stock + value of every phone that may use the property, the reference phone + first.** #95's `multipleOf: 47000` rejects stock cheetah's + `cirrus,vpbr-thld-uv = <3000000>`, which Google's driver rounds down. + *Check:* `grep -rn ` in the stock live DTs, then feed that value + through dt-validate. Extends L-52 and L-102. *From:* kernel #95, round 23. +- **L-237. Before accepting a per-compatible constant for a firmware layout, + check whether the vendor driver reads it from the device.** #93's 14-byte + GT9895 record is right, but Google's driver takes it from + `point_struct_len` in the IC info goodix-berlin already parses. *Check:* + grep the vendor driver for where the value comes from before agreeing to + match data. Extends L-53 and L-72. *From:* kernel #93, round 23. +- **L-238. A Kconfig `select` of a symbol that doesn't exist is silent, and a + sibling that selects the right one hides it.** #114 selects `CS_DSP` (the + symbol is `FW_CS_DSP`); it built because cs40l26-vibra and the CS35L41 + codec select the real one. *Check:* `git grep -n '^config $'` for + every selected symbol, then build with the siblings off. Extends L-20 and + L-143. *From:* kernel #114, round 24. +- **L-239. A board DT is checked against the condition its binding text + states.** Raven's DSIM got `google,decon` ("when no KMS driver runs it") in + the commit that enabled gs-decon's KMS on that DECON, leaving two drivers + doing unlocked read-modify-writes of `TRIG_CON`. *Check:* for each optional + property a board sets, read its binding description and confirm the board + meets it. *From:* kernel #116, round 24. +- **L-240. A board PR is built against the published branch's labels, not + the author's tree.** #98 references `&gph2`, which gs201 has only on the + integration branch. *Check:* for every `&label` a board PR adds, `git grep + '