AsahiLinux · Conan-Kudo · Mar 9, 2025 · Mar 9, 2025 · Mar 9, 2025 · Mar 9, 2025
diff --git a/README.md b/README.md
@@ -1,10 +1,29 @@
 # Asahi Linux documentation repository
-
 This is the [Asahi Linux documentation](https://asahilinux.org/docs/) repository.
 
+## Documentation structure
+Our documentation is organised into categories.
+
+- alt: Alternative operating system/Linux distribution support documentation
+  should go here.
+- fw: Documentation on vendor-controlled firmware and firmware interfaces should
+  go here.
+- hw: Any documentation related to hardware belongs here. This is further split
+  into subcategories:
+    - cpu: Application processor documentation
+    - devices: Documentation relating to specific Mac models
+    - peripherals: hardware found in Apple Silicon Macs but not the SoC itself
+    - soc: hardware blocks integrated into Apple Silicon SoCs
+- platform: Documentation that applies across the Apple Silicon platform
+- project: Project admin documents and stuff unrelated to hardware or software
+- sw: Documentation for non-firmware software
+
 ## Usage
 
-This is made with [MkDocs](https://www.mkdocs.org/). If you have mkdocs installed already, run `make build` to build the site, or `make test` to spin up a local webserver for review. If you don't, feel free to use our [container](https://github.com/AsahiLinux/docs/pkgs/container/mkdocs-asahi) with something like:
+This is made with [MkDocs](https://www.mkdocs.org/). If you have mkdocs installed
+already, run `make build` to build the site, or `make test` to spin up a local webserver
+for review. If you don't, feel free to use our [container](https://github.com/AsahiLinux/docs/pkgs/container/mkdocs-asahi)
+with something like:
 
 ```
 $ podman run -it --pull=newer -p=8000:8000 -v=$(pwd)/:/docs:z ghcr.io/asahilinux/mkdocs-asahi:latest
@@ -16,6 +35,9 @@ if you're using [Podman](https://podman.io), or
 $ docker run -it --pull=always -p=8000:8000 -v=$(pwd)/:/docs:z ghcr.io/asahilinux/mkdocs-asahi:latest
 ```
 
-if you're using [Docker](https://www.docker.com). Note that this repository uses [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so you'll want to set those up first with `git submodule update --init`.
+if you're using [Docker](https://www.docker.com). Note that this repository uses
+[Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so you'll
+want to set those up first with `git submodule update --init`.
 
-The website is rebuilt by the CI on every commit and served via GitHub Pages. The container is also automatically updated and pushed to the registry.
+The website is rebuilt by the CI on every commit and served via GitHub Pages.
+The container is also automatically updated and pushed to the registry.
diff --git a/docs/Apple-Silicon-Subsystems.md b/docs/Apple-Silicon-Subsystems.md
diff --git a/docs/HW-CPU-debug-registers.md b/docs/HW-CPU-debug-registers.md
diff --git a/docs/Reference-Asahi-kernel-config.md b/docs/Reference-Asahi-kernel-config.md
diff --git a/docs/SW-Getting-started.md b/docs/SW-Getting-started.md
diff --git a/docs/SW-Alternative-Distros.md → docs/alt/alt-distros.md b/docs/SW-Alternative-Distros.md → docs/alt/alt-distros.md
@@ -1,3 +1,10 @@
+---
+title: Alternative Distributions
+summary:
+  Linux distros and other OSes that have added support for
+  the Apple Silicon platform
+---
+
 The primary supported distribution is the [Fedora Asahi Remix](https://asahilinux.org/fedora/), but several members of the community have contributed guides and pre-built artifacts in order to use other distros on Apple Silicon Macs. These efforts are listed here. Please remember that these are user-contributed, and the Asahi Linux project cannot provide support or any guarantee of compatibility, functionality, or safety.
 
 | Distro | Maintainer | Installation Guide |
@@ -10,7 +17,7 @@ The primary supported distribution is the [Fedora Asahi Remix](https://asahilinu
 | deepin | <https://github.com/deepin-community> | <https://github.com/deepin-community/deepin-m1> |
 | deepin | deepin M1 SIG | <https://www.deepin.org/index/docs/sig/sig/deepin-m1/README> |
 | Fedora | <https://github.com/leifliddy> | <https://github.com/leifliddy/asahi-fedora-builder> |
-| Gentoo<br>(LiveCD method) | IRC: chadmed (<https://github.com/chadmed>) | [Installing Gentoo with LiveCD](Installing-Gentoo-with-LiveCD.md) |
+| Gentoo<br>(LiveCD method) | IRC: chadmed (<https://github.com/chadmed>) | [Installing Gentoo with LiveCD](installing-gentoo.md) |
 | NixOS | IRC: tpw_rules (<https://github.com/tpwrules>) | <https://github.com/tpwrules/nixos-apple-silicon/blob/main/docs/uefi-standalone.md> |
 | NixOS (Asahi-Installer package) | <https://github.com/quinneden> | <https://github.com/quinneden/nixos-asahi-package> |
 | Rocky Linux | <https://github.com/leifliddy> | <https://github.com/leifliddy/asahi-rocky-builder> |

diff --git a/docs/Distro-Boot-process-guide.md → docs/alt/boot-process-guide.md b/docs/Distro-Boot-process-guide.md → docs/alt/boot-process-guide.md
@@ -1,6 +1,13 @@
+---
+title: Asahi Boot Process
+summary:
+  How Asahi Linux boots on Apple Silicon Macs, intended for
+  distro/OS integrators
+---
+
 This page explains the packages/components involved in a bootable Asahi Linux system, and how they interact with each other. It is aimed at distro packagers and people who want to roll/maintain their own builds instead of using packages. It is based on the setup used in the Arch Linux ARM-based reference distro, but should apply to most systems.
 
-This is a practical guide. For a more formal description/spec, including how we handle vendor firmware, see [Open OS Ecosystem on Apple Silicon Macs](Open-OS-Ecosystem-on-Apple-Silicon-Macs.md). For information about specifically how everything is plumbed in Fedora Asahi Remix, see its [How it's made](https://docs.fedoraproject.org/en-US/fedora-asahi-remix/how-its-made/) page.
+This is a practical guide. For a more formal description/spec, including how we handle vendor firmware, see [Open OS Ecosystem on Apple Silicon Macs](../platform/open-os-interop.md). For information about specifically how everything is plumbed in Fedora Asahi Remix, see its [How it's made](https://docs.fedoraproject.org/en-US/fedora-asahi-remix/how-its-made/) page.
 
 ## Boot chain overview
 
@@ -114,4 +121,4 @@ You might want to rename the old `m1n1.bin` after an update. If booting fails, y
 
 m1n1 stuffs the Apple keyboard code into `/proc/device-tree/chosen/asahi,kblang-code` (as a big-endian u32 cell, standard for DT). The mapping is [here](https://github.com/AsahiLinux/asahi-calamares-configs/blob/main/bin/first-time-setup.sh#L109). Feel free to start a discussion on how to standardize a proper binding for this.
 
-We have a whole story for how vendor firmware (i.e. firmware that is not redistributable as a distro package, but is prepared at install time) is handled. How that works is covered in detail [here](Open-OS-Ecosystem-on-Apple-Silicon-Macs.md#firmware-provisioning).
+We have a whole story for how vendor firmware (i.e. firmware that is not redistributable as a distro package, but is prepared at install time) is handled. How that works is covered in detail [here](../platform/open-os-interop.md#firmware-provisioning).
diff --git a/docs/Installing-Gentoo-with-LiveCD.md → docs/alt/installing-gentoo.md b/docs/Installing-Gentoo-with-LiveCD.md → docs/alt/installing-gentoo.md
@@ -1,3 +1,12 @@
+---
+title: Installing Gentoo
+---
+
+**This page contains distro-specific information. This documentation**
+**repo is not for distro-specific documentation. The proper place for**
+**this is the distro's own documentation system. This page will be removed**
+**soon.**
+
 ## Table of Contents
 - [Introduction](#introduction)
 - [Prerequisites](#important-prerequisite-information)
@@ -97,7 +106,7 @@ When you update the U-Boot or m1n1 packages, Portage will only install the resul
 This is both a security and a reliability measure. m1n1 ships with a script, `update-m1n1`, which must be run as root
 every time you update the kernel, U-Boot, or m1n1 itself. This script is responsible for collecting the m1n1, U-Boot
 and Devicetree blobs, packaging them up into a single binary object, and installing it on the EFI System Partition.
-For more information on how this works and why it must work this way, consult [Open OS Ecosystem on Apple Silicon Macs](Open-OS-Ecosystem-on-Apple-Silicon-Macs.md)
+For more information on how this works and why it must work this way, consult [Open OS Ecosystem on Apple Silicon Macs](../platform/open-os-interop.md)
 
 ### Upgrading the kernel
 When you are running through a kernel upgrade, it is extremely important that you update the Stage 2 m1n1 payload at the

diff --git a/docs/SW-Ubuntu-Asahi-Gambas.md → docs/alt/ubuntu-gambas.md b/docs/SW-Ubuntu-Asahi-Gambas.md → docs/alt/ubuntu-gambas.md
@@ -1,3 +1,12 @@
+---
+title: Ubuntu Gambas
+---
+
+**This page contains distro-specific information. This documentation**
+**repo is not for distro-specific documentation. The proper place for**
+**this is the distro's own documentation system. This page will be removed**
+**soon.**
+
 Tested on Ubuntu 22.10 Asahi on M1 Air.
 
 https://gambas.sourceforge.net
@@ -39,4 +48,4 @@ As normal user:
 make -j$(nproc)
 
 sudo make install
-```
+```
diff --git a/docs/SW-Ubuntu-Asahi-Godot.md → docs/alt/ubuntu-godot.md b/docs/SW-Ubuntu-Asahi-Godot.md → docs/alt/ubuntu-godot.md
@@ -1,3 +1,12 @@
+---
+title: Ubuntu Godot
+---
+
+**This page contains distro-specific information. This documentation**
+**repo is not for distro-specific documentation. The proper place for**
+**this is the distro's own documentation system. This page will be removed**
+**soon.**
+
 Tested on Ubuntu 22.10 Asahi on M1 Air.
 
 https://godotengine.org

diff --git a/docs/SW-Ubuntu-Asahi-Qemu.md → docs/alt/ubuntu-qemu.md b/docs/SW-Ubuntu-Asahi-Qemu.md → docs/alt/ubuntu-qemu.md
@@ -1,6 +1,15 @@
+---
+title: Ubuntu Qemu
+---
+
+**This page contains distro-specific information. This documentation**
+**repo is not for distro-specific documentation. The proper place for**
+**this is the distro's own documentation system. This page will be removed**
+**soon.**
+
 Tested on Ubuntu 22.10 Asahi on M1 Air.
 
-See [this page](SW-Alternative-Distros.md) for other Ubuntu Asahi install info.
+See [this page](alt-distros.md) for other Ubuntu Asahi install info.
 
 Also installs virt-manager.
 

diff --git a/docs/FW-ADT.md → docs/fw/adt.md b/docs/FW-ADT.md → docs/fw/adt.md
@@ -1,3 +1,10 @@
+---
+title: Apple Device Tree (ADT)
+summary:
+  Apple Device Tree, the hardware discovery and initialisation
+  system used on Apple Silicon devices.
+---
+
 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.
 
 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.
@@ -43,7 +50,7 @@ make
 make install
 ```
 ### Obtaining device tree files
-copy the im4p file from the below directory. See [Devices](Devices.md) for Machine 'j' model details.
+copy the im4p file from the below directory. See [Devices](../hw/devices/device-list.md) for Machine 'j' model details.
 
 `/System/Volumes/Preboot/[UUID]/restore/Firmware/all_flash/DeviceTree.{model}.im4p`
 

diff --git a/docs/SW-Boot.md → docs/fw/boot.md b/docs/SW-Boot.md → docs/fw/boot.md
@@ -1,19 +1,25 @@
+---
+title: Apple Silicon Boot Flow
+summary:
+  Boot flow used by Apple Silicon devices, from SoC-integrated ROM to user code
+---
+
 Apple Silicon devices seem to follow a boot flow very similar to modern iOS devices.
 
 # Stage 0 (SecureROM)
 
-This stage is located in the boot [ROM](Glossary.md#r). Among others, it verifies, loads and executes normal stage 1 from [NOR](Glossary.md#n). If this fails, it falls back to [DFU](Glossary.md#d) and wait for an [iBSS](Glossary.md#i) loader to be sent, before continuing with the [DFU](Glossary.md#d) flow at stage 1.
+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 wait for an [iBSS](../project/glossary.md#i) loader to be sent, before continuing with the [DFU](../project/glossary.md#d) flow at stage 1.
 
 # Normal flow
 
 ## Stage 1 (LLB/iBoot1)
 
-This stage is the primary early loader, located in the on-board [NOR](Glossary.md#n). This boot stage very roughly goes as follows:
+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:
 
-* Read the `boot-volume` variable from [NVRAM](Glossary.md#n): its format is `<gpt-partition-type-uuid>:<gpt-partition-uuid>:<volume-group-uuid>`. Other related variables seem to be `update-volume` and `upgrade-boot-volume`, possibly selected by metadata inside the `boot-info-payload` variable;
+* Read the `boot-volume` variable from [NVRAM](../project/glossary.md#n): its format is `<gpt-partition-type-uuid>:<gpt-partition-uuid>:<volume-group-uuid>`. Other related variables seem to be `update-volume` and `upgrade-boot-volume`, possibly selected by metadata inside the `boot-info-payload` variable;
 * Get the local policy hash:
-  - First try the local proposed hash ([SEP](Glossary.md#s) command 11);
-  - If that is not available, get the local blessed hash ([SEP](Glossary.md#s) command 14)
+  - First try the local proposed hash ([SEP](../project/glossary.md#s) command 11);
+  - If that is not available, get the local blessed hash ([SEP](../project/glossary.md#s) command 14)
 * Read the local boot policy, located on the iSCPreboot partition at `/<volume-group-uuid>/LocalPolicy/<policy-hash>.img4`. This boot policy has the following specific metadata keys:
   - `vuid`: UUID: Volume group UUID - same as above
   - `kuid`: UUID: KEK group UUID
@@ -45,17 +51,17 @@ This stage is the primary early loader, located in the on-board [NOR](Glossary.m
   - The boot directory is located at the target partition Preboot subvolume, at path `/<volume-uuid>/boot/<local-policy.metadata.nsih>`;
   - Decrypt, verify and execute `<boot-dir>/usr/standalone/firmware/iBoot.img4` with the device tree and other firmware files in the same directory. No evidence towards other metadata descriptors yet.
 
-* If loading a custom stage ([fuOS](Glossary.md#f)):
+* If loading a custom stage ([fuOS](../project/glossary.md#f)):
 
   - ...
 
-If it fails at any point during this, it will either error out or fall back to [DFU](Glossary.md#d), waiting for an iBEC loader to be sent, before continuing with the [DFU](Glossary.md#d) flow at stage 2.
+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.
 
 ## Stage 2 (iBoot2)
 
 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.
 
-# [DFU](Glossary.md#d) flow
+# [DFU](../project/glossary.md#d) flow
 
 ## Stage 1 (iBSS)
 
@@ -65,7 +71,7 @@ This stage is sent to the device by the "reviving" host. It bootstraps, verifies
 
 # Modes
 
-Once booted, the [AP](Glossary.md#a) can be in one of several boot modes, as confirmed by the [SEP](Glossary.md#s):
+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):
 
 |  ID | Name                                      |
 |----:|-------------------------------------------|
@@ -76,4 +82,4 @@ Once booted, the [AP](Glossary.md#a) can be in one of several boot modes, as con
 |   4 | restoreOS                                 |
 | 255 | unknown                                   |
 
-The [SEP](Glossary.md#s) only allows execution of certain commands (such as editing the boot policy) in [1TR](Glossary.md#1), or it will fail with error 11, "AP boot mode".
+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".
diff --git a/docs/SW-MachO-Boot-Protocol.md → docs/fw/macho-boot-protocol.md b/docs/SW-MachO-Boot-Protocol.md → docs/fw/macho-boot-protocol.md
@@ -1,3 +1,10 @@
+---
+title: MachO Boot Protocol
+summary:
+  Boot protocol used by Apple Silicon devices when booting m1n1 as a
+  MachO binary
+---
+
 ## Boot protocol
 
 ### Memory

diff --git a/docs/SW-NVRAM.md → docs/fw/nvram.md b/docs/SW-NVRAM.md → docs/fw/nvram.md
@@ -1,3 +1,9 @@
+---
+title: NVRAM
+summary:
+  NVRAM variables used by Apple Silicon Macs
+---
+
 # Types
 
 * `string`: A standard string.
@@ -268,4 +274,4 @@
 </plist>
 ```
 
-</details>
+</details>
diff --git a/docs/HW-Apple-Instructions.md → docs/hw/cpu/apple-instructions.md b/docs/HW-Apple-Instructions.md → docs/hw/cpu/apple-instructions.md
@@ -1,3 +1,9 @@
+---
+title: Apple Proprietary Instructions
+summary:
+  Apple's proprietary extensions to the A64 Instruction Set
+---
+
 Apple proprietary instructions seem to be in the 0x0020xxxx range.
 
 ```

diff --git a/docs/hw/cpu/debug-registers.md b/docs/hw/cpu/debug-registers.md
@@ -0,0 +1,9 @@
+---
+title: Application Processor Debug Registers
+summary:
+  Debug registers found in Apple-designed ARM cores
+---
+
+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.
+
+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.
diff --git a/docs/HW-SMP-spin-up.md → docs/hw/cpu/smp.md b/docs/HW-SMP-spin-up.md → docs/hw/cpu/smp.md
@@ -1,3 +1,10 @@
+---
+title: Symmetric Multiprocessing (SMP)
+summary:
+  Secondary application processor initialisation routine for Apple Silicon
+  SoCs
+---
+
 ## SMP spin-up
 
 From the ADT:

diff --git a/docs/HW-SPRR-and-GXF.md → docs/hw/cpu/sprr-gxf.md b/docs/HW-SPRR-and-GXF.md → docs/hw/cpu/sprr-gxf.md
@@ -1,3 +1,9 @@
+---
+title: SPRR and GXF
+summary:
+  SPRR and GXF are in-silicon security features used to harden macOS/Darwin
+---
+
 
 # Guarded execution
 

diff --git a/docs/HW-ARM-System-Registers-Dumps.md → docs/hw/cpu/system-register-dumps.md b/docs/HW-ARM-System-Registers-Dumps.md → docs/hw/cpu/system-register-dumps.md
@@ -1,3 +1,7 @@
+---
+title: System Register Dumps
+---
+
 All implemented (readable) vendor-specific registers. Dumped while running m1n1 (after chicken bits):
 
 | Name | Register | Access | Icestorm | Firestorm |

diff --git a/docs/HW-ARM-System-Registers.md → docs/hw/cpu/system-registers.md b/docs/HW-ARM-System-Registers.md → docs/hw/cpu/system-registers.md
@@ -1,4 +1,8 @@
-See [HW-ARM System Registers Dumps](HW-ARM-System-Registers-Dumps.md) for exhaustive enumeration and research.
+---
+title: System Registers
+---
+
+See [System Register Dumps](system-register-dumps.md) for exhaustive enumeration and research.
 
 ## Glossary
 
@@ -730,4 +734,4 @@ Encoding unknown. Related to ACTLR_EL1[12].
 
 #### s3_4_c15_c10_4 (labeled SIQ_CFG_EL1 in m1n1)
 
-If a core writes 0x3 to it's copy of the register, AICv2 will not send IRQs to that core. FIQs unaffected, as those are part of the core complexes themselves. (0x0 and 0x2 are known values that will enable IRQs on a core, but 0x0 seems to cause weird EL1 problems)
+If a core writes 0x3 to it's copy of the register, AICv2 will not send IRQs to that core. FIQs unaffected, as those are part of the core complexes themselves. (0x0 and 0x2 are known values that will enable IRQs on a core, but 0x0 seems to cause weird EL1 problems)