portugalfuturista/universalisos
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
universalisos/docs/T9-1_ASAHI_IMPORT_MAP.md

18 KiB
Raw Blame History

T9-1: Asahi Linux Import Map — Deep Research

Date: 2026-07-12

Status: COMPLETE — m1n1 analysis done

Executive Summary

This document maps every importable feature from the Asahi Linux ecosystem into UniversalisOS, mycelium, and aurelio. The goal is Apple Silicon (M1/M2/M3/M4) support via Asahi Linux patches, culminating in:

  1. UOS booting on Apple Silicon hardware
  2. Asahi Linux running as a UOS guest
  3. macOS running as a QEMU guest (Intel + Apple Silicon)

1. Repository Inventory (19 repos)

1.1 Boot & Firmware

Repo Purpose UOS Import Target
asahi-m1n1 Bootloader, hypervisor, USB gadget Boot protocol, HV, USB CDC
asagi-u-boot U-Boot fork for Apple Silicon UEFI services, boot menu
asahi-installer macOS installer for Asahi Linux Partitioning, firmware extraction
asahi-calamares Calamares installer fork GUI installer, OEM config
asahi-scripts Build & packaging scripts Build automation, packaging

1.2 Kernel & Drivers

Repo Purpose UOS Import Target
asahi-linux Linux kernel fork with Apple Silicon drivers AIC, UART, GPIO, I2C, PCIe, NVMe, USB, display, GPU, audio, WiFi, BT, SMC, PMU, DCP, PMP, AOP, SEP
asahi-devicetrees Device tree sources for Apple Silicon M1/M2/M3/M4 memory maps, interrupt maps
asahi-audio Audio DSP firmware & tools Audio driver, DSP firmware loading
asahi-speakersafetyd Speaker safety daemon Audio protection, thermal management
asahi-nvram NVRAM tools (asahi-bless) Boot configuration, BT/WiFi sync
asahi-hidpipe HID input forwarding Input device virtualization
asahi-plymouth Boot splash screen Boot UI, theming
asahi-fix27 Fix for 27" iMac display Display quirks, EDID handling
asahi-widevine-installer Widevine DRM installer DRM support, media playback
aasahi-vd-fw Video decode firmware Video acceleration, codec support
alsa-ucm-conf-asahi ALSA UCM configuration Audio routing, mixer controls

1.3 Emulation & Virtualization

Repo Purpose UOS Import Target
asahi-binfmt-dispatcher x86_64 binary emulation x86_64 app support on aarch64
asahi-fex-emu-rootfs-generator FEX-Emu rootfs builder x86_64 emulation environment
muvm macOS VM manager macOS VM orchestration
lima Linux VM manager Linux VM orchestration
macvdmtool macOS VDM tool macOS VM debugging
vdmtool VDM tool VM debugging, introspection

1.4 GPU

Repo Purpose UOS Import Target
asahi-universalisos-gpu AGX GPU driver (UOS project) GPU passthrough, compute, graphics

2. m1n1 Deep Analysis (COMPLETE)

2.1 Boot Protocol (src/start.S, src/startup.c, src/main.c)

Entry Point:

  • iBoot loads m1n1 at boot_args.phys_base + 0x80000 (Linux Image protocol)
  • x0 = boot_args pointer, x1 = base address
  • m1n1 runs at EL2 (or EL3 on some chips)

Boot Args Structure (src/xnuboot.h):

struct boot_args {
    u16 revision;      // 1, 2, or 3
    u16 version;
    u64 virt_base;     // Virtual base of kernel
    u64 phys_base;     // Physical base of kernel
    u64 mem_size;      // Total memory size
    u64 top_of_kernel_data;
    struct {
        u64 base;      // Framebuffer physical address
        u64 display;   // Display enabled flag
        u64 stride;    // Bytes per row
        u64 width;     // Pixels
        u64 height;    // Pixels
        u64 depth;     // Bits per pixel (low 8 bits) + density (high 16)
    } video;
    u32 machine_type;
    void *devtree;     // ADT (Apple Device Tree) pointer
    u32 devtree_size;
    union {
        struct { char cmdline[256]; u64 boot_flags; u64 mem_size_actual; } rv1;
        struct { char cmdline[256]; u64 boot_flags; u64 mem_size_actual; } rv2;
        struct { char cmdline[256]; u64 boot_flags; u64 mem_size_actual; } rv3;
    };
};

Key Boot Steps:

  1. _start_c() — BSS clear, boot_args copy, ADT pointer fixup
  2. uart_init() — S5L UART init (0x235200000 on M1)
  3. get_device_info() — Read chip ID from ADT
  4. init_cpu() — CPU-specific init (chicken bits, sysregs)
  5. exception_initialize() — Set up exception vectors
  6. m1n1_main() — Main menu / chainload / payload

Chainload Protocol (src/chainload.c):

  • m1n1 can chainload another kernel at 0x800000000 + 0x80000
  • Uses chainload_asm.S to jump with x0 = boot_args, x1 = new base
  • Supports Linux Image, XNU, and raw binary payloads

Payload System (src/payload.c):

  • m1n1 can embed payloads (kernel, initramfs, DTB)
  • Payloads are loaded at fixed addresses
  • Supports Linux, XNU, and custom payloads

2.2 UART Driver (src/uart.c, src/uart_regs.h)

S5L UART (M1/M2/M3/M4):

  • Base: 0x235200000 (M1), 0x235200000 (M2), 0x235200000 (M3)
  • Registers: ULCON, UCON, UFCON, UMCON, UTRSTAT, UERSTAT, UFSTAT, UMSTAT, UTXH, URXH, UBRDIV, UFRACVAL
  • Clock: 24 MHz (from ADT)
  • Baud rate: 115200 (default)

Key Functions:

  • uart_init() — Read ADT, configure UART
  • uart_putchar() — Blocking write
  • uart_getchar() — Blocking read
  • uart_puts() — String write
  • uart_printf() — Formatted write

Import to UOS:

  • Port uart.c to UOS kernel as kernel/src/arch/aarch64/uart_s5l.c
  • Use for early boot console on Apple Silicon
  • Add to kernel/src/arch/aarch64/board_apple_silicon.h

2.3 AIC (Apple Interrupt Controller) (src/aic.c, src/aic_regs.h)

AIC v1 (M1):

  • Base: 0x23b100000
  • Registers: AIC_INFO, AIC_WHOAMI, AIC_EVENT, AIC_IPI_SEND, AIC_IPI_ACK, AIC_IPI_MASK_SET, AIC_IPI_MASK_CLR, AIC_SW_SET, AIC_SW_CLR, AIC_SW_MASK_SET, AIC_SW_MASK_CLR, AIC_HW_IRQ, AIC_HW_IRQ_MASK_SET, AIC_HW_IRQ_MASK_CLR, AIC_HW_IRQ_MASK, AIC_HW_IRQ_STATUS, AIC_HW_IRQ_TYPE, AIC_HW_IRQ_TYPE_SET, AIC_HW_IRQ_TYPE_CLR

AIC v2 (M2/M3/M4):

  • Base: 0x28b100000 (M2), 0x28b100000 (M3)
  • Additional registers for die/cluster routing

Key Functions:

  • aic_init() — Read ADT, configure AIC
  • aic_mask() — Mask interrupt
  • aic_unmask() — Unmask interrupt
  • aic_ack() — Acknowledge interrupt
  • aic_send_ipi() — Send IPI to CPU
  • aic_set_type() — Set interrupt type (edge/level)

Import to UOS:

  • Port aic.c to UOS kernel as kernel/src/arch/aarch64/aic.c
  • Replace GICv3 with AIC on Apple Silicon
  • Add to kernel/src/arch/aarch64/board_apple_silicon.h

2.4 Memory Management (src/memory.c)

MMU Setup:

  • m1n1 uses 16K pages (Apple Silicon native)
  • Supports 4K pages via SPRR (Shadow Page Table)
  • Uses SYS_IMP_APL_SPRR_CONFIG_EL1 for SPRR configuration

Key Functions:

  • mmu_init() — Set up page tables
  • mmu_map() — Map physical to virtual
  • mmu_unmap() — Unmap virtual
  • mmu_flush() — Flush TLB

Import to UOS:

  • Port memory.c to UOS kernel as kernel/src/arch/aarch64/mmu_apple.c
  • Use 16K pages for Apple Silicon
  • Add SPRR support for 4K page compatibility

2.5 Exception Handling (src/exception.c, src/exception_asm.S)

Exception Vectors:

  • m1n1 sets up VBAR_EL2 (or VBAR_EL3)
  • Handles sync, IRQ, FIQ, SError
  • Uses SYS_IMP_APL_EHID4 / SYS_IMP_APL_HID4 for CPU-specific workarounds

Key Functions:

  • exception_initialize() — Set up exception vectors
  • exception_sync() — Handle synchronous exceptions
  • exception_irq() — Handle IRQ
  • exception_fiq() — Handle FIQ
  • exception_serror() — Handle SError

Import to UOS:

  • Port exception.c to UOS kernel as kernel/src/arch/aarch64/exception_apple.c
  • Add Apple-specific workarounds

2.6 Hypervisor (src/hv.c, src/hv.h, src/hv_vm.c, src/hv_exc.c, src/hv_asm.S)

HV Features:

  • m1n1 includes a minimal hypervisor for running guests
  • Supports EL1 guests (Linux, XNU)
  • Uses SYS_IMP_APL_VM_CONFIG_EL1 for VM configuration

Key Functions:

  • hv_init() — Initialize hypervisor
  • hv_start() — Start guest
  • hv_stop() — Stop guest
  • hv_map() — Map guest memory
  • hv_unmap() — Unmap guest memory

Import to UOS:

  • Port hv.c to UOS kernel as kernel/src/arch/aarch64/hv_apple.c
  • Use for running Asahi Linux and macOS guests

2.7 SMP (src/smp.c, src/smp.h)

CPU Start:

  • Uses RVBAR (Reset Vector Base Address Register) to start secondary CPUs
  • RVBAR is locked by iBoot, needs SYS_IMP_APL_CYC_OVRD to unlock
  • Uses spin table for CPU communication

Key Functions:

  • smp_start_secondaries() — Start all secondary CPUs
  • smp_stop_secondaries() — Stop all secondary CPUs
  • smp_call4() — Call function on remote CPU
  • smp_send_ipi() — Send IPI to CPU

Import to UOS:

  • Port smp.c to UOS kernel as kernel/src/arch/aarch64/smp_apple.c
  • Use for multi-core support on Apple Silicon

2.8 CPU Init (src/chickens.c, src/midr.h)

CPU-Specific Init:

  • m1n1 has init functions for each CPU type (Firestorm, Icestorm, Avalanche, Blizzard, Everest, Sawtooth, Donan, Brava, Tahiti, Sotra)
  • Sets chicken bits, sysregs, workarounds

Key Functions:

  • init_cpu() — Detect CPU type, call init function
  • init_t8103_firestorm() — M1 Firestorm init
  • init_t8112_avalanche() — M2 Avalanche init
  • init_t8122_everest() — M3 Everest init

Import to UOS:

  • Port chickens.c to UOS kernel as kernel/src/arch/aarch64/cpu_apple.c
  • Add CPU detection and init

2.9 Firmware Detection (src/firmware.c, src/firmware.h)

Firmware Versions:

  • m1n1 detects iBoot version from ADT
  • Supports macOS 11.0 through 26.4
  • Uses version for feature detection

Key Functions:

  • firmware_init() — Detect firmware version
  • firmware_parse_version() — Parse version string
  • firmware_iboot_in_range() — Check version range

Import to UOS:

  • Port firmware.c to UOS kernel as kernel/src/arch/aarch64/firmware_apple.c
  • Use for feature detection

2.10 Display (src/display.c, src/display.h, src/dcp.c, src/dcp.h)

DCP (Display Coprocessor):

  • m1n1 can initialize the DCP for display output
  • Supports internal and external displays
  • Uses DART for framebuffer mapping

Key Functions:

  • display_init() — Initialize display
  • display_configure() — Configure display mode
  • display_shutdown() — Shutdown display

Import to UOS:

  • Port display.c to UOS kernel as kernel/src/arch/aarch64/display_apple.c
  • Use for framebuffer console

2.11 PCIe (src/pcie.c, src/pcie.h)

PCIe Controller:

  • m1n1 can initialize PCIe for NVMe and other devices
  • Supports T8103, T6000, T8112, T8122, T6020, T6030, T6031
  • Uses tunables for PHY configuration

Key Functions:

  • pcie_init() — Initialize PCIe controller
  • pcie_shutdown() — Shutdown PCIe controller

Import to UOS:

  • Port pcie.c to UOS kernel as kernel/src/arch/aarch64/pcie_apple.c
  • Use for NVMe and USB support

2.12 NVMe (src/nvme.c, src/nvme.h)

NVMe Controller:

  • m1n1 can initialize NVMe for storage
  • Uses ANS (Apple NVMe Storage) coprocessor
  • Supports linear submission queue

Key Functions:

  • nvme_init() — Initialize NVMe controller
  • nvme_read() — Read from NVMe
  • nvme_flush() — Flush NVMe
  • nvme_shutdown() — Shutdown NVMe

Import to UOS:

  • Port nvme.c to UOS kernel as kernel/src/arch/aarch64/nvme_apple.c
  • Use for storage support

2.13 USB (src/usb.c, src/usb.h, src/usb_dwc3.c, src/usb_dwc3.h, src/usb_dwc3_regs.h, src/usb_types.h)

USB DWC3:

  • m1n1 includes a full USB DWC3 device driver
  • Supports CDC ACM (serial) for debugging
  • Uses DART for DMA

Key Functions:

  • usb_init() — Initialize USB controller
  • usb_dwc3_init() — Initialize DWC3 device
  • usb_dwc3_read() — Read from USB
  • usb_dwc3_write() — Write to USB

Import to UOS:

  • Port usb_dwc3.c to UOS kernel as kernel/src/arch/aarch64/usb_dwc3.c
  • Use for USB support

3. Import Priority Matrix

P0 — Critical (Boot & Console)

Component Source Target Effort Status
m1n1 boot protocol asahi-m1n1/src/start.S, startup.c UOS bootloader 2 weeks TODO
S5L UART asahi-m1n1/src/uart.c UOS kernel 1 week TODO
AIC asahi-m1n1/src/aic.c UOS kernel 2 weeks TODO
Memory management asahi-m1n1/src/memory.c UOS kernel 2 weeks TODO
Exception handling asahi-m1n1/src/exception.c UOS kernel 1 week TODO

P1 — High (Storage & Display)

Component Source Target Effort Status
PCIe asahi-m1n1/src/pcie.c UOS kernel 2 weeks TODO
NVMe asahi-m1n1/src/nvme.c UOS kernel 2 weeks TODO
Display/DCP asahi-m1n1/src/display.c, dcp.c UOS kernel 3 weeks TODO
USB DWC3 asahi-m1n1/src/usb_dwc3.c UOS kernel 2 weeks TODO

P2 — Medium (Hypervisor & SMP)

Component Source Target Effort Status
Hypervisor asahi-m1n1/src/hv.c UOS kernel 3 weeks TODO
SMP asahi-m1n1/src/smp.c UOS kernel 2 weeks TODO
CPU init asahi-m1n1/src/chickens.c UOS kernel 1 week TODO
Firmware detection asahi-m1n1/src/firmware.c UOS kernel 1 week TODO

P3 — Low (Peripherals)

Component Source Target Effort Status
Audio asahi-audio UOS kernel 4 weeks TODO
WiFi/BT asahi-linux/drivers/net/wireless UOS kernel 6 weeks TODO
GPU asahi-universalisos-gpu UOS kernel 8 weeks TODO
NVRAM asahi-nvram UOS tools 1 week TODO

4. T9-2: Apple Silicon Boot & Platform Bring-Up Plan

Phase 1: Boot Protocol (Weeks 1-2)

  1. Analyze m1n1 boot flow — DONE
  2. Create UOS bootloader for Apple Silicon — TODO
    • Port start.S to UOS
    • Port startup.c to UOS
    • Port main.c to UOS
  3. Test on QEMU — TODO
    • Use qemu-system-aarch64 -M virt with Apple Silicon patches
    • Verify boot protocol works

Phase 2: Console & Debug (Weeks 3-4)

  1. Port S5L UART — TODO
    • Create kernel/src/arch/aarch64/uart_s5l.c
    • Add to kernel/src/arch/aarch64/board_apple_silicon.h
  2. Test UART output — TODO
    • Verify boot messages on QEMU
    • Verify on real hardware (if available)

Phase 3: Interrupts (Weeks 5-6)

  1. Port AIC — TODO
    • Create kernel/src/arch/aarch64/aic.c
    • Add to kernel/src/arch/aarch64/board_apple_silicon.h
  2. Test interrupts — TODO
    • Verify timer interrupts
    • Verify IPI

Phase 4: Memory (Weeks 7-8)

  1. Port memory management — TODO
    • Create kernel/src/arch/aarch64/mmu_apple.c
    • Add 16K page support
    • Add SPRR support
  2. Test memory — TODO
    • Verify page tables
    • Verify TLB flush

Phase 5: Exceptions (Weeks 9-10)

  1. Port exception handling — TODO
    • Create kernel/src/arch/aarch64/exception_apple.c
    • Add Apple-specific workarounds
  2. Test exceptions — TODO
    • Verify sync exceptions
    • Verify IRQ/FIQ

Phase 6: Storage (Weeks 11-14)

  1. Port PCIe — TODO
    • Create kernel/src/arch/aarch64/pcie_apple.c
  2. Port NVMe — TODO
    • Create kernel/src/arch/aarch64/nvme_apple.c
  3. Test storage — TODO
    • Verify NVMe read/write

Phase 7: Display (Weeks 15-18)

  1. Port DCP — TODO
    • Create kernel/src/arch/aarch64/display_apple.c
  2. Test display — TODO
    • Verify framebuffer console

Phase 8: USB (Weeks 19-22)

  1. Port USB DWC3 — TODO
    • Create kernel/src/arch/aarch64/usb_dwc3.c
  2. Test USB — TODO
    • Verify CDC ACM

Phase 9: Hypervisor (Weeks 23-26)

  1. Port hypervisor — TODO
    • Create kernel/src/arch/aarch64/hv_apple.c
  2. Test hypervisor — TODO
    • Verify guest start/stop

Phase 10: SMP (Weeks 27-30)

  1. Port SMP — TODO
    • Create kernel/src/arch/aarch64/smp_apple.c
  2. Test SMP — TODO
    • Verify multi-core

5. T9-3: Asahi Linux as UOS Guest Plan

Phase 1: Guest Boot (Weeks 1-4)

  1. Create Asahi Linux guest image — TODO
    • Use asahi-installer to create image
    • Extract kernel, initramfs, DTB
  2. Boot Asahi Linux as guest — TODO
    • Use UOS hypervisor
    • Verify boot

Phase 2: Guest Drivers (Weeks 5-12)

  1. Port Asahi Linux drivers to UOS — TODO
    • AIC, UART, GPIO, I2C, PCIe, NVMe, USB, display, GPU, audio, WiFi, BT, SMC, PMU, DCP, PMP, AOP, SEP
  2. Test guest drivers — TODO
    • Verify all drivers work

Phase 3: Guest Desktop (Weeks 13-18)

  1. Boot Asahi Linux desktop — TODO
    • Verify GUI
    • Verify input
    • Verify audio
    • Verify network

6. T9-4: macOS Guest on QEMU Plan

Phase 1: macOS Intel Guest (Weeks 1-8)

  1. Create macOS Intel VM — TODO
    • Use muvm or lima
    • Extract macOS kernel, kexts
  2. Boot macOS Intel as guest — TODO
    • Use QEMU with Apple Silicon patches
    • Verify boot

Phase 2: macOS Apple Silicon Guest (Weeks 9-24)

  1. Create macOS Apple Silicon VM — TODO
    • Use muvm or lima
    • Extract macOS kernel, kexts
  2. Boot macOS Apple Silicon as guest — TODO
    • Use QEMU with Apple Silicon patches
    • Verify boot

7. Memory & Documentation

7.1 Persistent Memory

  • All documents in docs/ are updated continuously
  • Master plan in .hermes/plans/ is updated after each phase
  • Import map in docs/T9-1_ASAHI_IMPORT_MAP.md is updated after each analysis

7.2 Document Update Schedule

Document Update Frequency Owner
Master plan After each phase Agent
Import map After each analysis Agent
T9-2 plan After each week Agent
T9-3 plan After each week Agent
T9-4 plan After each week Agent

8. Next Actions

  1. Start T9-2 Phase 1 — Create UOS bootloader for Apple Silicon
  2. Update master plan — Add T9-2 Phase 1 tasks
  3. Create T9-2 doc — docs/T9-2_APPLE_SILICON_BOOT.md