quest-kexec/HOW_TO_PORT.md

# Porting to another Meta Quest kernel

This implementation has only been tested on Meta Quest Pro. Other Quest models
use different SoCs, device trees, memory maps and hardware handoff states.

## Same headset, newer kernel

1. Get the source matching the new Android release.
2. Build `quest_kexec.ko` against its exact config, local version and
   `Module.symvers`.
3. Apply the patches under `kernel/patches/` to the new target source.
4. Resolve conflicts carefully in the affected drivers.
5. Capture a fresh runtime device tree with `tools/capture.sh`.
6. Test first with the supplied RAM-only initramfs.

Important target areas include:

- ARM64 entry and CPU startup
- GIC and SMMU inherited state
- RPMh and interconnect voting
- display clocks and power domains
- USB controller and PHY handoff
- AOP/QMP mailbox adoption
- SPMI and charger state
- retained logging and watchdog recovery

## Another Quest headset

Do not reuse the Quest Pro physical addresses or device names without checking
them. At minimum, determine:

- target Image, initramfs and DTB staging addresses
- safe retained-log RAM
- target kernel text offset and maximum image size
- CPU, GIC and SMMU setup
- USB controller and UDC name
- watchdog behavior
- platform-device names used by loader shutdown callbacks
- AOP/mailbox protocol used by that SoC

Update `module/loader.c`, `module/transition.S`, `tools/prepare.py` and the target
kernel patches for the new board.

## First test

Keep the first target small:

- static BusyBox initramfs
- no block-device mounts
- USB Ethernet only
- retained kernel log enabled

Verify CPUs, USB and basic device probing before adding a larger userspace.

Do not disconnect the AOP QMP link on Quest Pro. The tested implementation
adopts the inherited link with `qkx_qmp_adopt=1`.