├── .gitignore ├── docs ├── assets │ ├── favicon.png │ ├── logo.png │ ├── linuxOnM1.png │ ├── recoveryos.png │ ├── usb-setup.png │ ├── boot_picker.png │ ├── m1_iphone_5_fb.png │ ├── mba-xorg-fbdev.png │ ├── USB-TypeC-A-cable.png │ ├── central-scrutinizer.jpg │ └── central-scrutinizer-2.jpg ├── sw │ ├── getting-started.md │ ├── devicetree-bindings.md │ ├── speaker-stress-tests.md │ ├── m1n1-dev-guide.md │ ├── linux-bringup-x11.md │ ├── linux-bringup-usb-keyboard.md │ ├── linux-bringup-wifi.md │ ├── linux-bringup-usb.md │ ├── profiling.md │ ├── undoing-early-speaker-hacks.md │ ├── linux-bringup-nvme.md │ ├── u-boot.md │ ├── kernel-config.md │ ├── deleting-an-install.md │ ├── windows-11-vm.md │ ├── tethered-boot-macos-host.md │ ├── macos-kernelcache.md │ └── m1n1-hypervisor.md ├── hw │ ├── soc │ │ ├── avd.md │ │ ├── aop.md │ │ ├── wdt.md │ │ ├── clocks.md │ │ ├── display-controllers.md │ │ ├── accelerators.md │ │ ├── aic.md │ │ ├── soc-codenames.md │ │ ├── asc.md │ │ ├── usb-debug.md │ │ ├── gpio.md │ │ ├── apcie.md │ │ ├── smc.md │ │ └── serial-debug.md │ ├── cpu │ │ ├── debug-registers.md │ │ ├── smp.md │ │ ├── apple-instructions.md │ │ └── sprr-gxf.md │ ├── peripherals │ │ ├── keyboard-backlight.md │ │ ├── ace3.md │ │ └── camera.md │ └── devices │ │ └── device-list.md ├── project │ ├── board │ │ ├── minutes │ │ │ ├── 20250718.md │ │ │ ├── 20250808.md │ │ │ ├── 20250905.md │ │ │ ├── 20250606.md │ │ │ ├── 20250404.md │ │ │ ├── 20250307.md │ │ │ └── 20250502.md │ │ └── asahi-board.md │ ├── references.md │ ├── trivia.md │ ├── help-wanted.md │ ├── when-will-asahi-be-done.md │ ├── policies │ │ └── slop.md │ └── faq.md ├── stylesheets │ └── extra.css ├── platform │ ├── feature-support │ │ ├── overview.md │ │ └── m3.md │ ├── subsystems.md │ ├── quirks.md │ └── pc-boot-differences.md ├── index.md └── fw │ ├── adt.md │ ├── boot.md │ └── macho-boot-protocol.md ├── .gitmodules ├── Makefile ├── overrides └── main.html ├── Dockerfile ├── .github └── workflows │ ├── pages.yml │ └── container.yml ├── README.md └── mkdocs.yml /.gitignore: -------------------------------------------------------------------------------- 1 | /.cache/ 2 | /site/ 3 | -------------------------------------------------------------------------------- /docs/assets/favicon.png: -------------------------------------------------------------------------------- 1 | ../../artwork/logos/png_32/AsahiLinux_logomark.png -------------------------------------------------------------------------------- /docs/assets/logo.png: -------------------------------------------------------------------------------- 1 | ../../artwork/logos/png_256/AsahiLinux_logomark.png -------------------------------------------------------------------------------- /docs/assets/linuxOnM1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/linuxOnM1.png -------------------------------------------------------------------------------- /docs/assets/recoveryos.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/recoveryos.png -------------------------------------------------------------------------------- /docs/assets/usb-setup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/usb-setup.png -------------------------------------------------------------------------------- /docs/assets/boot_picker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/boot_picker.png -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "docs/artwork"] 2 | path = artwork 3 | url = https://github.com/AsahiLinux/artwork 4 | -------------------------------------------------------------------------------- /docs/assets/m1_iphone_5_fb.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/m1_iphone_5_fb.png -------------------------------------------------------------------------------- /docs/assets/mba-xorg-fbdev.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/mba-xorg-fbdev.png -------------------------------------------------------------------------------- /docs/assets/USB-TypeC-A-cable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/USB-TypeC-A-cable.png -------------------------------------------------------------------------------- /docs/assets/central-scrutinizer.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/central-scrutinizer.jpg -------------------------------------------------------------------------------- /docs/assets/central-scrutinizer-2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/AsahiLinux/docs/HEAD/docs/assets/central-scrutinizer-2.jpg -------------------------------------------------------------------------------- /docs/sw/getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting Started 3 | --- 4 | 5 | Obsolete, you want [Developer Quickstart](../platform/dev-quickstart.md) 6 | -------------------------------------------------------------------------------- /docs/hw/soc/avd.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Video Decoder 3 | --- 4 | 5 | Apple Video Decoder. 6 | 7 | Supports AVC, HEVC, AV1, VP9. 8 | 9 | Notes: 10 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | help: 2 | @echo "Run 'make test' to test locally or 'make build' to render the static site" 3 | 4 | build: 5 | mkdocs build 6 | 7 | clean: 8 | rm -rf site 9 | 10 | test: 11 | mkdocs serve 12 | 13 | .PHONY: help build test 14 | -------------------------------------------------------------------------------- /docs/hw/soc/aop.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Always-On Processor (AOP) 3 | --- 4 | 5 | # AOP 6 | 7 | AOP is the "Always-On Processor", which alludes more to the kind of functionality it implements (e.g. the 'Hey Siri' voice trigger) than it alludes to the fact that it should be always on (it's not). 8 | -------------------------------------------------------------------------------- /overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block extrahead %} 4 | 5 | {% endblock %} 6 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250718.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 18 July 2025 3 | --- 4 | 5 | Date: 18 July 2025 1700-0500 6 | 7 | ## Present 8 | - chaos princess 9 | - Neal Gompa 10 | - Davide Cavalca 11 | - Janne Grunau 12 | - Alyssa Rosenzweig 13 | - James Calligeros 14 | 15 | ## Agenda: 16 | - Akademy 17 | - Discuss finalised proposal 18 | - m1n1 release 19 | 20 | ## Discussion items 21 | - Akademy 22 | - Travel very expensive, probably not in remit to cover 23 | - Do a m1n1 release before Rust porting goes in 24 | -------------------------------------------------------------------------------- /docs/stylesheets/extra.css: -------------------------------------------------------------------------------- 1 | :root > * { 2 | --md-primary-fg-color: #A61200; 3 | --md-primary-fg-color--light: #A61200; 4 | --md-primary-fg-color--dark: #A61200; 5 | --md-accent-fg-color: #D3506F; 6 | --md-footer-bg-color: #2C2C2C; 7 | --md-footer-bg-color--dark: #2C2C2C; 8 | } 9 | 10 | /* Heading overrides as the default ones are very small */ 11 | .md-typeset { 12 | h4 { 13 | font-size: 0.95rem; 14 | } 15 | h5 { 16 | font-size: 0.8rem; 17 | } 18 | h6 { 19 | font-size: 0.7rem; 20 | } 21 | } 22 | 23 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM registry.fedoraproject.org/fedora:42 2 | 3 | LABEL org.opencontainers.image.description="Build the Asahi Linux documentation website using mkdocs" 4 | LABEL org.opencontainers.image.licenses=MIT 5 | LABEL org.opencontainers.image.source=https://github.com/AsahiLinux/docs 6 | LABEL org.opencontainers.image.vendor="Asahi Linux" 7 | 8 | RUN dnf -y install git-core mkdocs-material mkdocs-material+imaging python3-mkdocs-redirects && dnf -y clean all 9 | 10 | RUN mkdir /docs 11 | 12 | WORKDIR /docs 13 | 14 | EXPOSE 8000 15 | ENTRYPOINT ["mkdocs"] 16 | CMD ["serve", "--dev-addr=0.0.0.0:8000"] 17 | -------------------------------------------------------------------------------- /docs/hw/cpu/debug-registers.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Application Processor Debug Registers 3 | summary: 4 | Debug registers found in Apple-designed ARM cores 5 | --- 6 | 7 | The various CPU cores export entries in the [ADT](../../fw/adt.md) that hint at the existence of debug registers. The string "coresight" appears, and coresight register files are unlocked by writing `0xc5acce55` to offset `0xfb0`, which is also what the Corellium CPU start code does. The lock status register is at `0x210030fb4` for CPU0. 8 | 9 | CPU0's PC can be read at `0x210040090` (the usual offsets apply to the other cores), but the other registers don't appear to be making any obvious appearances. 10 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250808.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 8 August 2025 3 | --- 4 | 5 | Date: 8 August 2025 1700-0500 6 | 7 | ## Present 8 | - chaos princess 9 | - Sven Peter 10 | - Davide Cavalca 11 | - Janne Grunau 12 | - James Calligeros 13 | 14 | ## Agenda: 15 | - PackIt 16 | 17 | ## Discussion items 18 | - Get rid of PackIt on m1n1 repo, keep elsewhere for now 19 | - Might still remove if it gets even more annoying 20 | - Stats server looking good now, probably should bring the infra under project ownership 21 | - Infra sponsorship - contact AWS 22 | - Still need to figure out Bunny CDN push on installer updates 23 | 24 | 25 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250905.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 5 September 2025 3 | --- 4 | 5 | Date: 5 September 2025 1600-0500 6 | 7 | ## Present 8 | - chaos princess 9 | - Sven Peter 10 | - Davide Cavalca 11 | - Janne Grunau 12 | - Alyssa Rosenzweig 13 | 14 | ## Discussion items 15 | - 6.17 Progress Report 16 | - DART changes, USB-C, Devicetree changes, SMC 17 | - USB-C 18 | - Needs new U-Boot release 19 | - F43 beta 20 | - Mesa still broken 21 | - Asahi repos need splitting up 22 | - t602x DT submission 23 | - Figure out merge strategy 24 | 25 | ## Action items 26 | - Janne to spin up MR for Asahi repo split 27 | - Follow up with Fedora Mesa maintainers re F43 28 | - Cut a U-Boot release 29 | -------------------------------------------------------------------------------- /docs/platform/feature-support/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Feature Support Overview 3 | --- 4 | 5 | This page has been broken up into a separate page for each generation of available devices, as there are now too many to list on a single 6 | page. Each page below follows the same format as the old unified page. 7 | 8 | - [M1 Series (M1, M1 Pro, M1 Max, M1 Ultra) Feature Support](m1.md) 9 | - [M2 Series (M2, M2 Pro, M2 Max, M2 Ultra) Feature Support](m2.md) 10 | - [M3 Series (M3, M3 Pro, M3 Max) Feature Support](m3.md) 11 | - [M4 Series (M4, M4 Pro, M4 Max) Feature Support](m4.md) 12 | 13 | A condensed feature overview for the Fedora Asahi Remix is available at [https://asahilinux.org/fedora/#device-support](https://asahilinux.org/fedora/#device-support). 14 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250606.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 6 June 2025 3 | --- 4 | 5 | Date: 6 June 2025 1700-0500 6 | 7 | ## Present 8 | - chaos princess 9 | - Neal Gompa 10 | - Davide Cavalca 11 | - Janne Grunau 12 | - Sven Peter 13 | - James Calligeros 14 | 15 | ## Agenda: 16 | - Generative AI policy 17 | 18 | ## Discussion items 19 | - AI policy 20 | - Two documents - actual policy and justification 21 | - Emphasis on copyright issues for Asahi 22 | - CentOS builds have started 23 | - Upstream Mesa not working for some reason 24 | - Anaconda team to look at restricting partitioning 25 | 26 | ## Action Items 27 | - Neal to finalise proposal 28 | - Janne to submit Kiwi descriptor MR for live ISO builds 29 | - James to finalise AI policy 30 | -------------------------------------------------------------------------------- /docs/project/board/asahi-board.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board 3 | --- 4 | 5 | The Asahi Linux Board is the governing body of the Asahi Linux project. The board 6 | handles the administration of the project, including day-to-day operations, finances, 7 | and the Code of Conduct. 8 | 9 | The board meets once a month. 10 | 11 | ## Current Members 12 | - Alyssa Rosenzweig 13 | - Neal Gompa 14 | - Davide Cavalca 15 | - Janne Grunau 16 | - Sven Peter 17 | - chaos_princess 18 | - James Calligeros 19 | 20 | ## Meeting Minutes (times in US/Eastern) 21 | - [7 March 2025 16:00](minutes/20250307.md) 22 | - [4 April 2025 16:00](minutes/20250404.md) 23 | - [2 May 2025 17:00](minutes/20250502.md) 24 | - [6 June 2025 17:00](minutes/20250606.md) 25 | - [18 July 2025 17:00](minutes/20250718.md) 26 | - [8 August 2025 17:00](minutes/20250808.md) 27 | - [5 September 2025 16:00](minutes/20250905.md) 28 | -------------------------------------------------------------------------------- /.github/workflows/pages.yml: -------------------------------------------------------------------------------- 1 | name: Pages 2 | on: 3 | push: 4 | branches: 5 | - main 6 | pull_request: 7 | branches: 8 | - main 9 | 10 | permissions: 11 | contents: write 12 | 13 | jobs: 14 | deploy: 15 | runs-on: ubuntu-latest 16 | container: ghcr.io/asahilinux/mkdocs-asahi 17 | steps: 18 | - name: Checkout 19 | uses: actions/checkout@v4 20 | with: 21 | submodules: true 22 | - name: Configure Git Credentials 23 | run: | 24 | git config --global user.name github-actions[bot] 25 | git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com 26 | # This is needed for the deployment to work 27 | git config --global --add safe.directory "$GITHUB_WORKSPACE" 28 | - name: Build 29 | if: github.event_name == 'pull_request' 30 | run: mkdocs build 31 | - name: Build and deploy to GitHub Pages 32 | if: github.event_name != 'pull_request' 33 | run: mkdocs gh-deploy --force 34 | -------------------------------------------------------------------------------- /docs/hw/soc/wdt.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Watchdog Timer (WDT) 3 | --- 4 | 5 | The M1 includes a watchdog timer which can reboot the system automatically in case the kernel fails to boot or run properly. It can also be (ab)used to trigger an immediate or delayed reboot in other circumstances. 6 | 7 | The initial macho (usually m1n1) is booted with the watchdog timer enabled, so if it does nothing to it, the system will automatically reboot after a while. 8 | 9 | There's a 24MHz 32-bit timer at 0x23d2b0000+0x10, a compare value at 0x23d2b0000+0x14 (initially set to 120 seconds), and a control register at 0x23d2b0000+0x1c. When the timer exceeds or equals the compare value, and bit 0x04 in the control register is set, a reboot is triggered. 10 | 11 | The WDT is disabled by writing 0 to +0x1c, and enabled by writing 4 to +0x1c. 12 | 13 | Since the counters are 32-bit values and wrap, that means the maximum timeout is just short of three minutes. 14 | 15 | Registers 0x23d2b0000+0x0/0x4/0xc and 0x23d2b0000+0x20/0x24/0x2c seem to work like +0x10,+0x14,0x1c, but trigger a reboot into recovery mode instead. 16 | -------------------------------------------------------------------------------- /docs/sw/devicetree-bindings.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Devicetree Bindings 3 | --- 4 | 5 | ### PMGR 6 | - 'apple,t6000-pmgr' 7 | - 'apple,t8103-pmgr' 8 | - 'apple,pmgr' 9 | 10 | Proposal submitted by marcan 11 | 12 | ### PMGR nodes 13 | - 'apple,t6000-pmgr-pwrstate' 14 | - 'apple,t8103-pmgr-pwrstate' 15 | - 'apple,pmgr-pwrstate' 16 | 17 | Proposal submitted by marcan 18 | 19 | ### SPMI 20 | - 'apple,t8103-spmi' 21 | - 'apple,spmi' 22 | 23 | Used by OpenBSD; not submitted upstream yet 24 | 25 | ### SPMI PMU 26 | - 'apple,sera-pmu' 27 | 28 | Used by OpenBSD; not submitted upstream yet 29 | 30 | ### SPI 31 | - 'apple,t6000-spi' 32 | - 'apple,t8103-spi' 33 | - 'apple,spi' 34 | 35 | Used by OpenBSD; not submitted upstream yet 36 | 37 | ### SPI keyboard/touchpad 38 | - 'apple,spi-hid-transport' 39 | 40 | Not sumitted upstream yet 41 | 42 | ### SMC 43 | - 'apple,t8103-smc' 44 | - 'apple,smc' 45 | 46 | Soon to be used by OpenBSD; not submitted upstream yet 47 | 48 | ### NVME 49 | - 'apple,t6000-nvme-ans2' 50 | - 'apple,t8103-nvme-ans2' 51 | - 'apple,nvme-ans2' 52 | 53 | Not submitted upstream yet 54 | -------------------------------------------------------------------------------- /docs/sw/speaker-stress-tests.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Speaker stress tests 3 | --- 4 | 5 | * [Laufey - From The Start](https://www.youtube.com/watch?v=lSD_L-xic9o) - good bankstown test case, bass/guitar really stress the behavior 6 | * [J.Geco - Chicken Song](https://www.youtube.com/watch?v=msSc7Mv0QHY) - Konrad said this damaged a ThinkPad X13s's speakers... we seem to do okay but it's definitely something 7 | * [I Won The Loudness War](https://www.youtube.com/watch?v=WSg_6Osx-eE) - Speaker torture. Do not crank stream volume to 100% unless you're an Asahi developer and you have AppleCare. This is not *supposed* to damage anything, but seriously, leave it to the developers to risk this one please. 8 | * [可愛くてごめん feat. ちゅーたん／HoneyWorks](https://www.youtube.com/watch?v=K4xLi8IF1FM) - Messy bass, after a while speakersafetyd limits somewhat even at YouTube normalized volume (on J313). Probably hitting bankstown / the 200 Hz band too much, might be clipping? 9 | * [KZ5 - SUBWOOFA (In Him) MkII](https://www.youtube.com/watch?v=F-hA0B9fr08) - Brings bankstown to its knees, good test for overexcursion and overzealous compression. 10 | -------------------------------------------------------------------------------- /docs/sw/m1n1-dev-guide.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: m1n1 Developer Guide 3 | --- 4 | 5 | (Not written yet, just throwing some stuff in) 6 | 7 | ## Boot protocol 8 | 9 | The boot protocol used for m1n1 images is a trivial subset of the XNU boot protocol. Raw binaries can be loaded anywhere (at 16K aligned offsets). The RVBAR is at offset 0 (only relevant for resuming from sleep mode, due to iBoot locking down that register). Payloads are simply concatenated to the main binary and are loaded together with it. The entry point is at 0x800 with translation disabled and the physical address to the XNU [`boot_args`](https://github.com/AsahiLinux/m1n1/blob/main/src/xnuboot.h) structure in r0. 10 | 11 | There are also legacy Mach-O images; these are currently only still necessary for older iBoot2 versions and for run_guest.py (TODO: fix that). Those are basically the same thing with a Mach-O header and the .bss section trimmed, as the file is not loaded flat any more. There is a hacky large payload section at the end that is trimmed to 0 bytes and "hangs off of the end of the file", to provide space for payloads to be appended by concatenation. 12 | -------------------------------------------------------------------------------- /docs/sw/linux-bringup-x11.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Linux Bringup: X11 3 | --- 4 | 5 | # Running X11 6 | * You can run a non-accelerated X11 if you build the kernel with 7 | `CONFIG_DRM_FBDEV_EMULATION=y` 8 | * After booting that kernel install the relevant xserver fbdev (under debian) 9 | `sudo apt install xserver-xorg-video-fbdev` 10 | * Then you can try starting X 11 | `startx` 12 | * If you have problems look for error messages in the Xserver log 13 | `less /var/log/Xorg.0.log` 14 | * Assuming you get X starting up then will need to set up a window manager - as per your distribution e.g. see this Debian [GUI system](https://www.debian.org/doc/manuals/debian-reference/ch07.en.html) 15 | * I installed the very light keyboard based fluxbox 16 | `apt install fluxbox` 17 | * To get a simple graphical login screen 18 | `apt install xdm` 19 | * I install the nice X terminal **konsole** 20 | `apt install konsole` 21 | * For a web browser install firefox as Chrome requires special kernel paging support (not available at this time) 22 | `sudo apt install firefox-esr` 23 | 24 | (![X11 running on Macbook Air 2020](../assets/mba-xorg-fbdev.png)) 25 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250404.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 4 Apr 2025 3 | --- 4 | 5 | Date: 4 Apr 2025 1600-0500 6 | 7 | ## Present 8 | - Alyssa Rosenzweig 9 | - chaos princess 10 | - Neal Gompa 11 | - Davide Cavalca 12 | - Janne Grunau 13 | - Sven Peter 14 | - James Calligeros 15 | 16 | ## Agenda: 17 | - Expenses approval 18 | - Migrating Asahi Stats server 19 | - Standardising treatment of alt distros 20 | 21 | ## Discussion items 22 | - Expenses 23 | - Neal's laptop approved 24 | - Alyssa's Migadu expenses approved 25 | - Someone needs to host the stats server 26 | - Mesa CI? No point until uAPI is merged 27 | - We should turn off the GitHub wiki 28 | - Still need to transfer some domains from Hector to Asahi 29 | - OpenCollective can hold our domains for us if they're set up with Namecheap 30 | - FAR domains can't be transferred to Fedora Project 31 | - Fedora 42 testing - muvm patch needs to be backported if we don't release 32 | - How much support do we give distros? We should have a policy/quality standards 33 | 34 | ## Action Items 35 | - Neal to transfer domains to Namecheap 36 | - chaos_princess to take on hosting of the stats server temporarily 37 | - James to create alt distro policy 38 | -------------------------------------------------------------------------------- /docs/sw/linux-bringup-usb-keyboard.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Linux Bringup: USB Keyboard 3 | --- 4 | 5 | # Linux USB keyboard 6 | * Got a USB keyboard working with an ramdisk root filesystem. 7 | * By booting the [Asahi dart/dev kernel](https://github.com/AsahiLinux/linux/tree/dart/dev) with USB3 XHCD, DWC3 and DART et cetera 8 | * Can use this [Linux config file for M1 MacBook Air with USB](https://github.com/amworsley/asahi-wiki/blob/main/images/config-jannau-iso9660-noR.gz) as a base (doesn't enable gadget mode) 9 | * Modifying the initrd to just run /bin/sh (edit /init) 10 | * Booted it directly via ```python3.9 proxyclient/tools/linux.py -b 'earlycon console=tty0 console=tty0 debug' Image-dwc3.gz t8103-j274.dtb initrd-be2.gz``` 11 | * Where the Image-dwc3.gz is the Asahi dart/dev kernel, the t8103.j274.dtb built with that kernel, at **linux/arch/arm64/boot/dts/apple/t8103-j274.dtb**, and initrd-be2.gz is the modified debian Bullseye initrd to just run **/bin/sh** after the set up. 12 | * Then I used a Type-C to Type-A adapter to plug in a normal old USB Dell keyboard and enter commands into the /bin/sh running. 13 | ![Linux running on M1 macbook with input via external USB keyboard](../assets/linuxOnM1.png) 14 | 15 | * You can go one step further and try [booting a USB drive](linux-bringup-usb.md) 16 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250307.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 7 Mar 2025 3 | --- 4 | 5 | Date: 7 Mar 2025 1600-0500 6 | 7 | ## Present 8 | - Alyssa Rosenzweig 9 | - chaos princess 10 | - Neal Gompa 11 | - Davide Cavalca 12 | - Janne Grunau 13 | - Sven Peter 14 | - James Calligeros 15 | 16 | ## Agenda: 17 | No agenda set, first meeting 18 | 19 | ## Discussion items 20 | - Expenses 21 | - Approved purchase of J313 for AUD 722.50 22 | - Discussed purchase of laptop for Neal 23 | - Setting up email 24 | - @asahilinux.org emails for board members, CoC, etc. 25 | - Look at setting up Migadu 26 | - Domain ownership 27 | - Need to transfer domains to project ownership 28 | - Password vault 29 | - 1Password offers free services to OpenCollective projects 30 | - Blog posts and giving backers value 31 | - Blog post for each major kernel release 32 | - Blog posts to include important developments even if not upstreamed 33 | in the relevant kernel release 34 | - Start with 6.13, talk about PMUv3, mics, Vk sparse 35 | 36 | ## Action Items 37 | - Neal to investigate options for an M2 machine 38 | - Sven and Alyssa to set up Migadu 39 | - Neal and Alyssa to get domain transferred to OSC 40 | - Neal to reach out to 1Password for password vault 41 | - Everyone to start writing blog collateral 42 | -------------------------------------------------------------------------------- /docs/hw/soc/clocks.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Clocks 3 | --- 4 | 5 | There are (at least) two different kinds of clocks defined in the ADT: 6 | 7 | * `clock-gates` or `power-gates` which index into the `devices` array of the `pmgr` ADT node 8 | * `clock-ids` which represent clocks with a frequency and index into the `clock-frequencies` array of the `arm-io` node 9 | 10 | ## clock-gates / power-gates 11 | 12 | Gated clocks are used to remove the clock signal to certain peripherals when they are not used. The ids for a specific ADT node usually need to be turned on before the MMIO region of that device can be accessed. 13 | 14 | There is probably also some topology involved in these clocks since e.g. `SIO`, `UART_P` and `UART0` seem to be required to access the UART MMIO region even though the UART node only requests `UART0`. 15 | 16 | ## clock-ids 17 | 18 | These clocks are likely preconfigured by iBoot and never touched by XNU itself. Their frequencies are passed as nodes in the ADT. Low indexes (<0x100, but probably only 6 or so) are clocks given in the `cpu0` node (e.g. `bus-frequency`) and for now all seem to be set to 24 MHz. 19 | Indexes above 0x100 map to the `clock-frequencies` array of the `arm-io` node. These are usually used as reference clocks for e.g. the UART or the I2C bus. 20 | 21 | There is also the `clock-frequencies-regs` property but it's unknown how exactly the registers in there map to the above mentioned clocks. That property also seems to be completely unused by XNU. 22 | -------------------------------------------------------------------------------- /docs/project/board/minutes/20250502.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asahi Linux Board Meeting Minutes - 2 May 2025 3 | --- 4 | 5 | Date: 2 May 2025 1700-0500 6 | 7 | ## Present 8 | - Alyssa Rosenzweig 9 | - chaos princess 10 | - Neal Gompa 11 | - Davide Cavalca 12 | - Janne Grunau 13 | - Sven Peter 14 | - James Calligeros 15 | 16 | ## Agenda: 17 | - Expenses 18 | - Alt distro policy 19 | - Stats server 20 | - Progress report 21 | 22 | ## Discussion items 23 | - Domain expenses approved 24 | - Contracting Neal on an ongoing basis 25 | - What does this look like? 26 | - Go back to OSC to find out 27 | - Existing invoice 28 | - Approved 29 | - Stats server 30 | - Revert distro name commit 31 | - Get dump of db and send to chaos_princess 32 | - Set DNS record to point to new server 33 | - Distro stats are too abusable 34 | - HELLOTUX merch 35 | - Worth the revenue share? 36 | - Lots of demand, might as well 37 | - Alt distro policy 38 | - We're not going to host others' images 39 | - Installer criteria are too stringent for now 40 | - Progress report 41 | - Remember to mention everything that's been upstreamed 42 | - Follow up on any developments since the last one 43 | - Domain transfers 44 | - 60 day competitive cooldown 45 | 46 | ## Action Items 47 | - Neal to ask OSC about ongoing expenses/contracts 48 | - chaos_princess to get stats database backup 49 | - James to make changes to draft alt distro policy 50 | - James also to draft progress report 51 | -------------------------------------------------------------------------------- /docs/hw/peripherals/keyboard-backlight.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Keyboard Backlight Controller 3 | --- 4 | 5 | On the MacBook Pro, the keyboard backlight shows up in the ADT as: 6 | 7 | ``` 8 | fpwm { 9 | [...] 10 | AAPL.phandle = 59 11 | clock-gates = 37 12 | device_type = fpwm 13 | reg = [889470976, 16384] 14 | 15 | kbd-backlight { 16 | [...] 17 | } 18 | } 19 | ``` 20 | 21 | That suggests that there's a PWM at 0x235044000, enabled by the clock gate at 0x23b7001e0, which controls the keyboard backlight. That does appear to be the case :-) 22 | 23 | Registers, as far as I've figured them out: 24 | 25 | ``` 26 | +0x00: write 0x4239 to enable or after counter values changed 27 | +0x04: unknown, no effect 28 | +0x08: status bits: bit 0x01 is set when the light comes on, 0x02 is set when the light comes off. Write-to-clear. 29 | +0x0c: unknown, no effect 30 | +0x18: off period, in 24 MHz ticks 31 | +0x1c: on period, in 24 MHz ticks 32 | ``` 33 | 34 | So a complete m1n1 sequence to make the keyboard backlight flash in an annoying and possibly seizure-inducing way is: 35 | 36 | ``` 37 | >>> write32(0x23b7001e0, 0xf) 38 | >>> write32(0x23504401c, 1200000) 39 | >>> write32(0x235044018, 1200000) 40 | >>> write32(0x235044000, 0x4239) 41 | ``` 42 | 43 | changing the frequency while keeping a 50% duty cycle: 44 | 45 | ``` 46 | >>> write32(0x235044018, 4000) 47 | >>> write32(0x23504401c, 4000) 48 | >>> write32(0x235044000, 0x4239) 49 | ``` 50 | 51 | PR at https://github.com/AsahiLinux/linux/pull/5 52 | -------------------------------------------------------------------------------- /docs/project/references.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Miscellaneous References 3 | --- 4 | 5 | 6 | ### Web References 7 | These are just some references for people to build some background knowledge into getting Linux working on Apple Silicon. 8 | 9 | [Explore the new system architecture of Apple silicon Macs (WWDC 2020 Session)](https://developer.apple.com/videos/play/wwdc2020/10686/) 10 | 11 | [Apple Platform Security Documentation](https://support.apple.com/en-au/guide/security/welcome/web) 12 | 13 | [The T2 Development Blog](https://web.archive.org/web/20211023034503/https://blog.t8012.dev/ace-part-1/) 14 | 15 | [Apple Silicon DFU Restore guide](https://support.apple.com/guide/apple-configurator-mac/apdd5f3c75ad/mac) 16 | 17 | [arm Architecture Reference Manual (Armv8-A v8.6)](https://documentation-service.arm.com/static/5fa3bd1eb209f547eebd4141?token=) & [Errata](https://documentation-service.arm.com/static/5fc8ec531c8c5d708d2a336e?token=) 18 | 19 | [Rod Smiths Blog](https://www.rodsbooks.com/refind/) (More about the former UEFI mode used on Intel Macs but added for some historical context) 20 | 21 | [S3C2400 datasheet download link](https://www.digchip.com/datasheets/parts/datasheet/409/S3C2400-pdf.php) for samsung serial hardware 22 | ### Social Media 23 | 24 | [Xeno Kovah](https://twitter.com/XenoKovah) ( (ex) Apple Silicon secure boot architect ) 25 | 26 | [Nikolaj Schlej](https://twitter.com/NikolajSchlej) ( Apple Firmware Security Engineer) 27 | 28 | [Longhorn (@never_released)](https://twitter.com/never_released) 29 | -------------------------------------------------------------------------------- /docs/hw/soc/display-controllers.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Display Controllers 3 | --- 4 | 5 | M series of chips have two kinds of display controllers, `dcp` and `dcpext`. Both kinds support 6 | - DP 1.4 (4 lanes) with DSC. No MST! 7 | - HDMI via dp2hdmi converter. See below for routing restrictions. 8 | - USB-C ports: DP altmode, or USB4 tunneling with 2 controllers max per port. See below for routing restrictions. 9 | 10 | Controller-specific information: 11 | 12 | | Type | Mode limits | 13 | | - | - | 14 | | `dcp` | 5K, 60Hz, 10bpp (Apple-provided information, not tested) | 15 | | `dcpext` | 6K, 60Hz, 10bpp (Apple-provided information, not tested) | 16 | 17 | M1 routing restrictions: 18 | 19 | | Controller | Internal display | HDMI | USB-C | 20 | | - | - | - | - | 21 | | `dcp` | + | + | | 22 | | `dcpext` | | | + | 23 | 24 | M2 and later routing restrictions: 25 | 26 | | Controller | Internal display | HDMI | USB-C | 27 | | - | - | - | - | 28 | | `dcp` | + | + | + | 29 | | `dcpext` | | + | + | 30 | 31 | SoC-specific information: 32 | 33 | | SoC | Number of `dcp` | Number of `dcpext` | Notes | 34 | | - | - | - | - | 35 | | M1 | 1 | 1 | | 36 | | M1 Pro | 1 | 2 | | 37 | | M1 Max | 1 | 4 | 38 | | M1 Ultra | 1 | 8 | There are no Ultra devices with internal display. `dcp` is disabled on one of the dies, another `dcp` is routed to HDMI | 39 | | M2 | 1 | 1 40 | | M2 Pro | 1 | 2 41 | | M2 Max | 1 | 4 42 | | M2 Ultra | 0 | 8 | There are no Ultra devices with internal display. `dcp` on both dies are disabled | 43 | | M3 | 1 | 1 | 44 | | M3 Pro | 1 | 2 | 45 | | M3 Max | 1 | 4 | 46 | | M4 | ? | ? | TBD | 47 | | M4 Pro | ? | ? | TBD | 48 | | M4 Max | ? | ? | TBD | 49 | -------------------------------------------------------------------------------- /.github/workflows/container.yml: -------------------------------------------------------------------------------- 1 | name: Container 2 | on: 3 | push: 4 | branches: 5 | - main 6 | paths: 7 | - .github/workflows/container.yml 8 | - Dockerfile 9 | pull_request: 10 | branches: 11 | - main 12 | paths: 13 | - .github/workflows/container.yml 14 | - Dockerfile 15 | 16 | env: 17 | REGISTRY: ghcr.io 18 | # This has to be lowercase 19 | IMAGE_NAME: asahilinux/mkdocs-asahi 20 | 21 | jobs: 22 | build-and-push: 23 | runs-on: ubuntu-latest 24 | permissions: 25 | contents: read 26 | packages: write 27 | steps: 28 | - name: Log into the container registry 29 | uses: docker/login-action@v3 30 | if: github.event_name != 'pull_request' 31 | with: 32 | registry: ${{ env.REGISTRY }} 33 | username: ${{ github.actor }} 34 | password: ${{ secrets.GITHUB_TOKEN }} 35 | - name: Setup Docker Buildx 36 | uses: docker/setup-buildx-action@v3 37 | - name: Build the container image 38 | uses: docker/build-push-action@v6 39 | with: 40 | platforms: linux/amd64,linux/arm64 41 | tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 42 | push: ${{ github.event_name != 'pull_request' }} 43 | cache-from: type=gha 44 | cache-to: type=gha,mode=max 45 | # https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#adding-a-description-to-multi-arch-images 46 | outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=Build the Asahi Linux documentation website using mkdocs 47 | -------------------------------------------------------------------------------- /docs/platform/subsystems.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Silicon Platform Subsystems 3 | --- 4 | 5 | These pages detail the specifics of a particular platform subsystem. They are loosely categorised 6 | by function. 7 | 8 | ### Generalised overviews 9 | * [Introduction to Apple Silicon](introduction.md) 10 | * [Accelerator Engines](../hw/soc/accelerators.md) 11 | 12 | ### Coprocessors and accelerators 13 | * [AGX](../hw/soc/agx.md) - Apple's PowerVR-derived tile-based deferred renderer 14 | * [SEP](../hw/soc/sep.md) - The Secure Enclave, Apple's crypto/biometrics/security engine 15 | 16 | ### Platform control logic 17 | * [AIC](../hw/soc/aic.md) - Apple Interrupt Controller 18 | * [WDT](../hw/soc/wdt.md) - Watchdog Timer 19 | * [SMC](../hw/soc/smc.md) - System Management Controller 20 | * [ASC](../hw/soc/asc.md) - Apple's Mailbox-like firmware interface 21 | 22 | ### Platform initialisation and boot 23 | * [Boot](../fw/boot.md) 24 | * [MachO Boot Protocol](../fw/macho-boot-protocol.md) 25 | * [Memory Map](../hw/soc/memmap.md) 26 | * [SMP spinup](../hw/cpu/smp.md) 27 | * [ADT](../fw/adt.md) (Apple Device Tree) 28 | * [NVRAM](../fw/nvram.md) 29 | 30 | ### Application processors 31 | * [ARM System Registers](../hw/cpu/system-registers.md) 32 | * [SPRR and GXF](../hw/cpu/sprr-gxf.md) 33 | * [CPU Debug Registers](../hw/cpu/debug-registers.md) 34 | * [Apple Instructions](../hw/cpu/apple-instructions.md) 35 | 36 | ### I/O 37 | * [APCIe](../hw/soc/apcie.md) (Apple PCIe controller) 38 | * [GPIO](../hw/soc/gpio.md) 39 | * [USB Debug](../hw/soc/usb-debug.md) 40 | * [USB PD](../hw/soc/usb-pd.md) 41 | * [Stock Partition Layout](stock-partition-layout.md) 42 | 43 | ### Peripherals 44 | * [Camera](../hw/peripherals/camera.md) - Broadcom camera and ISP 45 | -------------------------------------------------------------------------------- /docs/sw/linux-bringup-wifi.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Linux Bringup: WiFi 3 | --- 4 | 5 | # WiFi Support 6 | ## Under MacOS grab the WiFi firmware as per [Glanzmann's notes](https://tg.st/u/asahi.txt) 7 | * Clone the installer 8 | `git clone https://github.com/AsahiLinux/asahi-installer` 9 | * Go into the src directory 10 | `cd asahi-installer/src` 11 | * Grab the firmware into a tar file 12 | `python3 -m firmware.wifi /usr/share/firmware/wifi /tmp/linux-firmware.tar` 13 | ## Install firmware 14 | * Under Linux booted via [USB drive](linux-bringup-usb.md) or [NVMe](linux-bringup-nvme.md) rootfs Create the firmware directory: 15 | `sudo mkdir -p /usr/lib/firmware` 16 | * Install the wifi firmware you extracted earlier 17 | `sudo tar -C /usr/lib/firmware -xf firmware.tar` 18 | * Install any other networking / WiFi packages you will need. e.g. wpasupplicant 19 | ## Enable WiFi 20 | * You need to have built a Asahi Linux kernel with the M1 WiFI support such as the [wifi/take5](https://github.com/AsahiLinux/linux/tree/wifi/take5) branch 21 | * Before you boot that kernel via [m1n1 over USB](linux-bringup.md#directly) - run this script to enable the WiFi hardware 22 | `python3 ./proxyclient/experiments/pcie_enable_devices.py` 23 | * There are other ways to do this - this what I did under Debian linux 24 | * Now after the linux kernel has booted you should be able to see a WiFi device (wlan0) via the usual tools 25 | `ip a l` 26 | * You can start networking the usual Linux tools e.g. 27 | * Edit the configuration file: 28 | ``` 29 | auto wlan0 30 | iface wlan0 inet dhcp 31 | wpa-ssid YOUR_SSID 32 | wpa-psk YOUR_WIFI_PASSPHRASE 33 | ``` 34 | * Then start up the interface (wlan0) via (note -v => verbose info) 35 | `sudo ifup -v wlan0` 36 | -------------------------------------------------------------------------------- /docs/sw/linux-bringup-usb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Linux Bringup: USB 3 | --- 4 | 5 | ## root as USB drive 6 | * Inspired by [Alyssa's tomshardware article](https://www.tomshardware.com/news/apple-m1-debian-linux) 7 | * Make an **arm64** root filesystem as per [debian rootfs](https://www.debian.org/releases/stretch/arm64/apds03.html.en) 8 | * Note: The following is done as root on a debian system: 9 | ``` 10 | mkdir debinst-buster 11 | debootstrap --arch arm64 --foreign buster debinst-buster http://ftp.au.debian.org/debian/ 12 | cp /usr/bin/qemu-aarch64-static debinst-buster/usr/bin 13 | LANG=C.UTF-8 chroot debinst-buster qemu-aarch64-static /bin/bash 14 | ``` 15 | * In the chroot complete the set up: 16 | ``` 17 | /debootstrap/debootstrap --second-stage 18 | ``` 19 | * Install any other packages you want with apt 20 | ``` 21 | apt install file screenfetch procps openssh-server 22 | ``` 23 | * Configure the sshd to allow root access and set the password to what you want 24 | ``` 25 | # Add PermitRootLogin yes 26 | vi /etc/ssh/sshd_config 27 | # Set root's password 28 | passwd 29 | ``` 30 | * Create an ext4 partition on a USB device (e.g. /dev/sdb in example below) 31 | ``` 32 | fdisk /dev/sdb 33 | # n => new partition 34 | # w => write it out 35 | ``` 36 | * Format ext4 filesystem ```mkfs.ext4 /dev/sdb1``` 37 | * Install your new rootfs on it (you could have just created the rootfs on the partition.... :-) 38 | ``` 39 | mount /dev/sdb1 /mnt/img 40 | cp -a debinst-buster/. /mnt/img 41 | umount /mnt/img 42 | ``` 43 | * Boot up linux with the USB drive plugged in (now should be /dev/sda1). I used a simple USB hub on the 2nd port with a USB keyboard the USB drive plugged in before powering on the Mac. 44 | ``` 45 | python3.9 proxyclient/tools/linux.py -b 'earlycon console=tty0 console=tty0 debug net.ifnames=0 rw root=/dev/sda1 rootdelay=5 rootfstype=ext4' Image-dart-dev.gz t8103-j274-dart-dev.dtb 46 | ``` 47 | * **Image-dart-dev.gz** - dart/dev branch of the Asahi linux as above 48 | * **t8103-j274-dart-dev.dtb** - the dtb from the above linux 49 | * NO initrd is passed 50 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Asahi Linux documentation repository 2 | This is the [Asahi Linux documentation](https://asahilinux.org/docs/) repository. 3 | 4 | ## Documentation structure 5 | Our documentation is organised into categories. 6 | 7 | - alt: Alternative operating system/Linux distribution support documentation 8 | should go here. 9 | - fw: Documentation on vendor-controlled firmware and firmware interfaces should 10 | go here. 11 | - hw: Any documentation related to hardware belongs here. This is further split 12 | into subcategories: 13 | - cpu: Application processor documentation 14 | - devices: Documentation relating to specific Mac models 15 | - peripherals: hardware found in Apple Silicon Macs but not the SoC itself 16 | - soc: hardware blocks integrated into Apple Silicon SoCs 17 | - platform: Documentation that applies across the Apple Silicon platform 18 | - project: Project admin documents and stuff unrelated to hardware or software 19 | - sw: Documentation for non-firmware software 20 | 21 | ## Usage 22 | 23 | This is made with [MkDocs](https://www.mkdocs.org/). If you have mkdocs installed 24 | already, run `make build` to build the site, or `make test` to spin up a local webserver 25 | for review. If you don't, feel free to use our [container](https://github.com/AsahiLinux/docs/pkgs/container/mkdocs-asahi) 26 | with something like: 27 | 28 | ``` 29 | $ podman run -it --pull=newer -p=8000:8000 -v=$(pwd)/:/docs:z ghcr.io/asahilinux/mkdocs-asahi:latest 30 | ``` 31 | 32 | if you're using [Podman](https://podman.io), or 33 | 34 | ``` 35 | $ docker run -it --pull=always -p=8000:8000 -v=$(pwd)/:/docs:z ghcr.io/asahilinux/mkdocs-asahi:latest 36 | ``` 37 | 38 | if you're using [Docker](https://www.docker.com). Note that this repository uses 39 | [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so you'll 40 | want to set those up first with `git submodule update --init`. 41 | 42 | The website is rebuilt by the CI on every commit and served via GitHub Pages. 43 | The container is also automatically updated and pushed to the registry. 44 | -------------------------------------------------------------------------------- /docs/hw/cpu/smp.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Symmetric Multiprocessing (SMP) 3 | summary: 4 | Secondary application processor initialisation routine for Apple Silicon 5 | SoCs 6 | --- 7 | 8 | ## SMP spin-up 9 | 10 | From the ADT: 11 | 12 | * `/arm-io/pmgr[reg]` power manager registers 13 | * CPU start block is at a device-dependent offset to this register 14 | * 0x30000 for A7-A8(X) 15 | * 0xd4000 for A9(X)-A11, T2 16 | * 0x54000 for M1 series 17 | * 0x34000 for M2 and M3 18 | * 0x28000 for M2 Pro/Max 19 | * 0x88000 for M3 Pro/Max 20 | * For multi-die systems, each die has its own power manager registers. 21 | The power manager registers for each die is at offset 22 | `die * 0x2000000000` from the registers of die 0. 23 | * `/cpus/cpu[cpu-impl-reg]` CPU implementation registers 24 | * `/cpus/cpu[reg]` CPU startup information 25 | * Bits [0:7] holds the core id 26 | * Bits [8:10] holds the cluster id 27 | * Bits [11:14] holds the die id 28 | 29 | A11 does not handle clusters properly, so both P and E CPUs are considered cluster 0. 30 | ECPUs are 0-3 while PCPUs are 4-5. 31 | 32 | For old firmwares, `/cpus/cpu[cpu-impl-reg]` may not exist, in this case 33 | `/arm-io/reg[2*n+2]` can be used to find the location to write the start address. 34 | 35 | CPU start registers in PMGR: 36 | 37 | ``` 38 | offset + 0x4: System-wide CPU core startup/active bitmask 39 | offset + 0x8: Cluster 0 (e) CPU core startup 40 | offset + 0xc: Cluster 1 (p) CPU core startup 41 | ``` 42 | 43 | ### Startup sequence 44 | 45 | * Write start address to RVBAR at `cpu-impl-reg + 0x00` 46 | * This is locked for cpu0 by iBoot, other CPUs are free to change 47 | * Set (1 << cpu) in `pmgr[offset + 0x4]` 48 | * This seems to be some kind of system-wide "core alive" signal. It is not 49 | required for the core to spin up, but without it AIC interrupts won't 50 | work, and probably other things. 51 | * Set (1 << core) in `pmgr[(offset + 0x8) + 4*cluster]` (that's core from 0-3, cluster 0-1) 52 | * This starts up the core itself. 53 | 54 | Core starts up at RVBAR. Chicken bits / etc must be applied as usual. 55 | -------------------------------------------------------------------------------- /docs/hw/soc/accelerators.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Silicon Accelerators 3 | --- 4 | 5 | The SoC has several onboard accelerator units, this is a useful list of the names and what they refer to. Most of the accelerators run firmware that can be found in the pre-boot partition `/System/Volumes/Preboot/[UUID]/restore/Firmware`, packaged as im4p files which may be extracted with and some dd. 6 | 7 | *Update none of the ANE, AVE, ADT im4p's extract with that. I'm not sure which ones do. You are better off following the im4p extraction steps in [ADT](../../fw/adt.md). Can we make a progress matrix regarding firmware? 8 | 9 | ## Names 10 | 11 | Names can be formatted the following ways depending on their official-ness: 12 | * Names in quotes with a question mark like: "?" are inventions/uncertain in origin. 13 | * Names in **bold** like: **** are found in Apple official documentation. 14 | * Names in *italics* like: ** are either common unofficial names or have uncertain but safe sources. 15 | 16 | ### A 17 | * **AGX**: "Apple Graphics? Accel(x)lerator?" (via `gfx`) The internal name for Apple's GPU series. 18 | * **AMX**: *Apple Matrix eXtensions*. A matrix coprocessor partially integrated into the ISA. 19 | * **ANE**: **Apple Neural Engine** Neural network execution acceleration based on convolutions. Think of Google's TPU 20 | * **AOP**: **Always On Processor**. "hey siri" activation and "other sensor stuff" 21 | * **APR**: **APR ProRes**. Handles ProRes video encoding + decoding. 22 | * **AVE**: **AVE Video Encoder**. Handles video encoding. Ostensibly the A is for Apple [citation needed], but I see a recursive acronym. 23 | * **AVD**: **AVD Video Decoder**. Handles video decoding. ^ 24 | 25 | ### D 26 | * **DCP**: "Display Compression Processor?"/"Display Control Processor?". Displayport/Display control of some sort. 27 | 28 | ### P 29 | * **PMP**: "Power Management Processor?". Handles power functionality 30 | 31 | ### S 32 | * **SEP**: **Secure Enclave Processor**. The M1's built-in HSM/TPM/etc device. Handles Touch ID and most crypto, as well as boot policy decisions. Harmless to Linux, but we can use its features if we want to. Contrast to AP. 33 | -------------------------------------------------------------------------------- /docs/hw/cpu/apple-instructions.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Proprietary Instructions 3 | summary: 4 | Apple's proprietary extensions to the A64 Instruction Set 5 | --- 6 | 7 | Apple proprietary instructions seem to be in the 0x0020xxxx range. 8 | 9 | ``` 10 | 00200000 - 002007ff MUL53, see https://gist.github.com/TrungNguyen1909/5b323edda9a21550a1621af506e8ce5f 11 | 12 | 00200800 | rD << 5 | rS wkdmc, compress memory page 13 | - rS is the source page address (page-aligned, bottom bits ignored) 14 | - rD is the destination compressed data address (64b aligned, bottom bits ignored) 15 | - Status/info gets returned in rS. 16 | 17 | 00200c00 | rD << 5 | rS wkdmd, uncompress memory page 18 | - rS is the source compressed data address (64b aligned, bottom bits ignored) 19 | - rD is the destination compressed data address (page-aligned, bottom bits ignored) 20 | - Status/info gets returned in rS. 21 | 22 | 00201000 - 002012df AMX, see https://gist.github.com/dougallj/7a75a3be1ec69ca550e7c36dc75e0d6f 23 | If AMX is not enabled (default), these fault with ESR_EL2 = 0xfe000003 24 | 25 | ..222~23f "hole" of unknown instructions 26 | 27 | 002012e0 - 0020143f Faults with unknown instruction 28 | 29 | *00201400 gexit, Exit guarded mode. Used by macOS; must need some enable (faults by default). 30 | *00201420 | imm5 genter, Enter guarded mode. Used by macOS; must need some enable (faults by default). 31 | imm5 stored in ESR_GLx[5:0] 32 | 33 | 00201440 | rA at_as1elx, Translate address. Returns in the same register: 34 | [63:56] MAIR attributes for translation (not index!) 35 | [??:12] Physical address 36 | [11:00] Flags/status/etc. 0x80x = unmapped, x varies depending on PT level that faulted? 37 | 38 | This seems to be the same as the PAR_EL1 system register, used as the output for the *official* ARM translate address instructions. 39 | 40 | 00201460 sdsb osh 41 | 00201461 sdsb nsh 42 | 00201462 sdsb ish - used by iBoot trampoline 43 | 00201463 sdsb sy 44 | 45 | 00201464 ~ Faults with unknown instruction 46 | 47 | 48 | ``` 49 | -------------------------------------------------------------------------------- /docs/hw/soc/aic.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Interrupt Controller (AIC) 3 | --- 4 | 5 | AIC is the Apple Interrupt Controller. These are some scattered RE notes. 6 | 7 | Apple likes to use a particular SET/CLR register pair style: 8 | 9 | * SET: reads current state, writes set bits set to 1 10 | * CLR: reads current state, writes clear bits set to 1 11 | 12 | ## Registers 13 | 14 | ``` 15 | 0000~ global stuff 16 | 0004: NR_IRQ? 17 | 0010: GLOBAL_CFG? (impl bits: f8fffff1) 18 | 2000~ interrupt acks, IPIs, etc 19 | 20 | 3000~ IRQ_TGT (1 per reg, CPU bitfield each reg) 21 | 4000~ SW_GEN_SET (bitfields) 22 | 4080~ SW_GEN_CLR (bitfields) 23 | 4100~ IRQ_MASK_SET (bitfields) 24 | 4180~ IRQ_MASK_CLR 25 | 4200~ HW_IRQ_MON (current interrupt line state?) 26 | 27 | 8020 Low 32 bits of MSR CNTPCT_EL0 (system timer) 28 | 8028 High 32 bits of MSR CNTPCT_EL0 (system timer) 29 | 30 | Mirror accessing per-core state for the current CPU core: 31 | 2004 IRQ_REASON 32 | 2008 IPI_SEND - Send an IPI, bits 0..<31 send an other IPI to a CPU, bit 31 sends a "self" IPI to this CPU 33 | 200c IPI_ACK - Acks an IPI, bit 0 acks an "other" IPI, and bit 31 acks a "self" IPI 34 | 2024 IPI_MASK_SET - Mask bits for IPIs correspond to the same type and position of the bits for IPI_ACK 35 | 2028 IPI_MASK_CLR 36 | 37 | TODO Document direct access to per-core state offsets 38 | ``` 39 | 40 | ## Usage 41 | 42 | IPI flow: 43 | 44 | * Write bit to IPI_SEND 45 | * ARM IRQ asserted 46 | * Read IRQ_REASON 47 | * IPI is masked in IPI_MASK 48 | * ARM irq is desasserted 49 | * Write bit to IPI_ACK 50 | * Write bit to IPI_MASK_CLR 51 | * IPI is unmasked 52 | * if IPI_ACK was not cleared, ARM irq would reassert here 53 | 54 | HW irq flow: 55 | 56 | * Set target bitfield in IRQ_TGT 57 | * Write bit to IRQ_MASK_CLR 58 | * (later) HW IRQ asserted 59 | * Read IRQ_REASON 60 | * IRQ_MASK is automatically set 61 | * ARM irq is desasserted 62 | * (clear the IRQ in the specific hardware) 63 | * Write bit to IRQ_MASK_CLR 64 | * IRQ is unmasked 65 | * if hardware line was not cleared, ARM irq would reassert here 66 | 67 | There are 11 targets? CPUs 0-7 and some auxiliary ones? 68 | 69 | Bits set in SW_GEN are ORed with the hardware IRQ lines 70 | 71 | ## Timer 72 | 73 | The system timer is the standard ARM64 MSR stuff, and bypasses AIC. It is wired straight to FIQ. 74 | -------------------------------------------------------------------------------- /docs/hw/soc/soc-codenames.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: SoC Codenames 3 | --- 4 | 5 | Apple likes to use many different names for the same devices. 6 | 7 | ## SoCs 8 | 9 | | Marketing | Internal | Codename | SoC | P-Core | E-Core | 10 | | --------- | -------- | -------- | --- | ------ | ------ | 11 | | S1 | M7 | | S7002 | Cortex-A7 12 | | S1P, S2, T1 | M8 | | T8002 | Cortex-A7 13 | | S3 | M8P | | T8004 | Cortex-A7 14 | | | | | S5L8747 | Cortex-A5 15 | | | H2 | | | Cortex-A8 16 | | A4 | H3 | | S5L8930 | Cortex-A8 17 | | A5 | H4 | | S5L8940 | Cortex-A9 18 | | A5 | H4A | | S5L8942 | Cortex-A9 19 | | A5 | H4i | | S5L8947 | Cortex-A9 20 | | A6 | H5P | Bali | S5L8950 | Swift 21 | | A6X | H5G | Bali | S5L8955 | Swift 22 | | A7 | H6 | Alcatraz | S5L8960 | Cyclone 23 | | A8 | H7P | Fiji | T7000 | Typhoon 24 | | A8X | H7G | Capri | T7001 | Typhoon 25 | | A9 | H8P (Samsung) | Maui | S8000 | Twister 26 | | A9 | H8P (TSMC) | Malta | S8003 | Twister 27 | | A9X | H8G | Elba | S8001 | Twister 28 | | A10 | H9P | Cayman | T8010 | Hurricane | Zephyr (CLS) 29 | | A10X | H9G | Myst | T8011 | Hurricane | Zephyr (CLS) 30 | | T2 | H9M | Gibraltar | T8012 | Hurricane | Zephyr (CLS) 31 | | A11 | H10 | Skye | T8015 | Monsoon | Mistral 32 | | A12 | H11P | Cyprus | T8020 | Vortex | Tempest 33 | | S4, S5 | M9 | | T8006 | - | Tempest 34 | | A12X, A12Z | H11G | Aruba | T8027 | Vortex | Tempest 35 | | | | Tinos | T8028 | Vortex | - 36 | | A13 | H12 | Cebu | T8030 | Lightning | Thunder 37 | | S6, S7, S8 | M10 | Turks | T8301 | - | Thunder 38 | | A14 | H13P | Sicily | T8101 | Firestorm | Icestorm 39 | | M1 ("A14X") | H13G | Tonga | T8103 | Firestorm | Icestorm 40 | | M1 Pro | H13J | Jade Chop | T6000 | Firestorm | Icestorm 41 | | M1 Max | H13J | Jade 1C | T6001 | Firestorm | Icestorm 42 | | M1 Ultra | H13J | Jade 2C | T6002 | Firestorm | Icestorm 43 | | R1 | | | T6500 | | 44 | | A15 | H14P | Ellis | T8110 | Avalanche | Blizzard 45 | | M2 | H14G | Staten | T8112 | Avalanche | Blizzard 46 | | M2 Pro | H14J | Rhodes Chop | T6020 | Avalanche | Blizzard 47 | | M2 Max | H14J | Rhodes 1C | T6021 | Avalanche | Blizzard 48 | | M2 Ultra | H14J | Rhodes 2C | T6022 | Avalanche | Blizzard 49 | | A16 | H15P | Crete | T8120 | Everest | Sawtooth 50 | | S9 | M9| | T8310 | - | Sawtooth 51 | | A17 Pro | H16P | Coll | T8130 | | 52 | | M3 | H15G | Ibiza | T8122 | Everest | Sawtooth 53 | | M3 Pro | H15J | Lobos | T6030 | Everest | Sawtooth 54 | | M3 Max | H15J/H15S | Palma | T6031 / T6034 | Everest | Sawtooth | 55 | | M4 | H16G | Donan | T8132 | | | 56 | | M4 Pro | H16S | Brava Chop | T6040 | | 57 | | M4 Max | H16C | Brava | T6041 | | 58 | | A18 | H17A | Tupai | T8140a | | 59 | | A18 Pro | H17P | Tahiti | T8140 | | 60 | | | | Hidra | | | 61 | | | | Sotra_C | | | 62 | | | | Sotra_S | | | 63 | | | | Sotra_D | | | 64 | | | | Thera | | | 65 | | | | Komodo | | | 66 | | | | Tilos | | | 67 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | Welcome to the Asahi Linux documentation! Here, you will find documentation on the 2 | Apple Silicon platform as implemented on Mac computers with M-series SoCs. We aim 3 | to document the platform in a way that is useful for everyone, however our focus is 4 | supporting third-party operating systems, particularly Linux. 5 | 6 | We also have documentation on the various pieces of software required to properly 7 | support this platform, such as m1n1 and U-Boot. Documentation for software that we 8 | have created (such as m1n1) aims to be as complete as possible. Documentation for 9 | external projects (such as U-Boot) is limited to how that software is used on the 10 | Apple Silicon platform. 11 | 12 | ## Who this documentation is for 13 | - Operating system and kernel developers looking to implement support for Apple Silicon 14 | - Folks interested in hacking on and reverse engineering the Apple Silicon platform 15 | - End users looking for guides and information on supported features 16 | - Anyone interested in the Asahi Linux project looking for more information 17 | 18 | Questions? Please check out the [FAQ](project/faq.md) first! 19 | 20 | ## Developers 21 | We have extensive documentation on the platform itself, and the tooling we use to 22 | reverse engineer and develop Linux drivers for it. Check out the sidebar for places 23 | to start! 24 | 25 | ## End Users 26 | Check out [Feature Support](platform/feature-support/overview.md) for supported devices 27 | and features. If you're after documentation on something specific, use the search feature 28 | at the top of the page or check out the sidebar for places to start! 29 | 30 | ## Latest Asahi Linux blog posts 31 | * [Beyond Gaming: X11 bridging in muvm](https://asahilinux.org/2024/12/muvm-x11-bridging/) 32 | * [AAA gaming on Asahi Linux](https://asahilinux.org/2024/10/aaa-gaming-on-asahi-linux/) 33 | * [Vulkan 1.3 on the M1 in 1 month](https://asahilinux.org/2024/06/vk13-on-the-m1-in-1-month/) 34 | * [Conformant OpenGL 4.6 on the M1](https://asahilinux.org/2024/02/conformant-gl46-on-the-m1/) 35 | * [New in Fedora Asahi Remix](https://asahilinux.org/2024/01/fedora-asahi-new/) 36 | * [Our new flagship distro: Fedora Asahi Remix](https://asahilinux.org/2023/08/fedora-asahi-remix/) 37 | * [OpenGL 3.1 on Asahi Linux](https://asahilinux.org/2023/06/opengl-3-1-on-asahi-linux/) 38 | * [Paving the Road to Vulkan on Asahi Linux](https://asahilinux.org/2023/03/road-to-vulkan/) 39 | * [Apple GPU drivers now in Asahi Linux](https://asahilinux.org/2022/12/gpu-drivers-now-in-asahi-linux/) 40 | * [Updates galore! November 2022 Progress Report](https://asahilinux.org/2022/11/november-2022-report/) 41 | * [M2 is here! July 2022 Release & Progress Report](https://asahilinux.org/2022/07/july-2022-release/) 42 | * [The first Asahi Linux Alpha Release is here!](https://asahilinux.org/2022/03/asahi-linux-alpha-release/) 43 | -------------------------------------------------------------------------------- /docs/hw/soc/asc.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: ASC 3 | --- 4 | 5 | ## ASC registers 6 | 7 | ``` 8 | 0x40 - some flags/ctrl 9 | 10 | 0x44 - CPU_CTRL 11 | 4 - CPU_START 12 | 13 | 0x48 - CPU_STATUS 14 | 5 - MBOXES_TO_AP_EMPTY 15 | 4 - ? 16 | 3 - FIQ_NOT_PENDING 17 | 2 - IRQ_NOT_PENDING 18 | 1 - CPU_STOPPED 19 | 0 - CPU_IDLE 20 | 21 | 0x400 22 | 10 - set when the CPU is started (probably by firmware) 23 | 24 | 0x80c - IRQ_CONFIG 25 | 0 - IRQ_CONTROLLER_ENABLE 26 | 27 | 0x818 - IRQ_EVENT_IRQ? 28 | 0x820 - IRQ_EVENT_FIQ? 29 | 30 | 0xa00.. - IRQ_MASK_SET 31 | 0xa80.. - IRQ_MASK_CLEAR 32 | 0xb00.. - IRQ_MASK2_SET? 33 | 0xb80.. - IRQ_MASK2_CLEAR? 34 | 35 | 0x1000 - CFG? 36 | 1 - IPIs to IRQ, not FIQ? 37 | 0x1010 - A_SET 38 | 0x1014 - B_SET 39 | 0x1018 - A_CLR 40 | 2 - triggers FIQ IPI? 41 | 1 - triggers IRQ IPI? 42 | 0x101c - B_CLR 43 | 44 | 0x1030 - C_SET 45 | 0x1034 - D_SET 46 | 0x1038 - C_CLR 47 | 0x103c - D_CLR 48 | 49 | 0x8000 - mirror of CPU_STATUS? 50 | 51 | 0x4000~ and 0x8000~ are mailbox stuff 52 | ``` 53 | 54 | ## Mailboxes 55 | 56 | Communication between the M1's main CPU cores and the ASCs/IOPs (I/O processors) uses hardware mailboxes to send 128-bit notifications back and forth between the processors, in addition to larger messages sent using shared memory. The usual protocol is that one of the processors writes to shared memory, then sends a mailbox notification to the other processor which triggers an interrupt which causes the other processor to look at the modified memory and interpret a larger message. 57 | 58 | While protocols differ between processors, a common element appears to be that the low-order 8 bits of the second 64-bit half of the message encode the endpoint at the IOP side of the message. The first 64 bits appear to be passed through by the mailbox without further changes and very different encodings are used for them. 59 | 60 | The hardware side of the mailbox is located at offset +0x8000 in MMIO space, and uses four interrupts numbered consecutively at the [AIC](aic.md), two of which are useful to us. 61 | 62 | Data is sent from the main CPU to the IOP when two 64-bit writes target offsets +0x8800 and +0x8808. Once the IOP reads the data and removes it from the queue, the interrupt with the lowest number at the AIC will trigger until it is disabled or further data is written. 63 | 64 | Data from the IOP is read by the main CPU, and removed from the queue, by performing 64-bit MMIO reads at offsets +0x8830 and +0x8838. While data is available, the interrupt with the highest number at the AIC will trigger. 65 | 66 | A 32-bit status register at +0x8110 indicates whether the CPU-to-IOP queue is empty (bit 17) or not empty (bit 16). Symmetrically, the status register at +0x8114 indicates whether the IOP-to-CPU queue is empty (bit 17) or not empty (bit 16). 67 | 68 | It is possible for several messages to be queued in the same direction at the same time, and this is used by IOPs which send more than one notification to the CPU without waiting for an ack. 69 | -------------------------------------------------------------------------------- /docs/hw/cpu/sprr-gxf.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: SPRR and GXF 3 | summary: 4 | SPRR and GXF are in-silicon security features used to harden macOS/Darwin 5 | --- 6 | 7 | 8 | # Guarded execution 9 | 10 | Guarded execution mode is a lateral exception level next to EL1 and EL2 which uses the same pagetables but different permissions (see SPRR). These levels are called GL1 and GL2. It's enabled with bit 1 in S3_6_C15_1_2. 11 | 12 | The instruction `0x00201420` is genter and switches from EL to GL and sets the PC to `S3_6_C15_C8_1`. 13 | `0x00201420` is gexit which returns to EL. 14 | 15 | ``` 16 | #define SYS_GXF_ENTER_EL1 sys_reg(3, 6, 15, 8, 1) 17 | ``` 18 | 19 | Guarded mode has a separate set of ELR, FAR, ESR, SPSR, VBAR and TPIDR registers just like EL1/2. 20 | Additionally the ASPSR register indicates if gexit should return to GL or EL. 21 | 22 | ``` 23 | #define SYS_TPIDR_GL1 sys_reg(3, 6, 15, 10, 1) 24 | #define SYS_VBAR_GL1 sys_reg(3, 6, 15, 10, 2) 25 | #define SYS_SPSR_GL1 sys_reg(3, 6, 15, 10, 3) 26 | #define SYS_ASPSR_GL1 sys_reg(3, 6, 15, 10, 4) 27 | #define SYS_ESR_GL1 sys_reg(3, 6, 15, 10, 5) 28 | #define SYS_ELR_GL1 sys_reg(3, 6, 15, 10, 6) 29 | #define SYS_FAR_GL1 sys_reg(3, 6, 15, 10, 7) 30 | ``` 31 | 32 | 33 | # SPRR 34 | 35 | SPRR takes the permission bits from pagetable entries and converts them into an attribute index similar to how MAIR works: 36 | 37 | ``` 38 | 3 2 1 0 39 | AP[1] AP[0] UXN PXN 40 | ``` 41 | 42 | Note that UXN and PXN are flipped compared to APRR! 43 | 44 | This is then used to index into a system register where each entry has four bits: 45 | 46 | 47 | ``` 48 | 3 2 1 0 49 | GL[1] GL[0] EL[1] EL[0] 50 | ``` 51 | 52 | GL/EL can be treated mostly separate but there are two exceptions where a specific GL permissions 53 | modifies what the two EL bits usually mean. 54 | 55 | 56 | | register value | EL page permissions | GL page permissions | 57 | |-|-|-| 58 | | `0000` | `---` | `---` | 59 | | `0001` | `r-x` | `---` | 60 | | `0010` | `r--` | `---` | 61 | | `0011` | `rw-` | `---` | 62 | | `0100` | `---` | `r-x` | 63 | | `0101` | `r-x` | `r-x` | 64 | | `0110` | `r--` | `r-x` | 65 | | `0111` | `---` | `r-x` | 66 | | `1000` | `---` | `r--` | 67 | | `1001` | `--x` | `r--` | 68 | | `1010` | `r--` | `r--` | 69 | | `1011` | `rw-` | `r--` | 70 | | `1100` | `---` | `rw-` | 71 | | `1101` | `r-x` | `rw-` | 72 | | `1110` | `r--` | `rw-` | 73 | | `1111` | `rw-` | `rw-` | 74 | 75 | 76 | These four bits indicate the actual permissions when running in EL or GL mode. 77 | EL0 and EL1 have separate registers such that the permissions are decoupled. 78 | 79 | bit 1 in S3_6_C15_C1_0 / SPRR_CONFIG_EL1 enables SPRR and access to new system registers. 80 | 81 | S3_6_C15_1_5 is the permissions register for EL0 and S3_6_C15_1_6 is for EL1/GL1. 82 | 83 | ``` 84 | #define SYS_SPRR_CONFIG_EL1 sys_reg(3, 6, 15, 1, 0) 85 | #define SPRR_CONFIG_EN BIT(0) 86 | #define SPRR_CONFIG_LOCK_CONFIG BIT(1) 87 | #define SPRR_CONFIG_LOCK_PERM_EL0 BIT(4) 88 | #define SPRR_CONFIG_LOCK_PERM_EL1 BIT(5) 89 | 90 | #define SYS_SPRR_PERM_EL0 sys_reg(3, 6, 15, 1, 5) 91 | #define SYS_SPRR_PERM_EL1 sys_reg(3, 6, 15, 1, 6) 92 | ``` 93 | 94 | -------------------------------------------------------------------------------- /docs/sw/profiling.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Profiling Linux Software 3 | --- 4 | 5 | `perf stat` works on Asahi Linux on bare metal, using Apple's proprietary performance counters (which are supported in the kernel). 6 | 7 | Since this is a big.LITTLE system, there are some caveats. Profiling across core types is confusing, so you should pin your task to one core type. And since performance counters can differ per core type, you have to explicitly qualify counters with the core type when you specify them. 8 | 9 | For example, to profile `echo` on core 4 (a big Firestorm core on all M1 variants): 10 | 11 | $ taskset -c 4 perf stat -e apple_firestorm_pmu/cycles/ -e apple_firestorm_pmu/instructions/ echo 12 | 13 | Performance counter stats for 'echo': 14 | 15 | 116,874 apple_firestorm_pmu/cycles/u 16 | 181,687 apple_firestorm_pmu/instructions/u 17 | 18 | 0.000352959 seconds time elapsed 19 | 20 | 0.000000000 seconds user 21 | 0.000357000 seconds sys 22 | 23 | On core 0 (a LITTLE Icestorm core on all M1 variants): 24 | 25 | $ taskset -c 0 perf stat -e apple_icestorm_pmu/cycles/ -e apple_icestorm_pmu/instructions/ echo 26 | 27 | Performance counter stats for 'echo': 28 | 29 | 185,564 apple_icestorm_pmu/cycles/u 30 | 181,669 apple_icestorm_pmu/instructions/u 31 | 32 | 0.000491126 seconds time elapsed 33 | 34 | 0.000510000 seconds user 35 | 0.000000000 seconds sys 36 | 37 | Note how Icestorm gets ~1 IPC while Firestorm gets ~1.6 IPC in this example; this is why you have to pin your tasks to get meaningful numbers. You can technically not pin your task and specify all counters, and then you will get independent counts for how many cycles/instructions were spent on each core type (aggregated across all cores of that type). Whether this is actually useful to anyone is unclear. 38 | 39 | This will never work in a VM, because Apple do not support the standard ARM performance counters (they use a custom PMU) and they do not expose proprietary features to VM guests (and nor will KVM/qemu for that matter). But it does work on bare metal (and on the m1n1 hypervisor, though benchmarking on it is probably a very bad idea). 40 | 41 | You can also get more counters other than cycles/instructions, by specifying the raw event IDs. These are not currently mapped to friendly names in Linux, but you can use `r`. Dougall has documented a bunch of them [here](https://github.com/dougallj/applecpu/blob/main/timer-hacks/bench.py#L85). For example, to get DCACHE_LOAD_MISS: 42 | 43 | $ taskset -c 4 perf stat -e apple_firestorm_pmu/rbf/ echo 44 | 45 | Performance counter stats for 'echo': 46 | 47 | 3,136 apple_firestorm_pmu/rbf/u 48 | 49 | 0.000288042 seconds time elapsed 50 | 51 | 0.000301000 seconds user 52 | 0.000000000 seconds sys 53 | 54 | Note that it is not guaranteed that all of these will be the same across big/LITTLE cores, and some will differ with newer core types. 55 | -------------------------------------------------------------------------------- /docs/project/trivia.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Platform Trivia 3 | --- 4 | 5 | A list of random fun trivia about this platform and its legacy. 6 | 7 | # iPhone legacy 8 | ## My M1 thinks it's an iPhone 5 9 | 10 | When an M1 Mac Mini is booted without a display connected, or unconditionally as of macOS 12.0, iBoot does not initialize the display. Instead it creates fake 640×1136 framebuffer. That's the screen resolution of the iPhone 5. 11 | 12 | Then this happens: 13 | 14 | ![Framebuffer](../assets/m1_iphone_5_fb.png) 15 | 16 | ## Just can't let go of Samsung 17 | 18 | The serial port peripheral in the M1 is ~identical to the one in the original iPhone SoC by Samsung (S5L8900), to the point where we use the same Samsung UART driver in Linux. We don't know if these days it's a re-implementation by Apple, or if they're still licensing the same old Samsung IP. 19 | 20 | In fact, the idea that the Apple A4 was the first "in-house" design by Apple is primarily marketing. Apple SoCs have been leading a slow transition away from third-party IP to Apple IP, but they still use plenty of third-party blocks. There is no clear line between third-party and in-house design. 21 | 22 | # PowerPC legacy 23 | 24 | ## HIDden registers 25 | 26 | Apple CPU cores call their miscellaneous configuration/[chicken bit](https://en.wiktionary.org/wiki/chicken_bit) registers "HIDx" registers, meaning "Hardware Implementation Dependent" register. This name was first used by IBM in their PowerPC CPUs for the same purpose. 27 | 28 | ## DARTing back to the Power Mac G5 29 | 30 | The IOMMUs in Apple SoCs are called "DART"s. This stands for "Device Address Resolution Table", which was also the name of the IOMMU in the U3H host bridge in Power Mac G5 systems. The actual details are unrelated, though, so there is no shared code for this; only the name is the same. 31 | 32 | ## What do an AmigaOne X1000 and an M1 Mac have in common? 33 | 34 | The I²C peripheral in the M1 and other recent Apple SoCs is a modified version of the I²C peripheral in the PWRficient PA6T-1682M chip from P. A. Semi. Apple bought the company to kickstart their SoC/CPU design team, and decided that one IP block was good enough to just keep. This is the same CPU that is used in the AmigaOne X1000, and we extended the existing Linux driver to support both platforms. 35 | 36 | # x86 legacy 37 | 38 | ## My M1 natively runs x86 code 39 | 40 | The DisplayPort to HDMI bridge chip in the Mac Mini and 14"/16" MacBook Pros (MDCP29xx) uses a V186 CPU core. That's an Intel 80186 clone, running good old 16-bit x86 real mode code. Yes, x86 from the MS-DOS era is in your Mac. 41 | 42 | # Attention to detail 43 | 44 | ## Help me! 45 | 46 | The Mac’s [SecureROM](../fw/boot.md#stage-0-securerom) is small and can’t do much by itself; on the Mac mini, it cannot display an image on the screen. It can, however, control the power LED. 47 | If you start the Mac in [DFU mode](glossary.md#d), the LED will be amber instead of white. 48 | If you start the Mac normally and the early boot process fails (for instance, because of a failed restore operation), the power LED will be amber, and blink with the following pattern: three short blinks, three longer blinks, three shorts blinks, a pause, and repeat. That is [Morse code for SOS](https://en.wikipedia.org/wiki/Morse_code#Applications_for_the_general_public)! The Mac is quietly asking to be saved… 49 | 50 | 51 | -------------------------------------------------------------------------------- /docs/sw/undoing-early-speaker-hacks.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Undoing Early Speaker Hacks 3 | --- 4 | 5 | ### Introduction 6 | You are probably here because you tried to enable your speakers early, and a change in config 7 | between when you did this and the public release of speaker support broke something. You were 8 | warned. 9 | 10 | Below are some fixes for common early adopter hacks. Please try _all_ of them before filing a bug. 11 | Your bug will be ignored if we find that you have failed to rectify any of the issues 12 | below. 13 | 14 | ### The Pro Audio profile is/was enabled for the internal speakers / headphones 15 | This one can happen in one of three ways: 16 | * You have changed the profile while headphones were plugged in 17 | * You have been using a very, very, _very_ old version of `asahi-audio` 18 | * You have circumvented Wireplumber node permissions to experiment with device profiles 19 | 20 | In the first case change the profile back to `Default` (HiFi). In KDE's Audio settings 21 | change the profile back to `Default`. If no headphones are plugged in press 22 | `Show Inactive Devices`. The same should be possible with applications like `pavucontrol`. 23 | In doubt delete WirePlumber's sstate directory (`rm -rf ~/.local/state/wireplumber/`) 24 | and reboot. 25 | 26 | The fix in the two other cases is the the same: 27 | 1. `rm -rf ~/.local/state/wireplumber/` 28 | 2. Reinstall `asahi-audio`, Pipewire _and_ Wireplumber 29 | 3. Reboot your machine 30 | 31 | ### You have files in /etc/ from a prerelease version of asahi-audio 32 | Very old versions of `asahi-audio` stored their configuration inside `/etc/pipewire/` and 33 | `/etc/wireplumber/`. There should be nothing Asahi related in _either_ of these directories 34 | or any of their subdirectories. To fix this: 35 | ```sh 36 | rm -rf /etc/wireplumber/wireplumber.conf.d/*asahi* 37 | rm -rf /etc/wireplumber/main.lua.d/*asahi* 38 | rm -rf /etc/wireplumber/policy.lua.d/*asahi* 39 | rm -rf /etc/pipewire/pipewire.conf.d/*asahi* 40 | ``` 41 | Once you have done this, reinstall `asahi-audio`, Pipewire _and_ Wireplumber then reboot 42 | your system. 43 | 44 | ### You have files in /usr/share/ from a prerelease version of asahi-audio 45 | Prerelease versions of `asahi-audio` had files in `/usr/share/` that do not match the ones 46 | that shipped with 1.0. These files can conflict with the release versions, causing issues. 47 | You must manually remove all `asahi-audio` files: 48 | ```sh 49 | rm -rf /usr/share/asahi-audio/ 50 | rm -rf /usr/share/wireplumber/wireplumber.conf.d/*asahi* 51 | rm -rf /usr/share/wireplumber/main.lua.d/*asahi* 52 | rm -rf /usr/share/wireplumber/policy.lua.d/*asahi* 53 | rm -rf /usr/share/pipewire/pipewire.conf.d/*asahi* 54 | ``` 55 | Once you have done this, reinstall `asahi-audio`, Pipewire _and_ Wireplumber then reboot 56 | your system. 57 | 58 | ### You have tried to manually circumvent our kernel-level safety controls 59 | Remove `snd_soc_macaudio.please_blow_up_my_speakers` from wherever you added it. This could be 60 | the default kernel command line, `modprobe.d`, or somewhere else. Reboot when this is done. 61 | 62 | ### Required speaker codec settings are not being applied 63 | This can happen if you are on an old kernel, or you have manually set `snd_soc_tas2764.apple_quirks` 64 | to some nonstandard value. As above, remove any reference to this module parameter, update your kernel, 65 | then reboot. 66 | -------------------------------------------------------------------------------- /docs/fw/adt.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Device Tree (ADT) 3 | summary: 4 | Apple Device Tree, the hardware discovery and initialisation 5 | system used on Apple Silicon devices. 6 | --- 7 | 8 | When Apple firmware boots a kernel, it passes a device tree in a binary format. This format is very similar to, but different from, the Open Firmware standard expected by Linux. 9 | 10 | Like Linux devicetrees, the Apple device tree (ADT) encodes a number of untyped byte arrays (properties) in a hierarchy of nodes. These describe the available hardware, or provide other information that Apple thinks the firmware might need to tell the kernel about. This includes identifying and secret information like serial numbers and WiFi keys. 11 | 12 | The main difference between ADTs and Linux DTs is byte order; since properties are untyped, we can't automatically correct for that. 13 | 14 | ## Obtaining your ADT 15 | 16 | Given hardware, you can access your ADT in a number of ways. 17 | 18 | ### Option 1: via m1n1 debug console. 19 | The easiest way is probably using m1n1 via adt.py 20 | 21 | ``` 22 | cd m1n1/proxyclient ; python -m m1n1.adt --retrieve dt.bin 23 | ``` 24 | 25 | This will write a file called "dt.bin" containing the raw (binary) ADT and print the decoded ADT. 26 | 27 | ### Option 2: via macOS im4p files (Note: these are missing details filled in by iBoot during boot) 28 | ### img4lib 29 | Get a copy of xerub's img4lib 30 | 31 | ``` 32 | git clone https://github.com/xerub/img4lib 33 | cd img4lib 34 | make -C lzfse 35 | make 36 | make install 37 | ``` 38 | 39 | ### img4tool 40 | Get a copy of tihmstar's img4tool (you will also need his libgeneral as well as autoconf, automake, libtool, pkg-config, openssl and libplist-2.0). 41 | 42 | ``` 43 | git clone https://github.com/tihmstar/libgeneral.git 44 | git clone https://github.com/tihmstar/img4tool.git 45 | ``` 46 | then for each 47 | ``` 48 | ./autogen.sh 49 | make 50 | make install 51 | ``` 52 | ### Obtaining device tree files 53 | copy the im4p file from the below directory. See [Devices](../hw/devices/device-list.md) for Machine 'j' model details. 54 | 55 | `/System/Volumes/Preboot/[UUID]/restore/Firmware/all_flash/DeviceTree.{model}.im4p` 56 | 57 | If the dir doesn't exist try disabling csrutil in recovery mode, going to settings and enabling terminal to access all files, or start from `Volumes/Macintosh HD/` because it may be symlinked. If it's still not accessible, try good ol `sudo find . -type f -name '*.im4p'`. 58 | 59 | then use img4tool to extract the im4p file into a .bin file e.g. 60 | ``` 61 | img4tool -e DeviceTree.j274ap.im4p -o j274.bin 62 | ``` 63 | To do the same with img4lib, do 64 | ``` 65 | img4 -i DeviceTree.j274ap.im4p -o j274.bin 66 | ``` 67 | 68 | ### Option 3: From macOS 69 | 70 | You can get a textual representation of the ADT directly from macOS by running: 71 | ``` 72 | ioreg -p IODeviceTree -l | cat 73 | ``` 74 | While this does not require decoding, it outputs much less information than using m1n1 (see below). 75 | 76 | ## Decoding an ADT 77 | 78 | after m1n1 installation (see [repo page](https://github.com/AsahiLinux/m1n1)) 79 | 80 | `cd m1n1/proxyclient` 81 | 82 | get construct python library (not a construct.py file, it's a library) 83 | 84 | `pip install construct` 85 | 86 | copy obtained j{*}.bin file into proxyclient dir && extract by: 87 | 88 | `python -m m1n1.adt j{*}.bin` 89 | 90 | You can also get a memory map with the -a option: 91 | 92 | `python -m m1n1.adt -a j{*}.bin` 93 | 94 | Other ways? 95 | 96 | -------------------------------------------------------------------------------- /docs/project/help-wanted.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Help Wanted! 3 | --- 4 | 5 | This page is a list of miscellaneous tasks that need to be done, but may have been de-prioritised in order to focus on frying bigger fish. 6 | Most of these tasks will be low stakes and low effort, making them good places to start for newcomers to kernel development or Free Software 7 | in general. 8 | 9 | If you decide to take up any of these tasks, please update the task's status to avoid duplicate work. Reach out on `#asahi-dev` if you have 10 | any questions or are in need of assistance. 11 | 12 | | Task | Status | Description | Contact | 13 | | ---- | ------ | ----------- | ------- | 14 | | libgnome-volume-control fixes | Unclaimed | GNOME's volume mixer is implemented in the `libgnome-volume-control` plugin. Unfortunately, this interacts poorly with WirePlumber/Pipewire and does not seem to respect node graph permissions. This leads to the default sink being the "raw" hardware device on GNOME, bypassing our DSP, which is completely unsupported. `libgnome-volume-control` needs to be fixed so that it hides the raw hardware sink and selects the correct default sink. | chadmed | 15 | | Rewrite tuxvdmtool to userspace i2c | **Unclaimed** | [tuxvdmtool](https://github.com/AsahiLinux/tuxvdmtool) uses a [sysfs API](https://github.com/AsahiLinux/linux/commit/786523ac62f0aeec37bf9c6b991e8bf2fadc590d) which isn't particularly nice and probably not upstreamable. After publishing tuxvdmtool we came to the conclusion that using linux userspace I2C client driver API is a better choice and should work. See https://github.com/AsahiLinux/tuxvdmtool/issues/1 | janne | 16 | | Fix serial port resets | **Unclaimed** | When using the apple silicon debug uart with two connected Apple silicon devices the serial port on the host device (`/dev/ttySAC0`) resets within seconds after `tuxvdmtool reboot serial`. Find the cause for this and fix the issue. This tasks is a little annoying since m1n1's hypervisor clobbers the hardware uart0 for its own use. | janne | 17 | | Keyboard layout cleanup (XKB/hid_apple) | Unclaimed | Apple keyboard support across the Linux desktop stack has been hit-and-miss, across layouts and hardware keyboards. Since our keyboard drivers are not upstream yet, we have the chance to do some major cleanup. In particular, the keyboards on these machines have a soft *Fn* key that is handled entirely in software. The `hid_apple` driver currently does this in the kernel, but this is the wrong approach. This key should be handled in userspace in XKB/Wayland (Xorg cannot do it, but it's deprecated), so that we can have more comprehensive Fn key mappings including letting users customize the key bindings like they would any other modifier key, or offer special symbols like macOS does. This should probably be done by introducing new XKB keyboard models, which do this mapping in userspace. To test this, use the `fnmode=0` module parameter for `hid_apple` to disable all Fn key processing. We will later want to introduce a new fnmode that *only* does Fn key combination emulation for the edit keys (insert/delete/home/end/pgup/pgdown), which is the minimum required for a usable TTY and Xorg, and leave the rest to XKB, defaulting to this mode on Apple Silicon machines. Besides the Fn story, there are also many regional Mac layouts that need to be fixed in XKB configuration, and everyone with a non-English keyboard is welcome to help out with that effort. [Relevant xkeyboard-config issue](https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/issues/379)| janne | 18 | -------------------------------------------------------------------------------- /docs/hw/soc/usb-debug.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: USB-PD Debugging Interface 3 | --- 4 | 5 | This seems to be a built-in debugging USB interface. 6 | 7 | Commands via EP 0x01, replies via 0x81, 0x82 unknown 8 | 9 | RE notes trying to send it random stuff: 10 | 11 | ``` 12 | First 3 bytes are ignored? Fourth byte matters. 13 | First 5 bytes are echoed at the beginning of replies 14 | Replies seem to follow a uniform format 15 | 16 | > 00000000 000c8000 00000000 00000000 17 | OOLLLL 18 | 19 | Reads LLLL bytes (rounded to dword) starting from dword register OO. 20 | 21 | Returns: 22 | 00000000 00000000 * 23 | 24 | > 00000000 02000000 00000000 00000000 00000000 00 25 | 26 | Returns: 27 | 00000000 02000000 08458400 28 | 29 | And then keeps flooding [a0030000] repeated forever 30 | 31 | Seems to be an insane length. Bug? 32 | ``` 33 | 34 | Register dump: 35 | 36 | ``` 37 | 00000000 a0 03 00 00 91 00 06 10 91 00 81 08 09 22 00 00 |............."..| 38 | 00000010 03 10 00 00 00 00 30 3d 02 00 00 00 0f 0f 00 00 |......0=........| 39 | 00000020 15 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 40 | 00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 41 | 00000040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 42 | 00000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 43 | 00000060 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 44 | 00000070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 45 | 00000080 00 01 00 04 01 01 0b 08 02 06 fe 40 00 00 00 00 |...........@....| 46 | 00000090 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 47 | 000000a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 48 | 000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 49 | 000000c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 50 | 000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 51 | 000000e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 52 | 000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 53 | 00000100 00 0a 00 00 01 03 00 00 02 04 00 00 03 08 00 00 |................| 54 | 00000110 04 00 00 00 05 00 00 00 06 00 00 00 07 00 00 00 |................| 55 | 00000120 08 00 00 00 09 00 00 00 0a 00 00 00 0b 00 00 00 |................| 56 | 00000130 0c 00 00 00 0d 00 00 00 0e 00 00 00 0f 00 00 00 |................| 57 | 00000140 10 00 00 00 11 00 00 00 12 00 00 00 13 00 00 00 |................| 58 | 00000150 14 00 00 00 15 00 00 00 16 00 00 00 17 00 00 00 |................| 59 | 00000160 18 00 00 00 19 00 00 00 1a 00 00 00 1b 00 00 00 |................| 60 | 00000170 1c 00 00 00 1d 00 00 00 1e 00 00 00 1f 20 00 00 |............. ..| 61 | 00000180 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 62 | 00000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 63 | 000001a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 64 | 000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 65 | 000001c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 66 | 000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 67 | 000001e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 68 | 000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 69 | ``` 70 | -------------------------------------------------------------------------------- /docs/hw/devices/device-list.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Device List 3 | summary: 4 | List of devices supported or intended to be supported by Asahi Linux 5 | --- 6 | 7 | This is a list of devices Asahi Linux intends to support. The Product and SoC are used for matching against device trees. Please check [Feature Support](../../platform/feature-support/overview.md) for the state of support for specific models. 8 | 9 | ## Devices 10 | | Marketing name | Device | Product | SoC | 11 | | -------------- | ------ | ------- | --- | 12 | | Mac mini (M1, 2020) | Macmini9,1 | J274AP | T8103 13 | | MacBook Pro (13-inch, M1, 2020) | MacBookPro17,1 | J293AP | T8103 14 | | MacBook Air (M1, 2020) | MacBookAir10,1 | J313AP | T8103 15 | | iMac (24-inch (4-port), M1, 2021) | iMac21,1 | J456AP | T8103 16 | | iMac (24-inch (2-port), M1, 2021) | iMac21,2 | J457AP | T8103 17 | | MacBook Pro (16-inch, M1 Pro, 2021) | MacBookPro18,1 | J316sAP | T6000 18 | | MacBook Pro (16-inch, M1 Max, 2021) | MacBookPro18,2 | J316cAP | T6001 19 | | MacBook Pro (14-inch, M1 Pro, 2021) | MacBookPro18,3 | J314sAP | T6000 20 | | MacBook Pro (14-inch, M1 Max, 2021) | MacBookPro18,4 | J314cAP | T6001 21 | | Mac Studio (M1 Max, 2022) | Mac13,1 | J375cAP | T6001 22 | | Mac Studio (M1 Ultra, 2022) | Mac13,2 | J375dAP | T6002 23 | | MacBook Pro (13-inch, M2, 2022) | Mac14,7 | J493AP | T8112 24 | | MacBook Air (13-inch, M2, 2022) | Mac14,2 | J413AP | T8112 25 | | Mac mini (M2, 2023) | Mac14,3 | J473AP | T8112 26 | | Mac mini (M2 Pro, 2023) | Mac14,12 | J474sAP | T6020 27 | | MacBook Pro (14-inch, M2 Pro, 2023) | Mac14,9 | J414sAP | T6020 28 | | MacBook Pro (16-inch, M2 Pro, 2023) | Mac14,10 | J416sAP | T6020 29 | | MacBook Pro (14-inch, M2 Max, 2023) | Mac14,5 | J414cAP | T6021 30 | | MacBook Pro (16-inch, M2 Max, 2023) | Mac14,6 | J416cAP | T6021 31 | | MacBook Air (15-inch, M2, 2023) | Mac14,15 | J415AP | T8112 32 | | Mac Studio (M2 Max, 2023) | Mac14,13 | J475cAP | T6021 33 | | Mac Studio (M2 Ultra, 2023) | Mac14,14 | J475dAP | T6022 34 | | Mac Pro (2023) | Mac14,8 | J180dAP | T6022 35 | | iMac (24-inch (2-port), M3, 2023) | Mac15,4 | J433AP | T8122 36 | | iMac (24-inch (4-port), M3, 2023) | Mac15,5 | J434AP | T8122 37 | | MacBook Pro (14-inch, M3, Nov 2023) | Mac15,3 | J504AP | T8122 38 | | MacBook Pro (14-inch, M3 Pro, Nov 2023) | Mac15,6 | J514sAP | T6030 39 | | MacBook Pro (16-inch, M3 Pro, Nov 2023) | Mac15,7 | J516sAP | T6030 40 | | MacBook Pro (14-inch, M3 Max, Nov 2023) | Mac15,8 | J514cAP | T6031 41 | | MacBook Pro (16-inch, M3 Max, Nov 2023) | Mac15,9 | J516cAP | T6031 42 | | MacBook Pro (14-inch, M3 Max, Nov 2023) | Mac15,10 | J514mAP | T6034 43 | | MacBook Pro (16-inch, M3 Max, Nov 2023) | Mac15,11 | J516mAP | T6034 44 | | MacBook Air (13-inch, M3, 2024) | Mac15,12 | J613AP | T8122 45 | | MacBook Air (15-inch, M3, 2024) | Mac15,13 | J615AP | T8122 46 | | Mac Studio (M3 Ultra, 2025) | Mac15,4 | J575dAP | T6032 47 | | iMac (24-inch (2-port), M4, 2024) | Mac16,2 | J623AP | T8132 48 | | iMac (24-inch (4-port), M4, 2024) | Mac16,3 | J624AP | T8132 49 | | Mac mini (M4, 2024) | Mac16,10 | J773gAP | T8132 50 | | Mac mini (M4 Pro, 2024) | Mac16,11 | J773sAP | T6040 51 | | MacBook Pro (14-inch, M4, Nov 2024) | Mac16,1 | J604AP | T8132 52 | | MacBook Pro (14-inch, M4 Pro, Nov 2024) | Mac16,8 | J614sAP | T6040 53 | | MacBook Pro (16-inch, M4 Pro, Nov 2024) | Mac16,7 | J616sAP | T6040 54 | | MacBook Pro (14-inch, M4 Max, Nov 2024) | Mac16,6 | J614cAP | T6041 55 | | MacBook Pro (16-inch, M4 Max, Nov 2024) | Mac16,5 | J616cAP | T6041 56 | | MacBook Air (13-inch, M4, 2025) | Mac16,12 | J713AP | T8132 57 | | MacBook Air (15-inch, M4, 2025) | Mac16,13 | J715AP | T8132 58 | | Mac Studio (M4 Max, 2025) | Mac16,9 | J575cAP | T6041 59 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Asahi Linux Documentation 2 | site_url: https://asahilinux.org/docs/ 3 | 4 | repo_url: https://github.com/AsahiLinux/docs 5 | repo_name: AsahiLinux/docs 6 | 7 | nav: 8 | - Home: index.md 9 | - Feature Support: 10 | - Overview: platform/feature-support/overview.md 11 | - M1 Series Feature Support: platform/feature-support/m1.md 12 | - M2 Series Feature Support: platform/feature-support/m2.md 13 | - M3 Series Feature Support: platform/feature-support/m3.md 14 | - M4 Series Feature Support: platform/feature-support/m4.md 15 | - Project related: 16 | - Glossary: project/glossary.md 17 | - FAQ: project/faq.md 18 | - When will Asahi Linux be done?: project/when-will-asahi-be-done.md 19 | - References: project/references.md 20 | - Asahi Linux Board: project/board/asahi-board.md 21 | - Policies: 22 | - Generative AI: project/policies/slop.md 23 | - Platform documentation: 24 | - Apple Silicon Subsystems: platform/subsystems.md 25 | - Apple Platform Security Crash Course: platform/security.md 26 | - Devices: hw/devices/device-list.md 27 | - Codenames: hw/soc/soc-codenames.md 28 | - Display Controllers: hw/soc/display-controllers.md 29 | - For users: 30 | - Fedora Asahi Remix Documentation : https://docs.fedoraproject.org/en-US/fedora-asahi-remix/ 31 | - Broken Software: sw/broken-software.md 32 | - Partitioning Cheatsheet: sw/partitioning-cheatsheet.md 33 | - Windows 11 VM setup guide: sw/windows-11-vm.md 34 | - For developers: 35 | - Yaks in need of shaving (HELP WANTED!): project/help-wanted.md 36 | - Tethered Boot Setup (For Developers): sw/tethered-boot.md 37 | - m1n1:User Guide Boot loader: sw/m1n1-user-guide.md 38 | - Hypervisor: sw/m1n1-hypervisor.md 39 | - U-Boot: sw/u-boot.md 40 | - Devicetree bindings: sw/devicetree-bindings.md 41 | - Open OS ecosystem on Apple Silicon Macs: platform/open-os-interop.md 42 | - Userspace Audio Stack: sw/audio-userspace.md 43 | - For distributions/OSes: 44 | - Distro guidelines: alt/policy.md 45 | 46 | theme: 47 | name: material 48 | logo: assets/logo.png 49 | favicon: assets/favicon.png 50 | palette: 51 | - media: "(prefers-color-scheme)" 52 | primary: custom 53 | accent: custom 54 | toggle: 55 | icon: material/brightness-auto 56 | name: Switch to light mode 57 | 58 | - media: "(prefers-color-scheme: light)" 59 | primary: custom 60 | accent: custom 61 | scheme: default 62 | toggle: 63 | icon: material/brightness-7 64 | name: Switch to dark mode 65 | 66 | - media: "(prefers-color-scheme: dark)" 67 | primary: custom 68 | accent: custom 69 | scheme: slate 70 | toggle: 71 | icon: material/brightness-4 72 | name: Switch to system preference 73 | 74 | features: 75 | - navigation.expand 76 | - navigation.instant 77 | - navigation.sections 78 | - navigation.tracking 79 | - navigation.top 80 | - toc.integrate 81 | custom_dir: overrides 82 | 83 | extra_css: 84 | - stylesheets/extra.css 85 | 86 | markdown_extensions: 87 | - toc: 88 | baselevel: 4 89 | permalink: true 90 | - admonition 91 | - pymdownx.tasklist: 92 | custom_checkbox: true 93 | clickable_checkbox: true 94 | - pymdownx.tilde 95 | 96 | plugins: 97 | - search 98 | - social: 99 | cards_layout_options: 100 | background_color: '#F4EAEA' 101 | color: '#2C2C2C' 102 | -------------------------------------------------------------------------------- /docs/hw/soc/gpio.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: GPIO Controller 3 | --- 4 | 5 | ## DT binding 6 | 7 | The "gpio,t8101" nodes in the ADT represent a GPIO controller with pinmux facilities. 8 | Judging from the Corellium code base the pins can be switched between "gpio" functionality and "periph" functionality. 9 | There may be more options though sine there are unknown bits right next to the bit that controls switching between those two modes. 10 | Given that the controller implements pinmux functionality we need to model this hardware as a pinctrl node in the FDT. This can be done entirely using generic pinctrl/pinmux/gpio binding properties: 11 | 12 | ``` 13 | #define APPLE_PINMUX(pin, func) ((pin) | ((func) << 16)) 14 | 15 | pinctrl: pinctrl@23c100000 { 16 | compatible = "apple,t8103-pinctrl"; 17 | reg = <0x2 0x3c100000 0x0 0x100000>; 18 | clocks = <&gpio_clk>; 19 | 20 | gpio-controller; 21 | #gpio-cells = <2>; 22 | gpio-ranges = <&pinctrl 0 0 212>; 23 | 24 | pcie_pins: pcie-pins { 25 | pinmux = , 26 | , 27 | ; 28 | }; 29 | }; 30 | ``` 31 | Using `pinmux` has the benefit that we don't have to invent names for pins and functions and hardcode those in the driver. 32 | The purpose of pins is likely to vary between SoCs and between controllers on a single SoC. There are four controllers on the M1 SoC! 33 | The example here uses a simple split of the 32-bit pinmux cell. 34 | The lower 16 bits encode the pin number whereas the upper 16 bits encode the pin function. 35 | It is unlikely we need the full 16 bits to encode the pin function so we repurpose some of those bits if we need to in the future. 36 | 37 | Some open questions: 38 | * Should the compatible string be "apple,t8101-gpio" given the name of the node in the ADT? Or should we mention both? 39 | * The controllers seem to provide interrupt functionality as well. The standard bindings allow for an `interrupt-controller` property so this this can be handled as well. There are (up to) 7 AIC interrupts per controllers each handling a group of GPIO pins. It seems GPIO pins can be freely assigned to a group although the ADT contains properties that suggest that not all groups are functional on some of the controllers. 40 | 41 | The gpio controller provides interrupt functionality to devices which uses it as `interrupt-parent`. Those devices have 2 `#interrupt-cells`. The first cell specifies the GPIO pin. The meaning of the second pin is unknown. `audio-tas5770L-speaker`, `audio-codec-output`, `hpmBusManager` use 0x1, `wlan` 0x2 and `bluetooth` 0x2000002. The second cells' value does not seem to correspond to the pin's configuration register. 42 | 43 | device | pin | 2nd cell | config by iboot (mac mini) 44 | ---------------------- | --- | --------- | -------------------------- 45 | hpmBusManager | 106 | 0x1 | 0x76b80 46 | bluetooth | 136 | 0x2000002 | 0x76a80 47 | audio-tas5770L-speaker | 182 | 0x1 | 0x76b81 48 | audio-codec-output | 183 | 0x1 | 0x76b81 49 | wlan | 196 | 0x2 | 0x76ac0 50 | 51 | Observed Mac OS behavior for device `/arm-io/gpio` at address `0x23c100000`: 52 | 1. read pin config (4 bytes) from offset `0x0000` to `0x34c` (212 pins) 53 | 2. clear interrupts for all 7 groups? writing ones 7 x 4 bytes in seven groups to the offsets `0x800`, `0x840`, `0x880`, `0x8C0`, `0x900`, `0x940`, `0x980` 54 | -------------------------------------------------------------------------------- /docs/sw/linux-bringup-nvme.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Linux Bringup: NVME 3 | --- 4 | 5 | # USB drive boot 6 | ## The easy way 7 | * As per [Glanzmann's notes](https://tg.st/u/asahi.txt) fetch a debian bullseye rootfs under MacOS and dd it directly into a newly created nvme partition. 8 | ## The harder way 9 | * This is done on another Linux machine - uses debian bullseye 10 | ### Build your rootfs 11 | * [build your own](https://www.debian.org/releases/stretch/arm64/apds03.html.en) 12 | ``` 13 | mkdir debinst 14 | sudo debootstrap --arch arm64 --foreign bullseye debinst http://ftp.au.debian.org/debian/ 15 | sudo cp /usr/bin/qemu-aarch64-static debinst/usr/bin 16 | ``` 17 | * Login via a chroot to a bash prompt:`sudo LANG=C.UTF-8 chroot debinst qemu-aarch64-static /bin/bash` 18 | * Then complete the 2nd stage `/debootstrap/debootstrap --second-stage` 19 | * While your there install any other packages you want: `apt install file screenfetch procps` 20 | * For ssh install an ssh server `apt install openssh-server` 21 | * Allow root login via ssh by setting `PermitRootLogin yes` via `vi /etc/ssh/sshd_config` 22 | * Most important set the root password `passwd` 23 | ### Install rootfs onto USB drive 24 | * Plug in your USB drive and create a partition with fdisk (assumes drive is /dev/sdb) `sudo fdisk /dev/sdb` 25 | * Format partition (assumes it's the first one) `sudo mkfs.ext4 /dev/sdb1` 26 | * Mount the drive some where like /mnt/img `sudo mount /dev/sdb1 /mnt/img` 27 | * Install the rootfs you created above onto the drive `sudo cp -a debinst/. /mnt/img` 28 | * Unmount the drive `sudo umount /mnt/img` 29 | ### Boot with USB drive as root 30 | * Back to [booting over USB cable](linux-bringup.md#running-linux-via-usb-cable) 31 | * Make sure you have the latest m1n1.macho loaded `python3 proxyclient/tools/chainload.py build/m1n1.macho` 32 | * Build a kernel with builtin features (check for =m and change to =y in .config) 33 | * In particular need CONFIG_EXT4_FS=y is needed to boot! 34 | * Try this [Asahi linux snapshot](https://github.com/amworsley/AsahiLinux/tree/asahi-kbd) and this [config](https://raw.githubusercontent.com/amworsley/asahi-wiki/main/images/config-keyboard+nvme) 35 | * Then boot the gzipp'ed image with the USB drive. I had to plug the drive in the 2nd USB type-C port on the MBA (MacBook Air) through a Type-C to USB-Type A HUB. 36 | * Be-aware when I plugged in a lower speed USB device (keyboard) it reset the HUB and corrupted my USB drive. So don't use a keyboard, a Type-A to Type-C dongle worked fine 37 | * Over the USB cable load the new kernel and boot with the USB drive as the root filesystem: 38 | ``` 39 | python3 proxyclient/tools/linux.py -b 'earlycon console=tty0 console=tty0 debug net.ifnames=0 rw root=/dev/sda1 rootdelay=5 rootfstype=ext4' Image.gz t8103-j313.dtb 40 | ``` 41 | * The root filesystem is in first partition of the drive (/dev/sda1) and it's a MBA (t8103-j313.dtb) 42 | * If your booting something different check the .dts file in **arch/arm64/boot/dts/apple/** by looking at the value of the **model** field 43 | ### Install rootfs in the nvme 44 | * Under MacOS you need to create some free space as per [Glanzmann's notes](https://tg.st/u/asahi.txt) 45 | * Be very careful you know exactly what partition you specify this is just an **example** your numbers may vary 46 | * make space - the last number is the space that macos will occupy `diskutil apfs resizeContainer disk0s2 200GB` 47 | * List the partitions and see where the free space now lies `diskutil list` 48 | * Allocate a FAT32 partition for your linux rootfs on the NVME from the free space 49 | * **NOTE** you have to specify the partition **before** the free space `diskutil addPartition disk0s3 FAT32 LB 42.6GB` 50 | * Boot with the USB ext4 USB drive as root (as above) 51 | * Use fdisk to confirm which partition is the new FAT32 one (it should have the size you created above too) `fdisk -l /dev/nvme0n1` 52 | * Once you have confirmed it format it to ext4 `mkfs.ext4 /dev/nvme0n1p4` 53 | * Mount it `mount /dev/nvme0n1p4 /mnt` 54 | * Copy your USB drive rootfs into it as before `cp -ax /. /mnt` 55 | * I believe the -x should prevent the recursive descent into the new filesystem on the nvme 56 | * Unmount it `umount /mnt` 57 | * Then try booting via the USB cable with your new root filesystem on the nvme 58 | ``` 59 | python3 proxyclient/tools/linux.py -b 'earlycon console=tty0 console=tty0 debug net.ifnames=0 rw root=/dev/nvme0n1p6 rootfstype=ext4' Image.gz t8103-j313.dtb 60 | -------------------------------------------------------------------------------- /docs/sw/u-boot.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Das U-Boot 3 | --- 4 | 5 | U-Boot is the default payload for m1n1 stage 2, and is used to provide a standard preboot environment familiar to 6 | AArch64 developers. External boot is not supported with the native Apple Silicon boot tooling, making U-Boot a hard 7 | necessity for providing a PC-like boot environment. This page explains how we use U-Boot and how to manually build and 8 | install it. It is assumed that you are working on an Apple Silicon machine using a well-supported distro. 9 | 10 | Do note that the process for building and installing U-Boot listed here is for documentation and development purposes 11 | only. If you are an Asahi user and not interested in hacking on U-Boot or m1n1, they are managed automatically 12 | via `pacman`. 13 | 14 | ## Standard boot flow 15 | We make use of U-Boot's UEFI implementation to load and execute a UEFI binary located at `/EFI/BOOT/BOOTAA64.EFI` 16 | on the paired EFI System Partition. The default payload for Asahi installs is GRUB. U-Boot passes GRUB a pointer 17 | to the FDT automatically. 18 | 19 | ## Alternative arrangements 20 | The default U-Boot script can be interrupted at runtime to manually alter the boot flow. This allows the user to 21 | do things like boot off external media, execute arbitrary UEFI code, load and jump to a kernel directly, et cetera. 22 | 23 | ## Known issues 24 | * USB-A ports on machines with them will not work due to their controller requiring firmware which we cannot redistribute 25 | * Ditto the two USB Type-C ports furthest from the power cable on the iMacs, and the two front facing ports on the M1 **Max** Mac Studio. 26 | * Certain USB devices which expose multiple functions (hubs with NICs, fancy gaming keyboards, etc.) do not work. 27 | * USB hubs with integrated SD card readers will cause your machine to hard reset if the slot is empty. The fix for this is queued. 28 | 29 | ## Prerequisites 30 | * An Apple Silicon machine running Asahi 31 | * A clean build of m1n1, see the [m1n1 User Guide](m1n1-user-guide.md) 32 | * The Apple DTBs from `AsahiLinux/linux`. Compiling these is out of scope for this document. 33 | * The Asahi EFI System Partition mounted at `/boot/efi/`. 34 | 35 | ## Building 36 | 1. Clone the `AsahiLinux/u-boot` repository. 37 | 2. `make apple_m1_defconfig` 38 | 3. `make -j$(nproc)` 39 | 40 | Do not be fooled by the name of the defconfig, it will build support for **all** Apple Silicon machines, not just the M1. You may tinker 41 | with the config, however try not to play around with Apple-specific stuff as most (all) of it is absolutely necessary just to cleanly boot. 42 | 43 | You may also build using Clang/LLVM. 44 | 45 | ## Installing 46 | Installing your build of U-Boot involves creating a new stage 2 of m1n1, which is why we require a clean build of m1n1 and the DTBs. 47 | Make a backup of `/boot/efi/m1n1/boot.bin`, then concatenate m1n1, the DTBs and U-Boot. This must be run as root. 48 | 49 | ```sh 50 | cat build/m1n1.bin /path/to/dtbs/*.dtb <(gzip -c /path/to/uboot/u-boot-nodtb.bin) > /boot/efi/m1n1/boot.bin 51 | ``` 52 | 53 | ### Important note for package maintainers 54 | We recommend that you install the bare m1n1/U-Boot images and DTBs to a specific location on the 55 | root filesystem, and ship a script that backs up the existing image and creates a new one. This prevents regressions from making bricking 56 | the OS install. Users can simply mount the ESP in macOS, delete the new `boot.bin` and rename the backup to recover their machine to a 57 | known good state. For an example of how we do this in Asahi, see `uboot-asahi` and `asahi-scripts/update-m1n1` in the 58 | `AsahiLinux/PKGBUILDs` repo. 59 | 60 | ## Helpful U-Boot tricks 61 | 62 | ### Booting from a USB 63 | 1. Make sure the only USB storage device connected is the one you want to boot from 64 | 2. Interrupt the default U-Boot script when prompted. 65 | ``` 66 | run bootcmd_usb0 67 | ``` 68 | 69 | If the USB fails to load, you might need to restart the USB, which can be done via: 70 | ``` 71 | usb start 72 | usb reset 73 | ``` 74 | 75 | If you are using a USB to load a recovery / "Live CD", ensure you also have `usbhid xhci_hcd` under MODULES in `/etc/mkinitcpio.conf`. Also have a read of [Install_Arch_Linux_on_a_removable_medium](https://wiki.archlinux.org/title/Install_Arch_Linux_on_a_removable_medium) for tips and tricks. 76 | 77 | ### Other useful U-Boot commands 78 | ```sh 79 | bootd # Continue the default U-Boot script 80 | reset # Reboot the machine 81 | poweroff # Shutdown the machine completely 82 | nvme scan # Discover NVMe disks (required for next command to succeed) 83 | ls nvme 0:4 / # List the contents of the paired EFI System Partition 84 | ``` 85 | -------------------------------------------------------------------------------- /docs/sw/kernel-config.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Silicon Kernel Config Options 3 | --- 4 | 5 | Your kernel configuration will need to include the Asahi-specific drivers. As of linux-asahi-6.12.4-1, this list is: 6 | 7 | ``` 8 | CONFIG_ARCH_APPLE=y 9 | CONFIG_ARM64_MEMORY_MODEL_CONTROL=y 10 | CONFIG_APPLE_AIC=y 11 | CONFIG_APPLE_WATCHDOG=y 12 | CONFIG_APPLE_DART=y 13 | CONFIG_APPLE_SART=y 14 | CONFIG_APPLE_PLATFORMS=y 15 | CONFIG_APPLE_MAILBOX=y 16 | CONFIG_APPLE_RTKIT=y 17 | CONFIG_APPLE_RTKIT_HELPER=y 18 | CONFIG_APPLE_SMC=y 19 | CONFIG_APPLE_SMC_RTKIT=y 20 | CONFIG_APPLE_PMGR_PWRSTATE=y 21 | CONFIG_APPLE_PMGR_MISC=y 22 | CONFIG_I2C_APPLE=y 23 | CONFIG_NVME_APPLE=y 24 | CONFIG_PCIE_APPLE=y 25 | CONFIG_PINCTRL_APPLE_GPIO=y 26 | CONFIG_PWM_APPLE=y 27 | CONFIG_SPI_APPLE=y 28 | CONFIG_SPMI_APPLE=y 29 | CONFIG_GPIO_MACSMC=y 30 | CONFIG_SENSORS_MACSMC=m 31 | CONFIG_ARM_APPLE_SOC_CPUFREQ=y 32 | CONFIG_APPLE_ADMAC=y 33 | CONFIG_APPLE_M1_CPU_PMU=y 34 | CONFIG_COMMON_CLK_APPLE_NCO=y 35 | CONFIG_ARM_APPLE_CPUIDLE=y 36 | CONFIG_TOUCHSCREEN_APPLE_Z2=m 37 | CONFIG_INPUT_MACSMC_HID=y 38 | CONFIG_POWER_RESET_MACSMC=y 39 | CONFIG_CHARGER_MACSMC=y 40 | CONFIG_MFD_APPLE_SPMI_PMU=y 41 | CONFIG_VIDEO_APPLE_ISP=m 42 | CONFIG_DRM_ASAHI=y 43 | CONFIG_DRM_ADP=m 44 | CONFIG_DRM_APPLE=m 45 | CONFIG_DRM_APPLE_AUDIO=y 46 | CONFIG_APPLE_SIO=m 47 | CONFIG_APPLE_SEP=y 48 | CONFIG_APPLE_AOP=y 49 | CONFIG_SND_SOC_APPLE_AOP_AUDIO=m 50 | CONFIG_SND_SOC_APPLE_MACAUDIO=m 51 | CONFIG_SND_SOC_APPLE_MCA=m 52 | CONFIG_SND_SOC_CS42L84=m 53 | CONFIG_SPI_HID_APPLE_OF=y 54 | CONFIG_HID_DOCKCHANNEL=m 55 | CONFIG_BT_HCIBCM4377=m 56 | CONFIG_RTC_DRV_MACSMC=y 57 | CONFIG_APPLE_DOCKCHANNEL=y 58 | CONFIG_PHY_APPLE_ATC=m 59 | CONFIG_PHY_APPLE_DPTX=m 60 | CONFIG_NVMEM_SPMI_MFD=y 61 | CONFIG_MUX_APPLE_DPXBAR=m 62 | CONFIG_NVMEM_APPLE_EFUSES=y 63 | CONFIG_IIO_AOP_SENSOR_LAS=m 64 | CONFIG_IIO_AOP_SENSOR_ALS=m 65 | ``` 66 | 67 | (Distros intending to support other platforms with their 16k arm64 kernel besides Apple Silicon will be inclined to build as many of these drivers as modules as they can. This is fine, though from a reliability standpoint building NVME_APPLE and SPI_HID_APPLE_OF in-kernel has worked much better for me.) 68 | 69 | ~~(Also note that the configuration options above do not match the standard dracut configuration provided by asahi-scripts.)~~ It looks like a recent change to asahi-scripts makes your choices of modules much less important: 70 | 71 | You should also double-check that you have the following configuration options set: 72 | 73 | ``` 74 | CONFIG_RUST=y 75 | # CONFIG_GCC_PLUGINS is not set 76 | CONFIG_ARM64_16K_PAGES=y 77 | # CONFIG_RUST_DEBUG_ASSERTIONS is not set 78 | CONFIG_RUST_OVERFLOW_CHECKS=y 79 | # CONFIG_RUST_BUILD_ASSERT_ALLOW is not set 80 | CONFIG_UCLAMP_TASK=y 81 | CONFIG_UCLAMP_TASK_GROUP=y 82 | CONFIG_SUSPEND=y 83 | # CONFIG_HIBERNATION is not set 84 | CONFIG_CPU_FREQ_DEFAULT_GOV_SCHEDUTIL=y 85 | CONFIG_ENERGY_MODEL=y 86 | CONFIG_SERIAL_SAMSUNG=y 87 | CONFIG_SERIAL_SAMSUNG_CONSOLE=y 88 | CONFIG_REGULATOR_FIXED_VOLTAGE=y 89 | CONFIG_WATCHDOG_HANDLE_BOOT_ENABLED=y 90 | # CONFIG_DRM_ASAHI_DEBUG_ALLOCATOR is not set 91 | CONFIG_DRM_FBDEV_EMULATION=y 92 | CONFIG_DRM_SCHED=y 93 | # CONFIG_DRM_VGEM is not set 94 | CONFIG_DRM_GEM_SHMEM_HELPER=y 95 | CONFIG_SND_SOC_CS42L83=m 96 | CONFIG_SND_SOC_TAS2764=m 97 | CONFIG_SND_SOC_TAS2770=m 98 | CONFIG_HID_BATTERY_STRENGTH=y 99 | CONFIG_HID_APPLE=m 100 | CONFIG_HID_MAGICMOUSE=m 101 | CONFIG_MOUSE_APPLETOUCH=m 102 | CONFIG_INPUT_LEDS=y 103 | CONFIG_LEDS_PWM=y 104 | CONFIG_USB_XHCI_HCD=m 105 | CONFIG_USB_XHCI_PCI_RENESAS=y 106 | CONFIG_USB_XHCI_PCI_ASMEDIA=y 107 | CONFIG_USB_DWC3=m 108 | CONFIG_USB_DWC3_DUAL_ROLE=y 109 | CONFIG_TYPEC_TPS6598X=m 110 | CONFIG_MMC_SDHCI=m 111 | CONFIG_MMC_SDHCI_PCI=m 112 | CONFIG_MMC_CQHCI=m 113 | CONFIG_NET_VENDOR_AQUANTIA=y 114 | CONFIG_AQTION=m 115 | CONFIG_NET_VENDOR_BROADCOM=y 116 | CONFIG_TIGON3=m 117 | CONFIG_BT=m 118 | CONFIG_BT_BREDR=y 119 | CONFIG_BT_RFCOMM=m 120 | CONFIG_BT_BNEP=m 121 | CONFIG_BT_HIDP=m 122 | CONFIG_BT_LE=y 123 | CONFIG_BT_HCIUART_BCM=y 124 | CONFIG_CFG80211=m 125 | CONFIG_WLAN_VENDOR_BROADCOM=y 126 | CONFIG_BRCMFMAC=m 127 | CONFIG_BRCMFMAC_PROTO_BCDC=y 128 | CONFIG_BRCMFMAC_PROTO_MSGBUF=y 129 | CONFIG_BRCMFMAC_USB=y 130 | CONFIG_BRCMFMAC_PCIE=y 131 | CONFIG_APPLE_MFI_FASTCHARGE=m 132 | 133 | ``` 134 | 135 | Warning: if this is your first time modifying a kernel configuration, please do take the advice at the top of the file about not hand-editing the file seriously. Do NOT just copy the fragments in this page into your config and try to build the kernel; this is likely to result in an inconsistent config and a failed build. Instead, use the `make menuconfig` or `make xconfig` system to modify your kernel configuration. 136 | -------------------------------------------------------------------------------- /docs/project/when-will-asahi-be-done.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: When Will Asahi Be Done? 3 | --- 4 | 5 | If you're after the support status of a specific feature, [Feature Support](../platform/feature-support/overview.md) has a list of all major hardware included in the Apple Silicon Macs, as well as its level of support. 6 | 7 | ## Why you shouldn't ask this question on IRC 8 | 9 | If you ask on any of our IRC channels when Asahi Linux will be done, you will likely get one of these responses, or a variant thereof: 10 | 11 | * "Soon" 12 | * "It already works" 13 | * "Never" 14 | 15 | All of these are actually correct, and the confusion sown by having all of these correct answers thrown at you will likely just give you a headache. 16 | 17 | ## Why they're all correct 18 | The problem with asking about "doneness" in such a broad community is that everyone's idea of "done" is different. We have a large community of developers, testers, and eager users from a variety of backgrounds, all of whom have different expectations of the project. 19 | 20 | 21 | ### "Soon" 22 | For an end user who uses Just WorksTM distro, Asahi Linux might not be "done" until they are able to boot their favourite distro's installer off a USB stick and run its install procedure like they would on an amd64 machine. They likely also expect features like 3D acceleration, modesetting, WiFi, Bluetooth, Thunderbolt etc. to all work out of the box. For this to all be the case, all the relevant kernel patches have to be accepted upstream and then pulled into the distro's generic kernel and the user's particular machine must have support in U-Boot. Considering that at the time of writing, many of these drivers haven't even been committed to `linux-asahi`, so this point is probably quite far away. For people who expect such things, Asahi Linux likely won't be "done" for another year, maybe two. 23 | 24 | 25 | ### "It already works" 26 | Next, we consider the case of someone who is actively testing bleeding edge drivers in `linux-asahi`. Someone like this may be eagerly awaiting a single feature or set of features to test out what these machines can do. For example, someone might be waiting for proper 3D acceleration to see how good the GPU is at certain workloads without the bottleneck of translating to Metal first. Another person might want to test using the Mac Mini as a networked build machine, for which they would probably only want networking, pstates, and a `cpufreq` driver. For people like this, "done" could very well mean whenever the specific feature they require lands in the `linux-asahi` kernel branch. That may be today, tomorrow, soon, or it may not even be on the list of things to look at. 27 | 28 | 29 | ### "Never" 30 | Finally, we consider the perspective of the developer. Development for an undocumented platform is a treadmill of work. Every new feature requires reverse engineering the relevant hardware, writing drivers, testing those drivers, then getting them upstreamed. Even after a driver is upstreamed, maintenance and optimisation is sometimes required, for example if Apple introduce a breaking change to any firmware we are required to interface with. For developers the work is never really done, however a sort of colloquial "doneness" we use around here to decide what work gets priority is when a driver is completed to a quality level where it is accepted for merging upstream. 31 | 32 | ## What this means for you 33 | No one can really decide when Asahi Linux is "done" except for you. Your use case, technical skill, ambition and risk tolerance are your own. As development work is ongoing, we will likely never have an official "done" date for you to live by, so your best bet is to use your own judgement and the list of features at [Feature Support](../platform/feature-support/overview.md) to decide if the time is right for you to try out Linux on Apple Silicon. 34 | 35 | 36 | ## A note on new hardware 37 | The time it takes us to bring new hardware online is entirely dependent on the changes Apple makes to that particular subsystem in new silicon revisions. Core SoC building blocks will likely Just WorkTM for a long while yet on many new machines with no changes, and other things may require totally new drivers and further work on reverse engineering. 38 | 39 | Apple make things somewhat easier for us by only introducing changes to hardware when it is absolutely necessary to do so. The original iteration of the AIC (Apple Interrupt Controller) was unchanged from the early iPhones all the way to the M1. We expect AIC2, first found in the M1 Pro and Max, to have a similar, if not longer lifespan. Generally, changes to any piece of hardware will be supported in less time than it took to bring up the hardware initially. 40 | 41 | Large architectural changes to things like the GPU and Neural Engine may take slightly longer to figure out. As such, we cannot guarantee dates or turnaround times for any new silicon Apple release. The answer to the question "When will [_feature_] on [_machine_] be supported?" is always "When it is listed as supported in the documentation." 42 | -------------------------------------------------------------------------------- /docs/fw/boot.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Silicon Boot Flow 3 | summary: 4 | Boot flow used by Apple Silicon devices, from SoC-integrated ROM to user code 5 | --- 6 | 7 | Apple Silicon devices seem to follow a boot flow very similar to modern iOS devices. 8 | 9 | # Stage 0 (SecureROM) 10 | 11 | This stage is located in the boot [ROM](../project/glossary.md#r). Among others, it verifies, loads and executes normal stage 1 from [NOR](../project/glossary.md#n). If this fails, it falls back to [DFU](../project/glossary.md#d) and waits for an [iBSS](../project/glossary.md#i) loader to be sent, before continuing with the [DFU](../project/glossary.md#d) flow at stage 1. 12 | 13 | # Normal flow 14 | 15 | ## Stage 1 (LLB/iBoot1) 16 | 17 | This stage is the primary early loader, located in the on-board [NOR](../project/glossary.md#n). This boot stage very roughly goes as follows: 18 | 19 | * Read the `boot-volume` variable from [NVRAM](../project/glossary.md#n): its format is `::`. Other related variables seem to be `update-volume` and `upgrade-boot-volume`, possibly selected by metadata inside the `boot-info-payload` variable; 20 | * Get the local policy hash: 21 | - First try the local proposed hash ([SEP](../project/glossary.md#s) command 11); 22 | - If that is not available, get the local blessed hash ([SEP](../project/glossary.md#s) command 14) 23 | * Read the local boot policy, located on the iSCPreboot partition at `//LocalPolicy/.img4`. This boot policy has the following specific metadata keys ([4CCs](../project/glossary.md#4)): 24 | - `vuid`: UUID: Volume group UUID - same as above 25 | - `kuid`: UUID: KEK group UUID 26 | - `lpnh`: SHA384: Local policy nonce hash 27 | - `rpnh`: SHA384: Remote policy nonce hash 28 | - `ronh`: SHA384: Recovery OS policy nonce hash 29 | - `nsih`: SHA384: Next-stage IMG4 hash 30 | - `coih`: SHA384: fuOS (custom kernelcache) IMG4 hash 31 | - `auxp`: SHA384: Auxiliary user-authorized kernel extensions hash 32 | - `auxi`: SHA384: Auxiliary kernel cache IMG4 hash 33 | - `auxr`: SHA384: Auxiliary kernel extension recept hash 34 | - `prot`: SHA384: Paired Recovery manifest hash 35 | - `hrlp`: bool: Recovery OS local policy is Secure Enclave–signed 36 | - `lobo`: bool: Local boot policy 37 | - `love`: bool: Local OS version 38 | - `smb0`: bool: Reduced security enabled 39 | - `smb1`: bool: Permissive security enabled 40 | - `smb2`: bool: Third-party kernel extensions enabled 41 | - `smb3`: bool: Manual mobile device management (MDM) enrollment 42 | - `smb4`: bool?: MDM device enrollment program disabled 43 | - `sip0`: u16: SIP customized 44 | - `sip1`: bool: Signed system volume (`csrutil authenticated-root`) disabled 45 | - `sip2`: bool: CTRR ([Configurable Text Read-only Region](https://keith.github.io/xcode-man-pages/bputil.1.html)) disabled 46 | - `sip3`: bool: `boot-args` filtering disabled 47 | 48 | And optionally the following linked manifests, each located at `//LocalPolicy/..im4m` 49 | - `auxk`: AuxKC (third party kext) manifest 50 | - `fuos`: fuOS (custom kernelcache) manifest 51 | 52 | * If loading the next stage: 53 | 54 | - The boot directory is located at the target partition Preboot subvolume, at path `//boot/`; 55 | - Decrypt, verify and execute `/usr/standalone/firmware/iBoot.img4` with the device tree and other firmware files in the same directory. No evidence towards other metadata descriptors yet. 56 | 57 | * If loading a custom stage ([fuOS](../project/glossary.md#f)): 58 | 59 | - ... 60 | 61 | If it fails at any point during this, it will either error out or fall back to [DFU](../project/glossary.md#d), waiting for an iBEC loader to be sent, before continuing with the [DFU](../project/glossary.md#d) flow at stage 2. 62 | 63 | ## Stage 2 (iBoot2) 64 | 65 | This stage is the OS-level loader, located inside the OS partition and shipped as part of macOS. It loads the rest of the system. 66 | 67 | # [DFU](../project/glossary.md#d) flow 68 | 69 | ## Stage 1 (iBSS) 70 | 71 | This stage is sent to the device by the "reviving" host. It bootstraps, verifies and runs the second stage, iBEC. 72 | 73 | ## Stage 2 (iBEC) 74 | 75 | # Modes 76 | 77 | Once booted, the [AP](../project/glossary.md#a) can be in one of several boot modes, as confirmed by the [SEP](../project/glossary.md#s): 78 | 79 | | ID | Name | 80 | |----:|-------------------------------------------| 81 | | 0 | macOS | 82 | | 1 | 1TR ("one true" recoveryOS) | 83 | | 2 | recoveryOS ("ordinary" recoveryOS) | 84 | | 3 | kcOS | 85 | | 4 | restoreOS | 86 | | 255 | unknown | 87 | 88 | The [SEP](../project/glossary.md#s) only allows execution of certain commands (such as editing the boot policy) in [1TR](../project/glossary.md#1), or it will fail with error 11, "AP boot mode". 89 | -------------------------------------------------------------------------------- /docs/project/policies/slop.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Generative AI Policy 3 | --- 4 | 5 | It is the opinion of the Board that Large Language Models (LLMs), herein referred 6 | to as Slop Generators, are unsuitable for use as software engineering tools, 7 | particularly in the Free and Open Source Software movement. 8 | 9 | The use of Slop Generators in _any_ contribution to the Asahi Linux project is 10 | expressly forbidden. Their use in any material capacity where code, documentation, 11 | engineering decisions, etc. are largely created with the "help" of a Slop Generators 12 | will be met with a single warning. Subsequent disregard for this policy will be 13 | met with an immediate and permanent ban from the Asahi Linux project and all 14 | associated spaces. 15 | 16 | ## Illegal output 17 | All of the popular Slop Generators are trained on an incomprehensibly large corpus 18 | of text. There is ample evidence across the Web of this training material including 19 | copyrighted material, brazenly stolen by the Slop Generator proprietors with 20 | impunity. Due to the nature of Slop Generators, they are prone to regurgitating 21 | their training corpus almost verbatim. This presents a challenge for FOSS projects 22 | in that the use of generated slop is highly likely to violate intellectual property 23 | law by way of regurgitating the aforementioned stolen training material. This 24 | likelihood is proportional to the specificity of the problem area. 25 | 26 | Asahi Linux is a _highly_ specific project, working in esoteric problem spaces 27 | on publicly undocumented hardware. Given the techniques used by Slop Generator 28 | manufacturers, it is not impossible for them to have confidential or leaked 29 | material owned by Apple or its vendor partners in their training corpi. It is 30 | therefore likely that Slop Generators will regurgitate this when queried in just 31 | the right way. We already forbid the use of illegally acquired or leaked 32 | documentation and tooling (e.g. Apple's internal repair diagnostic tools). This 33 | also applies to regurgitated slop. 34 | 35 | FOSS projects like Asahi Linux cannot afford costly intellectual property lawsuits 36 | in US courts. The current political situation in that nation also makes it 37 | incredibly unlikely that any FOSS project would win such a suit regardless of 38 | the quality of its defence. 39 | 40 | ## Waste of resources 41 | Slop Generators consume an unfathomable amount of resources we can scarcely afford 42 | to waste. Training, and to a lesser extent inference, require enormous amounts of 43 | energy, water, land, and hardware. Manufacturing the hardware itself requires enormous 44 | amounts of energy, water and minerals. All parts of the Slop Generator supply chain 45 | are environmentally intensive. These resources are better used on quite literally 46 | anything else. 47 | 48 | ## LMGTFY 49 | An emerging trend we have observed is people copying user questions or posts into 50 | a Slop Generator, then replying to the post with the generated slop. This is 51 | occurring with increasing frequency, particularly on Reddit. For some people it 52 | is tempting to "help" others and answer questions by feeding them to a LLM and 53 | then posting the answer as-is, or lightly edited at best. If this is you, please 54 | realise that others also have access to the same models as you do, and if they 55 | wanted an answer from one, they could have asked it themselves. Doing this is 56 | exactly as helpful as posting a LMGTFY link, and everyone else _will_ view your 57 | actions as if you did exactly that. 58 | 59 | ## It's just matmul 60 | It is very easy to get caught up in the hype that bad actors have built around 61 | Slop Generators. The anthropomorphic presentation of Slop Generators as "agents" 62 | or "assistants" is a very deliberate attempt to manufacture consent for their 63 | integration into workforces at the expense of human interaction. The implication 64 | of some higher degree intelligence or sentience is very much deliberate, and it 65 | is very much false. 66 | 67 | Make no mistake, they cannot think. They cannot reason. They cannot take into 68 | account context. They don't "know" things or have a sense of humour or any of the 69 | other human-centric qualities bad actors would have you believe of them. Slop 70 | Generators are a [chain of matrices in a stochastic system](https://en.wikipedia.org/wiki/Markov_chain). 71 | The output of a Slop Generator is nothing more than a statistical calculation, 72 | where the next word to be generated is decided by an opaque probabilistic 73 | function dependent on previously generated words. This is fundamentally the 74 | same mathematics that is used to predict the weather. 75 | 76 | A Slop Generator cannot assess the veracity of its claims, nor can it ever 77 | tell you that it simply does not know something. Slop Generators 78 | are often _confidently incorrect_ as a result, and require brow-beating 79 | to admit a mistake. They are therefore highly inappropriate tools in contexts where 80 | truth and correctness are of utmost importance, and when the user is not already 81 | highly knowledgeable and confident in the problem area. This presents a bit of 82 | an issue for Slop Generators; if the user is already highly knowledgeable and 83 | confident in the problem area, then why ask the Slop Generator in the first place? 84 | -------------------------------------------------------------------------------- /docs/sw/deleting-an-install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Deleting an installation 3 | --- 4 | 5 | # This is for default vanilla Asahi installs. These steps do not apply for custom partitioning setups. 6 | ## Do not use Diskutil GUI 7 | 8 | 1. Find the 3 partitions that Asahi installer creates. 9 | Run the installer script and exit after you get to the disk information. 10 | ``` 11 | curl https://alx.sh | sh 12 | ``` 13 | Example disk information: 14 | ``` 15 | Partitions in system disk (disk0): 16 | 1: APFS [Macintosh HD] (380.00 GB, 6 volumes) 17 | OS: [B ] [Macintosh HD] macOS v12.3 [disk3s1, D44D4ED9-B162-4542-BF50-9470C7AFDA43] 18 | 2: APFS [Asahi Linux] (2.50 GB, 4 volumes) 19 | OS: [ *] [Asahi Linux] incomplete install (macOS 12.3 stub) [disk4s2, 53F853CF-4851-4E82-933C-2AAEB247B372] 20 | 3: EFI (500.17 MB) 21 | 4: Linux Filesystem (54.19 GB) 22 | 5: (free space: 57.19 GB) 23 | 6: APFS (System Recovery) (5.37 GB, 2 volumes) 24 | OS: [ ] recoveryOS v12.3 [Primary recoveryOS] 25 | 26 | [B ] = Booted OS, [R ] = Booted recovery, [? ] = Unknown 27 | [ *] = Default boot volume 28 | ``` 29 | The partitions that Asahi installs are `Asahi Linux`, `EFI`, and `Linux Filesystem`. 30 | Note down the `disk#s#` beside Asahi Linux line. 31 | 32 | 2. Delete the "Asahi APFS container" 33 | ``` 34 | diskutil apfs deleteContainer disk 35 | ``` 36 | 37 | 3. Find the partition numbers of EFI and Linux Filesystem partitions. 38 | ``` 39 | diskutil list 40 | ``` 41 | Example output: 42 | ``` 43 | /dev/disk0 (internal, physical): 44 | #: TYPE NAME SIZE IDENTIFIER 45 | 0: GUID_partition_scheme *500.3 GB disk0 46 | 1: Apple_APFS_ISC Container disk1 524.3 MB disk0s1 47 | 2: Apple_APFS Container disk4 362.6 GB disk0s2 48 | (free space) 2.5 GB - 49 | 3: EFI EFI - FEDOR 524.3 MB disk0s4 50 | 4: Linux Filesystem 1.1 GB disk0s5 51 | 5: Linux Filesystem 127.7 GB disk0s6 52 | 6: Apple_APFS_Recovery Container disk3 5.4 GB disk0s7 53 | 54 | /dev/disk4 (synthesized): 55 | #: TYPE NAME SIZE IDENTIFIER 56 | 0: APFS Container Scheme - +362.6 GB disk4 57 | Physical Store disk0s2 58 | 1: APFS Volume Macintosh HD 11.2 GB disk4s1 59 | 2: APFS Snapshot com.apple.os.update-... 11.2 GB disk4s1s1 60 | 3: APFS Volume Preboot 6.9 GB disk4s2 61 | 4: APFS Volume Recovery 1.0 GB disk4s3 62 | 5: APFS Volume Data 287.6 GB disk4s5 63 | 6: APFS Volume VM 20.5 KB disk4s6 64 | ``` 65 | 66 | 4. Delete the EFI and Linux Filesystem partitions 67 | ``` 68 | diskutil eraseVolume free free disks 69 | diskutil eraseVolume free free disks<-other-num-here> 70 | ``` 71 | 72 | ## Resize MacOS to fill disk again 73 | 1. Get the logical Disk number corresponding to MacOS installation 74 | ``` 75 | diskutil list 76 | ``` 77 | Example output: 78 | ``` 79 | /dev/disk0 (internal, physical): 80 | #: TYPE NAME SIZE IDENTIFIER 81 | 0: GUID_partition_scheme *500.3 GB disk0 82 | 1: Apple_APFS_ISC Container disk1 524.3 MB disk0s1 83 | 2: Apple_APFS Container disk4 362.6 GB disk0s2 84 | (free space) 2.5 GB - 85 | 3: EFI EFI - FEDOR 524.3 MB disk0s4 86 | 4: Linux Filesystem 1.1 GB disk0s5 87 | 5: Linux Filesystem 127.7 GB disk0s6 88 | 6: Apple_APFS_Recovery Container disk3 5.4 GB disk0s7 89 | 90 | /dev/disk4 (synthesized): 91 | #: TYPE NAME SIZE IDENTIFIER 92 | 0: APFS Container Scheme - +362.6 GB disk4 93 | Physical Store disk0s2 94 | 1: APFS Volume Macintosh HD 11.2 GB disk4s1 95 | 2: APFS Snapshot com.apple.os.update-... 11.2 GB disk4s1s1 96 | 3: APFS Volume Preboot 6.9 GB disk4s2 97 | 4: APFS Volume Recovery 1.0 GB disk4s3 98 | 5: APFS Volume Data 287.6 GB disk4s5 99 | 6: APFS Volume VM 20.5 KB disk4s6 100 | ``` 101 | In the above example the `/dev/disk# (synthesized)` line which has Macintosh HD listed under it 102 | is the disk to note down. In this example you would expand logical disk4 103 | 104 | 2. Resize - expand logical volume to fill the free space. 105 | ``` 106 | diskutil apfs resizeContainer disk 0 107 | ``` 108 | 109 | ### Errors? Need More Background Information? 110 | [Partitioning cheatsheet](partitioning-cheatsheet.md) 111 | -------------------------------------------------------------------------------- /docs/sw/windows-11-vm.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: How to create a Windows 11 VM 3 | --- 4 | 5 | ### Introduction 6 | Here's a simple guide to install Windows 11 on Fedora Asahi Remix! 7 | This is going over how to install, configure, and manage your own instance of Windows 11 if you ever need anything from windows besides having to switch hardware or use bare metal windows machines. 8 | Credits to: aykevl and Davide Calvaca 9 | 10 | !!! note 11 | `dnf install @virtualization` is out of scope for this guide and not supported. It is, as of the writing of this unsupported and broken, as that includes virt-manager, libvirtd, and others. Please refer to https://github.com/AsahiLinux/docs/pull/206#issuecomment-3274648383 for more information. Please proceed with caution if you are experimenting with this. 12 | ### Steps 13 | 1. Install QEMU, via the command `dnf install qemu` 14 | 2. Create a new directory on your desktop or wherever, naming it to whatever you want, i.e. let's say, `windows11` using `mkdir windows11` via an appropriate terminal application or right clicking and making a directory on your desktop. 15 | 3. Go into that directory with `cd windows11` 16 | 4. Download a Windows 11 ISO, appropriately the Windows 11 Professional build for ARM64 [here](https://www.microsoft.com/en-us/software-download/windows11arm64). Feel free to rename it to a good name like `windows-11.iso` using `mv` in your appropriate terminal application of choice. 17 | 5. Along with that ISO, it would be good to use the virtio-drivers to better improve performance of the machine. Feel free to download it [here](https://github.com/virtio-win/kvm-guest-drivers-windows/wiki/Driver-installation) and renaming it appropriately to `win11-virtio.iso`. 18 | 6. Create a virtual disk for your Windows 11 VM by using the command: `qemu-img create -f qcow2 win11.qcow2 25G` and adjusting it to how much disk space you would want, 25GB is a placeholder. 19 | 7. Here we are going to create a startup script for our Windows 11 VM. Create a file named `win11.sh` and make sure it is executable with `chmod +x win11.sh`. The contents should be: 20 | ``` {.md .copy} 21 | #!/bin/sh 22 | 23 | performance_cores=$(awk ' 24 | /^processor/ { proc=$3 } 25 | /^CPU part/ { 26 | if ($4 == "0x023" || $4 == "0x025" || $4 == "0x029" || $4 == "0x033" || $4 == "0x035" || $4 == "0x039") 27 | procs=procs ? procs","proc : proc 28 | } END { print procs } 29 | ' /proc/cpuinfo) 30 | 31 | taskset -c "$performance_cores" \ 32 | qemu-system-aarch64 \ 33 | -display sdl,gl=on \ 34 | -cpu host \ 35 | -M virt \ 36 | -enable-kvm \ 37 | -m 2G \ 38 | -smp 2 \ 39 | -bios /usr/share/edk2/aarch64/QEMU_EFI.fd \ 40 | -hda win11.qcow2 \ 41 | -device qemu-xhci \ 42 | -device ramfb \ 43 | -device usb-storage,drive=install \ 44 | -drive if=none,id=install,format=raw,media=cdrom,file=windows-11-iot.iso \ 45 | -device usb-storage,drive=virtio-drivers \ 46 | -drive if=none,id=virtio-drivers,format=raw,media=cdrom,file=virtio-win.iso \ 47 | -object rng-random,filename=/dev/urandom,id=rng0 \ 48 | -device virtio-rng-pci,rng=rng0 \ 49 | -audio driver=pipewire,model=virtio \ 50 | -device usb-kbd \ 51 | -device usb-tablet \ 52 | -nic user,model=virtio-net-pci 53 | ``` 54 | !!! note 55 | You may have to adjust the file arguments if you have named it something different than windows-11.iso and virtio-win.iso 56 | 57 | 8. Now run `./win11.sh`. A QEMU window pops up. After going through some boot screens, it should show “Press any key to boot from CD or DVD…”. Press any key to boot Windows (quickly, because otherwise you’ll end up in a UEFI console). 58 | 9. Windows should now be booting, and you should end up in the Windows 11 setup. Most of this is straightforward, but there is one thing to be aware of: 59 | In the “Select location to install Windows 11”, no drives are shown. Fix this by clicking “Load Driver”, “Browse”, expand the virtio-win drive, and select viostor → w11 → ARM64. Click OK. Select the “Red Hat VirtIO SCSI controller” that appears, and click install. 60 | 10. During the installation, the VM will reboot a few times. Don’t do anything, just let it happen. 61 | 11. After installation you’ll end up in the first boot wizard (to configure location, keyboard, etc). 62 | In the “Let’s connect you to a network”, click “Install driver”, open the virtio-win drive, navigate to NetKVM → w11 → ARM64, and click “Select folder”. Wait a few seconds, and the network adapter should appear. You can now continue. 63 | 12. After completing the installation, you should have a working Windows 11 install! 64 | 65 | # Post Installation 66 | Shut down the VM as usual to not make Windows scared (don’t just exit the win11.sh script). To boot it again, simply run the ./win11.sh script again. 67 | 68 | After installation, you can remove the two ISOs and remove the following 4 lines from the win11.sh script: 69 | ``` md 70 | -device usb-storage,drive=install \ 71 | -drive if=none,id=install,format=raw,media=cdrom,file=windows-11-iot.iso \ 72 | -device usb-storage,drive=virtio-drivers \ 73 | -drive if=none,id=virtio-drivers,format=raw,media=cdrom,file=virtio-win.iso \ 74 | ``` 75 | 76 | # SSH Steps 77 | 1. Modify the QEMU command line, replace `-nic user,model=virtio-net-pci` with `-device virtio-net-pci,netdev=net0 -netdev user,id=net0,hostfwd=tcp::5555-:22` to forward port 5555 to port 22 in the VM (you can pick another port if you like). 78 | 2. Start “Optional Features”, click “View features”, search for OpenSSH Server, and install it. (This takes a while). 79 | 3. Allow port 22 through the Windows firewall, see [this StackOverflow post](https://stackoverflow.com/questions/68594235/allow-ssh-protocol-through-win-10-firewall). 80 | 4. Start “Services”, look for “OpenSSH SSH Server”, and start it (right click → start). Also, right click on it, go to properties, and set the startup type to automatic so it always starts at boot. 81 | 5. Now you can SSH into your Windows system using ssh yourusername@localhost -p 5555! 82 | 6. If you want to log into the system using public-key authentication, you can put the public key in C:\ProgramData\ssh\administrators_authorized_keys (assuming your account is an administrator account). -------------------------------------------------------------------------------- /docs/sw/tethered-boot-macos-host.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Tethered Boot: macOS host machine 3 | --- 4 | 5 | # macOS-hosted tethered boot setup 6 | 7 | This guide will give more details about tethered boot prerequisites setup for a macOS host. 8 | 9 | ## macOS host 10 | 11 | Host's requirements: 12 | 13 | * Any Apple computer running a decently recent MacOs version 14 | * Enough disk space on the host for installing and compiling software 15 | * a free USB port on the host 16 | * a USB-A/USB-C or USB-C/USB-C cable 17 | * [prerequisites installed](#installing-prerequisite-software) 18 | 19 | Tested with: 20 | 21 | * iMac 27' late 2015 running macOs Big Sur 11.7 (20G817) 22 | 23 | ## Serial port setup 24 | 25 | On macOs m1n1 UART device names are different from those of a Linux host (`/dev/m1n1` and `/dev/m1n1-sec` on Linux). Typically device names looks like: 26 | 27 | * `/dev/cu.usbmodemP_01` for the primary UART device used by m1n1 propy client 28 | * `/dev/cu.usbmodemP_03` for the secondary UART device used to hook into the m1n1 hypervisor early when the tethered machine boots 29 | 30 | Beware that devices names might change on your particular machine or configuration, if in doubt check how you can [find actual device names](#find-actual-device-names). 31 | 32 | ## Activate m1n1 backdoor 33 | 34 | Shutdown (powered-off state) and connect the USB cable to the target machine and then issue the following command on the host: 35 | 36 | ```shell 37 | ~/asahi/m1n1/proxyclient/tools/picocom-sec.sh 38 | ``` 39 | 40 | Now start the tethered machine. The `picocom-sec.sh` script waits for the device and connect to it once it appears, that will trigger m1n1 hypervisor backdoor and you should see some output on the terminal: 41 | 42 | ```console 43 | picocom v3.1 44 | 45 | port is : /dev/cu.usbmodemP_03 46 | flowcontrol : none 47 | baudrate is : 500000 48 | : 49 | : 50 | ``` 51 | 52 | From now on m1n1 hypervisor is ready to accept command through m1n1 proxy client tools: 53 | 54 | ```shell 55 | $ python3 ~/asahi/m1n1/proxyclient/tools/shell.py 56 | : 57 | : 58 | TTY> Waiting for proxy connection... . Connected! 59 | Fetching ADT (0x00058000 bytes)... 60 | m1n1 base: 0x802848000 61 | Have fun! 62 | >>> 63 | ``` 64 | 65 | ### Find actual device names 66 | 67 | Install `pyserial` and issue the following command (make sure the target machine is plugged to the host): 68 | 69 | ```shell 70 | while : ; do pyserial-ports ; sleep 1 ; done 71 | ``` 72 | 73 | Cold-boot (from powered-off state) the tethered machine and wait for new devices to appear: note down the device names (the one with the lower number should be the main m1n1 UART device and the other one the m1n1). 74 | 75 | ## Installing prerequisite software 76 | 77 | ### Installing Homebrew 78 | 79 | The prefered way to install software on your macOS host is by using the `homebrew` package manager, this is the matter of running a simple chell command. 80 | 81 | Open a terminal window (press `[Cmd]`+`[Space]` keys, then type `iterm`, then press `[enter]`) then type the following command (refer to [Homebrew web site](https://brew.sh) if in doubt): 82 | 83 | ```shell 84 | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 85 | ``` 86 | 87 | ### Installing Python >= 3.9 88 | 89 | macOS bundles Python 3.8 but Python 3.9 or later is required for the m1n1 scripting part that runs on the host and puppeteers the m1n1 hypervisor on the tethered machine: 90 | 91 | ```shell 92 | brew install python3 93 | ``` 94 | 95 | Check that you are able to access the desired python executable and that you get the minimum required version: 96 | 97 | ```shell 98 | $ type python3 99 | python3 is /usr/local/bin/python3 100 | $ python3 --version 101 | Python 3.10.8 102 | ``` 103 | 104 | ### Installing LLVM 105 | 106 | You'll need a C compiler to build m1n1 and its dependencies, and for building kernel too. LLVM is the recommended compiler for Asahi (I think ?): 107 | 108 | ```shell 109 | brew install llvm 110 | ``` 111 | 112 | ### Installing pyserial 113 | 114 | Pyserial is required for m1n1 and can help identify the name of the serial port device exposed by macOS when m1n1 boots: 115 | 116 | ```shell 117 | pip3 install pyserial construct serial.tool 118 | ``` 119 | 120 | Check `pyserial-ports` is installed: 121 | 122 | ```shell 123 | $ type pyserial-ports 124 | pyserial-ports is /usr/local/bin/pyserial-ports 125 | ``` 126 | 127 | ### Installing picocom 128 | 129 | A serial port communication software is required to establish communication with m1n1 proxy. We recommend installing `picocom` for use as a serial terminal, which is available with homebrew: 130 | 131 | ```shell 132 | brew install picocom 133 | ``` 134 | 135 | ### Installing img4tool (optional) 136 | 137 | Either use Homebrew Tap or install it manually 138 | 139 | #### Use Homebrew tap 140 | 141 | I created a tap to ease installation through Homebrew, just add the tap and install: 142 | 143 | ```shell 144 | brew tap aderuelle/homebrew-tap 145 | brew install img4tool 146 | ``` 147 | 148 | #### Install manually 149 | 150 | If you intend to boot a stock macOS kernel, you'll need these tools to extract the actual kernel file from the kernlecache of a macOS install on the target machine. In the absence of precompiled version for macOS you'll have to compile it. 151 | 152 | For this step, setup a `asahi` folder in your home directory and clone everything there, additionally install everything in an `~/asahi/deps` folder so as to not mess up with the rest of the system. 153 | 154 | First clone, build and install `libgeneral` 155 | 156 | ```shell 157 | cd ~/asahi 158 | git clone https://github.com/tihmstar/libgeneral.git 159 | cd libgeneral 160 | ./autogen.sh 161 | ./configure --prefix=/Users/alexis/asahi/deps 162 | make && make install 163 | ``` 164 | 165 | Then clone, build and install `img4tool` 166 | 167 | ```shell 168 | cd ~/asahi 169 | git clone https://github.com/tihmstar/img4tool.git 170 | cd img4tool 171 | ./autogen.sh 172 | PKG_CONFIG_PATH=~/asahi/deps/lib/pkgconfig ./configure --prefix=~/asahi/deps 173 | make && make install 174 | ``` 175 | 176 | Update your `PATH` variable so that you're able access `img4tool` binary 177 | 178 | ```shell 179 | export PATH=~/asahi/deps/bin:$PATH 180 | ``` 181 | -------------------------------------------------------------------------------- /docs/sw/macos-kernelcache.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: macOS Kernelcache 3 | --- 4 | 5 | # READ THIS BEFORE PROCEEDING FURTHER 6 | 7 | **Asahi Linux has a very strict [reverse engineering policy](https://asahilinux.org/copyright/). Do not start disassembling macOS code, including the Darwin kernel, unless you have fully read and understood the policy.** 8 | 9 | We expect any contributors who wish to use binary reverse engineering as part of their contribution to their project to discuss the specifics with us in advance. This will usually mean arranging a clean-room environment, where their only job will be to write specifications, not any source code, on any related subsystems. 10 | 11 | You may be banned from ever contributing code directly to our project if you do not do this. You have been warned. 12 | 13 | **Distributing macOS binaries, in whole or in part, is a copyright violation.** Do not upload or share any such files. You have to extract the files from your own installation of macOS, on an Apple computer. 14 | 15 | Again, **only proceed if you have talked to us first about this**. 16 | 17 | ## Extracting the Darwin kernelcache 18 | 19 | * Find your kernelcache in the Preboot partition of your OS install 20 | * Grab [img4tool](https://github.com/tihmstar/img4tool) 21 | * `img4tool -a kernelcache -e -p kernelcache.im4p -m kernelcache.im4m` 22 | * `img4tool kernelcache.im4p -e -o kernelcache.macho` 23 | * The result is a standard Mach-O file. You can look at the headers with [machodump.py](https://gist.github.com/marcan/e1808a2f4a5e1fc562357550a770afb1) if you do not have a Mach-O toolchain handy. 24 | 25 | ## Alternate using the kernel.release.* file 26 | 27 | * From suggestion by **davidrysk** there are some MacOS kernel images already available at **/System/Library/Kernels/kernel.release.t8020** 28 | * Below shows dumping the macho header with Marcan's script [machodump.py](https://gist.github.com/marcan/e1808a2f4a5e1fc562357550a770afb1) in order to get the offsets to disassemble the code: 29 | * Note: This requires the **construct** python package but the debian buster packages didn't work (python 3 or 2) or even a github version 30 | * I had to use the pypi install via pip3: 31 | ``` 32 | apt install python3-pip 33 | pip3 install construct 34 | ``` 35 | 36 | * Then dump out the headers to extract the offsets to the code: 37 | ``` 38 | python3 machodump.py kernel.release.t8020 39 | ... 40 | cmd = (enum) SEGMENT_64 25 41 | args = Container: 42 | segname = u'__TEXT' (total 6) 43 | vmaddr = 0xFFFFFE0007004000 44 | vmsize = 0x00000000000C4000 45 | fileoff = 0x0000000000000000 46 | filesize = 0x00000000000C4000 47 | ... 48 | Container: 49 | cmd = (enum) UNIXTHREAD 5 50 | args = ListContainer: 51 | Container: 52 | flavor = (enum) THREAD64 6 53 | data = Container: 54 | x = ListContainer: 55 | 0x0000000000000000 56 | ... 57 | 0x0000000000000000 58 | fp = 0x0000000000000000 59 | lr = 0x0000000000000000 60 | sp = 0x0000000000000000 61 | pc = 0xFFFFFE00071F4580 62 | cpsr = 0x00000000 63 | flags = 0x00000000 64 | .... 65 | ``` 66 | * Calculate the offset from the starting instruction pc=0xFFFFFE00071F4580 to the start of the VM (vmaddr=0xFFFFFE0007004000) 67 | ``` 68 | calc "base(16); 0xFFFFFE00071F4580 - 0xFFFFFE0007004000" 69 | 0x1f0580 70 | ``` 71 | * Skip over the first 0x1f0000 = 0x1f0 x 0x1000 (4k) blocks and split off 64K from the here: 72 | ``` 73 | dd if=/home/amw/doc/share/kernel.release.t8020 of=init.bin bs=4k skip=$((0x1f0)) count=16 74 | ``` 75 | * Disassemble the raw binary blob 76 | ``` 77 | aarch64-linux-gnu-objdump -D -b binary -m aarch64 init.bin 78 | 79 | init.bin: file format binary 80 | 81 | Disassembly of section .data: 82 | 83 | 0000000000000000 <.data>: 84 | 0: 14000100 b 0x400 85 | 4: d503201f nop 86 | 8: d503201f nop 87 | c: d503201f nop 88 | 10: d503201f nop 89 | 14: d503201f nop 90 | 18: d503201f nop 91 | 1c: d503201f nop 92 | 20: d503201f nop 93 | ... 94 | 3f4: d503201f nop 95 | 3f8: d503201f nop 96 | 3fc: d503201f nop 97 | 400: d510109f msr oslar_el1, xzr 98 | 404: d5034fdf msr daifset, #0xf 99 | 408: f2e88aa0 movk x0, #0x4455, lsl #48 100 | 40c: f2c80a80 movk x0, #0x4054, lsl #32 101 | 410: f2ac8cc0 movk x0, #0x6466, lsl #16 102 | 414: f28c8ee0 movk x0, #0x6477 103 | 418: 90003fe4 adrp x4, 0x7fc000 104 | 41c: 3944c085 ldrb w5, [x4, #304] 105 | 420: 710000bf cmp w5, #0x0 106 | ... 107 | ``` 108 | * On the actual Mac with XCode installed as pointed out by **davidrysk** you can do the much simpler: 109 | ``` 110 | otool -xv /System/Library/Kernels/kernel.release.t8020 111 | 112 | ... 113 | /System/Library/Kernels/kernel.release.t8020: 114 | (__TEXT_EXEC,__text) section 115 | fffffe00071ec000 sub x13, sp, #0x60 116 | fffffe00071ec004 sub sp, sp, #0x60 117 | fffffe00071ec008 st1.4s { v0, v1, v2 }, [x13], #48 ; Latency: 4 118 | ... 119 | fffffe00071f43f8 nop 120 | fffffe00071f43fc nop 121 | fffffe00071f4400 msr OSLAR_EL1, xzr 122 | fffffe00071f4404 msr DAIFSet, #0xf 123 | fffffe00071f4408 movk x0, #0x4455, lsl #48 124 | fffffe00071f440c movk x0, #0x4054, lsl #32 125 | fffffe00071f4410 movk x0, #0x6466, lsl #16 126 | fffffe00071f4414 movk x0, #0x6477 127 | fffffe00071f4418 adrp x4, 2044 ; 0xfffffe00079f0000 128 | fffffe00071f441c ldrb w5, [x4, #0x130] ; Latency: 4 129 | fffffe00071f4420 cmp w5, #0x0 130 | fffffe00071f4424 b.ne 0xfffffe00071f4438 131 | .... 132 | ``` 133 | -------------------------------------------------------------------------------- /docs/platform/quirks.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple Silicon Platform Quirks 3 | --- 4 | 5 | This page is basically a TL;DR of [Open OS Ecosystem on Apple Silicon Macs](open-os-interop.md). It is written for general Linux power users who are used to the boot process on other platforms. Read that page for the full details. 6 | 7 | ## This is not a typical UEFI platform 8 | 9 | On typical UEFI systems, UEFI is the native boot firmware and expected to manage any and all installed OSes. **This is not the case on Apple Silicon**. We only use the U-Boot UEFI layer as a bridge layer to allow you to use existing/familiar bootloaders and remain compatible with typical systems. This has a few implications: 10 | 11 | * There is no UEFI variable storage, because the platform has no native UEFI support that could accommodate it. This means you cannot configure UEFI boot. U-Boot will *always* boot from the default UEFI executable (`\EFI\BOOT\BOOTAA64.EFI`). 12 | * You can have *multiple* UEFI instances and each instance is intended to boot *only one* OS. Multi-boot is achieved at the native OS install layer and the native boot picker, *not* via UEFI. Installing multiple OSes under one UEFI subsystem is *not supported* and liable to breaking in the future for multiple reasons. 13 | * That means there can be *multiple EFI System Partitions*, which means that finding the ESP by type UUID *is not reliable*. Any tools that attempt to do so will be broken for some subset of users. 14 | 15 | When you boot an OS on an Apple Silicon platform, there are two concepts of an ESP: 16 | 17 | * The ESP that the OS was booted from, which could be on a USB drive if you told U-Boot to boot from USB. 18 | * The System ESP which is where U-Boot itself and m1n1 stage 2 are installed, along with vendor firmware. This is always on the internal NVMe. 19 | 20 | The System ESP can be identified by looking up the `asahi,efi-system-partition` chosen variable in the device tree, which you can find at `/proc/device-tree/chosen/asahi,efi-system-partition`. This variable always contains the PARTUUID of the System ESP, regardless of where you told U-Boot to boot from. 21 | 22 | The OS ESP is usually configured in `/etc/fstab` by UUID or PARTUUID and mounted at `/boot/efi` or `/boot`. 23 | 24 | On standard internal NVMe installs, there is a single ESP which fulfills both roles. 25 | 26 | ## Firmware is loaded and provided on boot 27 | 28 | We do not ship native platform firmware in `linux-firmware` or any other separate firmware package. Instead, there are three kinds of firmware: 29 | 30 | * *System-global* firmware that is updated by macOS together with macOS updates. This only ever goes forward in version, never backwards (unless you do a full DFU erase), and is intended to be backwards-compatible. It is loaded on boot by iBoot. 31 | * *OS-paired* firmware that is installed by the Asahi Linux installer into the stub APFS partition and directly loaded by iBoot. This is *not* backwards-compatible and whatever OS you install *must* support the specific firmware version used. This is why going into expert mode in the installer and picking a non-default version (despite all the warnings) will break your system. There is currently no way to upgrade this, but there will be in the future once there's a good reason to upgrade it. 32 | * *Extracted* vendor firmware that is collected by the Asahi Linux installer and placed in `\vendorfw\vendorfw.cpio` in your System ESP. This is loaded into memory by either your bootloader (as an initramfs) or by your initramfs, and extracted into a tmpfs mounted on `/lib/firmware/vendor` on every boot so the kernel can load it. This *should* match your OS-paired firmware version. The `asahi-fwextract` package contains the same extraction script as the Asahi Linux installer and is used to upgrade `vendorfw.cpio` when new kinds of firmware are added, to avoid having to go back to macOS and run the Asahi Linux installer. 33 | 34 | ## OSes should be considered paired to their UEFI environment and ESP 35 | 36 | The Linux kernel ships with device trees, and on typical setups with our Asahi enablement scripts, these device trees are installed alongside m1n1 and u-boot into the *System ESP* and updated when you update your kernel. U-Boot and m1n1 themselves are also installed as packages and updated that way. That means that **there can only be one OS installed that owns the System ESP and manages the bootloader there**. 37 | 38 | Nothing stops you from booting other OSes from such a UEFI environment, such as temporarily booting into a USB drive for recovery purposes, but *there is no absolute guarantee that mismatched kernels will work with foreign device trees*. In the past, changes have broken booting entirely. This is less likely these days, but could still happen. More likely, you may experience missing features or broken drivers. In general, all device tree bindings which are already upstream should remain backwards-compatible, but all bets are off with any drivers not yet upstream. 39 | 40 | If you nonetheless want to boot more than one OS from the same UEFI partition (which should really only be done for experimental or recovery purposes or if you intend to manage this all yourself manually, not as a long-term setup, and is not supported by us), you should make sure that *only one OS* owns your System ESP and will update the `/m1n1/boot.bin` file there. That means you need to edit/create `/etc/default/update-m1n1` file on *all but one* of the OS installs you intend to run, and add the `M1N1_UPDATE_DISABLED=1` variable there. This will stop the standard m1n1 update script from running, and therefore disable m1n1, u-boot, and device tree updates. 41 | 42 | Future features, like SEP support for encryption and secret storage, may further depend on this pairing and are not expected to work with multiple OSes sharing one ESP/UEFI container. 43 | 44 | On the other hand, it is perfectly acceptable to have one single external USB install that you always boot (e.g. from a "UEFI only" install with the Asahi Linux installer, which only sets up the APFS stub and System ESP), and to allow that install to manage your System ESP on the internal disk. In that case, OS tooling needs to use `/boot/efi` or `/boot` (depending on the setup) when it wants to update its own EFI bootloader (e.g. GRUB), and locate the System ESP by using the UUID in `/proc/device-tree/chosen/asahi,efi-system-partition` when it needs to update m1n1/u-boot/device trees or locate `vendorfw.cpio`. This is already the case in our reference implementation in asahi-scripts. 45 | -------------------------------------------------------------------------------- /docs/hw/soc/apcie.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Apple PCIe controller 3 | --- 4 | 5 | The PCIe host bridge includes at least some Synopsys DesignWare derived logic. The release version encoded at offset 0x8f8/0x8fc in PCIE config space indicates version 530*-ea15 (5.30a-ea15). 6 | 7 | ## ADT bindings 8 | 9 | | Property | Value | Meaning | 10 | |-------------------|------------------|-------------------| 11 | | compatible | apcie,t8103 | compatible string | 12 | | #address-cells | 3 | normal PCI DT: `len>` | 13 | | #size-cells | 2 | normal PCI DT | 14 | | interrupt-parent | - | phandle of AIC | 15 | | interrupts | (0x2b7, 0x2ba, 0x2bd) | Administrative interrupts. Maybe AER? | 16 | | msi-parent-controller | - | phandle of AIC | 17 | | #msi-vectors | 32 | number of IRQs in AIC for MSI | 18 | | msi-address | 0xfffff000 | program this into the MSI-X address BAR | 19 | | msi-vector-offset | 0x2c0 | (this + msi_id) go to the MSI-X value field in the MSI-X device BAR | 20 | | #ports | 3 | number of DART bindings | 21 | | apcie-common-tunables | 0x2c, 0x4, 0xff, 0x0, 0x1, 0x0, 0x54, 0x4, 0xffffffff, 0x0, 0x140, 0x0 | ? 22 | | apcie-axi2af-tunables | todo | ? | 23 | | apcie-phy-tunables | todo | ? | 24 | | apcie-phy-ip-pll-tunables | todo | ? | 25 | | apcie-phy-ip-auspma-tunables | todo | ? | 26 | 27 | ### reg 28 | 29 | | Address | Length | Meaning | 30 | |-------------|-------------|----------------------------| 31 | | 0x690000000 | 0x10000000 | ECAM space 32 | | 0x680000000 | 0x40000 | Ctrl 33 | | 0x680080000 | 0x90000 | Phy config 34 | | 0x6800c0000 | 0x20000 | ? 35 | | 0x68c000000 | 0x4000 | ? 36 | | 0x3d2bc000 | 0x1000 | ? 37 | | 0x681000000 | 0x8000 | port0 link / control registers 38 | | 0x681010000 | 0x1000 | port0 39 | | 0x680084000 | 0x4000 | port0 phy 40 | | 0x6800c8000 | 0x16610 | port0 41 | | 0x682000000 | 0x8000 | port1 link / control registers 42 | | 0x682010000 | 0x1000 | port1 43 | | 0x680088000 | 0x4000 | port1 phy 44 | | 0x6800d0000 | 0x6000 | port1 45 | | 0x683000000 | 0x8000 | port2 link / control registers 46 | | 0x683010000 | 0x1000 | port2 47 | | 0x68008c000 | 0x4000 | port2 phy 48 | | 0x6800d8000 | 0x6000 | port2 49 | 50 | ## Known register meanings 51 | 52 | | Space | Offset | name | Meaning / Values | 53 | |-------------|--------------|----------------|------------------------| 54 | | Ctrl | 0x28 | Refclk | 1 << 4 is good 55 | | Ctrl | 0x50 | ? | Write 1 to enable PCIe 56 | | Ctrl | 0x58 | ? | Reads 1 after 0x50 write 57 | | Phy config | 0x0 | ? | Writing bits 0x1 and 0x2 toggle 0x4 and 0x8 respectively 58 | | portX link | 0x100 | pcielint 59 | | portX link | 0x208 | linksts | Bit 0x1 means link is enabled. Requires write to 0x804 60 | | portX link | 0x210 | linkcdmsts 61 | | portX link | 0x800 | ? | Read in initializeRootComplex() 62 | | portX link | 0x804 | ? | Read in enablePortHardware() 63 | | portX phy | 0x0 | PhyGlueLaneReg / RefClockBuffer | Writing bits 0x1 and 0x2 toggle bits 0x4 and 0x2 respectively 64 | 65 | ## Tunables 66 | 67 | The following set of tunables operate on config space of the per-port PCIe bridge devices. 68 | 69 | ### pcie-rc-tunables 70 | On the 2020 M1 mini, this set of register writes modifies some bits on standardized capability structures as well as some other registers. 71 | 72 | | register | capability | effect | 73 | |----------|------------|--------| 74 | | 0x194 | L1 PM Substates | clear Port Common_Mode_Restore_Time | 75 | | | | clear Port T_POWER_ON Scale | 76 | | | | clear Port T_POWER_ON Value | 77 | | 0x2a4 | Data Link Feature | clear Data Link Feature Exchange Enable | 78 | | 0xb80 | | not part of an (extended) capability structure | 79 | | 0xb84 | | not part of an (extended) capability structure | 80 | | 0x78 | PCI Express | clear Max_Read_Request_Size | 81 | 82 | ### pcie-rc-gen3-shadow-tunables 83 | | register | capability | effect | 84 | |----------|------------|--------| 85 | | 0x154 | Secondary PCI Express | set Downstream Port 8.0 GT/s Transmitter Preset | 86 | | | | set Upstream Port 8.0 GT/s Transmitter Preset | 87 | | 0x890 | | not part of an (extended) capability structure | 88 | | | | appears to be the Synopsys Designware PCIe GEN3_RELATED register | 89 | | 0x8a8 | | not part of an (extended) capability structure | 90 | | | | appears to be the Synopsys Designware PCIe GEN3_EQ_CONTROL register | 91 | 92 | ### pcie-rc-gen4-shadow-tunables 93 | | register | capability | effect | 94 | |----------|------------|--------| 95 | | 0x178 | Physical Layer 16.0 GT/s | set Downstream Port 16.0 GT/s Transmitter Preset | 96 | | | | set Upstream Port 16.0 GT/s Transmitter Preset | 97 | | 0x890 | | not part of an (extended) capability structure | 98 | | | | (see above) | 99 | | 0x8a8 | | not part of an (extended) capability structure | 100 | | | | (see above) | 101 | 102 | So the changes to documented registers seem to disable some (buggy?) features as well do some lane equalization tuning. Maybe Apple hopes to re-enable this in a future respin of the silicon without having to specify specific silicon revs in their xnu driver? 103 | 104 | ## DT bindings 105 | 106 | Device tree bindings have been accepted upstream. 107 | 108 | Some open questions remain: 109 | * How do we enable the WiFi/BT PCIe device? This device needs to be explicitly enabled through the SMC before it shows up as a PCIe device. It has been suggested that this is how Apple implements "Airplane Mode" and there is a separate "amfm" node in the ADT for this. So maybe it makes sense to have some sort of rfkill device/node that takes care of this. Hopefully this means the APCIe device gets an interrupt when it is turned on such that we can (re)train the PCIe link. 110 | 111 | This proposed binding has been successfully implemented/tested in u-boot and OpenBSD. However, we still need clock, pinctrl/gpio and DART bindings to make this all work. 112 | -------------------------------------------------------------------------------- /docs/platform/pc-boot-differences.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Boot flow deviations from the AMD64 PC platform 3 | --- 4 | 5 | The M1 machines use a boot process that on the surface looks very different from how a regular PC or older Intel Mac boots. However, there is logic to the madness. This document gives you a way of thinking that you can use to better visualize how things work on Apple Silicon machines. 6 | 7 | # SSD 8 | 9 | The SSD on M1 machines contains both boot components and the OS that is installed on the machine. This is different from UEFI machines. Think of the SSD on Apple Silicon as being *both* parts of UEFI firmware flash memory (in particular, configuration is stored on the SSD), *and* the main OS NVMe device you boot from, including the OS loader, combined. If you're familiar with Android devices, those use a similar model. 10 | 11 | The SSD uses GPT, just like disks under most UEFI systems. The first partition is used for boot-related stuff, configuration, and sometimes firmware, kind of like the UEFI variable firmware volume and other bits. The OS is installed in a container that includes a volume that contains the OS bootloader, some firmware, and the OS kernel. Think of this as similar to the EFI System Partition (ESP). 12 | 13 | iBoot can only understand APFS, and all three partitions on the GPT disk are APFS containers themselves containing multiple APFS volumes. 14 | 15 | # NOR Flash 16 | 17 | There is also a separate flash chip, called a NOR flash. This is the same kind of chip that contains the UEFI firmware on PCs. It only contains product information and the first stage of iBoot. You can think of it as the early portion of the UEFI firmware, enough to boot the OS bootloader from internal storage but *not* including a huge amount of drivers like UEFI does. 18 | 19 | # SecureROM 20 | 21 | This is a ROM embedded in the M1 and is truly the first code that runs. Its job is to load the first stage of iBoot from NOR and run it. 22 | 23 | Intel/AMD PCs also have various ROMs and a complicated boot process, but we never hear about those parts because they are proprietary. The idea that modern Intel PCs directly start executing code from the firmware in Flash without any initialization is an illusion, but we like to pretend that that's still how it works. 24 | 25 | # iBoot 26 | 27 | iBoot is the main bootloader on M1 machines. It is small. It cannot understand external storage. It does not support USB. It does not have a UI. All it can do is boot from internal storage, and show an Apple logo and a few error messages. 28 | 29 | iBoot is like the lower level components of UEFI firmware on a PC. Enough to boot from internal NVMe, but without any USB drivers. 30 | 31 | There are two stages to iBoot. One of them lives in NOR Flash, and its job is to understand APFS and load the second stage from the SSD. This is like system firmware, and it is persistent. The second stage is effectively a macOS bootloader, and boots the macOS kernel. This is like boot.efi on Intel Macs. 32 | 33 | # Recovery Mode 34 | 35 | Recovery Mode is a macOS instance that is built in to a separate partition. It is a secure environment where you can select which OS to boot, or go into a recovery shell/environment. When you hold down the power button on an Apple Silicon machine, you actually boot macOS. The boot options screen is already a full-screen macOS application. Once you go into recovery mode, you can pull up a terminal and you get a root shell. You can use the network, curl, sh, perl, and other tools that come with the installation. You can run arbitrary scripts and the environment has commands useful for configuring boot. You can run your own ad-hoc signed binaries (as of 11.2). However, SIP and AMFI (entitlement) restrictions apply, so you cannot grant your own binaries e.g. permission to interact with the boot policy/SEP. 36 | 37 | Recovery mode is like a supercharged UEFI shell and UEFI setup menu combined into one. It should be powerful enough for us to build a Linux installer off of. Think of it as the rest of the UEFI firmware, and more. 38 | 39 | # macOS 40 | 41 | macOS boots from the second GPT partition. It is the real OS. It starts with the Darwin kernel and goes from there. 42 | 43 | Asahi Linux replaces or complements macOS. This point is where we are allowed to replace things and boot our own code. 44 | 45 | The concept of an "OS" for Apple Silicon macs includes both the OS loader (the second stage of iBoot) and the Darwin kernel and filesystem. We can replace the kernel, but not the second stage of iBoot - the kernel is the point in the boot process where Apple has developed the ability to downgrade security and run our own code. We also need to keep the overall structure looking like macOS. This means that, effectively, Linux will bootstrap off of a "shell" of macOS, a volume with just iBoot and a few files to convince Apple's boot infrastructure that it is a legitimate OS that can be booted. Think of this whole thing as a somewhat complicated EFI System Partition. 46 | 47 | Since there are special requirements on how the first boot stage that replaces macOS is installed, it is inconvenient to update from Linux. Therefore, what we will do is insert our own bootloader chain at this point. You can think of this as the UEFI secureboot "shim" used to install Linux on UEFI environments that use the Microsoft secureboot keys. The signing is different; we won't be needing nor using any Apple developer certificates for this; instead what will happen is that the install process will "sign" the first stage for use on a single machine only - but the concept is similar. After this stage, we can chainload to anything we want from filesystems more standard in Linux land, such as ext4 or FAT32. 48 | 49 | # DFU 50 | 51 | DFU is a recovery mode built in to the SecureROM of the M1 that allows flashing the device from scratch, if iBoot and/or recovery mode are gone. DFU works even if the data in the NOR Flash is gone. 52 | 53 | DFU does not exist on most PCs. If the UEFI flash is corrupted, the PC is bricked. DFU mode is a unique feature of Apple Silicon devices. 54 | 55 | Some PC motherboards implement a similar feature as part of a separate chip, which can flash the UEFI firmware from a USB stick without actually turning on the motherboard normally, but this is only common in higher-end stand alone motherboards. 56 | 57 | Thanks to DFU mode, it is just about impossible to brick an Apple Silicon machine in such a way that it cannot be recovered externally. The worst case scenario is that the product information (serial number, calibration, etc) in NOR is erased. If that happens, in theory, the DFU process should pull that information from Apple during the phone-home steps of the recovery process. Even then, this happening by accident is vanishingly unlikely. 58 | -------------------------------------------------------------------------------- /docs/hw/soc/smc.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: System Management Controller (SMC) 3 | --- 4 | 5 | The SMC is a piece of hardware handling access to such things as temperature sensors, voltage/power meters, battery status, fan status, and the LCD backlight and lid switch. 6 | 7 | It is "documented", to the extent that it is, in [https://github.com/corellium/linux-m1/blob/master/drivers/hwmon/apple-m1-smc.c](https://github.com/corellium/linux-m1/blob/master/drivers/hwmon/apple-m1-smc.c), but that's just the protocol, which essentially allows you to do three things: 8 | 9 | 1. read data for each of many, many four-ASCII-character "keys". There are about 1,400 such keys on the MacBook Pro. 10 | 2. read data for a key, supplying a payload. 11 | 3. write data for a key. 12 | 13 | In addition to receiving the bytes of data, the SMC provides a type for that data, encoded as four ASCII characters, and a flags byte. 14 | 15 | So far, I haven't been brave enough to try (2) or (3). 16 | 17 | ## SMC key types 18 | 19 | Encoded as four ASCII characters, the last of which I omit if it's a space. 20 | 21 | * `flt`: a 32-bit single-precision IEEE float. In at least one case, the byte order is actually reversed. 22 | * `si8`, `ui8`, `si16`, `ui16`, `si32`, `ui32`, `si64`, `ui64`: signed/unsigned 8-/16-/32-/64-bit values 23 | * `hex_`: random binary data 24 | * `flag`: 1 or 0 25 | * `ioft`: this appears to be a 64-bit unsigned fixed-point value (48.16, most likely). 26 | * `ch8*`: ASCII string 27 | * `{jst`: unknown. Possibly some sort of binary-encoded structured document? 28 | 29 | ### SMC flags 30 | 31 | Almost totally unknown. Keys with `0xf0` flags don't appear to return non-zero values reliably (see Quirks). 32 | 33 | ### SMC keys 34 | 35 | Many. [https://github.com/torvalds/linux/blob/master/drivers/hwmon/applesmc.c](https://github.com/torvalds/linux/blob/master/drivers/hwmon/applesmc.c) documents some, but mostly you have to guess based on the four-character name. There are more than 1,400 such keys on the MacBook Pro, with many apparently unused. 36 | 37 | Some guesses as to what they might mean: 38 | 39 | * `T???`: temperature values, in Celsius, as float. There are many of those. The question marks specify, presumably, the location (and possibly whether or not the value is averaged to provide a more meaningful reading?) 40 | * `TB0T`: battery temperature 41 | * `TCHP`: charger temperature (increases sligtly when charging) 42 | * `TW0P`: wireless temperature (increases slightly when wireless is turned on) 43 | * `Ts0P`: palm rest temperature 44 | * `Ts1P`: palm rest temperature 45 | * `V???`: voltages. Probably in volts. 46 | * `gP??`: "GPIO" pins. Actually output only, and there appears to be a bug preventing you from reading the level of a pin non-destructively, except it works for the very first such pin to be read. 47 | * `gP0d`: controls the WiFi/BT chips. Without enabling this, the PCI devices for WiFi and BT don't show up. Used to implement "rfkill" functionality? 48 | * `gP12`: on at least one system, the LCD backlight. Can be turned off, which reduces apparent power consumption, and turned back on. 49 | * `gp??` (note capitalization): presumably also some kind of GPIO pin? 50 | * `D1??`: information about the device connected to the first USB-C port 51 | * `D1in`: name of the connected charger 52 | * `D1is`: serial number of the connected charger 53 | * `D2??`: refer to `D1??` 54 | * `P???`: power meters, presumably in watts 55 | * `PSTR`: entire system's power consumption in W 56 | * `SBA?`: system battery information 57 | * `SBA1`: battery cell 1 voltage in mV 58 | * `SBA2`: battery cell 2 voltage in mV 59 | * `SBA3`: battery cell 3 voltage in mV 60 | * `SBAV`: battery voltage in mV (sum of `SBA1`, `SBA2` and `SBA3`, same as `B0AV` but as a `flt`) 61 | * `SBAR`: battery remaining capacity in mAh (same as `B0RM` but as a `flt`) 62 | * `SBAS`: battery charge in percent (same as `BRSC` but as a `flt`) 63 | * `RPlt`: platform name, such as "J293". 64 | * `a???`: highly volatile power-related measurement, so possibly current going to various device parts. 65 | * `F???`: fan information. Refer to https://github.com/torvalds/linux/blob/master/drivers/hwmon/applesmc.c. 66 | * `CL??`: various times, measured in microseconds since (possibly) manufacturing/RTC reset time 67 | * `CLKU`: continuously-updated current time 68 | * `CLBT`: SMC boot time (e.g. AC power applied) 69 | * `CLSP`: possibly the time the SMC last went to sleep 70 | * `CLWK`: possibly the time the SMC last woke up 71 | * `MSLD`: the lid switch, 1 for closed, 0 for open 72 | * `bHLD`: power button currently pressed 73 | * `MBSe`: power button pressed since last read, read-to-clear 74 | * `B0CT`: battery charge cycle count 75 | * `B0AV`: battery voltage in mV (same as `SBAV` but as an `si16`) 76 | * `BRSC`: battery charge in percent (same as `SBAS` but as a `ui16`) 77 | * `B0DC`: battery design capacity in mAh 78 | * `B0FC`: battery full capacity in mAh 79 | * `B0RM`: battery remaining capacity in mAh (same as `SBAR` but as a `ui16` in reverse byte order) 80 | * `B0TE`: battery time-to-empty in minutes 81 | * `B0TF`: battery time-to-full in minutes 82 | * `ID0R`: input current in A 83 | * `VD0R`: input voltage in V 84 | * `PDTR`: input power in W 85 | 86 | ### Quirks 87 | 88 | Or possibly quirks? 89 | 90 | * `#KEY`: contains the number of keys in the SMC, but in reversed byte order. 91 | * `VP3b`: apparently byte-reversed 92 | * `gP??`: latched in a weird way: the first time one of these keys is read, the data indicates the pin's power status. But reading any of the keys afterwards returns `0`, except after a write to one of them, which allows you to read data once more (but just once), for any of the pins. So you can read all pins by repeatedly writing 1 to a pin you know to be at high level, then reading the other pin levels one by one. Reading with a payload of 0xffffffff or 0x00000001 returns the right value. 93 | * `rLD0` etc. cannot be read normally, but can be read with a 0x00000001 or 0x00ffffff payload. Maybe that's related to the "flags" byte being 0xf0. 94 | 95 | ### Notifications 96 | 97 | Setting the "NTAP" (notify application processor, maybe?) flag to 1 makes the SMC send notifications when certain system events happen, such as power being connected and disconnected, the power button being pressed, or the lid being opened or 98 | closed. Notifications are mailbox messages apparently limited to the 64-bit payload. 99 | 100 | ### ADC 101 | 102 | In addition to the keys accessible "directly" through the SMC, there is what appears to be a muxed single-channel ADC providing access to 111 further values. It is accessed through "aDC#" (giving the number of keys), "aDC?" (query key name using a numeric payload), and "aDCR", the actual result value. 103 | -------------------------------------------------------------------------------- /docs/hw/soc/serial-debug.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Debugging via Serial Console 3 | --- 4 | 5 | Taken from the original Developer Quickstart guide 6 | 7 | ## Getting a serial console 8 | 9 | Having a serial console is indispensable for a fast development cycle and to debug low-level issues. 10 | 11 | M1 Macs expose their debug serial port over one of their Type C ports (the same one used for DFU). On MacBooks, this is the rear left port. On the Mac Mini, this is the port closest to the power plug. 12 | 13 | The target machine can also be hard-rebooted using USB-PD VDM commands, making for a quick test cycle (no holding down power buttons). 14 | 15 | See [USB-PD](usb-pd.md) for details on the USB-PD VDM commands and what you can do with them. 16 | 17 | The serial port is a UART using 1.2V logic levels, and requires vendor-specific USB-PD VDM commands to enable. Thus, making a compatible cable is nontrivial. You have the following options. 18 | 19 | ### Using an M1 machine 20 | 21 | If you have two M1 boxes, this is the simplest solution. Just grab [macvdmtool](https://github.com/AsahiLinux/macvdmtool/), connect both machines with a standard Type C SuperSpeed cable using the DFU port on *both* machines, and that's it! 22 | 23 | **IMPORTANT NOTE:** The cable needs to be the USB 3 / SuperSpeed type. USB 2 only cables won't work, **the charging cable that comes with the MacBook/MacBook Air will not work** and neither will most other cheap cables or cables marketed for their charging capacity. If it doesn't say "SuperSpeed" or "USB3.0" in the package it almost certainly won't work. If it's thin and bendy it is almost certainly *not* a SuperSpeed cable. Cables that work need to have upwards of **15** wires inside them; if it doesn't feel like it could possibly have that many wires inside, it is not the cable you need. If you are sure your cable is SuperSpeed capable (i.e. devices do enumerate as SuperSpeed through it) and it still doesn't work, then it is non-compliant and the manufacturer deserves to be shamed on their Amazon reviews page, because it means they didn't connect the SBU1/2 pins. 24 | 25 | ```shell 26 | $ xcode-select --install 27 | $ git clone https://github.com/AsahiLinux/macvdmtool 28 | $ cd macvdmtool 29 | $ make 30 | $ sudo ./macvdmtool reboot serial 31 | ``` 32 | 33 | You should see something like this: 34 | 35 | ``` 36 | Mac type: J313AP 37 | Looking for HPM devices... 38 | Found: IOService:/AppleARMPE/arm-io@10F00000/AppleT810xIO/i2c0@35010000/AppleS5L8940XI2CController/hpmBusManager@6B/AppleHPMBusController/hpm0/AppleHPMARM 39 | Connection: Sink 40 | Status: APP 41 | Unlocking... OK 42 | Entering DBMa mode... Status: DBMa 43 | Rebooting target into normal mode... OK 44 | Waiting for connection........ Connected 45 | Putting target into serial mode... OK 46 | Putting local end into serial mode... OK 47 | Exiting DBMa mode... OK 48 | ``` 49 | 50 | See the macvdmtool page or just run it without arguments for a list of supported commands. Your serial port device is `/dev/cu.debug-console`. You can try picocom with: `sudo picocom -q --omap crlf --imap lfcrlf -b 115200 /dev/tty.debug-console`. 51 | 52 | 53 | NOTE: if you have enabled serial debug output on your host machine (via nvram settings), the serial port device will be in use by the kernel. You need to turn that off to use it as a generic serial port. 54 | 55 | ### DIY Arduino-based USB-PD interface 56 | 57 | You can build a DIY USB-PD interface with the following parts: 58 | 59 | * An Arduino or clone 60 | * An FUSB302 chip, either stand-alone or on a breakout board 61 | * A USB Type C breakout board (get a male one, plugging in directly into the target, for the most flexibility) 62 | * A 1.2V compatible UART interface 63 | 64 | Note that most FUSB302 breakout boards will not usefully break out the Type C pins you need, so it's best to use a separate full breakout board. 65 | 66 | Go to the [vdmtool](https://github.com/AsahiLinux/vdmtool) repository for more information and a wiring list. Documentation is a bit sparse at the moment. You can ask us on IRC (OFTC/#asahi) if you need help. 67 | 68 | 1.2V compatible UART interfaces are relatively rare. 1.8V ones will usually work for input (RX); you can use a resistor divider to step down the TX voltage (`TX -- 220Ω -+- 470Ω -- GND` will step down 1.8V TX to 1.22V at the `+` point). 69 | 70 | The default `vdmtool` code will put serial on the SBU1/SBU2 pins. At the device side connector (no cable), TX (output from the Mac) will be on the SBU1 pin on the connector side that has the active CC line (you should only connect one), and RX (input to the Mac) will be directly opposite the CC line. 71 | 72 | This is all rather rudimentary because it's a stop-gap for the proper solution, which is... 73 | 74 | ### Inflexible USB-PD Debug Interface (aka Central Scrutinizer) 75 | 76 | An alternative to the above DIY approach is the Central Scrutinizer project, which started exactly as the above, only using a custom PCB instead of a breadboard. It has since evolved to support additional features, but the core functionality is exactly the same: 77 | 78 | ![Central Scrutinizer](../../assets/central-scrutinizer.jpg) 79 | ![Central Scrutinizer (side)](../../assets/central-scrutinizer-2.jpg) 80 | 81 | Main features are: 82 | - RaspberryPi Pico as the micro-controller (yes, totally overkill, but cheaper than an Arduino!) 83 | - level shifters for the serial lines 84 | - USB2.0 pass-through to feed m1n1 85 | - stackable (a single Pico is capable of driving **two** Central Scrutinizer boards) 86 | - USB-C orientation detection (v2+) 87 | - capable of using dumb USB2.0 cables for serial, at the expense of not being able to use the pass-through feature (v3+) 88 | 89 | The KiCad project is available [here](https://git.kernel.org/pub/scm/linux/kernel/git/maz/cs-hw.git), and the corresponding firmware for the Pico is [there](https://git.kernel.org/pub/scm/linux/kernel/git/maz/cs-sw.git). The hardware side of the project is pre-configured to production at JLCPCB, so that producing it is only a few clicks away. Alternatively, you can find some pre-built boards on Tindie, but building your own should be the first port of call. 90 | 91 | If you want more information about this project, feel free to get in touch with [maz](mailto:maz@kernel.org). 92 | 93 | ### Flexible USB-PD Debug Interface (project name TBD) 94 | 95 | ~~In the coming weeks we'll be designing an open hardware interface for interfacing to M1 serial ports, and more (supporting other debug pinsets on Apple devices, as well as UARTs on other devices such as certain Android phones, etc). Stay tuned for more information. Established kernel developers who want to get an early prototype when they become available should contact [marcan](mailto:marcan@marcan.st).~~ 96 | 97 | Note: This is indefinitely backburnered and mostly rendered obsolete by USB support in m1n1/hypervisor. 98 | -------------------------------------------------------------------------------- /docs/fw/macho-boot-protocol.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: MachO Boot Protocol 3 | summary: 4 | Boot protocol used by Apple Silicon devices when booting m1n1 as a 5 | MachO binary 6 | --- 7 | 8 | ## Boot protocol 9 | 10 | ### Memory 11 | 12 | Memory starts at 0x8_0000_0000. 13 | 14 | The memory when iBoot calls us looks like this: 15 | 16 | ``` 17 | +==========================+ <-- bottom of RAM (0x8_0000_0000) 18 | | Coprocessor carveouts, | 19 | | iBoot stuff, etc. | 20 | +==========================+ <-- boot_args->phys_base, VM = boot_args->virt_base 21 | | kASLR slide gap (<32MiB) | 22 | +==========================+ 23 | | Device Tree (ADT) | /chosen/memory-map.DeviceTree 24 | +--------------------------+ 25 | | Trust Cache | /chosen/memory-map.TrustCache 26 | +==========================+ <-- Mach-O lowest vmaddr mapped to here (+ slide!) 27 | | Mach-O base (header) | /chosen/memory-map.Kernel-mach_header 28 | +-- --+ 29 | | Mach-O segments... | /chosen/memory-map.Kernel-(segment ID)... 30 | +-- --+ 31 | | m1n1: Payload region | /chosen/memory-map.Kernel-PYLD (64MB currently) 32 | +==========================+ 33 | | SEP Firmware | /chosen/memory-map.SEPFW 34 | +--------------------------+ <-- boot_args 35 | | BootArgs | /chosen/memory-map.BootArgs 36 | +==========================+ <-- boot_args->top_of_kdata 37 | | | 38 | | (Free memory) | 39 | | (incl. iBoot trampoline) | 40 | | | 41 | +==========================+ <-- boot_args->top_of_kdata + boot_args->mem_size 42 | | Video memory, SEP | 43 | | carveout, and more | 44 | +==========================+ <-- 0x8_0000_0000 + boot_args.mem_size_actual 45 | ``` 46 | 47 | ### About pointers 48 | 49 | There are four kinds of addresses you might come across: 50 | 51 | * Physical addresses 52 | * m1n1 unrelocated offsets (relative to 0) 53 | * Mach-O virtual addresses 54 | * kASLR-slid virtual addresses 55 | 56 | Physical addresses are the only thing you should care about. 57 | 58 | m1n1 unrelocated offsets are only used by the m1n1 startup code prior to running relocations, and 59 | the related linker script info. The C environment is properly position-adjusted after those, so you 60 | should never see them there. However, if you're debugging m1n1 and printing pointers, and want to 61 | map those back to the raw ELF file, you will have to subtract the m1n1 load offset to get the 62 | unrelocated offset. 63 | 64 | Virtual addresses have no significance; this is just used because Mach-O has no concept of physical 65 | addresses, and the whole set-up assumes Darwin will map itself in a certain way. For our purposes, 66 | a vaddr is just `paddr + ba.virt_base - ba.phys_base`. m1n1 does not use top-half virtual addresses, 67 | and Linux does its own thing that has nothing to do with Darwin. 68 | 69 | In addition, there are two virtual address maps: whatever's in the Mach-O, and the pointers iBoot 70 | actually passes us. The latter is offset by the kASLR slide, which also affects vaddrs. This makes 71 | everything more confusing. 72 | 73 | Thus, for any Darwin kASLR-slid virtual pointer received from iBoot, we compute 74 | `vaddr - ba.virt_base + ba.phys_base` and that's all we care about; conversely, only the linker 75 | script (and the Mach-O header generation within) cares about Mach-O unslid virtual addresses. 76 | If you're writing m1n1 code you will never see those. Really, don't try to think about it too much, 77 | you'll just confuse yourself. 78 | 79 | ### Entry 80 | 81 | iBoot enters us at the entrypoint defined in the (ridiculous) Mach-O data structure as an unslid 82 | vaddr. Entry is with the MMU off. `x0` points to the [boot_args structure](https://github.com/AsahiLinux/m1n1/blob/main/src/xnuboot.h). 83 | 84 | In addition, iBoot sets and locks the RVBAR of the boot CPU to be the top of the page that the 85 | entrypoint lives in. This cannot be changed after boot, and thus this address will always have 86 | a special significance and have to be treated as resident bootloader code. Right now the practical 87 | significance is unclear, but presumably after a resume from deep sleep, the boot CPU will start 88 | executing code here. Note that this does not lock the actual CPU vectors (that can be changed 89 | freely in `VBAR_EL2`) nor does it affect the RVBAR of secondary CPUs (which can be freely set prior 90 | to issuing the start command). 91 | 92 | ## m1n1 memory layout 93 | 94 | When running m1n1 initially, the relevant memory looks like this: 95 | 96 | ``` 97 | +==========================+ 98 | | Device Tree (ADT) | /chosen/memory-map.DeviceTree 99 | +--------------------------+ 100 | | Trust Cache | /chosen/memory-map.TrustCache 101 | +==========================+ <-- _base 102 | | Mach-O header | /chosen/memory-map.Kernel-_HDR 103 | +-- --+ <-- _text_start, _vectors_start 104 | | m1n1 .text | /chosen/memory-map.Kernel-TEXT 105 | +-- --+ 106 | | m1n1 .rodata | /chosen/memory-map.Kernel-RODA 107 | +-- --+ <-- _data_start 108 | | m1n1 .data & .bss | /chosen/memory-map.Kernel-DATA 109 | +-- --+ <-- _payload_start 110 | | m1n1 Payload region | /chosen/memory-map.Kernel-PYLD (64MB currently) 111 | +==========================+ <-- _payload_end 112 | | SEP Firmware | /chosen/memory-map.SEPFW 113 | +--------------------------+ <-- boot_args 114 | | BootArgs | /chosen/memory-map.BootArgs 115 | +==========================+ <-- boot_args->top_of_kdata, heap_base 116 | | m1n1 heapblock | (>=128MB) 117 | +-- --+ <-- ProxyUtils.heap_base (m1n1 heapblock in use end + 128MB) 118 | | Python heap | (1 GiB) 119 | +-- --+ 120 | | (Unused memory) | 121 | +==========================+ <-- boot_args->top_of_kdata + boot_args->mem_size 122 | ``` 123 | 124 | m1n1's heapblock area (used as a backend for malloc, and for loading payloads) starts at `boot_args.top_of_kdata` and has no bound at this time. When using proxyclient, ProxyUtils will set up a Python heap base 128MiB above whatever the current heapblock top is, which means m1n1 can use up to 128MiB of additional memory before it runs into Python-side structures. Note that fresh executions of the Python side will re-initialize their heap starting at whatever the current m1n1 end is, so e.g. m1n1-side memory leaks on each Python execution are not an immediate problem until you run out of total RAM. 125 | 126 | When chainloading another Mach-O payload, the next stage overwrites m1n1 in-place. The chainload.py Mach-O loading code skips the padding end of the m1n1 payload section (except 4 zero bytes as a marker), so SEP firmware and BootArgs follow directly in what would've otherwise been the m1n1 payload area, saving RAM. Relocating the SEP firmware is optional; if it is not enabled, it remains where it is, and top_of_kdata is kept untouched. Unless m1n1 grows by more than the size of its payload region, this should be safe. 127 | -------------------------------------------------------------------------------- /docs/hw/peripherals/ace3.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: ACE3 3 | --- 4 | 5 | ACE3 is the new USB-C / USB-PD controller in M3 products. It has a sn201202x compatible value in the ADT. 6 | 7 | ## SPMI registers 8 | 9 | Unlike its predecessors, the ACE3 is accessed via SPMI rather than I2C. However the underlying interface hasn't changed, a thin transport layer allows accessing what were previously I2C registers (which we'll refer to as "logical registers") through the SPMI registers. 10 | 11 | - **0x00 (logical register address) [RW]:** writing `0x80 | logical_register_address` to this SPMI register triggers a logical register selection process. Once finished, the SPMI registers below are updated, the MSB in this register is cleared and an interrupt is asserted (see "Interrupts"). 12 | 13 | Note 1: The "register 0 write" SPMI command can also be used (the 7-bit value is completed with MSB=1 and will therefore trigger a logical register selection). In fact selections triggered using this command appear to have stricter semantics and seem to be needed in some cases, see "Dual-slave operation" below. 14 | Note 2: Writes with MSB=0 will update the register's value, but won't trigger a selection. 15 | 16 | - **0x1F (logical register size) [RO]:** when a logical register is selected, its size in bytes is written here by the hardware. 17 | 18 | - **0x20..0x5F (logical register data) [RW]:** when a logical register is selected, its data is read, zero-padded and written here by the hardware. Writes anywhere in this area cause the area's contents to be written (truncated as appropriate) to the last selected logical register. 19 | 20 | Note 1: There doesn't seem to be a way to monitor the completion of a logical register write, but it seems to block further selections. 21 | Note 2: There doesn't seem to be a way to hold off the logical register write until later, so only logical registers of size ≤ 16 can be written atomically. 22 | 23 | Other observations: 24 | 25 | - Only the first 0x60 addresses are mapped, but address bits 7 and higher seem to be ignored, causing the block to be aliased every 0x80 bytes. Many consecutive SPMI registers can be accessed at once using extended (or extended long) commands. 26 | 27 | - The device also supports the sleep and wakeup SPMI commands, and it's sleeping at boot. When sleeping, writes to SPMI registers are ACKed but ignored. It takes some time for the device to wake up after receiving the command (see also "Interrupts"). Even while in sleeping state, the ACE3 can respond to events (such as plugging a cable) and send the appropriate interrupts. 28 | 29 | ## Interrupts 30 | 31 | Interrupts are no longer delivered through a GPIO pin; instead they are delivered through the SPMI controller, which thus also acts as an interrupt controller. I don't know how this works at the bus level, maybe delivery happens via a master write command? See the SPMI controller documentation for more info on how to receive these "SPMI interrupts". 32 | 33 | The ADT lists 3 odd interrupts for each ACE3; we call the smaller of those `BASE`. 34 | 35 | - [`BASE + 0`] **Logical interrupts** (marked as type 0 in the ADT): Asserted when an unacked (logical register 0x14) and unmasked (logical register 0x16) interrupt becomes pending. This serves the same purpose as the previous GPIO pin, however SPMI interrupts have edge/MSI semantics: each (unmasked) interrupt causes `BASE + 0` to be asserted once (even if there were other unacked+unmasked interrupts already) and not asserted again until ACKed. 36 | 37 | - [`BASE + 2`] **Selection complete?** (doesn't appear in the ADT): Asserted each time a logical register selection completes. 38 | 39 | - [`BASE + 4`] (doesn't appear in the ADT): Never observed in the wild. 40 | 41 | - [`BASE + 6`] **Sleep complete?** (marked as type 2 in the ADT): Asserted when an SPMI sleep command is sent to the slave, even if the slave was already in that state. Possibly to indicate when the operation completes? 42 | 43 | - [`BASE + 8`] **Wakeup complete?** (marked as type 3 in the ADT): Asserted when an SPMI wakeup command is sent to the slave, even if the slave was already in that state. Possibly to indicate when the operation completes? But the registers become writable much much earlier than receipt of the interrupt, so it may be something else. 44 | 45 | The reason for this spacing of 2 in between (possible) interrupts is to support the dual-slave operation outlined below. 46 | 47 | ## Dual-slave operation 48 | 49 | Each ACE3 seems to have two SPMI slaves at the bus: one listening at the address listed in the ADT (even), presumably for use by the AP, and another listening at the address immediately after (odd), presumably for use by *something else* (the SMC, perhaps). This seems to allow the ACE3 to be accessed by two masters without fighting over the state of the interface (SPMI registers, interrupts, etc). In particular: 50 | 51 | - Each slave holds its own selection, even though they operate over the same logical registers. Each slave also seems to have some sort of cache for selections, which appears to be invalidated when the "register 0 write" command is used. By contrary, using a normal write to trigger a selection uses the cache and may return stale data: for example, logical registers may appear out of sync among the two slaves, and command execution (which involves writing a command to logical register 8) may appear to not finish, since subsequent reads of register 8 return the cached command rather than the result of the execution. Logical register writes are always committed immediately on writes to the 0x20..0x5F area, regardless how the selection was made. 52 | 53 | - Each slave holds its own interrupt state: the "AP slave" uses register 0x14 for pending interrupts, register 0x16 for unmasked interrupts and register 0x18 to ACK interrupts. The other slave uses the same registers but shifted by +1 (0x15 for pending, 0x17 for unmasked, 0x19 for ACK). Drivers should be careful not to touch these (along with any other state owned by the secondary slave). 54 | 55 | - Each slave holds its own sleeping state, but the ACE3 is only put to sleep if both slaves are in sleeping state. In this state, both slaves ignore writes to SPMI registers (but still ACK the commands). If at least one of the slaves is woken up, this doesn't happen (neither slave ignores writes). Whatever is using the secondary slave makes sure to only wake up the slave temporarily, perform the commands it needs to, and put it to sleep again. The "AP slave" is sleeping at boot. 56 | 57 | - While the "AP slave" uses the SPMI interrupts documented above, the other slave uses the same interrupts but shifted by -1 (*not* +1). So for example selecting a register in the secondary slave causes a `BASE + 1` interrupt, the triggering of one of the interrupts in register 0x17 causes a `BASE - 1` interrupt, sending a sleep command to the secondary slave causes a `BASE + 5` interrupt and so on. 58 | 59 | The secondary slave triggers abundant interrupts when e.g. plugging in a cable, making it clear something else is actually operating it. The fact that these interrupts make it to our SPMI controller hints at the interrupt delivery mechanism not being a "master write" command, since that's addressed to a single master and presumably the other user isn't using our SPMI controller but a separate SPMI master. 60 | -------------------------------------------------------------------------------- /docs/project/faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: FAQ 3 | --- 4 | 5 | ## When will Asahi Linux be "done"? 6 | 7 | → ["When will Asahi Linux be done?"](when-will-asahi-be-done.md) 8 | 9 | ## Does $thing work yet? 10 | 11 | → [Feature Support](../platform/feature-support/overview.md) 12 | 13 | ## How do I install it? 14 | 15 | See the website for instructions: https://asahilinux.org/ 16 | 17 | ## Can I install Asahi Linux from an external macOS installation? 18 | 19 | [No](https://github.com/AsahiLinux/asahi-installer/issues/250). It is necessary to keep an *internal* macOS installation to install Asahi Linux, update/repair m1n1 and resize active Asahi Linux installations. 20 | 21 | ## How do I uninstall / clean up a failed installation? 22 | 23 | There is no automated uninstaller, but see [Partitioning cheatsheet](../sw/partitioning-cheatsheet.md) to learn how to delete the partitions manually. 24 | 25 | ## Can I dual boot Asahi Linux? 26 | 27 | Yes! The Installer already configures dual booting. You would need to go out of your way to erase macOS, and it's *not recommended* to do so. 28 | 29 | ## Can I boot Asahi Linux purely from an USB drive? 30 | 31 | No, unfortunately not. Apple Silicon hardware does not support booting from USB storage, at all. It is completely physically impossible to boot from USB while making no changes to internal storage. This is by design, for security reasons. 32 | 33 | ## I have ~40GB of free disk space but the installer says that's not enough! 34 | 35 | The installer always leaves 38GB of disk space *free* for macOS upgrades to work. That means you need enough disk space for the new OS *on top of* those 38GB. 36 | 37 | If you want to skip this check, enable expert mode at the beginning. Keep in mind that you might be unable to update macOS if you do not have enough free disk space left over! 38 | 39 | ## Can I install Asahi Linux on an iPad? 40 | 41 | No, iPads (and iPhones and other devices) do not support running custom OS kernels. Due to the system design, even if one were to achieve arbitrary code execution in userspace (say, via a jailbreak), that would not help with running a Linux kernel. A boot ROM exploit _might_ help, should one exist, but supporting these devices is not a project goal for Asahi Linux. 42 | 43 | ## Common problems 44 | 45 | ### I get an error during the macOS resize step of the installer 46 | 47 | Read the error message carefully. It'll be one of these: 48 | 49 | #### "Storage system verify or repair failed" 50 | 51 | You have existing APFS filesystem corruption (not caused by the installer) that is preventing a successful resize of your macOS partition. See [this issue](https://github.com/AsahiLinux/asahi-installer/issues/81) for more information and fix steps. 52 | 53 | #### "Your APFS Container resize request is below the APFS-system-imposed minimal container size (perhaps caused by APFS Snapshot usage by Time Machine)" 54 | 55 | As the message implies, this is caused by Time Machine snapshots taking up "free" space on your disk. See [this issue](https://github.com/AsahiLinux/asahi-installer/issues/86) for more information and fix steps. 56 | 57 | ### Disk Utility doesn't work for me after installing / for uninstalling / any other time! 58 | 59 | Don't use Disk Utility, it's broken and only works for really simple partition setups. See [Partitioning cheatsheet](../sw/partitioning-cheatsheet.md) to learn how to manage partitions with the command line instead. 60 | 61 | ## Do I need to reinstall to get new features / updates? 62 | 63 | No! Just upgrade your system using `dnf upgrade`. Kernel updates will require a reboot. Consider a tool like `needrestart` to determine if there are any outdated services or an outdated kernel running. 64 | 65 | ## Two of the keys on my keyboard are swapped 66 | 67 | This is a property inherent to some apple keyboards. Please read https://wiki.archlinux.org/title/Apple_Keyboard to learn how to fix this issue. 68 | 69 | ## My system keeps booting into macOS, not Asahi! 70 | 71 | macOS may be set as your default boot medium. Enter One True Recovery (1TR) by shutting down and powering on while holding the power button for 15 seconds. You can either select Asahi Linux while holding the Option key or enter the Settings page, unlock macOS, then set the bootloader to reboot into Asahi. 72 | 73 | ## I am having performance/tearing/feature issues on Xorg 74 | 75 | Please stop using Xorg and switch to Wayland. Xorg as a primary display server is all but unmaintained, and its architecture is at odds with modern display hardware as is present on Apple Silicon devices. We do not have the development bandwidth to spend time on Xorg and its idiosyncrasies. Distributions and downstream desktop environments are already dropping Xorg support. You are free to keep using it if you wish, but we will not be supporting it beyond "it starts and displays a basic desktop correctly". 76 | 77 | The [Fedora Asahi Remix](https://asahilinux.org/fedora/) (the flagship reference distribution) is Wayland-only out of the box for this reason. 78 | 79 | ## Screen reader software or other accessibility features are not working by default 80 | 81 | As of February 2025, accessibility features were enabled by default, and should soon after be available on the lock screen after installation. This was implemented in the following [https://pagure.io/fedora-asahi/calamares-firstboot-config/pull-request/5](https://pagure.io/fedora-asahi/calamares-firstboot-config/pull-request/5). 82 | 83 | ## Screen recording is slow 84 | 85 | Make sure you have the GPU drivers installed. If screen recording is still slow, you are probably using a screen recording app or compositor that directly reads out or copies GPU display surfaces from the CPU. GPU display surfaces are optimized for GPU access, and direct CPU readout is unlikely to even work at all once we switch to compressed primary display framebuffers. In other words, approaches such as [kmsgrab](http://underpop.online.fr/f/ffmpeg/help/kmsgrab.htm.gz) are fundamentally flawed, will perform poorly, and will stop working entirely in the future. You should use a display compositor and recording app that correctly share GPU textures and then optimize the read-out for CPU encoding. KDE's KWin and OBS are known to work well together, as well as KDE's standalone Spectacle screenshot/recording app. 86 | 87 | ## Chromium / VS Code / Slack / Discord / some other Electron app or Chrome-based browser stopped rendering after an update. 88 | This is an [upstream Chromium bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1442633) affecting all Chromium-based frameworks such as [Electron](https://github.com/electron/electron/issues/40366). You have to manually delete your shader cache (e.g. `~/.config/Slack/GPUCache`). We can't do anything about it until the fix is backported/released to users. 89 | 90 | ## Start up automatically after a power failure 91 | 92 | This configuration is available at `/sys/bus/platform/devices/macsmc-reboot/ac_power_mode`. Valid options are `off` and `restore`, which is equivalent to the toggle in System Settings on macOS. It is not possible to set the machine to power on unconditionally when power is connected. 93 | 94 | ## Wake for network access (WoL/WoWLAN) 95 | 96 | - Wake on LAN does not work. The BCM57762 gigabit Ethernet controller supports WoL via magic packets, it can be enabled with `ethtool -s REPLACE_WITH_YOUR_INTERFACE wol g`, but the machine does not wake up when it receives magic packets. 97 | - Wake on Wireless LAN is untested. 98 | 99 | ## Lights Out Management (LOM) 100 | 101 | LOM is only supported on devices with [10Gbps Ethernet cards](https://support.apple.com/guide/deployment/dep580cf25bc/web) enrolled in a mobile device management (MDM) solution. This feature has not yet been reverse engineered. 102 | -------------------------------------------------------------------------------- /docs/sw/m1n1-hypervisor.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: m1n1 Hypervisor 3 | --- 4 | 5 | # Running macOS under the m1n1 hypervisor 6 | 7 | You can run either a development kernel obtained from Apple, in which case you will have debug symbols, or use the stock kernel found in a macOS install. 8 | 9 | ## Preparation 10 | 11 | You can use either your existing macOS install, or alternatively install a second copy of macOS. 12 | 13 | To install a second copy of macOS you will need to complete a couple of steps: 14 | 15 | 1. Create a second Volume on your macOS partition: 16 | 17 | diskutil apfs addVolume disk4 APFS macOSTest -mountpoint /Volumes/macOSTest 18 | 19 | Change disk4 and volume name (i.e `macOSTest`) for your particular system/preferences. 20 | _Note: Don't make this a system role or it will mess with your existing system (no valid users in 1TR)_. 21 | 22 | 2. Download and install macOS. To download a specific version of macOS installer you can use the command: 23 | 24 | softwareupdate --fetch-full-installer --full-installer-version 12.3 25 | 26 | Substitute `12.3` for whichever version you require. The installer will be found in the Applications folder. Copy it out of here if you want to save it, otherwise it deletes itself once you have installed once. 27 | 28 | Unfortunately, Apple's CDN only keeps the full-installer package for a limited number of version, and doesn't have 12.3 anymore. 29 | _Note: we are now at firmware version 13.5, which is available normally. You don't need to install 12.3._ 30 | 31 | ### Using archived InstallAssistant.pkg 32 | 33 | The Montery 12.3 InstallAssistant.pkg has been archived [here](https://archive.org/details/12.3-21-e-230-release), but trying to install by double-clicking installs an online version of the `Install macOS Monterey.app`, with a file size of about 40MB. When that file is run, it will install the latest version of macOS. However, installing it via the command line appears to do the correct thing: 34 | 35 | sudo installer -pkg 12.3\ 21E230\ \(Release\).pkg -target / 36 | 37 | 38 | Check that `Install macOS Monterey.app` in the `applications` folder is ~12GB. 39 | 40 | 41 | ## Getting the macOS development kernel and creating the kernelcache 42 | 43 | 1. Create a macOS developer account (requires an iCloud account). 44 | 2. Download the Mac OS Kernel Debug Kit (KDK) from Apple [here](https://developer.apple.com/download/more/). It should match your Mac OS version. 45 | 3. Install the KDK into Mac OS. The KDK will be installed to `/Library/Developer/KDKs/KDK__.kdk` 46 | 4. Change to the kernels directory: 47 | 48 | cd /Library/Developer/KDKs/KDK__.kdk/System/Library/Kernels 49 | 50 | 5. Switch into the KDK folder and run the following command: 51 | 52 | kmutil create -z -n boot -a arm64e -B ~/dev.kc.macho -V development \ 53 | -k kernel.development.t8101 \ 54 | -r /System/Library/Extensions/ \ 55 | -r /System/Library/DriverExtensions \ 56 | -x $(kmutil inspect -V release --no-header | grep -v "SEPHiber" | awk '{print " -b "$1; }') 57 | 58 | `-B` designates the output file, our kernel cache is written to `dev.kc.macho` in the home directory 59 | 60 | `-k` must match a kernel in the kernels directory 61 | 62 | ## Preparing the macOS Volume by disabling security features 63 | 64 | 0. Set the macOS Volume as a default boot target. 65 | 1. Start into 1tr and start a terminal. 66 | 2. Disable most security feature in the boot policy: `bputil -nkcas`; use `diskutil info [disk name]` to get UUID. 67 | 3. Disable SIP (bputil resets it): `csrutil disable`. 68 | 4. Install [m1n1](m1n1-user-guide.md) as custom boot object: 69 | 70 | kmutil configure-boot \ 71 | -c build/m1n1.bin \ 72 | --raw \ 73 | --entry-point 2048 \ 74 | --lowest-virtual-address 0 \ 75 | -v /Volumes/macOSTest 76 | 77 | ## Starting the development kernel under the m1n1 hypervisor 78 | 79 | 1. Copy the kernelcache to your development machine. 80 | 2. Copy the debug DWARF from `/Library/Developer/KDKs/KDK__.kdk/System/Library/Kernels/kernel.development.t8101.dSYM/Contents/Resources/DWARF/kernel.development.t8101` 81 | 3. To start macOS with the m1n1 hypervisor, run: 82 | 83 | python3 proxyclient/tools/run_guest.py \ 84 | -s \ 85 | \ 86 | -- "debug=0x14e serial=3 apcie=0xfffffffe -enable-kprintf-spam wdt=-1 clpc=0" 87 | 88 | Note: t8101 files (both kernel and dwarf symbols) are available starting with KDK for macOS 11.3. Marcan streams on booting macOs with hypervisor were done with 11.3. 89 | These notes have also been validated with macOS 11.5.2 and can get to login with WiFi network on a MacBook Air: 90 | 91 | - Kernel version: 92 | ``` 93 | $ uname -a 94 | > Darwin MacBook-Air.home 20.6.0 Darwin Kernel Version 20.6.0: Wed Jun 23 00:26:27 PDT 2021; root:xnu-7195.141.2~5/RELEASE_ARM64_T8101 arm64 95 | ``` 96 | - macOS version: 97 | ``` 98 | $ sw_vers 99 | > ProductName: macOS / ProductVersion: 11.5.2 / BuildVersion: 20G95 100 | ``` 101 | 102 | If you see the apple logo (rainbow version) and not the progress bar, this means you probably had a macOS panic early in the boot process. This can come from a mismatch of macOS version between the kernel cache (kernel + extensions) and the macOS root FS. 103 | To figure out where the boot process is stuck, you can start a serial utility like minicom/picocom and the like, with 115200 baud rate (something like `picocom -b 115200 /dev/ttyACM1`). 104 | Be patient when you are booting with one cpu and the hypervisor. Depending on what you are tracing, it is slower than normal and it is expected. 105 | 106 | Here are some numbers from some experiment with macOS `11.5.2` and m1n1 version commit `bd5211909e36944cb376d66c909544ad23c203bc`: 107 | - From run_guest command launched (`t0`) to start loading kernel: 9s. 108 | - From `t0` to login screen (without keyboard nor mouse cursor moving first): around 2min. 109 | - With keyboard and mouse cursor moving: around 2min35s. 110 | - From password entered to desktop and menu bar: around +2min. 111 | 112 | ## Running the stock macOS kernel from a macOS install 113 | 114 | 1. Boot into macOS. 115 | 2. Find the `kernelcache`, it is at `/System/Volumes/Preboot/(UUID)/boot/(long hash)/System/Library/Caches/com.apple.kernelcaches/kernelcache` 116 | 3. Make a copy of this file somewhere. 117 | 4. Get (or build) a copy of img4tool (https://github.com/tihmstar/img4tool). 118 | 5. Extract the im4p image: 119 | 120 | img4tool -e -p out.im4p kernelcache 121 | 122 | 6. Extract the machO from the im4p: 123 | 124 | img4tool -e -o kernel.macho out.im4p 125 | 126 | 7. You can now run macOS in a similar manner as shown above (just no debug DWARF): 127 | 128 | python3 proxyclient/tools/run_guest.py \ 129 | \ 130 | -- "debug=0x14e serial=3 apcie=0xfffffffe -enable-kprintf-spam wdt=-1 clpc=0" 131 | 132 | ## Updating your m1n1 hypervisor tree 133 | 134 | The hypervisor/m1n1 ABI is *not* stable. If you have installed a fresh m1n1 build as above, you can use `run_guest.py` directly to save some time. However, as soon as you update your m1n1 git tree, you *must* build the updated m1n1 and run 135 | ``` 136 | python tools/chainload.py -r ../build/m1n1.bin 137 | ``` 138 | before `run_guest.py`, to make sure the ABI is synced. Failure to do this will lead to random errors/crashes due to ABI mismatches. 139 | 140 | ## Using GDB/LLDB 141 | 142 | `gdbserver` command starts the server implementation that can be connected to GDB or LLDB. LLDB is more recommended because it supports pointer authentication and Darwin kernel dyld. 143 | 144 | You need to load kernel extensions to get symbols on LLDB. The below shell script generates `target.lldb`, a convenient LLDB script that sets the target and loads kernel extensions: 145 | 146 | ```sh 147 | echo target create -s kernel.development.t8101.dSYM kernel.development.t8101 > target.lldb 148 | for k in $(find Extensions); do [ "$(file -b --mime-type $k)" != application/x-mach-binary ] || printf 'image add %q\n' $k; done >> target.lldb 149 | ``` 150 | 151 | The following commands for LLDB loads the generated script and connects to m1n1: 152 | ``` 153 | command source -e false target.lldb 154 | process connect unix-connect:///tmp/.m1n1-unix 155 | ``` 156 | 157 | Do not run hypervisor console commands interfering with GDB/LLDB, or they will be out-of-sync. For example, do not edit breakpoints from both of hypervisor console and GDB/LLDB at the same time. 158 | 159 | # Sources 160 | Source for the kernelcache creation: [https://kernelshaman.blogspot.com/2021/02/building-xnu-for-macos-112-intel-apple.html](https://kernelshaman.blogspot.com/2021/02/building-xnu-for-macos-112-intel-apple.html) 161 | -------------------------------------------------------------------------------- /docs/hw/peripherals/camera.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Camera and Image Signal Processor 3 | --- 4 | 5 | 6 | # ISP 7 | This information is based on Macbook Pro M1 2020 ISP. It may differ for other devices. 8 | 9 | ## Sensor Type -> ISP Version 10 | 11 | | Sensor Type | ISP Version | 12 | |--- |--- | 13 | | 0xee | 0xf | 14 | | 0x54 | 0xb | 15 | | 0x55 | 0xb | 16 | | 0x56 | 0xb | 17 | | 0x57 | 0xb | 18 | | 0xe4 | 0xb | 19 | | 0xe5 | 0xb | 20 | | 0xe0 | 0xb | 21 | | 0xe1 | 0xb | 22 | | 0xe2 | 0xb | 23 | | 0xe3 | 0xb | 24 | | 0x1 | 0xb | 25 | | 0x2 | 0xb | 26 | | 0x3 | 0xb | 27 | | 0xe8 | 0xc | 28 | | 0xe7 | 0xc | 29 | | 0xe9 | 0xc | 30 | | 0xea | 0xc | 31 | | 0x1a | 0xc | 32 | | 0x1b | 0xc | 33 | | 0xb | 0xb | 34 | | 0xc | 0xb | 35 | | 0xf5 | 0xb | 36 | | 0xd | 0xc | 37 | | 0xe | 0xc | 38 | | 0x13 | 0xc | 39 | | 0x14 | 0xc | 40 | | 0x15 | 0xc | 41 | | 0x16 | 0xc | 42 | | 0x9a | 0xc | 43 | | 0x5 | 0xc | 44 | | 0x6 | 0xc | 45 | | 0x7 | 0xc | 46 | | 0x18 | 0xb | 47 | | 0x19 | 0xb | 48 | | 0x1c | 0xf | 49 | | 0x1d | 0xf | 50 | ## Registers 51 | 52 | - ISP registers (regs[0]): Depending on chip revision different registers are used. 53 | 54 | | Register Name | ISP Version | ISP Revision? | Offset | Notes | 55 | |--- |--- |--- |--- |--- | 56 | | ISP_REVISION | 0xF | N/A | 0x1800000 | 31:0 bits are used.
([31:0] == 0x1) => 0x15a
([31:0] != 0x1001) => 0x15b | 57 | | | 0xC | N/A | 0x1800000 | 31:0 bits are used.
([31:0] == 0x90) => 0x14a
([31:0] != 0x1090) => 0x14b
([31:0] == 0x3091) => 0x14c | 58 | | | 0xB | N/A | 0x1800000 | 31:0 bits are used.
([31:0] == 0x90) => 0x13a
([31:0] != 0x3091) => 0x13c | 59 | |--- |--- |--- |--- |--- | 60 | | SENSOR_REF_CLOCK0 | 0xF | != 0x15b | 0x24c41f0 | Sensor Ref Clock 0 | 61 | | | 0xF | == 0x15b | 0x24c41f4 | Sensor Ref Clock 0 | 62 | | | 0xC | != 0x14c | 0x24c41d0 | Sensor Ref Clock 0 | 63 | | | 0xC | == 0x14c | 0x2104190 | Sensor Ref Clock 0 | 64 | | | Other | * | 0x2104190 | Sensor Ref Clock 0 | 65 | | SENSOR_REF_CLOCK1 | 0xF | != 0x15b | 0x24c41f4 | Sensor Ref Clock 1 | 66 | | | 0xF | == 0x15b | 0x24c41f8 | Sensor Ref Clock 1 | 67 | | | 0xC | != 0x14c | 0x24c41d4 | Sensor Ref Clock 1 | 68 | | | 0xC | == 0x14c | 0x2104194 | Sensor Ref Clock 1 | 69 | | | Other | * | 0x2104194 | Sensor Ref Clock 1 | 70 | | SENSOR_REF_CLOCK2 | 0xF | != 0x15b | 0x24c41f8 | Sensor Ref Clock 2 | 71 | | | 0xF | == 0x15b | 0x24c41fc | Sensor Ref Clock 2 | 72 | | | 0xC | != 0x14c | 0x24c41d8 | Sensor Ref Clock 2 | 73 | | | 0xC | == 0x14c | 0x2104198 | Sensor Ref Clock 2 | 74 | | | Other | * | 0x2104198 | Sensor Ref Clock 2 | 75 | | SENSOR_REF_CLOCK3 | 0xF | != 0x15b | 0x24c41fc | Sensor Ref Clock 3 | 76 | | | 0xF | == 0x15b | 0x24c4200 | Sensor Ref Clock 3 | 77 | | | 0xC | != 0x14c | 0x24c41dc | Sensor Ref Clock 3 | 78 | | | 0xC | == 0x14c | 0x210419c | Sensor Ref Clock 3 | 79 | |--- |--- |--- |--- |--- | 80 | | POWER_ON? | 0xF | * | 0x24a0080 | Set to 0x1 during power on | 81 | | POWER_ON? | 0xC | != 0x14c | 0x24a0080 | Set to 0x1 during power on | 82 | | POWER_ON? | Other | * | 0x20e0080 | Set to 0x1 during power on | 83 | |--- |--- |--- |--- |--- | 84 | | UNKNOWN0 | 0xF | * | 0x24c41d0 | | 85 | | | 0xC | != 0x14c | 0x24c41b0 | | 86 | | | Other | Other | 0x2104170 | | 87 | | UNKNOWN1 | 0xF | * | 0x24c41d4 | | 88 | | | 0xC | != 0x14c | 0x24c41b4 | | 89 | | | Other | Other | 0x2104174 | | 90 | | UNKNOWN2 | 0xF | * | 0x24c41d8 | | 91 | | | 0xC | != 0x14c | 0x24c41b8 | | 92 | | | Other | Other | 0x2104178 | | 93 | | UNKNOWN3 | 0xF | * | 0x24c41dc | | 94 | | | 0xC | != 0x14c | 0x24c41bc | | 95 | | | Other | Other | 0x210417c | | 96 | | UNKNOWN4 | 0xF | * | 0x24c41e0 | | 97 | | | 0xC | != 0x14c | 0x24c41c0 | | 98 | | | Other | Other | 0x2104180 | | 99 | | UNKNOWN5 | 0xF | * | 0x24c41e4 | | 100 | | | 0xC | != 0x14c | 0x24c41c4 | | 101 | | | Other | Other | 0x2104184 | | 102 | | UNKNOWN6 | 0xF | * | 0x24c41e8 | | 103 | | | 0xC | != 0x14c | 0x24c41c8 | | 104 | | | Other | Other | 0x2104188 | | 105 | | UNKNOWN7 | 0xF | * | 0x24c41ec | | 106 | | | 0xC | != 0x14c | 0x24c41cc | | 107 | | | 0xC | * | 0x210418c | | 108 | | | 0xB | * | 0x188 | | 109 | | SMBUS_REG_MTXFIFO0 | * | * | 0x2110000 | I2C Channel 0 110 | | SMBUS_REG_MRXFIFO0 | * | * | 0x2110004 | 111 | | SMBUS_REG_UNKNOWN0_1 | * | * | 0x2110008 | 112 | | SMBUS_REG_UNKNOWN0_2* | * | * | 0x211000c | 113 | | SMBUS_REG_UNKNOWN0_3* | * | * | 0x2110010 | 114 | | SMBUS_REG_SMSTA0 | * | * | 0x2110014 | | 115 | | SMBUS_REG_UNKNOWN0_4 | * | * | 0x2110018 | 116 | | SMBUS_REG_CTL0 | * | * | 0x211001c | 117 | | SMBUS_REG_UNKNOWN0_5 | * | * | 0x2110030 | 118 | | SMBUS_REG_UNKNOWN0_6 | * | * | 0x2110034 | 119 | | SMBUS_REG_UNKNOWN0_7 | * | * | 0x211003c | 120 | |--- |--- |--- |--- |--- | 121 | | SMBUS_REG_MTXFIFO1 | * | * | 0x2111000 | I2C Channel 1 122 | | SMBUS_REG_MRXFIFO1 | * | * | 0x2111004 | 123 | | SMBUS_REG_UNKNOWN1_1 | * | * | 0x2111008 | 124 | | SMBUS_REG_UNKNOWN1_2* | * | * | 0x211100c | 125 | | SMBUS_REG_UNKNOWN1_3* | * | * | 0x2111010 | 126 | | SMBUS_REG_SMSTA1 | * | * | 0x2111014 | | 127 | | SMBUS_REG_UNKNOWN1_4 | * | * | 0x2111018 | 128 | | SMBUS_REG_CTL1 | * | * | 0x211101c | 129 | | SMBUS_REG_UNKNOWN1_5 | * | * | 0x2111030 | 130 | | SMBUS_REG_UNKNOWN1_6 | * | * | 0x2111034 | 131 | | SMBUS_REG_UNKNOWN1_7 | * | * | 0x211103c | 132 | |--- |--- |--- |--- |--- | 133 | | SMBUS_REG_MTXFIFO2 | * | * | 0x2112000 | I2C Channel 2 134 | | SMBUS_REG_MRXFIFO2 | * | * | 0x2112004 | 135 | | SMBUS_REG_UNKNOWN2_1 | * | * | 0x2112008 | 136 | | SMBUS_REG_UNKNOWN2_2* | * | * | 0x211200c | 137 | | SMBUS_REG_UNKNOWN2_3* | * | * | 0x2112010 | 138 | | SMBUS_REG_SMSTA2 | * | * | 0x2112014 | | 139 | | SMBUS_REG_UNKNOWN2_4 | * | * | 0x2112018 | 140 | | SMBUS_REG_CTL2 | * | * | 0x211201c | 141 | | SMBUS_REG_UNKNOWN2_5 | * | * | 0x2112030 | 142 | | SMBUS_REG_UNKNOWN2_6 | * | * | 0x2112034 | 143 | | SMBUS_REG_UNKNOWN2_7 | * | * | 0x211203c | 144 | |--- |--- |--- |--- |--- | 145 | | SMBUS_REG_MTXFIFO3 | * | * | 0x2113000 | I2C Channel 3 146 | | SMBUS_REG_MRXFIFO3 | * | * | 0x2113004 | 147 | | SMBUS_REG_UNKNOWN3_1 | * | * | 0x2113008 | 148 | | SMBUS_REG_UNKNOWN3_2* | * | * | 0x211300c | 149 | | SMBUS_REG_UNKNOWN3_3* | * | * | 0x2113010 | 150 | | SMBUS_REG_SMSTA3 | * | * | 0x2113014 | | 151 | | SMBUS_REG_UNKNOWN3_4 | * | * | 0x2113018 | 152 | | SMBUS_REG_CTL3 | * | * | 0x211301c | 153 | | SMBUS_REG_UNKNOWN3_5 | * | * | 0x2113030 | 154 | | SMBUS_REG_UNKNOWN3_6 | * | * | 0x2113034 | 155 | | SMBUS_REG_UNKNOWN3_7 | * | * | 0x211303c | 156 | |--- |--- |--- |--- |--- | 157 | | REG_DPE_UNKNOWN0 | * | * | 0x2504000 | 158 | | REG_DPE_UNKNOWN1 | * | * | 0x2508000 | 159 | |--- |--- |--- |--- |--- | 160 | | REG_UNKNOWN | * | * | 0x1050000 | 161 | 162 | - Unknown (offset: 0x1400044) 163 | - Unknown (offset: 0x1aa801c) 164 | 165 | - PS registers (regs[1]): Depending on chip revision different register range is used. Most chip revisions seems to use 0x4000-0x4060 166 | - Unknown (offset: 0x00) 167 | - Unknown (offset: 0x08) 168 | - Unknown (offset: 0x10) 169 | - Unknown (offset: 0x18) 170 | - Unknown (offset: 0x20) 171 | - Unknown (offset: 0x28) 172 | - Unknown (offset: 0x30) 173 | - Unknown (offset: 0x38) 174 | - Unknown (offset: 0x40) 175 | - Unknown (offset: 0x328) 176 | - Unknown (offset: 0x3d8) 177 | - Unknown (offset: 0x4000) 178 | - Unknown (offset: 0x4008) 179 | - Unknown (offset: 0x4010) 180 | - Unknown (offset: 0x4018) 181 | - Unknown (offset: 0x4020) 182 | - Unknown (offset: 0x4028) 183 | - Unknown (offset: 0x4030) 184 | - Unknown (offset: 0x4038) 185 | - Unknown (offset: 0x4040) 186 | - Unknown (offset: 0x4048) 187 | - Unknown (offset: 0x4050) 188 | - Unknown (offset: 0x4058) 189 | - Unknown (offset: 0x4060) 190 | - Unknown (offset: 0x1c3e8) 191 | - Unknown (offset: 0x1c400) 192 | - Unknown (offset: 0x1c418) 193 | - SOC SPMI CSR registers (regs[2]) 194 | - Unknown (offset: 0x80a0) (Initialized as 1 << 2^(1..5)) 195 | - Unknown (offset: 0x80a4) (Value here seems to be ORed with one of following values: 0x4000000, 0x8000000, 0x1, 0x2) 196 | - Unknown (offset: 0x28) (Initialized as 0) 197 | - Unknown (offset: 0x90) (Initialized as 1) 198 | - Unknown (offset: 0x40) (Initialized as 0x4000000) 199 | 200 | - SOC SPMI0 registers (regs[3]) 201 | - Unknown (offset: 0x80a0) (Initialized as 1 << 2^(1..5)) 202 | - Unknown (offset: 0x80a4) (Value here seems to be ORed with one of following values: 0x4000000, 0x8000000, 0x1, 0x2) 203 | - Unknown (offset: 0x28) (Initialized as 0) 204 | - Unknown (offset: 0x90) (Initialized as 1) 205 | - Unknown (offset: 0x40) (Initialized as 0x4000000) 206 | 207 | - SOC SPMI1 registers (regs[4]) 208 | - Unknown (offset: 0x80a0) (Initialized as 1 << 2^(1..5)) 209 | - Unknown (offset: 0x80a4) (Value here seems to be ORed with one of following values: 0x4000000, 0x8000000, 0x1, 0x2) 210 | - Unknown (offset: 0x28) (Initialized as 0) 211 | - Unknown (offset: 0x90) (Initialized as 1) 212 | - Unknown (offset: 0x40) (Initialized as 0x4000000) 213 | 214 | 215 | 216 | -------------------------------------------------------------------------------- /docs/platform/feature-support/m3.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: M3 Series Feature Support 3 | --- 4 | 5 | This page details currently supported features on all M3 series (M3, M3 Pro, M3 Max) Apple Silicon Macs, as well as 6 | their progress towards being upstreamed. The tables herein can be interpreted as follows: 7 | 8 | * **Kernel release, *e.g.* 6.0:** the feature was incorporated upstream as of this release 9 | * **linux-asahi (kernel release):** the feature is stable, available for use in `linux-asahi`, and should be upstream by the release indicated 10 | * **linux-asahi**: the feature is (mostly) stable and available for use in Fedora Asahi Remix and in `linux-asahi` 11 | * **asahi-edge**: the feature is (mostly) stable and available for use in Fedora Asahi Remix. For historical reason it is available in the `linux-asahi-edge` package in the linux-asahi Linux distribution 12 | * **WIP**: Development work on the feature is actively progressing, however is not yet ready for wider testing, use or distribution 13 | * **TBA**: Active work on this feature is not being undertaken at this time 14 | 15 | If a feature is not ready, then there is no estimation on when it will be ready. [Please do not ask for estimations in support channels (e.g. IRC)](../../project/when-will-asahi-be-done.md). 16 | 17 | ## Table of Contents 18 | - [SoC blocks](#soc-blocks) 19 | - [M3 devices](#m3-devices) 20 | - [M3 Pro/Max devices](#m3-promax-devices) 21 | - [Notes](#notes) 22 | 23 | Note that as these machines have not been released for general availability yet, supported and missing features are predictions based on what Apple has changed 24 | on a per-SoC and per-machine basis in the past. This page will change rapidly once work begins on support for these machines. 25 | 26 | ## SoC blocks 27 | These are features/hardware blocks that are present on all devices with the given SoC. 28 | 29 | | | M3
(T8122) | M3 Pro/Max
(T603x) | 30 | |------------------|:--------------------:|:---------------------------:| 31 | | DCP | TBA | TBA | 32 | | USB2 (TB ports) | linux-asahi | linux-asahi | 33 | | USB3 (TB ports) | linux-asahi | linux-asahi | 34 | | Thunderbolt | TBA | TBA | 35 | | DP Alt Mode | WIP | WIP | 36 | | GPU | TBA | TBA | 37 | | Video Decoder | TBA | TBA | 38 | | NVMe | 5.19 | 5.19 | 39 | | PCIe | TBA | TBA | 40 | | PCIe (GE) | - | - | 41 | | cpufreq | 6.2 | 6.2 | 42 | | cpuidle | linux-asahi ([notes](#cpuidle-situation)) | linux-asahi ([notes](#cpuidle-situation)) | 43 | | Suspend/sleep | asahi-edge | asahi-edge | 44 | | Video Encoder | TBA | TBA | 45 | | ProRes Codec | TBA | TBA | 46 | | AICv3 | TBA | TBA | 47 | | DART | TBA | TBA | 48 | | PMU | TBA | TBA | 49 | | UART | 5.13 | 5.13 | 50 | | Watchdog | 5.17 | 5.17 | 51 | | I2C | 5.16 | 5.16 | 52 | | GPIO | 5.16 | 5.16 | 53 | | USB-PD | 5.16 | 5.16 | 54 | | MCA | 6.1 / 6.4 (dts) | linux-asahi | 55 | | SPI | linux-asahi | linux-asahi | 56 | | SPI NOR | linux-asahi | linux-asahi | 57 | | SMC | linux-asahi | linux-asahi | 58 | | SPMI | linux-asahi | linux-asahi | 59 | | RTC | linux-asahi | linux-asahi | 60 | | SEP | WIP | WIP | 61 | | Neural Engine | out of tree ([notes](#ane-driver)) | out of tree ([notes](#ane-driver)) | 62 | 63 | 64 | ## M3 devices 65 | | | iMac
(2023) | MacBook Pro
(14-inch, late 2023) | MacBook Air
(13” and 15” 2024) | 66 | |--------------------|:------------------:|:-----------------------------------:|:------------------------------:| 67 | | Installer | no | no | | 68 | | Devicetree | TBA | TBA | | 69 | | Main display | TBA | TBA | | 70 | | Keyboard | - | TBA | | 71 | | KB backlight | - | TBA | | 72 | | Touchpad | - | TBA | | 73 | | Brightness | TBA | TBA | | 74 | | Battery info | - | TBA | | 75 | | WiFi | TBA | TBA | | 76 | | Bluetooth | TBA | TBA | | 77 | | HDMI Out | - | TBA | - | 78 | | 3.5mm jack | TBA | TBA | | 79 | | Speakers | TBA | TBA | | 80 | | Microphones | TBA | TBA | | 81 | | Webcam | TBA | TBA | | 82 | | SD card slot | - | TBA | - | 83 | | 1Gbps Ethernet | TBA | - | - | 84 | | 10Gbps Ethernet | - | - | - | 85 | | TouchID | - | TBA | | 86 | 87 | ## M3 Pro/Max devices 88 | | | MacBook Pro
(14/16-inch, late 2023) | 89 | |--------------------|:---------------------------------:| 90 | | Installer | no | 91 | | Devicetree | TBA | 92 | | Main display | TBA | 93 | | Keyboard | linux-asahi | 94 | | KB backlight | linux-asahi | 95 | | Touchpad | linux-asahi | 96 | | Brightness | TBA | 97 | | Battery info | linux-asahi | 98 | | WiFi | TBA | 99 | | Bluetooth | TBA | 100 | | HDMI Out | TBA | 101 | | 3.5mm jack | linux-asahi | 102 | | Speakers | WIP | 103 | | Microphones | TBA | 104 | | Webcam | TBA | 105 | | SD card slot | 5.17 | 106 | | 1Gbps Ethernet | - | 107 | | 10Gbps Ethernet | - | 108 | | TouchID | TBA | 109 | 110 | Note: Many peripherals depend on DART and PCIe support. 111 | 112 | 113 | ## Notes 114 | 115 | ### cpuidle situation 116 | Some power management functionality on ARM machines is controlled via the PSCI interface. The 117 | kernel has a specific way of talking to PSCI that is not compatible with Apple Silicon, and a 118 | discussion is required with upstream maintainers in order to figure out the best way forward. Given 119 | that this discussion has failed to materialise for two years, the decision has been 120 | made to hack together a driver that directly calls WFI/WFE instructions in order to bring 121 | this functionality to Asahi Linux. This greatly improves the UX on laptops when coupled with 122 | energy-aware scheduling, as it resolves the issue of the machines running warm to the touch 123 | and significantly improves battery life. This can never be upstreamed, however the hope is 124 | that this hacked together driver becomes unnecessary at some point in the near future. 125 | 126 | ### ANE driver 127 | An out of tree [kernel module](https://github.com/eiln/ane/tree/main) is available. It will be merged into linux-asahi. 128 | --------------------------------------------------------------------------------