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 opt-in SSH on 10.66.0.1 after account setup.
• Thor joystick RGB helper with battery-status, static color, and off 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, ROCKNIX handheld DTB set, Thor-specific initramfs, asymmetric-CPU compatibility argument, and image root UUID.
• Ext4 or compressed Btrfs roots, auto-sized around the populated system with configurable free-space headroom.
• A 512 MiB tmpfs for the selected user's cache by default to reduce Firefox and KDE write amplification on SD cards.
• 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 does not flash or replace ABL, but block-device mistakes can still make a device painful to recover.

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 btrfs-progs 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. With no override, the Makefile reads the pinned ROCKNIX_REF from config/thorch.conf; pass a different full commit only when deliberately updating the hardware baseline.

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. The requested source and kernel refs live in config/thorch.conf; generated PROVENANCE files record the exact resolved inputs used by each build:

make kernel

Package and image builds compare the recorded kernel release and installed module tree with THORCH_KERNEL_REF; stale or mismatched artifacts are rejected instead of being silently packaged.

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 user and root accounts remain locked until firstboot applies the password chosen by the device owner. For a local-only bring-up image, an explicit THORCH_PASSWORD seeds both accounts; never use a shared value for a published image:

make build

SSH starts by default, but password authentication remains unavailable until firstboot provisions the owner's password. For a local image that must accept remote verification immediately, seed an explicit throwaway password:

THORCH_PASSWORD='<local-test-password>' THORCH_ENABLE_SSH=1 make build

Btrfs is the root default, with zstd compression enabled for SD-card and nightly images. To build an uncompressed ext4 root instead:

THORCH_ROOT_FSTYPE=ext4 make build

Auto-sized images remove package caches and retain 1 GiB of root headroom by default. Btrfs population goes through a kernel mount with zstd compression, then every file is read back before the raw GPT image is assembled. This avoids invalid compressed extents produced by affected btrfs-progs offline --rootdir compression paths for some already-compressed files.

For a ROCKNIX-style containerized build, use the project builder image and run the same make target inside Docker or Podman:

make docker-image-pull || make docker-image-build
make docker-build

Nightly GitHub Actions image builds are documented in docs/nightly-actions.md. They run on GitHub-hosted Ubuntu using the same make docker-nightly builder path and the plain chroot rootfs backend; no self-hosted Arch runner or nested systemd-nspawn is required. The container wrapper disables SELinux relabeling on the workspace bind mount for Docker-on-SELinux hosts.

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 root UUID, allow_mismatched_32bit_el0, BinderFS support, exactly one symbol-bearing Thor DTB, and no generic AIM300 DTB:

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 ordered default package set is defined once in manifests/packages.json. Inspect the image profile with python3 scripts/package-manifest.py profile image --format space. Override THORCH_IMAGE_PACKAGES when you need a custom image package set. See docs/package-maintenance.md for package input, version, and isolated-build rules. See docs/update-safety.md before testing package upgrades on an installed system.

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. Its package owns the service preset; image composition applies the presets supplied by the selected packages, so custom package sets can omit it without editing the image builder.

After first boot from a larger SD card, the firstboot flow grows the booted root partition and its ext4 or Btrfs 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.

To cut down on tiny browser and desktop writes on SD cards, new images mount the default user's ~/.cache as tmpfs (THORCH_USER_CACHE_TMPFS_SIZE=512M). Set THORCH_USER_CACHE_TMPFS_SIZE=0 before building if you want cache data to stay on the root filesystem. If firstboot renames or creates the selected user, it retargets the tmpfs entry to that user's home and numeric UID/GID.

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.

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

Published images start SSH but do not contain a shared password. Complete firstboot so the selected account has its owner-chosen password. SSH can then be turned off or back on with the quick setting, or managed directly with:

sudo systemctl enable --now sshd.service

Connect the Thor to a Linux host over USB-C and use the selected username:

ssh <username>@10.66.0.1

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. The checker parses the compressed kernel and appended DTB table rather than searching arbitrary boot-image bytes, so a Thor string in the ramdisk cannot create a false pass.

An early CPU_OUT_OF_SPEC taint or Unsupported CPU feature variation message means the boot command line is missing ROCKNIX's allow_mismatched_32bit_el0 compatibility argument. Current images preserve it, and make check rejects images that do not.

Thorch matches the imported ROCKNIX qcom-abl disk contract: the FAT boot filesystem is labelled ROCKNIX, starts at the 16 MiB offset, and lives in a Microsoft Basic Data GPT partition named system with the legacy-boot attribute. Its top-level /KERNEL is an Android boot image. This metadata is intentional; a generic EFI System Partition does not reproduce the known-good ROCKNIX layout.

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 a THORCH_ROOT ext4 or Btrfs 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.

Internal install uses the running SD root filesystem type by default, so a Btrfs SD image produces a compressed Btrfs internal root and an ext4 image produces ext4. Set THORCH_ROOT_FSTYPE=ext4 or btrfs explicitly to override that choice; Btrfs mount options come from THORCH_BTRFS_MOUNT_OPTIONS.

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.