M3-family support: SoC detection, software rendering, M3 installer path, branch kernels

[staccDOTsol]

Summary

Makes Omarchy Mac installable and usable on M3, M3 Pro and M3 Max Macs on the public Asahi trees as they are today, and shaped so the day Asahi ships the M3 display driver and GPU driver nothing here needs a migration.

Where Asahi is (September 2026): the kernel Asahi Alarm ships (7.1.6) has device trees for every M3 machine, m1n1 1.6.1 boots them, and Asahi's own installer (0.9.x) lists them in expert mode against firmware 14.8.3. What is in no public tree: the M3 display driver wiring and any M3 GPU (G15) support in the kernel driver or Mesa. Asahi says an official M3 release is weeks away; the GPU is later.

• bin/omarchy-hw-apple-soc — generation from the device tree (m1..m4), codename, and --gpu: whether the Asahi GPU driver is actually bound. Everything keys off that rather than a model list.
• Software rendering when there is no GPU driver — vulkan.sh installs vulkan-asahi only when the driver is bound; default/hypr/apple.lua (loaded from envs.lua next to nvidia.lua) sets AQ_NO_MODIFIERS, software cursors, no direct scanout and vfr, checked at every session start so a kernel that binds the driver turns them off by itself. install/hardware/apple/m3.sh says on the console what the machine will not do.
• bin/omarchy-mac-asahi-install — runs on macOS (bash 3.2). Two things stop the stock Asahi Alarm bootstrap on an M3. First, Asahi Alarm's installer package (0.8.4) is an older asahi-installer build whose device table ends at M2, so it exits with "This device is not supported yet!" before asking anything, and the expert-mode question only appears when EXPERT is set. Second, installer_data.json lists no image against firmware 14.8.3 (Add M3, M3 Pro and M3 Max devices using macOS 14.8.3 OTA AsahiLinux/asahi-installer#424, Add llmman to Install > AI and Remove > AI #438). The wrapper fetches Asahi Alarm's package, checks its device table, and when M3 is missing fetches Asahi's own installer from cdn.asahilinux.org and runs it against Asahi Alarm's image list and images (the installer is data-driven; the package layout is identical). It adds "14.8.3" to every supported_fw, sets EXPERT=1, briefs the user, and hands over. The day Asahi Alarm rebuilds its installer with the M3 table, the wrapper uses it with no change. On M1/M2 it runs the stock package and data unchanged.
• pkgbuilds/linux-asahi-wip + bin/omarchy-mac-kernel-wip — build any branch of any Asahi fork with Asahi Alarm's kernel config and install it alongside linux-asahi (GRUB lists both). The branch is a build-time choice, so the M3 display branch is a one-line change when it is public.
• Docs — docs/apple-m3.md, README step 1 M3 variant, manual note, and an M3 warning in omarchy-mac-setup before "Start?".

Test plan

• test/shell.d/apple-soc-test.sh — 15 cases against stubbed device trees and sysfs
• test/shell.d/apple-m3-test.sh — leaf wiring, vulkan gating, envs.lua, PKGBUILD parses and does not conflict, installer wrapper parses under bash 3.2, falls back to Asahi's package and enables the expert question, installer_knows_m3 against an M2-only and an M3 table, patch_installer_data against multi-line / one-line / already-present / empty / null lists, idempotent, target-name mapping
• tests/test-asahi-compatibility.sh passes
• Wrapper run on a MacBook Pro 16 M3 Pro (J516s, macOS 26.6.2): detects Asahi Alarm 0.8.4 as M2-only, fetches Asahi 0.9.1, patches the five image entries, prints the briefing, reaches the installer's sudo prompt
• Full install on that machine — next step, will report back

🤖 Generated with Claude Code

[malik-na]

• Set AQ_NO_MODIFIERS=1 before Hyprland starts (for example in the UWSM environment). Setting it from apple.lua happens after Aquamarine initializes, so the M3 workaround may not apply.

• Do not promise that the released kernel is a safe GRUB fallback. update-m1n1 installs the WIP kernel’s DTBs into the shared boot.bin, so both kernel entries can fail with incompatible DTBs. Add a real boot-image rollback path or document recovery via boot.bin.old.

[malik-na]

Can you look at this as well, @scottjones ?

[scottjones]

Reviewed the SoC detector here against #326, which adds a second one. Ran both on an M2 Max (apple,j414c, t6021) and against stubbed device trees for the IDs where the two tables disagree.

bug: t6032 — M3 Ultra — is missing, so detection fails outright on a Mac Studio M3 Ultra.

SoC     #326                            #343 --gen
t8122   m3                              m3
t6030   m3-pro                          m3
t6031   m3-max                          m3
t6032   m3-ultra                        <empty>  rc=1     <-- fails
t6040   unconfirmed-compatible  rc=1    m4
t6050   unrecognized-compatible rc=1    m4

--gen returns empty with rc=1, which every caller here reads as "not an Apple Silicon machine." So install/hardware/apple/m3.sh, the software-rendering apple.lua, the vulkan.sh change and the M3 installer path would all silently not activate — in the PR whose purpose is M3 support. One line in the case.

I should be honest about provenance: t6032 = M3 Ultra is #326's claim, sourced to a pinned Asahi SoC table. I have not verified it against Asahi upstream myself, though the pattern holds (t6002 = M1 Ultra, t6022 = M2 Ultra) and Apple did ship an M3 Ultra. Worth settling between you and @CptPanko, since one table has it and the other doesn't.

suggestion: t6040, t6041, t6050 and t6051 are claimed as m4 with no cited source, where #326 deliberately returns unconfirmed-compatible for t6040/t6041 and says in its description that it keeps M4 Pro/Max reserved until primary root-DTS or live device-tree evidence exists. Lower stakes since M4 is not supported either way, but it is an unsourced claim in a table other code will trust.

The --gpu check is the best idea in either PR, and I verified it is correct. On this machine:

/sys/class/drm/card1                        driver=asahi
/sys/bus/platform/drivers/asahi/406400000.gpu   present
omarchy-hw-apple-soc --gpu                  -> 0

Both of your sysfs views fire, no false positive. Keying the software-rendering decisions off "is the driver bound" rather than "which generation is this" is the right abstraction — a generation table goes stale the day Asahi ships an M3 driver, the binding check never does, and vulkan.sh and apple.lua correct themselves on the next session. #326 has no equivalent.

The duplication

There are now three device-tree detectors in flight:

PR	command	does
#331 (@malik-na)	omarchy-hw-apple-silicon	boolean: is this Apple Silicon
#326 (@CptPanko)	omarchy-hw-apple-silicon-generation	device tree -> M1..M4, granular (m2-max)
this	omarchy-hw-apple-soc	device tree -> m1..m4 + codename + --gpu

Different filenames, so git will not stop any of them and we could land all three. My read is that this PR has the better shape and #326 has the better table: yours is env-stubbable (OMARCHY_APPLE_COMPATIBLE) like every other omarchy-hw-*, has --gpu, and is 96 lines against 197; #326 is better sourced, has t6032, and correctly refuses the unconfirmed M4 rows. The merge of those two is the command I would want.

Granularity is a real interface decision someone should make deliberately rather than by merge order — m2 plus --codename versus m2-max. Worth you and @CptPanko agreeing rather than both landing.

nit: install/hardware/vulkan.sh is also touched by #331, the one file you overlap on.

One heads-up that is not stale, despite the commit name. bf040df9a is titled "Fix bin-style test: drop raw command -v in M3 helper scripts", but the branch still carries this:

-  | rg -v '/omarchy-(cmd-|pkg-|upgrade-to-quattro|mac-setup$|system-...)'
+  | rg -v '/omarchy-(cmd-|pkg-|upgrade-to-quattro|mac-(setup|asahi-install)$|system-...)'

#289 fails the same lint rule and I have asked it to delete its command -v line rather than widen that regex. If this PR keeps the allowlist entry, the two collide on a single line. Dropping command -v from omarchy-mac-asahi-install too would leave that file untouched and avoid it.

[malik-na]

Still blocked on the existing AQ_NO_MODIFIERS timing and boot.bin rollback points. Please also reconcile the SoC detector with #326 so we do not ship two overlapping interfaces or lose the t6032 mapping.

[pkyanam]

I prepared a focused follow-up for the m3 branch: staccDOTsol/omarchy#4.

It corrects the stale M3 briefing (webcam/video decoding are supported; sleep is unavailable), updates docs/apple-m3.md, and rejects the unsupported M3 Ultra path before any installer fetch. The final commit c52724f passed 33 focused checks, macOS Bash 3.2 syntax checks, independent QA, and independent review. No installer or native hardware operation was performed.