diff --git a/device/tegu/TELEPHONY-PLAN.md b/device/tegu/TELEPHONY-PLAN.md new file mode 100644 index 000000000..d19766400 --- /dev/null +++ b/device/tegu/TELEPHONY-PLAN.md @@ -0,0 +1,139 @@ + +# Pixel 9a telephony: call audio and starting the modem at boot + +Status (2026-11-03): the SIM test passed on the owner's kernel (MODEM-PLAN, +"SIM test results"), and both parts of this plan have since run on the +palmtop on 2026-11-02 (the daily kernel, +`7.3.0-rc6-omamobile-tegu-s2mpg15-m1-g991042e2eff3-dirty`): speakerphone +calls with audio both ways through section 1's route (#367), and a cold +boot that started the modem and the phone service on its own through +#372's opt-in unit. Section 2 marks which items #363 and #372 do and which +remain targets. +Sources: the 9a's stock vendor image (`vendor_a.img` from the owner's +factory capture, read-only: the audio HAL's configuration and the AoC ALSA +driver), `packages/omamobile-modem*`, MODEM-PLAN and AGENTS.md section 4. + +## 1. Call audio + +### What stock does + +| Direction | Stock PCM | Mixer route | Back end | +| --- | ---: | --- | --- | +| Downlink | 4, EP5 playback | `TDM_0_RX Mixer EP5` = 1 | TDM 0, the TAS2572 speakers | +| Uplink | 11, EP4 capture | `EP4 TX Mixer INTERNAL_MIC_TX` = 1 | the built-in microphones | + +- Built-in microphone list 0, 1, -1, -1; the voice path turns the DC + blocker on, sets the microphone hardware gain to 130 cB and the record + software gain to 0 dB, selects `Builtin_MIC`, and puts the downlink ASRC + in `ASP_ON`. TDM 0 stays at the four slots, S32_LE, 48 kHz the media + profile already uses. +- The HAL opens the voice PCMs as mono S16_LE, 8 kHz, 80-frame periods, + two of them. They carry no speech through userspace: they switch the + AoC's modem path on. +- The handshake is in ALSA: preparing EP5 sends the AoC + `TELEPHONY_MODEM_START`, closing it sends `TELEPHONY_MODEM_STOP`. The + driver also has a conditional CPIF voice-call notifier for power + management. No separate SIT "audio ready" request was found in the + HAL's start path (`SET_AUDIOPATH` and `SET_AUDIO_CLK` exist in the RIL, + but nothing shows this path needs them). + +### The smallest route for one call + +1. Extend `packages/omamobile-modem-sit/lib/voice_audio.py` with a tegu + route: keep its ownership and cleanup, replace its CS35L41 protection + and gain checks (the 9a's amplifiers are TAS2572). +2. Speakerphone first, on the working TAS playback configuration. Stock's + earpiece path selects a separate voice amplifier profile that our setup + doesn't expose. +3. Per call: save the mixer state, mute the call sink, set the microphone + and the two routes, open, prepare and start the voice PCMs once; on + hang-up or any failure restore everything. +4. Gain: set a conservative TAS attenuation after the PCMs start and read + it back before unmuting, because the amplifier profile rewrites gains at + start. PipeWire's -10 dB ceiling doesn't cover this direct AoC route, + and the card's `Voice Call Rx Volume` control has no implementation, so + it can't be the limiter. +5. Before any call: audit the AoC voice memory window. The CPIF overlay + (`overlays/tegu-modem-cpif.dtso`) leaves it out on purpose; whether the + running firmware needs it isn't known. Don't add a guessed mapping. + +Qualification: one announced, attended speakerphone call; speech both ways; +mute and hang-up; no AoC assertion, CP reset or UFS error; media routing +restored afterwards. + +### The safety gap to close first + +If sitd can't confirm a call's release, its safety stop stops the modem in +place (`cp.stop_modem`). On the 9a a stop of the running modem profile by +hand hard-reset the palmtop once (MODEM-PLAN M5), and the unit it targets +(`omamobile-modem.service`) is masked here. The 9a needs its own answer +before the first call: radio off, record, and an attended reboot, never a +stop in place. + +## 2. Starting the modem at boot + +Opt-in and attended at first, with sleep blocked for the boot. + +1. **Packaging first.** *Done in #363.* `omamobile-modem` depends on + `omamobile-device-cheetah`, which conflicts with `omamobile-device-tegu`, + so the 9a's install used `pacman -U -dd`. Replace the dependency with the + virtual `omamobile-modem-policy` (already provided by device-raven), have + each supported device package provide it, and give tegu its own start + policy. `-dd` is never the install method. +2. **One modem service.** *Partly in #372:* `omamobile-tegu-modem-up` is + packaged, with the explicit CP ONLINE check and an opt-in boot unit, and + #371 replaces the copied sitd unit with device drop-ins. *Target:* the + transient unit. Give it tegu's start (today the bring-up script + `/usr/local/bin/omamobile-tegu-modem-up` and its transient unit) with the + AoC's ordering, and drop the copied `/etc/systemd/system/omamobile-sitd.service` + and the transient-unit workaround. sitd starts only after an explicit + "CP ONLINE" check: a unit being active isn't enough. +3. **Preflight before any hardware access:** *Target.* #372 runs the + profile's own check (NV read-only, unmounted, checksums of its RAM + copies), after the drivers load because it needs CPIF's ports; the + up-front NV-only check and the gaps below are still to do. the kernel, DT, firmware, + private provisioning and board properties present; the six NV and + firmware partitions found by `PARTNAME`, read-only, unmounted and + matching the checksums. Today's profile hashes five RAM copies, doesn't + hash `modem_b`, and exempts `persist` from its read-only check: the boot + preflight closes those gaps. A mismatch stops the start; the baseline is + never refreshed automatically. +4. **Two guards:** *Partly in #372:* a boot that has loaded CPIF refuses a + second start, and the latch is written and synced before any driver. *Target:* + keeping it from ONLINE until a clean shutdown. an atomic per-boot "attempted" marker, never cleared in + that boot, and a persistent failure latch written and synced before any + driver loads, kept through the whole phone-service start while this is + being qualified. No automatic CP or sitd restart, module unload, power + cycle or latch clearing. +5. **Sleep:** *Done in #372*, before the drivers and until the reboot. take and confirm the sleep inhibitor before the modem drivers + load, and hold it past sitd and the profile, until shutdown. Keep the + owner's auto-sleep setting as it is; the inhibitor blocks the sleep and + says why. No suspend hook that stops and restarts the modem. Low-battery + actions must not force an unqualified suspend. +6. **Failure stays visible:** *Partly in #372:* the stage is reported and + the latch stays after a failed start, with no retry. *Target:* the shutdown + order through one modem service. the failed stage reported, diagnostics left in + place, no retry. At shutdown, the established order: the phone service's + cleanup, the CP off, then rfsd. + +### 2.7 Enabling the boot start (gated runbook, #372) + +Attended, on the charger, one step per boot. Preconditions: slot B marked +successful, a kernel with linux-omarchy-mobile#172, an off-repo NV backup. + +| Step / risk | Commands | Expect / pass | Stop condition | Rollback | +| --- | --- | --- | --- | --- | +| 1. Read-only / none | `uname -r`; `pacman -Q omamobile-device-tegu omamobile-modem omamobile-modem-sit omamobile-mmd`; `tools/nv-backup --check "$NV_BACKUP"` (laptop); `ls /var/lib/omamobile/modem-bringup-started` | The kernel and packages recorded, NV matches, no latch | NV mismatch, a latch present, B not marked | None | +| 2. Enable / low | `systemctl enable omamobile-tegu-modem-boot` | A wants link, nothing started | Anything starts | `systemctl disable omamobile-tegu-modem-boot` | +| 3. Cold boot / medium (the CP starts at boot, sleep blocked) | Power off, then on; after login: `journalctl -b -u omamobile-tegu-modem-boot`; `omamobile-sit status`; `systemd-inhibit --list`; `tools/phone-smoke` (laptop) | "modem OK: CP ONLINE", sitd running and registered, the inhibitor held, the latch present (it stays until a clean shutdown), phone-smoke clean | No ONLINE, a reset, a UFS or NV error, no inhibitor | `systemctl disable omamobile-tegu-modem-boot`, reboot; after a reset the latch keeps the next boot from starting the modem | +| 4. Clean shutdown / medium (one UFS handler pass expected on the 7 Pro's pattern) | `systemctl reboot`; after login: `journalctl -b -1 -k \| grep -c ufshcd_err_handler`; `ls /var/lib/omamobile/modem-bringup-started`; `tools/nv-backup --check` | The latch gone (clean stop), the CP up again at this boot, the UFS count recorded, NV matches | The latch still there after a clean reboot, I/O errors, NV mismatch | As step 3 | +| 5. A day's use / low | Calls, texts and data as usual | No reset, no latch left over | A reset or hang | As step 3 | + +Record each run here with the date, `uname -r`, the package versions, the +phone-smoke report and the UFS count. + +Qualification, attended and on the charger: boot to ONLINE, data and texts; +the inhibitor; NV and UFS unchanged; then shutdown and reboot on their own. +Suspend with the CP on needs its own tests, with NFC polling stopped, and +incoming texts after resume. The cost until then: the modem on blocks sleep, +so the battery drains as if awake.