Usage guide

These steps are tested on Meta Quest Pro with rooted Android.

Prepare

Build the modules, target Image and initramfs first. See HOW_TO_BUILD.md.

Boot Android, enable ADB and confirm root:

adb shell 'su -c id'

Capture the current device information:

tools/capture.sh out/captured

This is read-only. It captures the runtime device tree, iomem, command line and kernel configuration.

tools/prep.sh out/captured /path/to/target/Image \
  out/initramfs.gz out/payload

tools/run.sh out/payload

The script copies the module, Image, initramfs and DTB to /data/local/tmp, runs sync, verifies their hashes and starts kexec.

The initramfs exposes USB Ethernet with:

Find the new interface:

ip link

NetworkManager can normally obtain the address from the headset:

nmcli device connect <interface>
tools/shell.sh

If DHCP does not work:

sudo ip addr add 10.42.0.1/24 dev <interface>
tools/shell.sh

Run one command without an interactive shell:

python3 tools/qkx_sh.py 'uname -a'

tools/return-android.sh

After Android returns:

tools/read-log.sh

To capture Android kernel logs over its existing USB gadget before a run:

tools/load-usb-log.sh 60

usb_log.ko intentionally remains installed until Android reboots.