Orchard hub · Guide · Get the full setup · Set up with Claude Code · Test results
Drivers, patches and install scripts that add GPU acceleration, Touch ID and other fixes to Fedora Asahi Remix on Apple silicon Macs. Tested on the MacBook Pro 16-inch M3 Pro (J516S); other Macs need a machine profile.
Part of Orchard, extra drivers and fixes for Linux on Apple silicon Macs.
Community project. It builds on Asahi Linux but is not part of it, and the Asahi developers do not support it. Please report problems here, not to Asahi.
Start here: GUIDE.md. It takes you from a fresh Fedora Asahi Remix install to the tested state, step by step, with undo steps.
| Area | Result on the tested Mac | Details |
|---|---|---|
| GPU | OpenGL 4.6, GLES 3.2, Vulkan 1.4 on the native Mesa driver. KDE runs on the GPU. | GUIDE.md, install/ |
| Memory speed | About 130 GB/s instead of about 32 GB/s, with the PMP memory floor patch | memory-pmp-findings.md |
| Touch ID | Unlocks the KDE lock screen and the login screen. A wrong finger is refused. sudo stays password-only. | touchid.md |
| Video decode | H.264, HEVC, VP9 and AV1 in hardware. Includes a fix for an AV1 driver bug. | audio-camera-video.md |
| Displays and ports | HDMI, DisplayPort over USB-C, USB4 links | display-hdmi.md |
| Bluetooth | Resume fix. AirPods through LibrePods with three local patches. | bluetooth.md |
| Fans | A kernel patch and a fan curve service. Without them the fans stay off. | fans-heat.md |
| Power key | A short press locks the screen. Only a long hold powers off. | power-key/ |
Not done: sleep drains the battery, the Neural Engine is research only, and video encode uses the CPU. The full table is in GUIDE.md, section 3.
Fedora Asahi Remix 44 with the Mac-like KDE desktop from apple-silicon-linux-desktop, running on the native GPU driver.
| Desktop with top bar and dock | Lock screen: password or Touch ID |
| Meta+Space search | Window overview |
| Native GPU driver: OpenGL 4.6 and Vulkan 1.4 | About this System (2026-11-02) |
Each step links to its section in the guide. Each section has the commands, a verify check and an undo step. Do not go on when a verify check fails.
flowchart LR
prep(["Step 1: Prepare<br/><small>backup, rollback rehearsal,<br/>Fedora Asahi Remix 44</small>"]):::hw
build("Step 2: Build<br/><small>kernel, m1n1, Mesa</small>"):::core
install("Step 3: Install stages A to E<br/><small>3 reboots, stock kernel<br/>stays as fallback</small>"):::core
gpu("Step 4: GPU desktop and fixes<br/><small>memory, fans, Bluetooth,<br/>video decode</small>"):::ui
extra(["Step 5: Optional and check<br/><small>Mac-like desktop, Touch ID,<br/>self-test</small>"]):::ai
prep --> build --> install --> gpu --> extra
classDef hw fill:#e8f0fe,stroke:#4a72d9,stroke-width:1.5px,color:#14264d
classDef core fill:#e6f4ea,stroke:#2f8f4e,stroke-width:1.5px,color:#0f3a1f
classDef ui fill:#f3e8fd,stroke:#8e44c9,stroke-width:1.5px,color:#38174f
classDef ai fill:#fdeee0,stroke:#d9822b,stroke-width:1.5px,color:#4a2706
classDef todo fill:#f1f3f4,stroke:#9aa0a6,stroke-width:1.5px,stroke-dasharray:5 4,color:#3c4043
-
Before you start: back up macOS, connect the charger, free 40 GB, and rehearse the rollback.
-
Install Fedora Asahi Remix 44 with the official Asahi installer.
-
Get the kit on the M3, and pick the
j516sprofile. -
Fetch the sources, then build the kernel, m1n1 and Mesa.
-
Install stages A to E. Three of them reboot once. The stock kernel stays your fallback.
-
Desktop on the native GPU (stage G).
-
Feature fixes: memory speed, Bluetooth, fans, video decode, USB-C displays, camera.
-
Mac-like desktop and lock screen from the distro pack. Optional.
-
File sharing with LocalSend. Optional.
-
Touch ID. Optional and advanced. Read its warnings first.
-
Check that everything works. Run the self-test as your desktop user, after each reboot and at the end:
tests/m3-selftest.sh
It prints one line for each check (boot, GPU, display, audio, camera, video decode, ports, network, power, fans and heat, services, storage) with PASS, WARN, FAIL or SKIP. The exit code is the number of FAILs. Use
--quickto skip the GPU load and the camera capture.
To let Claude Code do the work with you, see docs/claude-code-setup.md. It has a ready prompt.
| Test | Result | Source |
|---|---|---|
| GPU readback and render correctness | Exact pixel and integer results | tests/, performance.md |
| GPU shader stress, 10 min | 228 billion pixel-iterations per second, 0 wrong values in 32,621 checks | performance.md |
| Memory bandwidth | 123 GB/s (P cores) and 130 GB/s (GPU) with the memory floor patch, about 32 GB/s without | memory-pmp-findings.md |
| llama.cpp on the GPU | Llama 3.1 8B: 150 tokens/s prompt, 22.7 tokens/s generation | apple-silicon-neural-engine |
| Video decode | H.264, HEVC, VP9 and AV1: 300 of 300 frames each | audio-camera-video.md |
| Touch ID | Lock screen and login unlock with the enrolled finger. A wrong finger is refused. | touchid.md |
| Touch ID install scripts, offline | 50 of 50 pass (tests/touchid-integration-test.sh) |
tests/ |
| Self-test on the M3 (2026-11-02) | 27 PASS, 0 WARN, 0 FAIL. GPU load 20 s with 0 wrong values. Camera 60 frames in 2 s. | test-results-2026-11.md |
| Touch ID speed, lock to unlock | About 1 s with the finger on the key. Unlocks on the clock screen with no key press. | test-results-2026-11.md, touchid.md |
The feature reports in docs/features/ have the full test steps and logs.
| Repository | Contents |
|---|---|
| orchard | The project hub: overview, status and links |
| apple-silicon-linux-kit (this one) | The guide, the patches, and the build, install and test scripts |
| apple-silicon-linux-desktop | The agx installer for other distributions, a Fedora kernel RPM build, and a Mac-like KDE desktop and lock screen |
| apple-silicon-neural-engine | Neural Engine research, and llama.cpp fixes for local LLMs on the M3 GPU |
The Apple GPU is called AGX.
The kit builds a community kernel, m1n1 and Mesa from pinned commits, and installs them next to your distribution's own kernel in small stages that you can undo. The stock kernel stays installed and stays the default boot. The GPU kernel boots only when you select it.
| Machine | Profile | Date | Result |
|---|---|---|---|
| MacBook Pro 16-inch M3 Pro (Mac15,7, J516s, chip revision B1), Fedora Asahi Remix 44 | machines/j516s.sh |
2026-10-26 | OpenGL 4.6, GLES 3.2, Vulkan 1.4; KDE desktop and login screen on the GPU; exact readback and stress tests pass |
Other machines need a profile in machines/ (see machines/README.md). Untested profiles are welcome only with test results.
| Item | Result |
|---|---|
| GPU driver | Accepts the firmware after a one-entry pin (patches/). 18 cores. |
| OpenGL / GLES / Vulkan | 4.6 / 3.2 / 1.4.363, renderer "Apple M3 Pro (G15S B1)" |
| Vulkan compute | Exact results (tests/vk-compute.c). llama.cpp runs on the GPU: Llama 3.1 8B at 150 tokens/s prompt, 22.7 tokens/s generation (with the memory floor patch). Flash attention works with patches/mesa-agx3-fmul-narrow-wait.patch (not yet installed). |
| Memory bandwidth | 123 GB/s (P cores) and 130 GB/s (GPU) with patches/t6030-pmp-memory-floor.patch; about 32 GB/s without it. See docs/performance.md. |
| KDE desktop and login screen | KWin composites with OpenGL on the GPU |
| Render correctness | Exact pixel and integer readback tests pass |
| Shader stress, 10 min | 228 billion pixel-iterations per second, 0 wrong values in 32,621 checks |
| Native display and brightness | Work (3456x2160, /sys/class/backlight/apple-panel-bl) |
| Stock kernel with the GPU boot.bin | Boots normally and keeps the system Mesa |
| Default boot | GPU kernel with the memory floor (stage K, 2026-10-26); stock kernel as the GRUB fallback. First boot as default not tested yet |
| Not done yet | Desktop stress test, sleep |
Details: docs/performance.md and the test log TEST-LOG.html (build it with python3 -I log/build-log.py, then open it in a browser).
- Community project. This is not Asahi Linux code, and the Asahi project does not support it. The tested source set is the community SiliconForest fork (
iconidentify/siliconforest-*, based onomacom/linux-aurora). - Private use. The SiliconForest Mesa contains instruction tables derived from Apple's LLVM AGX3 encoder. Their license status is unclear. Build it for yourself; do not redistribute the binaries.
- Firmware identity. The M3-generation GPU driver accepts only firmware builds it knows by hash. If yours is refused, read
docs/gpu-firmware-investigation.mdbefore you add a pin. Never force an unknown build with the prefix override. - Safe kernel config.
build/build-kernel.shturns off the SEP driver (it writes to xART storage shared with macOS), the user 4K page mode, livepatch and KUnit. Seedocs/gpu-stack-review.md. - Have a way back. Rehearse the macOS rollback in
docs/install-plan.md(section 3) before stage C. It needs SSH from another Mac to the target in macOS, or a keyboard at the target.
- A Mac with a profile in
machines/, and Fedora Asahi Remix (KDE) installed. - About 40 GB free in the home folder for sources and builds.
- The Mac on power, with automatic sleep turned off during builds.
| Path | Contents |
|---|---|
config.sh |
Shared settings. Reads config.local.sh (yours, not in git) and the machine profile. |
machines/ |
One profile per Mac: board, DTB, GPU node, GPU driver, m1n1 options. |
build/ |
Fetch the pinned sources, install build tools, build the kernel, m1n1 and Mesa. No install. |
install/ |
Stages A to K. Each one runs with sudo, checks the machine, and prints what it changed. install/m3-installed/ holds copies of the root-owned files on the tested M3 (old m3gpu names). |
system/ |
Templates for the root-owned files. The install stages fill in the machine's values. |
patches/ |
Kernel patches, for example the J516S B1 firmware pin. |
tests/ |
GPU tests: readback, stress, soak, desktop stress, Vulkan compute, and a Metal version for macOS. |
docs/ |
Research, reviews, the install plan, the firmware investigation, performance. |
log/ |
Generator and overview for TEST-LOG.html. |
Run everything on the target Mac in Fedora, as your normal user, from this folder.
- Pick the profile:
cp config.local.example.sh config.local.sh, then setAGX_PROFILEand any other value you need. - Fetch and build. Only
build/deps.shasks for the sudo password.build/fetch-sources.sh
build/deps.sh
systemd-run --user --unit=agx-kernel build/build-kernel.sh
build/build-m1n1.sh
If the driver later refuses your GPU firmware, apply a pin frombuild/build-mesa.sh
patches/withgit -C ~/agx-work/src/linux apply <patch>and build the kernel again. - Install in stages. Check the output of each stage before the next one.
| Stage | Command | What it does | Reboots |
|---|---|---|---|
| A | sudo install/stage-a.sh |
Backups, pauses automatic boot.bin rebuilds. Then rehearse the macOS rollback. | No |
| B | sudo install/stage-b.sh |
Mesa into /opt/mesa-agx, test kernel as an extra GRUB entry (next boot only). |
No |
| C | sudo install/stage-c.sh |
New m1n1 with the distribution's DTBs, no new options. | Yes, stock kernel |
| D | sudo install/stage-d.sh |
New m1n1 with the test kernel's DTBs, GPU still off. | Yes, test kernel once |
| E | sudo install/stage-e.sh |
boot.bin with the GPU and display options. | Yes, test kernel once |
| F | sudo install/stage-f.sh |
Replace the installed test kernel with a rebuild (for example with a pin). | No |
| G | sudo install/stage-g.sh |
Desktop and login screen on the native Mesa, only on GPU boots. Also installs the no-password tool. | No |
| H | sudo install/stage-h-diag.sh |
J516S only: test kernel image with firmware digest log lines. | No |
| I | sudo install/stage-i-masked.sh |
J516S only: test kernel image that admits the firmware by UUID plus the masked digest. | No |
| J | sudo install/stage-j-memfloor.sh |
T6030 only: test kernel image with the PMP memory floor (memory 4 times faster). | No |
| K | sudo install/stage-k-default.sh |
J516S only: GPU kernel becomes the default boot, stock kernel stays the GRUB fallback, kernel updates keep the default. | No |
Stages H to K are copied unchanged from the tested M3. They still use its old names: ~/m3gpu, /usr/local/sbin/m3gpu-boot, /opt/mesa-m3 and /root/m3gpu-backup. Read each script before you run it on another machine.
- Test (as your user):
tests/build-tests.sh
In an SSH shell, select the native Vulkan driver before any Vulkan test. The desktop session does this for you.nohup setsid tests/soak.sh >/dev/null 2>&1 < /dev/null &
export VK_DRIVER_FILES=/opt/mesa-agx/share/vulkan/icd.d/asahi_icd.aarch64.json
install/setup-nopasswd.sh (also run by stage G) installs /usr/local/sbin/agx-boot and a sudoers rule for exactly these actions:
sudo -n /usr/local/sbin/agx-boot statusOther actions: build-stageE, use-stock, use-stageC, use-stageD, use-stageE, test-once (boot the test kernel once), mesa-select, restart-login, cleanup (removes the rule), and sudo -n systemctl reboot.
A GPU test boot over SSH:
sudo -n /usr/local/sbin/agx-boot use-stageE && sudo -n /usr/local/sbin/agx-boot test-once && sudo -n systemctl rebootsudo install/setup-macos-switch.sh installs asahi-bless and /usr/local/sbin/agx-os, with a sudoers rule for its three subcommands. The default boot volume does not change.
sudo -n /usr/local/sbin/agx-os macos-once && sudo -n systemctl rebootagx-os status shows the default and next boot volumes, and agx-os clear-next cancels macos-once. To return from macOS, restart it normally: Fedora stays the default. Tested on the M3 Pro on 2026-10-26 (set, read back and cleared, no reboot).
- Boot the stock kernel: reboot without
test-once. The default entry is the stock kernel. - GPU options off for every kernel:
sudo -n /usr/local/sbin/agx-boot use-stageD(oruse-stock). - Native Mesa off:
sudo touch /etc/agx-native-mesa.off, then reboot. - Fedora does not boot: the macOS rollback in
docs/install-plan.mdsection 3 putsboot.bin.stockback. - End of testing:
sudo -n /usr/local/sbin/agx-boot cleanup, and removeM1N1_UPDATE_DISABLED=1from/etc/sysconfig/update-m1n1.
These steps rebuild the state of the tested MacBook Pro 16-inch M3 Pro (J516S) on 2026-10-26, from a fresh Fedora Asahi Remix 44 (KDE) install.
- Build with the M3's old names (see
config.local.example.sh): work folder~/m3gpu, Mesa prefix/opt/mesa-m3, kernel7.2.11-m3gpu+. - Kernel: before
build/build-kernel.sh, applypatches/m3-kernel-tree-2026-10-26.patchto the SiliconForest kernel at commit0e1f46661376. That one patch equals the stackg15-j516s-b1-pin.patch,g15-fw-digest-diag.patch,g15-fw-masked-identity.patchandt6030-pmp-memory-floor.patch. The installed image has sha25665798c91.... - Mesa: SiliconForest commit
7515336. Optional: applypatches/mesa-agx3-fmul-narrow-wait.patchfor llama.cpp flash attention. On the M3 this fix is built but not yet installed in/opt/mesa-m3. Built but not installed on the M3 (2026-10-26 21:45, staged in~/m3gpu/out/kernel-7.2.11-m3gpu+-usb4-bt):CONFIG_USB4_APPLE_SOC=m(now inbuild/build-kernel.sh) andpatches/hci-bcm4377-j516s-resume-recovery.patch. The kernel image is the same. Only two modules differ: the newthunderbolt_apple.koand a changedhci_bcm4377.ko. - Run stages A to G, then I, J and K. Stage H is a diagnostic step that stage I replaces. Stage F is only for a rebuilt kernel; stages I and J do the same for their images.
- Optional:
sudo install/setup-macos-switch.sh(boot macOS once without a password). - Test:
tests/mem-shared.sh(expect about 120 GB/s for the P cores and 130 GB/s for the GPU) andane-linux/llm/stage0.sh bench.
Only on the M3, not in this repository:
- The GPU firmware. Fedora extracts it from macOS during the Asahi install; it is not redistributable.
- The source trees and build folders in
~/m3gpu(src,build-linux,build-mesa,out). The kernel and Mesa edits are saved here as patches. - Backups in
/root/m3gpu-backup(one folder per stage) and/root/agx-backup(stage A). - The action log
/var/log/m3gpu/actions.log. - llama.cpp, the models and the results in
~/llm-work. - The full Apple device tree dumps (machine identifiers), kept only in a private folder on the host Mac.
The first install (2026-10-26) used the names m3gpu-boot, /etc/sudoers.d/m3gpu, m3gpu-mesa-select and ~/m3gpu. install/setup-nopasswd.sh and stage G remove those files and install the agx-* ones. Keep the old work folder, kernel suffix and Mesa prefix with the commented values in config.local.example.sh.
| File | Topic |
|---|---|
docs/whats-in-the-repo.md |
Every kernel and Mesa change, and where its patch is |
docs/performance.md |
Benchmarks, soak results and the comparison plan |
docs/gpu-firmware-investigation.md |
Why the firmware was refused, and the pin |
docs/upstream-report-draft.md |
Report for SiliconForest, posted as chriskearney/siliconforest-linux#20 (docs/upstream-issue-title.txt, docs/upstream-issue-body.md hold the exact posted text) |
docs/features/ |
Feature test reports on the M3: audio, camera and video; display and HDMI. More reports follow when their tests end |
docs/memory-pmp-findings.md |
Why memory was slow, and the PMP memory floor fix |
docs/install-plan.md |
Install plan, stage results, macOS rollback |
docs/build-status.md |
Build notes and problems |
docs/gpu-stack-review.md |
Review of the SiliconForest kernel, m1n1 and Mesa |
docs/asahi-m3-pro-status.md |
What Asahi supports on the M3 Pro, with sources |
docs/feasibility.md |
How the missing parts could be finished |
docs/rea-plan.md |
Plan for a private reverse-engineering toolkit |
docs/asahi-install-findings.md |
Notes from the Fedora Asahi install |
The documents in docs/ record the work on the tested machine. They use the names of that time (m3gpu, ~/m3gpu/scripts).
The scripts, tools and documents in this repository are under the GNU General Public License version 2 (LICENSE).
A patch is a change to another project's code. Each patch keeps the license of the project it changes:
| Patches | Project | License |
|---|---|---|
patches/g15-*, patches/t6030-*, patches/avd-*, patches/hci-*, patches/macsmc-*, patches/m3-kernel-tree-*, patches/touchid/ |
Linux kernel | GPL-2.0 |
patches/mesa-* |
Mesa | MIT |
patches/librepods-* |
LibrePods | The LibrePods license |
The GPU firmware is not in this repository. Fedora Asahi Remix copies it from macOS during the install.
This work is built on the Asahi Linux project and on the community SiliconForest fork. Thanks to their developers.