Thorch

Thorch is an experimental Arch Linux ARM image for the AYN Thor, built on top of public ROCKNIX work. It syncs ROCKNIX's SM8550 kernel recipe, patch stack, Thor DTS overlays, firmware, runtime graphics pieces, FEX assets, device configuration, handheld package patch sets, and ABL-compatible boot layout.

Join the Thorch Discord to follow development, test builds, or help inform future development.

What Thorch adds is an Arch root filesystem, a ROCKNIX-derived Thor kernel with Thorch's BinderFS/Waydroid config fragment, a Thorch initramfs repacked into the ROCKNIX-compatible boot image, local Arch packages, KDE defaults, handheld input/gaming integration, debug tooling, and an internal installer around that base.

The first target is a bootable SD image for bring-up, diagnostics, and internal installation. Internal install is the intended performance path, but SD remains the recovery and staging path.

Current Scope

• Arch Linux ARM aarch64 root filesystem.
• Local packages for the ROCKNIX-derived Thor kernel artifacts, firmware/runtime artifacts, board support, KDE defaults, internal install, FEX runtime, ROCKNIX-patched Gamescope, InputPlumber maps, ROCKNIX SM8550 quirks, MangoHud, and firstboot-driven Steam/gaming setup.
• Plasma Desktop Wayland as the default session while Thor touch is being stabilized.
• Plasma Mobile Wayland is optional, and SteamOS-mode helpers can temporarily switch the shell/launcher flow for gaming tests.
• InputPlumber-based gamepad mapping for the AYN/RSInput MCU path.
• ROCKNIX-derived SM8550 handheld hints for audio, thermal, CPU/GPU frequency paths, modifier buttons, touchscreen, and MangoHud support.
• USB RNDIS debug gadget with SSH on 10.66.0.1 when connected to a host.
• Thor joystick RGB helper with battery-status, static color, off, and opt-in ambient desktop color modes.
• ROCKNIX ABL-compatible FAT boot partition.
• Top-level /KERNEL Android boot image repacked from the ROCKNIX boot-image template with Thorch's BinderFS-capable kernel, initramfs, and image root UUID.
• Internal installer that formats selected Linux boot/root partitions and never flashes ABL.

ROCKNIX Inputs

This project would not boot on Thor without ROCKNIX. The Qualcomm SM8550 and AYN Thor enablement lives there, so a clean Thorch build expects real public ROCKNIX inputs rather than files generated by this repository alone.

We are super grateful for that work. Thorch exists because ROCKNIX made the Linux boot path practical enough to build on.

Thorch is not affiliated with ROCKNIX or its maintainers. It uses public ROCKNIX work as upstream hardware enablement and tries to keep provenance, authorship, and license notices clear.

Thorch currently syncs or imports:

• Official ROCKNIX SM8550 image artifacts: /KERNEL boot-image template, selected /SYSTEM runtime files, and FEX runtime files.
• Public ROCKNIX firmware, filesystem overlays, device configuration, package patches/configs, quirk metadata, kernel metadata, and related platform files.
• ROCKNIX handheld gamescope patches, MangoHud SM8550 GPU support/config, and InputPlumber device/capability map inputs from the synced public source tree.
• The ROCKNIX-compatible Thor ABL boot layout, including the FAT boot partition label ROCKNIX.

The Arch Linux ARM userspace, local packages, initramfs, KDE defaults, debug gadget, etc, are Thorch's layer on top. Thorch is unofficial and is not endorsed or supported by ROCKNIX.

Experimental Status

Thorch is hardware bring-up work, not a supported operating system release. Use it only on a test device you can recover.

Builds may fail to boot, lose input/display/networking, corrupt an install attempt, require manual recovery, or need a full reinstall. Read scripts before running them, especially anything that writes block devices.

The internal installer formats selected Linux boot/root partitions. The explicit --create-from-userdata mode shrinks Android userdata by deleting and recreating it smaller, which wipes the Android instance stored there. Thorch v1 does not flash or replace ABL, but block-device mistakes can still make a device painful to recover.

AI Disclosure

This project uses aggressive AI assistance for research, patch archaeology, documentation, scripting, debugging, and general "what if we tried this?" engineering chaos. AI-generated changes still need human review, hardware testing, and attribution checks before they are treated as trustworthy. Assume the machines are helping loudly, not driving unsupervised.

Quick Start

These commands are for workshop/test devices only. Read the scripts and the safety notes before running them.

Install host dependencies on an Arch-like build host:

sudo pacman -S --needed base-devel curl devtools dosfstools e2fsprogs git gptfdisk jq libarchive mtools pacman-contrib qemu-user-static qemu-user-static-binfmt rsync squashfs-tools systemd util-linux

Sync public ROCKNIX sources and firmware:

make sync

This populates vendor/rocknix-sm8550 with public firmware, source overlays, InputPlumber data, ROCKNIX package patch/config inputs, and SM8550 quirk metadata. It also records source provenance for later audits.

Sync matching ROCKNIX runtime artifacts and build the Thorch kernel. By default this downloads the latest official ROCKNIX SM8550 nightly, verifies its .sha256, extracts the boot-image template and FEX runtime artifacts, writes them to vendor/rocknix-kernel and vendor/rocknix-runtime, then source-builds a ROCKNIX-derived Thor kernel with BinderFS support:

make kernel

You can also import manually from a mounted or extracted ROCKNIX image. The import needs a real ROCKNIX /KERNEL and matching modules; the make target then rebuilds the Thorch BinderFS kernel against that imported boot template/runtime unless THORCH_KERNEL_SOURCE_BUILD=0 is set for diagnostics:

make import-kernel BOOT_DIR=/mnt/rocknix-boot ROOT_DIR=/mnt/rocknix-root KERNEL_REF=<rocknix-build-label>

A clean build needs real ROCKNIX image input. Do not satisfy this step from previous Thorch build artifacts, local makepkg package directories, or smoke-test kernel trees; those paths are intentionally rejected. make build and make packages will run the ROCKNIX kernel/runtime sync when kernel or FEX artifacts are missing, and will run the public source sync when package patch/config inputs are missing.

Build the image. The default password/PIN for the default user and root is 1234; override THORCH_PASSWORD when you want a different one:

make build

The Arch Linux ARM rootfs tarball is verified before extraction. By default the builder downloads the matching detached .sig, fetches the pinned Arch Linux ARM signing key into a temporary GPG keyring if needed, and verifies the signature. Alternatively set ALARM_ROOTFS_SHA256 to a pinned tarball hash for hermetic builds.

For package/default/service iteration, use the fast path. It rebuilds only missing or stale local Thorch packages, refreshes the cached rootfs when one exists, regenerates boot artifacts, and reassembles the image. If build/image-rootfs does not exist yet, it is created from the local package repo after the package refresh. The fast path skips rebuilding linux-thorch by default when a kernel package already exists; run scripts/build-image-fast.sh --with-kernel directly when kernel package changes also need to be rebuilt:

make fast

Write the image to a removable SD card. The writer refuses mounted devices and does not mount or unmount anything. make write validates the image first, including that /KERNEL is an Android boot image with the Thor DTB embedded:

make write DEVICE=/dev/sdX

Validate an existing image:

make check

You can also validate a written SD card by passing the whole block device:

make check IMAGE=/dev/sdX

The Makefile is a thin wrapper around scripts/. Use the scripts directly when you need non-default options. See docs/build.md and docs/package-layout.md for deeper build and package notes.

The default image package set is: linux-thorch thorch-bsp thorch-firmware-rocknix thorch-kde-defaults thorch-firstboot thorch-installer thorch-fex-bin thorch-gamescope thorch-gaming-installers thorch-waydroid-installer thorch-inputplumber thorch-rocknix-quirks thorch-mangohud thorch-gamepadcalibration. Override THORCH_IMAGE_PACKAGES when you need a custom image package set.

thorch-firstboot starts a fullscreen QML onboarding flow on first login for Wi-Fi, SD-vs-internal install intent, default mode, user/password setup, theme selection, Steam/Waydroid setup when selected, and safe in-window automatic SD expansion/internal install actions. A footer Skip action is available from every page to mark firstboot complete and leave the setup flow if the user gets stuck or wants to configure things later.

thorch-inputplumber installs InputPlumber's upstream rootfs contents and overlays only the Thor input maps. The image builder enables its service only when that package/unit is present, so custom package sets can omit it.

After first boot from a larger SD card, the firstboot flow grows the booted root partition and ext4 filesystem to fill the card unless you choose internal storage. The expander only operates on the mounted / device and accepts either removable media or the expected two-partition Thorch SD layout.

thorch-kde-defaults pulls in Firefox and the core KDE desktop applications: Ark, Dolphin, Gwenview, Kate, KCalc, Konsole, Okular, and Spectacle.

RGB controls are documented in docs/rgb.md, including static colors, battery-status mode, brightness, and temporary color application. Ambient RGB mirroring is installed but left disabled for experiments. Start it with sudo systemctl start thorch-rgb-ambient.service; enable it only after it behaves well on the target hardware.

Fan curve tuning is documented in docs/fancontrol.md, including the built-in quiet/moderate/aggressive profiles and custom temperature-to-PWM curves.

First Boot Debug

The image enables SSH and a USB Ethernet gadget for bring-up. Connect the Thor to a Linux host over USB-C, wait a few seconds after boot, then try:

ssh thorch@10.66.0.1

The SSH password/PIN is the build-time THORCH_PASSWORD, defaulting to 1234. Each boot writes /boot/thorch-debug-report.txt so a failed Wi-Fi/touch test can be inspected by moving the SD card back to the build host.

If the device reports no match found for DTB!, it is still in the bootloader; SSH will not be available. That usually means the top-level /KERNEL on the FAT boot partition is not the rebuilt Thorch Android boot image. Re-run make check IMAGE=/dev/sdX against the SD card and rebuild or rewrite the image if the /KERNEL DTB check fails.

Thorch keeps the FAT boot filesystem labelled ROCKNIX for compatibility with the imported ROCKNIX boot image conventions, but the current evidence does not prove that Thor ABL chooses Linux media by that filesystem label. The practical boot contract is a FAT/ESP-style partition with a top-level /KERNEL Android boot image.

If an internal Thorch install is present and ABL loads the internal /KERNEL before the SD card's /KERNEL, Thorch's initramfs now prefers an inserted Thorch SD root automatically. It detects the expected two-partition SD layout: ROCKNIX FAT boot plus THORCH_ROOT ext4 root on the same mmcblk card. Pass thorch.sdprefer=0 on the kernel command line to disable this behavior.

Internal Install

Internal install is not recommended unless this is a disposable test device and you have a known-good recovery path.

Boot the SD image first, then choose the internal Linux boot and root partitions explicitly:

sudo thorch-install-internal --boot-device /dev/<linux-boot-partition> --root-device /dev/<linux-root-partition>

The installer refuses to run unless / appears to be on removable media. It also rejects common Android partition labels, backs up existing boot files when readable, formats only the selected partitions, rebuilds /boot/KERNEL, and validates the boot layout.

Without device arguments it can auto-detect one existing internal ROCKNIX/Thorch target. It only shrinks and wipes Android userdata when launched explicitly with --create-from-userdata and confirmed with SHRINK USERDATA.

The first-boot internal install path uses that explicit create-if-needed mode after you accept the internal-storage data-loss warning: it installs to an existing ROCKNIX/Thorch target when one is present, or creates a target from the unique Android userdata partition at the Android size selected in firstboot when no existing target is found. If Android userdata is already smaller and there is post-userdata space from a previous interrupted install, Thorch reuses that space instead of shrinking userdata again.

Warning: shrinking Android userdata is destructive. It deletes and recreates the userdata partition, so the existing Android instance, apps, settings, and local data on that partition are wiped.

Upstream Provenance

Thorch has its own source tree and packaging, but today the hardware side comes from ROCKNIX and other public upstreams:

• ROCKNIX/distribution
• Arch Linux ARM
• Linux kernel upstream
• KDE Plasma and Plasma Mobile

See docs/provenance.md for details.

Thanks

Thank you to the ROCKNIX maintainers and contributors for the Thor and SM8550 work that makes this project possible. Thorch also builds on work from Arch Linux ARM, Linux, KDE Plasma, FEX-Emu, Mesa/Freedreno, Qualcomm platform maintainers, and the handheld Linux community.

Thank you to AYN for creating the Thor.

Mentioning these projects is gratitude, not an endorsement claim. Thorch is an unofficial experiment.

Safety

This targets a Qualcomm Android handheld with an existing Linux-capable ABL path. Keep Android recovery and a known-good SD card available. Thorch v1 does not flash or replace ABL. Treat every image and install command in this repository as experimental and unsuitable for devices you depend on.