diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 609d7a073..43d63d13d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,7 +60,18 @@ Every rule here exists because breaking it either bricks a phone or loses data n - **Qualcomm A/B phones (Pixel 4 family) store the slot flags in the partition table** (GPT attributes), and flashing `boot_b` clears `slot-successful:b`. Marking slot B bootable means writing four GPT sectors on the boot LUN, which the storage guard can't block. It is allowed only as a narrow, per-device exception, written into this section before it is used: the device, the LUN, the sectors (LBAs 1, 2, last-1 and last), the attribute bit and the CRCs it rewrites. The device's plan records the slot flags before and after, the rollback for a corrupted GPT, and the way back (stock restored on slot A first, or the owner's written acceptance of buttons-only recovery). It runs by hand, once per install of slot B's boot image, never from a service or at boot. No device has an entry yet. - **Never relock the bootloader** (`fastboot flashing lock`) while any non-stock image is on the phone. - **Never flash a factory image older than the one installed.** Pixels enforce bootloader anti-rollback. -- Before your first flash, check that both slots carry the same bootloader version (`fastboot getvar all`). If they don't, stop and ask in an issue. +- Before your first flash, check that both slots carry the same bootloader version (`fastboot getvar all`). If they don't, never flash a bootloader partition to fix it: from stock Android, sideload the full OTA for your build twice, so each slot gets the same build. If that doesn't make them match, stop and ask in an issue. + +#### Phones without A/B slots + +Keeping stock on slot A is how we avoid bricking phones during development, not a requirement for every phone. A phone with a single set of boot partitions (no `_a`/`_b` names) can become a supported device. With no second slot, a failed boot can't fall back to stock, so these rules replace the slot B rules above for that phone: + +- **The device's entry comes first.** Before any flash, the port adds its phone here: the codename, the boot partitions the installer writes (normally `boot` alone, plus `dtbo` or `vendor_boot` where the phone needs them), and how to reach fastboot or the vendor's download mode by the buttons. A device PR never writes its own exception into AGENTS.md or this file. +- **We write only the boot partitions the entry names, and `userdata`.** Through `bin/omamobile flash`/`push` and `tools/install-phone`, with the serial pinned, the codename typed, the allowlist checked and a dry run first. No tool may write a partition named on its command line, and nothing is written from a rooted stock Android, where the storage guard doesn't run. +- **A full read-only backup before the first flash,** of every partition except `userdata` and `super`, checked against checksums taken on the phone, stored outside the repository (§3.3). It includes stock's boot partitions, which are the way back: the device's notes say how to write them back by the buttons, step by step, and the owner reads that before the first flash. +- **The storage guard works the same way:** every other partition read-only from the first moment, the allowlist by name. Partitions that hold calibration or identity (`persist`, `modemst*`, `fsg`, `efs` or the phone's equivalents) are never mounted. Read the files you need with `debugfs` or from the backup. +- **The initramfs's no-USB-host panic needs a review for the phone.** On an A/B phone it hands over to stock on slot A; on a single-slot phone it would restart into the same image. The device's descriptor and plan say what happens instead (stay up with the screen lit, or reboot into fastboot) before the first boot. +- **Everything else in this section still applies:** never relock with a non-stock image, never flash an older factory image, the backup rules, the hang safety nets. ### 3.2 The read-only storage guard diff --git a/device/cheetah/REINSTALL-RUNBOOK.md b/device/cheetah/REINSTALL-RUNBOOK.md index 27e3825b3..84d1f1650 100644 --- a/device/cheetah/REINSTALL-RUNBOOK.md +++ b/device/cheetah/REINSTALL-RUNBOOK.md @@ -200,8 +200,10 @@ Expect `product: cheetah`, `unlocked: yes`. Coming from our Linux, the current slot is `b`: `version-bootloader` is slot B's. Compare it with slot A's from the stock capture (`~/android/reference/cheetah-stock-cp2a/fastboot-getvar-all.txt`, taken with slot A current). **Stop** if they differ: setting slot B active -runs slot B's bootloader; flash the same factory bootloader to both from -stock first. If equal, that value is the `--bootloader-slots-match` below. +runs slot B's bootloader. Never flash a bootloader partition by hand +(CONTRIBUTING §3.1); from stock, sideload the full OTA twice so each slot +gets the same build, or ask in an issue. If equal, that value is the +`--bootloader-slots-match` below. On a first install the phone comes from stock Android: slot `a` is current, so `version-bootloader` is slot A's, and there is no stock capture to compare it with. I2's dry run checks the slots, and when the phone reports diff --git a/tools/install-phone b/tools/install-phone index 0adf5040b..0339dca95 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -396,7 +396,7 @@ current_bl=$(var version-bootloader) bl_a=$(sed -nE 's/^version-bootloader[-_:]a:[ ]*//p' <<<"$vars" | head -1) bl_b=$(sed -nE 's/^version-bootloader[-_:]b:[ ]*//p' <<<"$vars" | head -1) if [[ -n $bl_a && -n $bl_b ]]; then - [[ $bl_a == "$bl_b" ]] || die "the bootloader slots differ (a: $bl_a, b: $bl_b): flash the same factory bootloader to both from stock first" + [[ $bl_a == "$bl_b" ]] || die "the bootloader slots differ (a: $bl_a, b: $bl_b). Never flash a bootloader partition by hand (CONTRIBUTING §3.1): from stock Android, sideload the full OTA for your build twice, so each slot gets the same bootloader, then rerun. If that doesn't make them match, stop and ask in an issue" note "bootloader $bl_a on both slots" elif [[ -n $slots_match ]]; then [[ $slots_match == "$current_bl" ]] || die "--bootloader-slots-match $slots_match, but slot ${current_slot:-?} has $current_bl"