Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions device/flame/ABL-PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<!-- SPDX-License-Identifier: MIT -->
# flame: direct ABL candidate, not a verified boot path

Status: 2026-10-26, host assessment only. The measured Pixel 4 installation
still uses U-Boot. The Pixel 4 XL report in
[PR #52](https://github.com/derekross/omarchy-mobile/pull/52),
[BRINGUP-M1 at c0375d7](https://github.com/HemangKumawat/omarchy-mobile/blob/c0375d71e70bbba6a94c7901caa6bc01d3c8ed08/device/coral/BRINGUP-M1.md),
is a candidate recipe for the shared `c2f2-0.5-8906123` bootloader family.
Derek's [review](https://github.com/derekross/omarchy-mobile/pull/52#issuecomment-6428244248)
asks for the missing source branches and slot evidence. Its hardware results
have not been reproduced on flame and do not change flame's device matrix.

## Source and image gates

| Reported ABL requirement | Flame evidence / next gate |
| --- | --- |
| ARM64 Image `text_offset=0x80000` | The retained `7.0.0-sm8150` flame Image has `text_offset=0x0` (read-only host header inspection). Build a published, pinned GPL kernel branch with the reviewed `head.S` change; validate the built header. The current input does not pass this gate. |
| Modern LZ4 frame, magic `04 22 4d 18` | Build from that kernel's uncompressed Image with modern frame compression, then decompress and compare. The gzip payload used by U-Boot is not this ABL input. |
| Two base DTBs with `qcom,msm-id` revisions `<339 0x20000>` and `<339 0x20001>`, `qcom,board-id=<0 0>`, and symbols | Use the public flame DTS and its panel/touch configuration. Publish any source change in the kernel repository; validate both generated DTBs and retain their source pins. Coral's panel/board DTB is not a flame input. |
| Matched no-op `dtbo` entries | Derive count, IDs and revisions from the owner's own flame factory image and retain them privately. The coral MP1.0/index-11 values are evidence for coral only. Review a flame-specific guarded boot/dtbo path before any slot-B write. |

The recipe needs Android header v2 with base `0`, page size `4096`,
kernel offset `0x8000`, ramdisk offset `0x01000000`, tags offset `0x100`,
and DTB offset `0x01f00000`. These values are a reported candidate, not a
flame boot test. The native U-Boot payload instead uses its standard
sentinel base `0x10000000`; the two images must never be interchanged.
Keep image roles and hashes separate.

## Hardware gates after source and host validation

Each step requires the owner's approval, current verified private backups,
physical Android Fastboot access, PID 1's watchdog, external logs and a fresh
independent RAM recovery login. This handset has no bootable stock A;
**recovery is the buttons alone** to Fastboot, with stock B backups ready.

| Step | Expect / pass | Stop condition | Rollback | Risk |
| --- | --- | --- | --- | --- |
| Read-only slot/source check | Own boot/dtbo backups; B active; each slot's success/unbootable/retry flags and available bootloader versions recorded privately; source/header/DT checks pass | Missing or ambiguous evidence | Keep the current installation | Low |
| Separately reviewed candidate boot/dtbo stage | Named `boot_b`/`dtbo_b` writes only through a guarded flame-specific tool path, and only after explicit approval | No reviewed path, slot/size/hash mismatch, exhausted/unsuccessful B | Stay in Fastboot with private stock B images retained | High |
| Approved candidate boot | Guard holds; fresh root and RAM rescue logins; watchdog handoff; readable display | Hang, missing USB/control or unexpected write | Buttons to Android Fastboot | Medium |
| Approved normal/battery restarts | Fresh boot, clear UI, Wi-Fi traffic and protected hashes unchanged | Recovery loop, display fault, missing control | Buttons to Android Fastboot | Medium |

Direct ABL could remove U-Boot and its small-image header-prefix erase.
It does not settle the boot-success policy: writing `boot_b` cleared its
success flag on the measured flame handset. GPT and userdata writes remain
held for the maintainer's named policy decision. No PMIC/PON latch or charger
register mechanism from the coral report is adopted by this assessment.
9 changes: 9 additions & 0 deletions device/flame/BRINGUP-M1.md
Original file line number Diff line number Diff line change
Expand Up @@ -287,3 +287,12 @@ and panic reset have not been exercised on the phone. The provisioning
container integration and root-image smoke test were skipped because their
test image and a completed Omarchy root image were not present. ShellCheck
passed for the new scripts.

## Separate native-root development path (2026-10-19)

The default descriptor and first-light tool above remain RAM-only. The explicit
`FLAME_NATIVE=1` profile, runtime package, source-pinned loader build and
separate userdata/boot-B gates are documented in
[native/README.md](native/README.md), with bounded handset results and
host-only publication changes in [native/RESULTS.md](native/RESULTS.md).
This does not establish a release installer or a healthy stock A fallback.
179 changes: 179 additions & 0 deletions device/flame/native/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
<!-- SPDX-License-Identifier: MIT -->
# flame: experimental permanent installation

Status: 2026-10-19, measured on Pixel 4 with Linux `7.0.0-sm8150`.
Native Arch on ext4 `userdata` and a U-Boot loader in `boot_b` passed the
[recorded restart, display and app checks](RESULTS.md). This is an opt-in
contributor workflow, **not a release installer**. The published loader recipe
has additional host-only changes and needs a fresh approved RAM test.

The ordinary `device/flame/device.conf` remains RAM-only. Only
`DEVICE=flame FLAME_NATIVE=1` selects [native/device.conf (review snapshot)](https://github.com/wirelessjoe/omarchy-mobile/blob/c6ce0c41f58a387f18e4f06a6de1a283698c9500/device/flame/native/device.conf).
The generic `tools/install-phone` still refuses flame. Native `push` and the
Tensor initramfs/image layout are refused; native boot writes go through
`bin/omamobile flash`. Nothing here automatically repairs GPT metadata,
selects a slot, restores calibration, or installs a separate Codex desktop app.

The runtime package must land before native root/build use. Boot plumbing
and SSH options are separate review components. Links to companion files
pin the original review snapshot while those components land; the basic
recovery procedure below is independent of the held GPT proposal.

## Prerequisites and source

Read [proposed BOOT-PLAN](https://github.com/wirelessjoe/omarchy-mobile/blob/c6ce0c41f58a387f18e4f06a6de1a283698c9500/device/flame/BOOT-PLAN.md) and the repository safety rules first.
Obtain the owner's approval for every hardware reboot or write. Keep a current
verified private backup set, matching factory image, physical Fastboot access,
and the exact stock boot/DTBO backups. The tested handset's stock A is
**unbootable**; it is not an available fallback. Restoring Android after this
installation also needs a factory data reset. Never relock the bootloader.

| Component | Source / role |
| --- | --- |
| U-Boot base | Andrew Gigena's GPL flame tree, `0c42ac323aea8368b0624e405ded403351022df2`, [source](https://gitlab.com/andrewgigena/u-boot/-/commit/0c42ac323aea8368b0624e405ded403351022df2) |
| Display fix and standalone configuration | [GPL source](https://github.com/wirelessjoe/u-boot/tree/e210c6956ce90e48b667eb15a8c6f20bc292b52e), pinned by `tools/build-flame-loader`; includes the missing-rotation/stride correction, overflow fixture and compiled-environment checks |
| Linux inputs | The matching kernel, DTB, watchdog and modules listed in [BRINGUP-M1](../BRINGUP-M1.md); documentary firewall additions remain in [kernel-extra.config](../kernel-extra.config) |
| Native root | `omamobile-device-flame` plus the normal Omarchy Mobile packages; the owner supplies local first-boot configuration and SSH keys |
| Wi-Fi | Separate firmware/NV gates below; no Google firmware or device data is distributed |

The automatic U-Boot path waits two seconds, scans UFS, resolves GPT
`userdata`, reads `/boot/omamobile/boot.img` through ext4 and runs `bootm`.
Healthy boots do not wait for USB. Failure enters download-only Fastboot.
The new configuration has a volatile environment and removes EFI/FAT writes,
DFU, USB mass-storage and fastboot OEM run facilities. It is not a hardware
storage guard: never issue interactive U-Boot storage-write commands.

## Build on the host

The loader tool needs a Linux environment with an aarch64 GCC cross compiler,
make, dtc, flex, bison, OpenSSL/UUID development headers and Python 3. Supply
AOSP `mkbootimg.py` together with its `gki/` helpers. It does not use the phone.

```sh
git clone https://github.com/wirelessjoe/u-boot /path/to/u-boot
cd /path/to/u-boot
git checkout e210c6956ce90e48b667eb15a8c6f20bc292b52e
cd /path/to/omarchy-mobile
tools/build-flame-loader --uboot /path/to/u-boot \
--mkbootimg /path/to/mkbootimg.py --out /private/output/loader
```

Build the native Linux payload with `tools/build-flame-system`, using the
same input flags as `tools/build-flame-probe`. Use a fresh output directory.
It verifies Pixel 4/SM8150, ARM64 Image magic and watchdog vermagic. The
native init has a separate initial allowlist of `boot_b userdata`; it never
clears read-only flags or recreates `/dev/sda`. All other UFS nodes remain
protected through the handoff to Arch.

The default native payload disables all remote processors. `--wifi` enables
only `/soc@0/remoteproc@4080000` after checking that its compatible is
`qcom,sm8150-mpss-pas`. It does not supply firmware, start the radio or enable
its service. Keep the other DSPs disabled. The final Android command line
uses `console=tty0` only: a USB console or journal forwarding to ttyGS0 can
stall a restart after unplugging. ACM is available for explicit attached-only
debugging; it is not a standalone boot console.

`DEVICE=flame FLAME_NATIVE=1 tools/build-rootfs --keep-raw` selects the flame
package and ext4 features compatible with the storage loader. It still needs
the normal signed local package repository and the complete matching modules.
The image has no owner, credentials, SSH host keys or Google firmware. A full
new signed root build is not part of the recorded host validation.

## Root preparation and the current write boundary

The native builder selects `omamobile-device-flame`, with first-boot 0.1.3
and shell 0.2.24 hooks. Keep all images, owner configuration, public keys,
firmware and current backup manifests outside Git. Root image preparation
is host-only; this split does not add a userdata flash command. The proposed
userdata write and GPT transaction await the maintainer's policy decision
in [the original review](https://github.com/derekross/omarchy-mobile/pull/17#issuecomment-6428241495).
The generic installer remains unavailable for flame.

The loader plumbing accepts only the checked header-v0 loader or a verified
64 MiB stock header-v2 boot B backup. Every Fastboot query/write is pinned to
one selected handset, using current main's `FASTBOOT_SERIAL` selection. A
loader install requires already-active successful B, erases/writes only boot B,
and stops in Fastboot if the success flag is cleared. It never selects a slot
or starts a GPT repair. Do not repeatedly boot an unsuccessful B.

The native package enables only the storage guard. Its dependencies include
Foot, `xdg-terminal-exec` and `udiskie`. SDDM/user services use the tested
software-rendering fallback. Normal user setup selects 2.5 scale and merges
the tested 0.6 Chrome scale only if Chrome is installed. The helper preserves
other flags and backs up prior files. The upstream AI Agent chooser is used.

## Rescue SSH and its authority

The initramfs listener on `172.16.42.1:22` and the RAM rescue listener on
`172.16.42.1:2222` use the **same builder-supplied `key.pub`**, installed as
`/root/.ssh/authorized_keys` in each filesystem. The second listener survives
`switch_root` in a separate RAM root, with the real root bind-mounted
**read-write at `/realroot`**. Its key grants recovery write access to that
root; a separate process is not a separate credential or storage boundary.
The storage guard still protects other partitions.

The initial rescue listener is IPv4-only. A host using USB IPv6 needs an
explicit USB-only IPv6 RAM listener, a key verified through the trusted Arch
connection and a fresh independently pinned login. Do not assume the root
filesystem's SSH connection proves RAM recovery works.

The `phone-ssh` options support a known scoped USB endpoint, an explicit key
and a strict known-hosts file. Shared connections retain upstream's
`OMAMOBILE_SSH_SHARE=1`, `--fresh` and `--stop`; use `--fresh` to prove that
USB or firewall changes left a new connection possible. There is no LAN scan.

## Gates before another hardware test

These are separate owner-approved operations; the new split is host-tested.
Stock A is unbootable on the measured handset: recovery is **the buttons
alone** to reach Android Fastboot, with the verified stock B backups ready.

| Gate | Expect / pass | Stop condition | Rollback | Risk |
| --- | --- | --- | --- | --- |
| Offline source/image check | Pinned sources, matching modules, checked image header/hash, clean ext4 and private backup set | Missing provenance or any mismatch | Discard local output | Low |
| Approved temporary boot of reviewed loader/native payload | Correct root, absent whole-disk node, protected partitions RO, PID 1 watchdog, clear UI and fresh root/rescue logins | Wrong root, storage/display fault or lost control | Physical Android Fastboot | Medium |
| Optional guarded Wi-Fi start | Current firmware/NV checks, association, bound HTTPS, hashes unchanged | Firmware/storage error or failed-start marker | Independent RAM recovery timer / physical Fastboot | Medium |
| Approved boot B loader write | One handset selected, exact reviewed bytes, active B; stop on clear success flag | Any identity/write/metadata error | Stay in Fastboot; separately approved stock B restoration | High |
| GPT success / userdata write | **Blocked pending a named maintainer policy exception** | No policy decision | Keep current installation and private backups | High |
| Approved connected/battery restart | New boot, clear UI, fresh SSH, Wi-Fi and protected hashes pass | Loop, unreadable display or missing control | Physical Android Fastboot | Medium |

Arm a host log stream, PID 1 watchdog and an independent RAM recovery timer
before a risky driver/USB test. Cancel the timer only after a **fresh** RAM
recovery login. Do not use U-Boot or SCSI writes to work around the pending
metadata policy. [Direct ABL boot](../ABL-PLAN.md) is a candidate from the
Pixel 4 XL report, with no flame hardware result yet.

## Wi-Fi provisioning remains a separate gate

Ship `flame-wifi.service` disabled. The owner supplies matching `rmtfs` and
`tqftpserv`, modem/WLAN firmware, API metadata, and raw factory
`ath10k/WCN3990/hw1.0/board.bin`. Keep generic `board-2.bin` (including
compressed and update-directory copies) outside every firmware search path:
API 2 takes precedence over the tested raw factory board file.

Create private manifests at `/etc/omamobile/flame-calibration.sha256` and
`flame-firmware.sha256`. Calibration paths use unique GPT-name links under
`/run/omamobile/flame-partitions`; LUN letters changed in a measured reboot.
Keep current protected NV copies, mode 0600, in root-only
`/var/lib/omamobile/flame/nv` as `modem_fs1`, `modem_fs2`, `modem_fsg`,
`modem_fsc`. Refresh the backup and copies after any stock Android boot.
The helper verifies current real-partition hashes before using RAM shadows;
rmtfs never gets the protected NV block nodes. Preserve its failed-start
marker until logs have been reviewed. Do not retry a failed radio loop or
load the untested UART pin overlay. Bluetooth stays blacklisted.

## Recovery and limits

To restore only the verified 64 MiB stock boot B backup, stage it with
`FLAME_BOOT_ROLE=stock-recovery`, `UBOOT_IMAGE`, `UBOOT_SHA256`, `DEVICE=flame`
and `FLAME_NATIVE=1`. The flash tool writes only boot B and stays in Android
Fastboot. Restoring Android requires the matching factory data-reset path;
this loses native userdata. Never restore calibration as a routine rollback.
This stock restore role has mock coverage; the full post-native Android
restore/factory-reset cycle has not been performed on the handset.

Hardware acceleration, Bluetooth pairing, modem calls, audio/camera and
release-quality power management are not established by these tests. Large
USB output still needs small verified transfers. The original spontaneous
runtime-reset cause remains unresolved. Read [RESULTS](RESULTS.md) before
interpreting the successful restart tests as general reliability evidence.
Loading