diff --git a/README.md b/README.md index eb90f11c..0bf8db02 100644 --- 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 deleted file mode 100644 index 838ab5bb..00000000 --- a/docs/Apple-Silicon-Subsystems.md +++ /dev/null @@ -1,40 +0,0 @@ -These pages detail the specifics of a particular platform subsystem. They are loosely categorised -by function. - -### Generalised overviews -* [Introduction to Apple Silicon](Introduction-to-Apple-Silicon.md) -* [Accelerator Engines](Accelerator-Engines.md) - -### Coprocessors and accelerators -* [HW-AGX](HW-AGX.md) - Apple's PowerVR-derived tile-based deferred renderer -* [HW-SEP](HW-SEP.md) - The Secure Enclave, Apple's crypto/biometrics/security engine - -### Platform control logic -* [HW-AIC](HW-AIC.md) - Apple Interrupt Controller -* [HW-WDT](HW-WDT.md) - Watchdog Timer -* [HW-SMC](HW-SMC.md) - System Management Controller -* [HW-ASC](HW-ASC.md) - Apple's Mailbox-like firmware interface - -### Platform initialisation and boot -* [SW-Boot](SW-Boot.md) -* [SW-MachO Boot Protocol](SW-MachO-Boot-Protocol.md) -* [HW-Memory map](HW-Memory-map.md) -* [HW-SMP spin up](HW-SMP-spin-up.md) -* [FW:ADT](FW-ADT.md) (Apple Device Tree) -* [SW-NVRAM](SW-NVRAM.md) - -### Application processors -* [HW-ARM System Registers](HW-ARM-System-Registers.md) -* [HW- SPRR and GXF](HW-SPRR-and-GXF.md) -* [HW-CPU debug registers](HW-CPU-debug-registers.md) -* [HW-Apple Instructions](HW-Apple-Instructions.md) - -### I/O -* [HW-APCIe](HW-APCIe.md) (Apple PCIe controller) -* [HW-GPIO](HW-GPIO.md) -* [HW-Debug USB](HW-Debug-USB.md) -* [HW-USB PD](HW-USB-PD.md) -* [SW-Storage](SW-Storage.md) - -### Peripherals -* [HW-Camera](HW-Camera.md) - Broadcom camera and ISP diff --git a/docs/HW-CPU-debug-registers.md b/docs/HW-CPU-debug-registers.md deleted file mode 100644 index e08ebf94..00000000 --- a/docs/HW-CPU-debug-registers.md +++ /dev/null @@ -1,3 +0,0 @@ -The various CPU cores export entries in the [ADT|FW: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/Reference-Asahi-kernel-config.md b/docs/Reference-Asahi-kernel-config.md deleted file mode 100644 index ba6d6cac..00000000 --- a/docs/Reference-Asahi-kernel-config.md +++ /dev/null @@ -1 +0,0 @@ -See diff --git a/docs/SW-Getting-started.md b/docs/SW-Getting-started.md deleted file mode 100644 index edcf409f..00000000 --- a/docs/SW-Getting-started.md +++ /dev/null @@ -1 +0,0 @@ -Obsolete, you want [Developer Quickstart](Developer-Quickstart.md) \ No newline at end of file diff --git a/docs/SW-Alternative-Distros.md b/docs/alt/alt-distros.md similarity index 90% rename from docs/SW-Alternative-Distros.md rename to docs/alt/alt-distros.md index bf496dc7..6f5cb6e9 100644 --- a/docs/SW-Alternative-Distros.md +++ b/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 | | | | deepin | deepin M1 SIG | | | Fedora | | | -| Gentoo
(LiveCD method) | IRC: chadmed () | [Installing Gentoo with LiveCD](Installing-Gentoo-with-LiveCD.md) | +| Gentoo
(LiveCD method) | IRC: chadmed () | [Installing Gentoo with LiveCD](installing-gentoo.md) | | NixOS | IRC: tpw_rules () | | | NixOS (Asahi-Installer package) | | | | Rocky Linux | | | diff --git a/docs/Distro-Boot-process-guide.md b/docs/alt/boot-process-guide.md similarity index 96% rename from docs/Distro-Boot-process-guide.md rename to docs/alt/boot-process-guide.md index 95b726bd..acc20117 100644 --- a/docs/Distro-Boot-process-guide.md +++ b/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 b/docs/alt/installing-gentoo.md similarity index 95% rename from docs/Installing-Gentoo-with-LiveCD.md rename to docs/alt/installing-gentoo.md index 5677e226..76faf5d3 100644 --- a/docs/Installing-Gentoo-with-LiveCD.md +++ b/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 b/docs/alt/ubuntu-gambas.md similarity index 82% rename from docs/SW-Ubuntu-Asahi-Gambas.md rename to docs/alt/ubuntu-gambas.md index 9dc77ad8..2e5837bd 100644 --- a/docs/SW-Ubuntu-Asahi-Gambas.md +++ b/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 -``` \ No newline at end of file +``` diff --git a/docs/SW-Ubuntu-Asahi-Godot.md b/docs/alt/ubuntu-godot.md similarity index 73% rename from docs/SW-Ubuntu-Asahi-Godot.md rename to docs/alt/ubuntu-godot.md index 950aeac7..735b94fd 100644 --- a/docs/SW-Ubuntu-Asahi-Godot.md +++ b/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 b/docs/alt/ubuntu-qemu.md similarity index 94% rename from docs/SW-Ubuntu-Asahi-Qemu.md rename to docs/alt/ubuntu-qemu.md index b1822724..593590cc 100644 --- a/docs/SW-Ubuntu-Asahi-Qemu.md +++ b/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 b/docs/fw/adt.md similarity index 91% rename from docs/FW-ADT.md rename to docs/fw/adt.md index ae9ff4dc..d3ad436f 100644 --- a/docs/FW-ADT.md +++ b/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 b/docs/fw/boot.md similarity index 64% rename from docs/SW-Boot.md rename to docs/fw/boot.md index bf062360..ab18a183 100644 --- a/docs/SW-Boot.md +++ b/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 `::`. 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 `::`. 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 `//LocalPolicy/.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 `//boot/`; - 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. -* 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 b/docs/fw/macho-boot-protocol.md similarity index 98% rename from docs/SW-MachO-Boot-Protocol.md rename to docs/fw/macho-boot-protocol.md index 1ab03df6..b005eab8 100644 --- a/docs/SW-MachO-Boot-Protocol.md +++ b/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 b/docs/fw/nvram.md similarity index 98% rename from docs/SW-NVRAM.md rename to docs/fw/nvram.md index a843f906..6607dd38 100644 --- a/docs/SW-NVRAM.md +++ b/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 @@ ``` - \ No newline at end of file + diff --git a/docs/HW-Apple-Instructions.md b/docs/hw/cpu/apple-instructions.md similarity index 94% rename from docs/HW-Apple-Instructions.md rename to docs/hw/cpu/apple-instructions.md index a852b1bc..7b757062 100644 --- a/docs/HW-Apple-Instructions.md +++ b/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 new file mode 100644 index 00000000..93f59409 --- /dev/null +++ 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 b/docs/hw/cpu/smp.md similarity index 92% rename from docs/HW-SMP-spin-up.md rename to docs/hw/cpu/smp.md index cd322806..1b5e8dd6 100644 --- a/docs/HW-SMP-spin-up.md +++ b/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 b/docs/hw/cpu/sprr-gxf.md similarity index 95% rename from docs/HW-SPRR-and-GXF.md rename to docs/hw/cpu/sprr-gxf.md index 1e348045..3850f435 100644 --- a/docs/HW-SPRR-and-GXF.md +++ b/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 b/docs/hw/cpu/system-register-dumps.md similarity index 99% rename from docs/HW-ARM-System-Registers-Dumps.md rename to docs/hw/cpu/system-register-dumps.md index a9bafc7b..cc2c7245 100644 --- a/docs/HW-ARM-System-Registers-Dumps.md +++ b/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 b/docs/hw/cpu/system-registers.md similarity index 99% rename from docs/HW-ARM-System-Registers.md rename to docs/hw/cpu/system-registers.md index 6539fd41..fe3edeb1 100644 --- a/docs/HW-ARM-System-Registers.md +++ b/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) \ No newline at end of file +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) diff --git a/docs/Devices.md b/docs/hw/devices/device-list.md similarity index 91% rename from docs/Devices.md rename to docs/hw/devices/device-list.md index 1e172402..d617e0bd 100644 --- a/docs/Devices.md +++ b/docs/hw/devices/device-list.md @@ -1,4 +1,10 @@ -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](Feature-Support.md) for the state of support for specific models. +--- +title: Device List +summary: + List of devices supported or intended to be supported by Asahi Linux +--- + +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. ## Devices | Marketing name | Device | Product | SoC | @@ -47,4 +53,4 @@ This is a list of devices Asahi Linux intends to support. The Product and SoC ar | MacBook Pro (14-inch, M4 Max, Nov 2024) | Mac16,6 | J614cAP | T6041 | MacBook Pro (16-inch, M4 Max, Nov 2024) | Mac16,5 | J616cAP | T6041 | MacBook Air (13-inch, M4, 2025) | Mac16,12 | J713AP | T8132 -| MacBook Air (15-inch, M4, 2025) | Mac16,13 | J715AP | T8132 \ No newline at end of file +| MacBook Air (15-inch, M4, 2025) | Mac16,13 | J715AP | T8132 diff --git a/docs/HW-Camera.md b/docs/hw/peripherals/camera.md similarity index 99% rename from docs/HW-Camera.md rename to docs/hw/peripherals/camera.md index 88936e82..d9cae593 100644 --- a/docs/HW-Camera.md +++ b/docs/hw/peripherals/camera.md @@ -1,3 +1,8 @@ +--- +title: Camera and Image Signal Processor +--- + + # ISP This information is based on Macbook Pro M1 2020 ISP. It may differ for other devices. diff --git a/docs/HW-MacBook-Pro-keyboard-backlight-FPWM0.md b/docs/hw/peripherals/keyboard-backlight.md similarity index 92% rename from docs/HW-MacBook-Pro-keyboard-backlight-FPWM0.md rename to docs/hw/peripherals/keyboard-backlight.md index 4d6f06d8..1fb7e028 100644 --- a/docs/HW-MacBook-Pro-keyboard-backlight-FPWM0.md +++ b/docs/hw/peripherals/keyboard-backlight.md @@ -1,3 +1,7 @@ +--- +title: Keyboard Backlight Controller +--- + On the MacBook Pro, the keyboard backlight shows up in the ADT as: ``` @@ -44,4 +48,4 @@ changing the frequency while keeping a 50% duty cycle: >>> write32(0x235044000, 0x4239) ``` -PR at https://github.com/AsahiLinux/linux/pull/5 \ No newline at end of file +PR at https://github.com/AsahiLinux/linux/pull/5 diff --git a/docs/Accelerator-Engines.md b/docs/hw/soc/accelerators.md similarity index 93% rename from docs/Accelerator-Engines.md rename to docs/hw/soc/accelerators.md index 3de0e6fd..e08b0d70 100644 --- a/docs/Accelerator-Engines.md +++ b/docs/hw/soc/accelerators.md @@ -1,6 +1,10 @@ +--- +title: Apple Silicon Accelerators +--- + 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. -*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? +*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? ## Names diff --git a/docs/HW-ACE3.md b/docs/hw/soc/ace3.md similarity index 99% rename from docs/HW-ACE3.md rename to docs/hw/soc/ace3.md index c7369590..814d6110 100644 --- a/docs/HW-ACE3.md +++ b/docs/hw/soc/ace3.md @@ -1,3 +1,7 @@ +--- +title: ACE3 +--- + ACE3 is the new USB-C / USB-PD controller in M3 products. It has a sn201202x compatible value in the ADT. ## SPMI transport diff --git a/docs/HW-AGX.md b/docs/hw/soc/agx.md similarity index 99% rename from docs/HW-AGX.md rename to docs/hw/soc/agx.md index 7e39024d..02146071 100644 --- a/docs/HW-AGX.md +++ b/docs/hw/soc/agx.md @@ -1,3 +1,9 @@ +--- +title: Apple GPU (AGX) +summary: + Lina's reverse engineering notes about AGX, Apple's PowerVR-derived GPU +--- + # Lina's AGX notes Reader beware, here be dragons. Pointer-shaped dragons. Lots of them. @@ -614,4 +620,4 @@ These status registers are continually checked by *something* on the CPU 0x11014 : u32 - Useally 0 There doesn't seem to be a good relationship of when these status registers are read, relative to -the ASC Pong and Kicks. \ No newline at end of file +the ASC Pong and Kicks. diff --git a/docs/HW-AIC.md b/docs/hw/soc/aic.md similarity index 95% rename from docs/HW-AIC.md rename to docs/hw/soc/aic.md index 70cf6e47..9259659b 100644 --- a/docs/HW-AIC.md +++ b/docs/hw/soc/aic.md @@ -1,3 +1,7 @@ +--- +title: Apple Interrupt Controller (AIC) +--- + AIC is the Apple Interrupt Controller. These are some scattered RE notes. Apple likes to use a particular SET/CLR register pair style: @@ -66,4 +70,4 @@ Bits set in SW_GEN are ORed with the hardware IRQ lines ## Timer -The system timer is the standard ARM64 MSR stuff, and bypasses AIC. It is wired straight to FIQ. \ No newline at end of file +The system timer is the standard ARM64 MSR stuff, and bypasses AIC. It is wired straight to FIQ. diff --git a/docs/HW-AOP.md b/docs/hw/soc/aop.md similarity index 83% rename from docs/HW-AOP.md rename to docs/hw/soc/aop.md index 249a8a52..ce760b3b 100644 --- a/docs/HW-AOP.md +++ b/docs/hw/soc/aop.md @@ -1,3 +1,7 @@ +--- +title: Always-On Processor (AOP) +--- + # AOP 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). diff --git a/docs/HW-APCIe.md b/docs/hw/soc/apcie.md similarity index 98% rename from docs/HW-APCIe.md rename to docs/hw/soc/apcie.md index d50bf76c..a76a1188 100644 --- a/docs/HW-APCIe.md +++ b/docs/hw/soc/apcie.md @@ -1,3 +1,7 @@ +--- +title: Apple PCIe controller +--- + 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). ## ADT bindings @@ -103,4 +107,4 @@ Device tree bindings have been accepted upstream. Some open questions remain: * 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. -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. \ No newline at end of file +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. diff --git a/docs/HW-ASC.md b/docs/hw/soc/asc.md similarity index 97% rename from docs/HW-ASC.md rename to docs/hw/soc/asc.md index 5a0113bf..9081358a 100644 --- a/docs/HW-ASC.md +++ b/docs/hw/soc/asc.md @@ -1,3 +1,7 @@ +--- +title: ASC +--- + ## ASC registers ``` @@ -53,7 +57,7 @@ Communication between the M1's main CPU cores and the ASCs/IOPs (I/O processors) 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. -The hardware side of the mailbox is located at offset +0x8000 in MMIO space, and uses four interrupts numbered consecutively at the [AIC](HW-AIC.md), two of which are useful to us. +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. 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. diff --git a/docs/HW-AVD.md b/docs/hw/soc/avd.md similarity index 79% rename from docs/HW-AVD.md rename to docs/hw/soc/avd.md index 59ed3255..ee5d146f 100644 --- a/docs/HW-AVD.md +++ b/docs/hw/soc/avd.md @@ -1,3 +1,7 @@ +--- +title: Apple Video Decoder +--- + Apple Video Decoder. Supports AVC, HEVC, AV1, VP9. diff --git a/docs/HW-Clocks.md b/docs/hw/soc/clocks.md similarity index 98% rename from docs/HW-Clocks.md rename to docs/hw/soc/clocks.md index 23b45f98..3f8ec694 100644 --- a/docs/HW-Clocks.md +++ b/docs/hw/soc/clocks.md @@ -1,3 +1,6 @@ +--- +title: Clocks +--- There are (at least) two different kinds of clocks defined in the ADT: @@ -15,4 +18,4 @@ There is probably also some topology involved in these clocks since e.g. `SIO`, 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. 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. -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. \ No newline at end of file +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. diff --git a/docs/Display-Controllers.md b/docs/hw/soc/display-controllers.md similarity index 97% rename from docs/Display-Controllers.md rename to docs/hw/soc/display-controllers.md index 3520c8de..2b1eee95 100644 --- a/docs/Display-Controllers.md +++ b/docs/hw/soc/display-controllers.md @@ -1,3 +1,7 @@ +--- +title: Display Controllers +--- + M series of chips have two kinds of display controllers, `dcp` and `dcpext`. Both kinds support - DP 1.4 (4 lanes) with DSC. No MST! - HDMI via dp2hdmi converter. See below for routing restrictions. diff --git a/docs/HW-GPIO.md b/docs/hw/soc/gpio.md similarity index 99% rename from docs/HW-GPIO.md rename to docs/hw/soc/gpio.md index ac1ee773..fb834c2a 100644 --- a/docs/HW-GPIO.md +++ b/docs/hw/soc/gpio.md @@ -1,3 +1,7 @@ +--- +title: GPIO Controllre +--- + ## DT binding The "gpio,t8101" nodes in the ADT represent a GPIO controller with pinmux facilities. diff --git a/docs/HW-Memory-map.md b/docs/hw/soc/memmap.md similarity index 99% rename from docs/HW-Memory-map.md rename to docs/hw/soc/memmap.md index f9081064..6ceaafbf 100644 --- a/docs/HW-Memory-map.md +++ b/docs/hw/soc/memmap.md @@ -1,3 +1,7 @@ +--- +title: T8103 Memory Map +--- + # M1 (T8103) memory map (Incomplete) diff --git a/docs/HW-SEP.md b/docs/hw/soc/sep.md similarity index 99% rename from docs/HW-SEP.md rename to docs/hw/soc/sep.md index bb1db096..4c537119 100644 --- a/docs/HW-SEP.md +++ b/docs/hw/soc/sep.md @@ -1,3 +1,7 @@ +--- +title: Secure Enclave Processor (SEP) +--- + Some notes on the SEP based on past community research and digging into the SEP, along with some TODOs for anyone wanting to trace the SEP on Asahi Linux fair warning: this page is messy and will likely remain so, until enough understanding is built up to build a clean page. diff --git a/docs/Low-level-serial-debug.md b/docs/hw/soc/serial-debug.md similarity index 95% rename from docs/Low-level-serial-debug.md rename to docs/hw/soc/serial-debug.md index a3b093e1..bcce1425 100644 --- a/docs/Low-level-serial-debug.md +++ b/docs/hw/soc/serial-debug.md @@ -1,3 +1,7 @@ +--- +title: Debugging via Serial Console +--- + Taken from the original Developer Quickstart guide ## Getting a serial console @@ -8,7 +12,7 @@ M1 Macs expose their debug serial port over one of their Type C ports (the same The target machine can also be hard-rebooted using USB-PD VDM commands, making for a quick test cycle (no holding down power buttons). -See [HW-USB-PD](HW-USB-PD.md) for details on the USB-PD VDM commands and what you can do with them. +See [USB-PD](usb-pd.md) for details on the USB-PD VDM commands and what you can do with them. 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. @@ -71,8 +75,8 @@ This is all rather rudimentary because it's a stop-gap for the proper solution, 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: -![Central Scrutinizer](assets/central-scrutinizer.jpg) -![Central Scrutinizer (side)](assets/central-scrutinizer-2.jpg) +![Central Scrutinizer](../../assets/central-scrutinizer.jpg) +![Central Scrutinizer (side)](../../assets/central-scrutinizer-2.jpg) Main features are: - RaspberryPi Pico as the micro-controller (yes, totally overkill, but cheaper than an Arduino!) diff --git a/docs/HW-SMC.md b/docs/hw/soc/smc.md similarity index 98% rename from docs/HW-SMC.md rename to docs/hw/soc/smc.md index a4798c03..c72c2439 100644 --- a/docs/HW-SMC.md +++ b/docs/hw/soc/smc.md @@ -1,3 +1,7 @@ +--- +title: System Management Controller (SMC) +--- + 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. It is "documented", to the extent that it is, in 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: @@ -96,4 +100,4 @@ Setting the "NTAP" (notify application processor, maybe?) flag to 1 makes the SM closed. Notifications are mailbox messages apparently limited to the 64-bit payload. ### ADC -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. \ No newline at end of file +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. diff --git a/docs/Codenames.md b/docs/hw/soc/soc-codenames.md similarity index 98% rename from docs/Codenames.md rename to docs/hw/soc/soc-codenames.md index 497dac63..19d4c8ed 100644 --- a/docs/Codenames.md +++ b/docs/hw/soc/soc-codenames.md @@ -1,3 +1,7 @@ +--- +title: SoC Codenames +--- + Apple likes to use many different names for the same devices. ## SoCs @@ -59,4 +63,4 @@ Apple likes to use many different names for the same devices. | | | Sotra_D | | | | | | Thera | | | | | | Komodo | | | -| | | Tilos | | | \ No newline at end of file +| | | Tilos | | | diff --git a/docs/HW-Debug-USB.md b/docs/hw/soc/usb-debug.md similarity index 98% rename from docs/HW-Debug-USB.md rename to docs/hw/soc/usb-debug.md index 3259602d..73070ccb 100644 --- a/docs/HW-Debug-USB.md +++ b/docs/hw/soc/usb-debug.md @@ -1,3 +1,7 @@ +--- +title: USB-PD Debugging Interface +--- + This seems to be a built-in debugging USB interface. Commands via EP 0x01, replies via 0x81, 0x82 unknown @@ -62,4 +66,4 @@ Register dump: 000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 000001e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| -``` \ No newline at end of file +``` diff --git a/docs/HW-USB-PD.md b/docs/hw/soc/usb-pd.md similarity index 99% rename from docs/HW-USB-PD.md rename to docs/hw/soc/usb-pd.md index 9f3d9bab..989020df 100644 --- a/docs/HW-USB-PD.md +++ b/docs/hw/soc/usb-pd.md @@ -1,3 +1,7 @@ +--- +title: USB-PD +--- + ## Introduction Apple uses custom USB-PD messages to control pin muxing on their Type-C ports for debug and other purposes. USB-PD communication takes place over the CCx line of the port (CC1 or CC2 depending on port orientation) diff --git a/docs/HW-WDT.md b/docs/hw/soc/wdt.md similarity index 94% rename from docs/HW-WDT.md rename to docs/hw/soc/wdt.md index 09ff9c26..b1b82c5a 100644 --- a/docs/HW-WDT.md +++ b/docs/hw/soc/wdt.md @@ -1,3 +1,7 @@ +--- +title: Watchdog Timer (WDT) +--- + 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. 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,4 +12,4 @@ The WDT is disabled by writing 0 to +0x1c, and enabled by writing 4 to +0x1c. Since the counters are 32-bit values and wrap, that means the maximum timeout is just short of three minutes. -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. \ No newline at end of file +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. diff --git a/docs/index.md b/docs/index.md index a8e27c08..f080e2df 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,30 +1,42 @@ -# Welcome to the Asahi Linux documentation! +Welcome to the Asahi Linux documentation! Here, you will find documentation on the +Apple Silicon platform as implemented on Mac computers with M-series SoCs. We aim +to document the platform in a way that is useful for everyone, however our focus is +supporting third-party operating systems, particularly Linux. -We are just getting started. +We also have documentation on the various pieces of software required to properly +support this platform, such as m1n1 and U-Boot. Documentation for software that we +have created (such as m1n1) aims to be as complete as possible. Documentation for +external projects (such as U-Boot) is limited to how that software is used on the +Apple Silicon platform. -Questions? Please check out the [FAQ](FAQ.md) first! +## Who this documentation is for +- Operating system and kernel developers looking to implement support for Apple Silicon +- Folks interested in hacking on and reverse engineering the Apple Silicon platform +- End users looking for guides and information on supported features +- Anyone interested in the Asahi Linux project looking for more information -## Developers +Questions? Please check out the [FAQ](project/faq.md) first! -If you are a developer or interested in hardware/software documentation, -check out the sidebar for places to start. +## Developers +We have extensive documentation on the platform itself, and the tooling we use to +reverse engineer and develop Linux drivers for it. Check out the sidebar for places +to start! ## End Users +Check out [Feature Support](platform/feature-support/overview.md) for supported devices +and features. If you're after documentation on something specific, use the search feature +at the top of the page or check out the sidebar for places to start! -Asahi Linux is work in progress. Many hardware components -are not yet supported! Check out the [Feature Support](Feature-Support.md) page first. -If you still want to give it a go, see the blog post for the initial installer and -following updates adding support for more devices and hardware: - -* [The first Asahi Linux Alpha Release is here!](https://asahilinux.org/2022/03/asahi-linux-alpha-release/) -* [M2 is here! July 2022 Release & Progress Report](https://asahilinux.org/2022/07/july-2022-release/) -* [Updates galore! November 2022 Progress Report](https://asahilinux.org/2022/11/november-2022-report/) -* [Apple GPU drivers now in Asahi Linux](https://asahilinux.org/2022/12/gpu-drivers-now-in-asahi-linux/) -* [Paving the Road to Vulkan on Asahi Linux](https://asahilinux.org/2023/03/road-to-vulkan/) -* [OpenGL 3.1 on Asahi Linux](https://asahilinux.org/2023/06/opengl-3-1-on-asahi-linux/) -* [Our new flagship distro: Fedora Asahi Remix](https://asahilinux.org/2023/08/fedora-asahi-remix/) -* [New in Fedora Asahi Remix](https://asahilinux.org/2024/01/fedora-asahi-new/) -* [Conformant OpenGL 4.6 on the M1](https://asahilinux.org/2024/02/conformant-gl46-on-the-m1/) -* [Vulkan 1.3 on the M1 in 1 month](https://asahilinux.org/2024/06/vk13-on-the-m1-in-1-month/) -* [AAA gaming on Asahi Linux](https://asahilinux.org/2024/10/aaa-gaming-on-asahi-linux/) +## Latest Asahi Linux blog posts * [Beyond Gaming: X11 bridging in muvm](https://asahilinux.org/2024/12/muvm-x11-bridging/) +* [AAA gaming on Asahi Linux](https://asahilinux.org/2024/10/aaa-gaming-on-asahi-linux/) +* [Vulkan 1.3 on the M1 in 1 month](https://asahilinux.org/2024/06/vk13-on-the-m1-in-1-month/) +* [Conformant OpenGL 4.6 on the M1](https://asahilinux.org/2024/02/conformant-gl46-on-the-m1/) +* [New in Fedora Asahi Remix](https://asahilinux.org/2024/01/fedora-asahi-new/) +* [Our new flagship distro: Fedora Asahi Remix](https://asahilinux.org/2023/08/fedora-asahi-remix/) +* [OpenGL 3.1 on Asahi Linux](https://asahilinux.org/2023/06/opengl-3-1-on-asahi-linux/) +* [Paving the Road to Vulkan on Asahi Linux](https://asahilinux.org/2023/03/road-to-vulkan/) +* [Apple GPU drivers now in Asahi Linux](https://asahilinux.org/2022/12/gpu-drivers-now-in-asahi-linux/) +* [Updates galore! November 2022 Progress Report](https://asahilinux.org/2022/11/november-2022-report/) +* [M2 is here! July 2022 Release & Progress Report](https://asahilinux.org/2022/07/july-2022-release/) +* [The first Asahi Linux Alpha Release is here!](https://asahilinux.org/2022/03/asahi-linux-alpha-release/) diff --git a/docs/Developer-Quickstart.md b/docs/platform/dev-quickstart.md similarity index 97% rename from docs/Developer-Quickstart.md rename to docs/platform/dev-quickstart.md index 38e8ba71..62c25e84 100644 --- a/docs/Developer-Quickstart.md +++ b/docs/platform/dev-quickstart.md @@ -1,8 +1,12 @@ +--- +title: Developer Quickstart Guide +--- + # THIS GUIDE IS LARGELY OBSOLETE This guide documents a manual installation process that is only required for kernel developers doing reverse engineering of macOS drivers using the m1n1 hypervisor. -If you are a more typical developer and you want to help work on the kernel or just experiment with the platform, and are happy doing tethered boots via USB (uploading the kernel from another machine), have a look [over here][Tethered-Boot-Setup-For-Developers.md]. +If you are a more typical developer and you want to help work on the kernel or just experiment with the platform, and are happy doing tethered boots via USB (uploading the kernel from another machine), have a look [over here][../sw/tethered-boot.md]. If you are an end user or you would otherwise like to set up a stand-alone install, stop now. It isn't ready yet. It will be soon. Just hang tight. @@ -59,7 +63,7 @@ The boot process: 4. The OS kernel (XNU/Darwin) boots * Mounts the root filesystem, etc -Read [[SW:Boot]] and [[M1 vs. PC Boot]] for more info. +Read [Boot](open-os-interop.md) and [PC Boot Process Differences](pc-boot-differences.md) for more info. Mini glossary: @@ -95,12 +99,11 @@ Notes: ### Further Reading -* [[Glossary]] -* [[SW:Boot]] -* [[M1 vs. PC Boot]] -* [[SW:NVRAM]] -* [[SW:NVRAM]] -* [[SW:Storage]] +* [Glossary](../project/glossary.md) +* [Boot](open-os-interop.md) +* [PC Boot Process Differences](pc-boot-differences.md) +* [NVRAM](../fw/nvram.md) +* [Stock Partition Layout](stock-partition-layout.md) ### If things go wrong @@ -223,7 +226,7 @@ M1 Macs expose their debug serial port over one of their Type C ports (the same The target machine can also be hard-rebooted using USB-PD VDM commands, making for a quick test cycle (no holding down power buttons). -See [[HW:USB-PD]] for details on the USB-PD VDM commands and what you can do with them. +See [USB-PD](../hw/soc/usb-pd.md) for details on the USB-PD VDM commands and what you can do with them. 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. @@ -288,7 +291,7 @@ In the coming weeks we'll be designing an open hardware interface for interfacin ### USB gadget mode using a standard USB cable -m1n1 now supports exposing its debug console and proxy interface via a standard USB [CDC-ACM](https://en.wikipedia.org/wiki/USB_communications_device_class) device. All you need is a standard USB cable (C to C or A to C, as appropriate for your host machine). ![USB Type-C to Type A cable](assets/USB-TypeC-A-cable.png) +m1n1 now supports exposing its debug console and proxy interface via a standard USB [CDC-ACM](https://en.wikipedia.org/wiki/USB_communications_device_class) device. All you need is a standard USB cable (C to C or A to C, as appropriate for your host machine). ![USB Type-C to Type A cable](../assets/USB-TypeC-A-cable.png) This interface is much faster than a serial port, and is the preferred way of using m1n1 remotely. However, a serial console is still recommended in addition to this for low-level debugging and development. @@ -323,7 +326,7 @@ picocom /dev/ttyACM1 Note that this method cannot (yet) be used as an earlycon for Linux, and USB gadget support is not yet in our main Linux tree either. -* See [Running Linux via USB cable](SW-Linux.md#running-linux-via-usb-cable) for some more details +* See [Running Linux via USB cable](../sw/linux-bringup.md#running-linux-via-usb-cable) for some more details ## Using m1n1 @@ -533,7 +536,7 @@ Proxy is alive again #### Boot a Linux kernel -This is what you're here for, right? :-). See [[SW:Linux]] for full instructions. +This is what you're here for, right? :-). See [Linux Bringup](../sw/linux-bringup.md) for full instructions. ```shell $ python linux.py -b 'earlycon console=ttySAC0,1500000 console=tty0 debug' Image.gz apple-j274.dtb initramfs.cpio.gz diff --git a/docs/M1-Series-Feature-Support.md b/docs/platform/feature-support/m1.md similarity index 99% rename from docs/M1-Series-Feature-Support.md rename to docs/platform/feature-support/m1.md index 80bd6642..e7f34b14 100644 --- a/docs/M1-Series-Feature-Support.md +++ b/docs/platform/feature-support/m1.md @@ -1,3 +1,7 @@ +--- +title: M1 Series Feature Support +--- + This page details currently supported features on all M1 series (M1, M1 Pro, M1 Max, M1 Ultra) Apple Silicon Macs, as well as their progress towards being upstreamed. The tables herein can be interpreted as follows: @@ -7,7 +11,7 @@ their progress towards being upstreamed. The tables herein can be interpreted as * **WIP**: Development work on the feature is actively progressing, however is not yet ready for wider testing, use or distribution * **TBA**: Active work on this feature is not being undertaken at this time -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)](When-will-Asahi-Linux-be-done.md). +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). ## Table of Contents - [SoC blocks](#soc-blocks) diff --git a/docs/M2-Series-Feature-Support.md b/docs/platform/feature-support/m2.md similarity index 99% rename from docs/M2-Series-Feature-Support.md rename to docs/platform/feature-support/m2.md index c8d96114..a66fed37 100644 --- a/docs/M2-Series-Feature-Support.md +++ b/docs/platform/feature-support/m2.md @@ -1,3 +1,7 @@ +--- +title: M2 Series Feature Support +--- + This page details currently supported features on all M2 series (M2, M2 Pro, M2 Max, M2 Ultra) Apple Silicon Macs, as well as their progress towards being upstreamed. The tables herein can be interpreted as follows: @@ -9,7 +13,7 @@ their progress towards being upstreamed. The tables herein can be interpreted as * **dts**: Feature is included as part of the Linux Device Tree system * **-**: Feature not supported by hardware on this platform -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)](When-will-Asahi-Linux-be-done.md). +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). ## Table of Contents - [SoC blocks](#soc-blocks) diff --git a/docs/M3-Series-Feature-Support.md b/docs/platform/feature-support/m3.md similarity index 98% rename from docs/M3-Series-Feature-Support.md rename to docs/platform/feature-support/m3.md index 2f9883ee..0668f814 100644 --- a/docs/M3-Series-Feature-Support.md +++ b/docs/platform/feature-support/m3.md @@ -1,3 +1,7 @@ +--- +title: M3 Series Feature Support +--- + This page details currently supported features on all M3 series (M3, M3 Pro, M3 Max) Apple Silicon Macs, as well as their progress towards being upstreamed. The tables herein can be interpreted as follows: @@ -8,7 +12,7 @@ their progress towards being upstreamed. The tables herein can be interpreted as * **WIP**: Development work on the feature is actively progressing, however is not yet ready for wider testing, use or distribution * **TBA**: Active work on this feature is not being undertaken at this time -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)](When-will-Asahi-Linux-be-done.md). +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). ## Table of Contents - [SoC blocks](#soc-blocks) diff --git a/docs/M4-Series-Feature-Support.md b/docs/platform/feature-support/m4.md similarity index 98% rename from docs/M4-Series-Feature-Support.md rename to docs/platform/feature-support/m4.md index 8cdb4c24..1c900877 100644 --- a/docs/M4-Series-Feature-Support.md +++ b/docs/platform/feature-support/m4.md @@ -1,3 +1,7 @@ +--- +title: M4 Series Feature Support +--- + This page details currently supported features on all M4 series (M4, M4 Pro, M4 Max) Apple Silicon Macs, as well as their progress towards being upstreamed. The tables herein can be interpreted as follows: @@ -8,7 +12,7 @@ their progress towards being upstreamed. The tables herein can be interpreted as * **WIP**: Development work on the feature is actively progressing, however is not yet ready for wider testing, use or distribution * **TBA**: Active work on this feature is not being undertaken at this time -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)](When-will-Asahi-Linux-be-done.md). +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). ## Table of Contents - [SoC blocks](#soc-blocks) diff --git a/docs/Feature-Support.md b/docs/platform/feature-support/overview.md similarity index 52% rename from docs/Feature-Support.md rename to docs/platform/feature-support/overview.md index c0cfa338..fa17b717 100644 --- a/docs/Feature-Support.md +++ b/docs/platform/feature-support/overview.md @@ -1,9 +1,13 @@ +--- +title: Feature Support Overview +--- + 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 page. Each page below follows the same format as the old unified page. -- [M1 Series (M1, M1 Pro, M1 Max, M1 Ultra) Feature Support](M1-Series-Feature-Support.md) -- [M2 Series (M2, M2 Pro, M2 Max, M2 Ultra) Feature Support](M2-Series-Feature-Support.md) -- [M3 Series (M3, M3 Pro, M3 Max) Feature Support](M3-Series-Feature-Support.md) -- [M4 Series (M4, M4 Pro, M4 Max) Feature Support](M4-Series-Feature-Support.md) +- [M1 Series (M1, M1 Pro, M1 Max, M1 Ultra) Feature Support](m1.md) +- [M2 Series (M2, M2 Pro, M2 Max, M2 Ultra) Feature Support](m2.md) +- [M3 Series (M3, M3 Pro, M3 Max) Feature Support](m3.md) +- [M4 Series (M4, M4 Pro, M4 Max) Feature Support](m4.md) A condensed feature overview for the Fedora Asahi Remix is available at [https://asahilinux.org/fedora/#device-support](https://asahilinux.org/fedora/#device-support). diff --git a/docs/Introduction-to-Apple-Silicon.md b/docs/platform/introduction.md similarity index 99% rename from docs/Introduction-to-Apple-Silicon.md rename to docs/platform/introduction.md index d8b97553..1cc28109 100644 --- a/docs/Introduction-to-Apple-Silicon.md +++ b/docs/platform/introduction.md @@ -1,3 +1,7 @@ +--- +title: Introduction to Apple Silicon +--- + ## Foreword This document attempts to explain the Apple Silicon (i.e. M1 and later) Mac boot ecosystem (henceforth "AS Macs"), as it pertains for how open OSes interoperate with the platform. @@ -132,11 +136,11 @@ recoveryOS is a macOS image that is used to provide an environment for users to recoveryOS can be requested via NVRAM variables on reboot, or can automatically be invoked after a certain number of boot failures. It is a minimal macOS image that presents the user with a recovery menu that allows them to change system security settings, partition disks, launch a web browser, launch a root terminal, reinstall macOS, etc. Network access is supported. -![recoveryOS](assets/recoveryos.png) +![recoveryOS](../assets/recoveryos.png) In addition, there is a "special" boot flow that grants additional capabilities. When the user powers up the machine by holding down the power button, this loads the recoveryOS paired with the currently active default boot OS volume (falling back to the system one), and first shows a boot picker to allow the user to choose an OS to boot (and optionally make the default): -![Boot Picker](assets/boot_picker.png) +![Boot Picker](../assets/boot_picker.png) If the user chooses "Options", they will be presented with the recoveryOS menu, as above. When booted this way, it is called "One True recoveryOS" (1TR), and it has additional powers granted to it by SEP (secure enclave) firmware. Additionally, this recoveryOS will be considered "paired" with the OS container it belongs to, and be able to perform specific operations on that OS. In particular, this mode is required in order to install a custom OS kernel. diff --git a/docs/SW-Keyboard-Layouts.md b/docs/platform/kb-layout-issues.md similarity index 99% rename from docs/SW-Keyboard-Layouts.md rename to docs/platform/kb-layout-issues.md index 8fed25b9..c55d3b9d 100644 --- a/docs/SW-Keyboard-Layouts.md +++ b/docs/platform/kb-layout-issues.md @@ -1,3 +1,7 @@ +--- +title: Mac keyboard layout issues +--- + Long story short, Mac keyboard layouts on Linux are a complete mess. We want to fix it. Please help us figure out what is wrong for *your* layout! Note: This is only for MacBook internal keyboards and also possibly external Apple keyboards. Please do not report issues with third-party keyboards. diff --git a/docs/Open-OS-Ecosystem-on-Apple-Silicon-Macs-historical.md b/docs/platform/open-os-interop-old.md similarity index 97% rename from docs/Open-OS-Ecosystem-on-Apple-Silicon-Macs-historical.md rename to docs/platform/open-os-interop-old.md index 09654f08..0524c370 100644 --- a/docs/Open-OS-Ecosystem-on-Apple-Silicon-Macs-historical.md +++ b/docs/platform/open-os-interop-old.md @@ -1,6 +1,10 @@ +--- +title: Open OS Platform Interoperability (Old Version) +--- + ## Foreword -This document presents our vision for how open OSes should interoperate on Apple Silicon (i.e. M1 and later) Macs. We recommend first reading [Introduction to Apple Silicon](Introduction-to-Apple-Silicon.md) to first learn how the platform is designed from Apple's perspective. +This document presents our vision for how open OSes should interoperate on Apple Silicon (i.e. M1 and later) Macs. We recommend first reading [Introduction to Apple Silicon](introduction.md) to first learn how the platform is designed from Apple's perspective. The ideas in this document are not intended to set hard requirements or rules; anyone is of course free (and encouraged) to go their own way if they so choose. Rather, we would like to agree on a set of standards that make it easier for different OSes to co-exist and be installed by end users, aiming to make the process as simple, seamless, and future-proof as possible. @@ -76,7 +80,7 @@ This boot chain is designed to progressively bring the system closer to a "typic ### m1n1 -m1n1 is our first-stage bootstrap for Apple Silicon systems. Its purpose is to bridge between the XNU boot protocol and the Device Tree / ARM64 Linux boot protocol, and do low-level bring-up so that subsequent boot stages do not have to be concerned with it. See the [m1n1 User Guide](m1n1-User-Guide.md) for more details on how it works. +m1n1 is our first-stage bootstrap for Apple Silicon systems. Its purpose is to bridge between the XNU boot protocol and the Device Tree / ARM64 Linux boot protocol, and do low-level bring-up so that subsequent boot stages do not have to be concerned with it. See the [m1n1 User Guide](../sw/m1n1-user-guide.md) for more details on how it works. m1n1 can also be puppeteered via USB for development and reverse engineering purposes, including loading kernels to allow for a very fast build-test cycle. It also features a bare-metal hypervisor that can boot Linux or macOS and provide a virtualized UART over USB, and includes advanced Python-based event tracing framework. These features are not intended for end users, but we hope they make OS development and testing on these platforms as enjoyable as possible. @@ -116,7 +120,7 @@ At this time, the Asahi Linux installer is supported as a purely online installe Future installation options could include: -* USB netinstall images/bundles, setting up the installer as "bootable install media". This can be set up by just unpacking some files to a FAT32 partition on a USB drive, so it is easy for users to use, and will allow them to select the installer from the boot picker ([more info](Introduction-to-Apple-Silicon.md#boot-picker) on how this magic works). It would still fetch the OS to be installed from the internet. +* USB netinstall images/bundles, setting up the installer as "bootable install media". This can be set up by just unpacking some files to a FAT32 partition on a USB drive, so it is easy for users to use, and will allow them to select the installer from the boot picker ([more info](introduction.md#boot-picker) on how this magic works). It would still fetch the OS to be installed from the internet. * USB local install images/bundles, which can also serve as UEFI install media for later or for other platforms. This will install the target OS from USB, but will still hit Apple's CDN for the Apple components, making the install not truly offline. * An option for end users to add the Apple components, e.g. by running a script from the USB drive, making it fully offline * An option for end users to add the Apple components when creating the USB installer, e.g. by running a script that downloads them and provisions the installer in one go, instead of a pre-baked image. diff --git a/docs/Open-OS-Ecosystem-on-Apple-Silicon-Macs.md b/docs/platform/open-os-interop.md similarity index 95% rename from docs/Open-OS-Ecosystem-on-Apple-Silicon-Macs.md rename to docs/platform/open-os-interop.md index 7f739676..823ce96d 100644 --- a/docs/Open-OS-Ecosystem-on-Apple-Silicon-Macs.md +++ b/docs/platform/open-os-interop.md @@ -1,6 +1,10 @@ +--- +title: Open OS Platform Interoperability +--- + ## Foreword -This document presents our vision for how open OSes should interoperate on Apple Silicon (i.e. M1 and later) Macs. We recommend first reading [Introduction to Apple Silicon](Introduction-to-Apple-Silicon.md) to first learn how the platform is designed from Apple's perspective. +This document presents our vision for how open OSes should interoperate on Apple Silicon (i.e. M1 and later) Macs. We recommend first reading [Introduction to Apple Silicon](introduction.md) to first learn how the platform is designed from Apple's perspective. The ideas in this document are not intended to set hard requirements or rules; anyone is of course free (and encouraged) to go their own way if they so choose. Rather, we would like to agree on a set of standards that make it easier for different OSes to co-exist and be installed by end users, aiming to make the process as simple, seamless, and future-proof as possible. @@ -33,7 +37,7 @@ Due to the presence of multiple ESPs, OSes will need a way to figure out which i ### Boot overview -A typical boot of a reference Linux system will go as follows, continuing on from the [Boot Flow](Introduction-to-Apple-Silicon.md#boot-flow) section: +A typical boot of a reference Linux system will go as follows, continuing on from the [Boot Flow](introduction.md#boot-flow) section: * iBoot2 loads the custom kernel, which is a build of m1n1 * m1n1 stage 1 runs and @@ -76,7 +80,7 @@ This boot chain is designed to progressively bring the system closer to a "typic ### m1n1 -m1n1 is our first-stage bootstrap for Apple Silicon systems. Its purpose is to bridge between the XNU boot protocol and the Device Tree / ARM64 Linux boot protocol, and do low-level bring-up so that subsequent boot stages do not have to be concerned with it. See the [m1n1 User Guide](m1n1-User-Guide.md) for more details on how it works. +m1n1 is our first-stage bootstrap for Apple Silicon systems. Its purpose is to bridge between the XNU boot protocol and the Device Tree / ARM64 Linux boot protocol, and do low-level bring-up so that subsequent boot stages do not have to be concerned with it. See the [m1n1 User Guide](../sw/m1n1-user-guide.md) for more details on how it works. m1n1 can also be puppeteered via USB for development and reverse engineering purposes, including loading kernels to allow for a very fast build-test cycle. It also features a bare-metal hypervisor that can boot Linux or macOS and provide a virtualized UART over USB, and includes advanced Python-based event tracing framework. These features are not intended for end users, but we hope they make OS development and testing on these platforms as enjoyable as possible. @@ -116,7 +120,7 @@ At this time, the Asahi Linux installer is supported as a purely online installe Future installation options could include: -* USB netinstall images/bundles, setting up the installer as "bootable install media". This can be set up by just unpacking some files to a FAT32 partition on a USB drive, so it is easy for users to use, and will allow them to select the installer from the boot picker ([more info](Introduction-to-Apple-Silicon.md#boot-picker) on how this magic works). It would still fetch the OS to be installed from the internet. +* USB netinstall images/bundles, setting up the installer as "bootable install media". This can be set up by just unpacking some files to a FAT32 partition on a USB drive, so it is easy for users to use, and will allow them to select the installer from the boot picker ([more info](introduction.md#boot-picker) on how this magic works). It would still fetch the OS to be installed from the internet. * USB local install images/bundles, which can also serve as UEFI install media for later or for other platforms. This will install the target OS from USB, but will still hit Apple's CDN for the Apple components, making the install not truly offline. * An option for end users to add the Apple components, e.g. by running a script from the USB drive, making it fully offline * An option for end users to add the Apple components when creating the USB installer, e.g. by running a script that downloads them and provisions the installer in one go, instead of a pre-baked image. @@ -186,4 +190,4 @@ An example implementation for Linux can be found in the [asahi-scripts](https:// Direct CPIO load can be accomplished with stock GRUB if `/boot` is the ESP mountpoint (i.e. GRUB and the kernels are directly installed in the ESP), using `GRUB_EARLY_INITRD_LINUX_STOCK=vendorfw/firmware.cpio` in `/etc/default/grub`. -Note: an [older version](Open-OS-Ecosystem-on-Apple-Silicon-Macs-historical.md) of this document proposed an alternate mechanism with a tarball and incremental updates of firmware on the root filesystem. This was found to be error-prone, insufficient when the initramfs is not involved, and incompatible with immutable-root setups, and is now deprecated. +Note: an [older version](open-os-interop-old.md) of this document proposed an alternate mechanism with a tarball and incremental updates of firmware on the root filesystem. This was found to be error-prone, insufficient when the initramfs is not involved, and incompatible with immutable-root setups, and is now deprecated. diff --git a/docs/M1-vs.-PC-Boot.md b/docs/platform/pc-boot-differences.md similarity index 98% rename from docs/M1-vs.-PC-Boot.md rename to docs/platform/pc-boot-differences.md index 8c3c3d4e..b4d14bc0 100644 --- a/docs/M1-vs.-PC-Boot.md +++ b/docs/platform/pc-boot-differences.md @@ -1,3 +1,7 @@ +--- +title: Boot flow deviations from the AMD64 PC platform +--- + 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. # SSD @@ -50,4 +54,4 @@ DFU does not exist on most PCs. If the UEFI flash is corrupted, the PC is bricke 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. -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. \ No newline at end of file +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. diff --git a/docs/Differences-with-other-platforms.md b/docs/platform/quirks.md similarity index 95% rename from docs/Differences-with-other-platforms.md rename to docs/platform/quirks.md index 38ac5afe..e3f343ce 100644 --- a/docs/Differences-with-other-platforms.md +++ b/docs/platform/quirks.md @@ -1,4 +1,8 @@ -This page is basically a TL;DR of [Open OS Ecosystem on Apple Silicon Macs](Open-OS-Ecosystem-on-Apple-Silicon-Macs.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. +--- +title: Apple Silicon Platform Quirks +--- + +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. ## This is not a typical UEFI platform @@ -37,4 +41,4 @@ If you nonetheless want to boot more than one OS from the same UEFI partition (w 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. -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. \ No newline at end of file +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. diff --git a/docs/Apple-Platform-Security-Crash-Course.md b/docs/platform/security.md similarity index 98% rename from docs/Apple-Platform-Security-Crash-Course.md rename to docs/platform/security.md index 9df787cd..89ed224b 100644 --- a/docs/Apple-Platform-Security-Crash-Course.md +++ b/docs/platform/security.md @@ -1,3 +1,7 @@ +--- +title: Apple Silicon Platform Security +--- + ## Introduction The Apple Silicon platform has been designed from the ground up to offer properly configured systems an extremely secure operating environment that is resilient to multiple forms of attack. The security @@ -5,7 +9,7 @@ model is based on the Swiss Cheese Model - no single security mechanism can guar level of security on its own, so mechanisms are layered to cover each others' holes. Platform security features are orchestrated by the Secure Enclave Processor (SEP). An overview of the SEP's -features, the different boot policies, and the boot picker itself is available at [Introduction to Apple Silicon](Introduction-to-Apple-Silicon.md). +features, the different boot policies, and the boot picker itself is available at [Introduction to Apple Silicon](introduction.md). This page instead attempts to extrapolate upon and clarify the concepts which may be of interest to users and system maintainers. @@ -175,4 +179,4 @@ macOS container. Asahi Linux creates a small APFS container and volume set with the correct file structure to be recognised as a valid OS, then uses Apple's tooling to set its security to Permissive and enroll m1n1 as its signed boot object. We do not - and never will - alter the security settings of _any other_ OS volume, nor will Apple's security -policies for those containers affect the Asahi volume. More details can be found at [Open OS Ecosystem on Apple Silicon Macs](Open-OS-Ecosystem-on-Apple-Silicon-Macs.md). \ No newline at end of file +policies for those containers affect the Asahi volume. More details can be found at [Open OS Ecosystem on Apple Silicon Macs](open-os-interop.md). diff --git a/docs/SW-Storage.md b/docs/platform/stock-partition-layout.md similarity index 99% rename from docs/SW-Storage.md rename to docs/platform/stock-partition-layout.md index 5fe0db2b..6cd7efef 100644 --- a/docs/SW-Storage.md +++ b/docs/platform/stock-partition-layout.md @@ -1,3 +1,7 @@ +--- +title: Stock SSD Partition Layout +--- + # Summary * **disk0**: main SSD diff --git a/docs/platform/subsystems.md b/docs/platform/subsystems.md new file mode 100644 index 00000000..af09325f --- /dev/null +++ b/docs/platform/subsystems.md @@ -0,0 +1,44 @@ +--- +title: Apple Silicon Platform Subsystems +--- + +These pages detail the specifics of a particular platform subsystem. They are loosely categorised +by function. + +### Generalised overviews +* [Introduction to Apple Silicon](introduction.md) +* [Accelerator Engines](../hw/soc/accelerators.md) + +### Coprocessors and accelerators +* [AGX](../hw/soc/agx.md) - Apple's PowerVR-derived tile-based deferred renderer +* [SEP](../hw/soc/sep.md) - The Secure Enclave, Apple's crypto/biometrics/security engine + +### Platform control logic +* [AIC](../hw/soc/aic.md) - Apple Interrupt Controller +* [WDT](../hw/soc/wdt.md) - Watchdog Timer +* [SMC](../hw/soc/smc.md) - System Management Controller +* [ASC](../hw/soc/asc.md) - Apple's Mailbox-like firmware interface + +### Platform initialisation and boot +* [Boot](../fw/boot.md) +* [MachO Boot Protocol](../fw/macho-boot-protocol.md) +* [Memory Map](../hw/soc/memmap.md) +* [SMP spinup](../hw/cpu/smp.md) +* [ADT](../fw/adt.md) (Apple Device Tree) +* [NVRAM](../fw/nvram.md) + +### Application processors +* [ARM System Registers](../hw/cpu/system-registers.md) +* [SPRR and GXF](../hw/cpu/sprr-gxf.md) +* [CPU Debug Registers](../hw/cpu/debug-registers.md) +* [Apple Instructions](../hw/cpu/apple-instructions.md) + +### I/O +* [APCIe](../hw/soc/apcie.md) (Apple PCIe controller) +* [GPIO](../hw/soc/gpio.md) +* [USB Debug](../hw/soc/usb-debug.md) +* [USB PD](../hw/soc/usb-pd.md) +* [Stock Partition Layout](stock-partition-layout.md) + +### Peripherals +* [Camera](../hw/peripherals/camera.md) - Broadcom camera and ISP diff --git a/docs/FAQ.md b/docs/project/faq.md similarity index 93% rename from docs/FAQ.md rename to docs/project/faq.md index 8facbd2f..4381fb61 100644 --- a/docs/FAQ.md +++ b/docs/project/faq.md @@ -1,10 +1,14 @@ +--- +title: FAQ +--- + ## When will Asahi Linux be "done"? -→ ["When will Asahi Linux be done?"](When-will-Asahi-Linux-be-done.md) +→ ["When will Asahi Linux be done?"](when-will-asahi-be-done.md) ## Does $thing work yet? -→ [Feature Support](Feature-Support.md) +→ [Feature Support](../platform/feature-support/overview.md) ## How do I install it? @@ -12,7 +16,7 @@ See the website for instructions: https://asahilinux.org/ ## How do I uninstall / clean up a failed installation? -There is no automated uninstaller, but see [Partitioning cheatsheet](Partitioning-cheatsheet.md) to learn how to delete the partitions manually. +There is no automated uninstaller, but see [Partitioning cheatsheet](../sw/partitioning-cheatsheet.md) to learn how to delete the partitions manually. ## Can I dual boot Asahi Linux? @@ -48,7 +52,7 @@ As the message implies, this is caused by Time Machine snapshots taking up "free ### Disk Utility doesn't work for me after installing / for uninstalling / any other time! -Don't use Disk Utility, it's broken and only works for really simple partition setups. See [Partitioning cheatsheet](Partitioning-cheatsheet.md) to learn how to manage partitions with the command line instead. +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. ## Do I need to reinstall to get new features / updates? diff --git a/docs/Glossary.md b/docs/project/glossary.md similarity index 97% rename from docs/Glossary.md rename to docs/project/glossary.md index 5bbfb9ac..926135ae 100644 --- a/docs/Glossary.md +++ b/docs/project/glossary.md @@ -1,3 +1,7 @@ +--- +title: Glossary +--- + Useful terms to know. Add terms specific to the hardware, reverse engineering, and Apple ecosystems that are relevant. Don't add things that everyone is expected to know (CPU, GPU, HDD, SSD, OSX, USB, HDMI, RAM, etc.) or which are not likely to be relevant to the project. Think of the target audience as "random Linux developer". @@ -48,7 +52,7 @@ If you want to collect a large set of terms specific to a sub-field (such as GPU ### G * **GPT**: GUID Partition Table: A partition table format created for EFI/UEFI and now used on most modern systems. -* **GXF**: probably Guarded Execution Function. Lateral exception levels used to create a low-overhead hypervisor to protect pagetables and equally important structures from XNU itself. See e.g. [Sven's write-up](https://blog.svenpeter.dev/posts/m1_sprr_gxf/) or [HW-SPRR-and-GXF](HW-SPRR-and-GXF.md) +* **GXF**: probably Guarded Execution Function. Lateral exception levels used to create a low-overhead hypervisor to protect pagetables and equally important structures from XNU itself. See e.g. [Sven's write-up](https://blog.svenpeter.dev/posts/m1_sprr_gxf/) or [SPRR and GXF](../hw/cpu/sprr-gxf.md) ### H * **HFS+**: Hierarchical Filesystem+: Apple's previous filesystem, used for external storage. Not used for internal storage on M1 Macs. @@ -63,7 +67,7 @@ If you want to collect a large set of terms specific to a sub-field (such as GPU * **IOMMU**: I/O Memory Management Unit, a more general term for Apple's DART. * **IOKit**: I/O Kit is Apple's device driver framework for XNU (Apple's operating system kernel). * **IPI**: Inter-processor interupt. An interrupt used by one processor to interrupt another. -* **iSC**: iBoot System Container. A disk partition (usually first on the internal SSD) containing the system wide boot data. (See [SW-Storage](SW-Storage.md)) +* **iSC**: iBoot System Container. A disk partition (usually first on the internal SSD) containing the system wide boot data. (See [Stock Partition Layout](../platform/stock-partition-layout.md)) * **ISP**: Image Signal Processor. Webcam on M-series laptops. Denotes the entire camera unit, from sensors to strobe to the coprocessor. ### J @@ -104,11 +108,11 @@ If you want to collect a large set of terms specific to a sub-field (such as GPU * **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. * **SFR**: System Firmware and Recovery, the collection of firmware and the recovery image shared by all OSes installed on the system, including components in NOR (like iBoot1), the iBoot System Container, the System Recovery partition, and external Flash memories and other miscellaneous locations. SFR always goes forward in version, never backwards (other than via a full wipe). * **SIP**: System Integrity Protection. Also called "rootless", where the macOS kernel stops even root from doing some things. -* **SMC**: System Management Controller: 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. See [HW-SMC](HW-SMC.md) +* **SMC**: System Management Controller: 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. See [SMC](../hw/soc/smc.md) * **SOP**: Start Of Packet. Used to differentiate packet types in USB-PD. SOP for normal comms, SOP' and SOP" to talk to built-in chips in a cable, SOP'DEBUG and SOP"DEBUG for custom vendor specific things like Apple VDMs. * **SPI**: Serial Peripheral Interface. A 4-wire standard for communicating at low speed between chips on a board. * **SPMI**: System Power Management Interface from MIPI Alliance: 2-wire bi-directional interface, Multi master(up to 4), Multi slave(up to 16), 32KHz to 26MHz. See [System Power Management Interface](https://en.wikipedia.org/wiki/System_Power_Management_Interface) -* **SPRR**: probably Shadow Permission Remap Registers. Turns the normal page permission attributes (AP,PXN,UXN) into an index to a separate table. This new table then determines the real page permissions. Also disallows pages that writeable and executable at the same time. See e.g. [Sven's write-up](https://blog.svenpeter.dev/posts/m1_sprr_gxf/) or [HW-SPRR-and-GXF](HW-SPRR-and-GXF.md) +* **SPRR**: probably Shadow Permission Remap Registers. Turns the normal page permission attributes (AP,PXN,UXN) into an index to a separate table. This new table then determines the real page permissions. Also disallows pages that writeable and executable at the same time. See e.g. [Sven's write-up](https://blog.svenpeter.dev/posts/m1_sprr_gxf/) or [SPRR and GXF](../hw/cpu/sprr-gxf.md) * **SWD**: Serial Wire Debug. A 2-pin interface used for debugging ARM cores, like JTAG over fewer pins. Used on Apple devices, but inaccessible (for the main CPU/SoC) in production devices due to security restrictions. ### T diff --git a/docs/Yaks-in-need-of-shaving.md b/docs/project/help-wanted.md similarity index 93% rename from docs/Yaks-in-need-of-shaving.md rename to docs/project/help-wanted.md index d3537394..6fd18b61 100644 --- a/docs/Yaks-in-need-of-shaving.md +++ b/docs/project/help-wanted.md @@ -1,3 +1,7 @@ +--- +title: Help Wanted! +--- + 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. 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 in general. @@ -9,7 +13,7 @@ any questions or are in need of assistance. | ---- | ------ | ----------- | ------- | | 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 | | Bankstown enhancements | Unclaimed | Our psychoacoustic bass enhancer needs some work to clean up the output. There are some filtering tricks that can be done to make it sound better, however someone with more experience in DSP for audio applications should probably handle this. All PRs will be tested by ear on J314, J475, and J415. | chadmed | -| Extend tipd driver | **Unclaimed** | Add support to reset other Apple Silicon machines, and to enable serial, to [tipd](https://github.com/AsahiLinux/linux/blob/asahi/drivers/usb/typec/tipd/core.c). On the Macs, some parts of the USB specification are implemented by (undocumented) CD321x chips, similar to [TPS65982](https://www.ti.com/lit/ds/symlink/tps65982.pdf). Apple added some [debugging features](HW-USB-PD.md) to their Type-C ports, and if we want to make use of those when running Linux on an M1/M2 host for development (connected to another M1/M2 machine being the target of experimentation), we need to extend the `tipd` driver. | suggested by sven | +| Extend tipd driver | **Unclaimed** | Add support to reset other Apple Silicon machines, and to enable serial, to [tipd](https://github.com/AsahiLinux/linux/blob/asahi/drivers/usb/typec/tipd/core.c). On the Macs, some parts of the USB specification are implemented by (undocumented) CD321x chips, similar to [TPS65982](https://www.ti.com/lit/ds/symlink/tps65982.pdf). Apple added some [debugging features](../hw/soc/usb-pd.md) to their Type-C ports, and if we want to make use of those when running Linux on an M1/M2 host for development (connected to another M1/M2 machine being the target of experimentation), we need to extend the `tipd` driver. | suggested by sven | | Bluetooth suspend | **Unclaimed** | Currently, when suspending and then resuming Bluetooth breaks. This is either an issue with the way hci_bcm4377 uses the bluetooth suspend API or we are missing some special vendor-specific commands before suspend or after resume. It's probably possible to figure this out without making the hypervisor survive a full suspend/resume cycle by using Apple's PacketLogger which is part of the "Additional Tools for XCode" to look for additional commands. It's probably also a good idea to compare how hci_bcm4377 suspend works to other Bluetooth drivers since it's also possible that it's just misusing some API that gets the device stuck in a wrong state. | sven | | 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)| marcan | | Various unexplained errors | Unclaimed | As of asahi-6.8.10-4, there continue to be a variety of low-severity messages logged in the dmesg. They don't appear to prevent proper functioning, but someone with kernel debugging experience should track them down and submit fixes for them. Here are [some examples](https://gist.github.com/zzywysm/d4f1669ff3b7454e2821a65e31c511e1) from a M1 MacBook Air, found by running `sudo dmesg`. | ? | diff --git a/docs/Project-References.md b/docs/project/references.md similarity index 96% rename from docs/Project-References.md rename to docs/project/references.md index 33fcc2b7..fd466690 100644 --- a/docs/Project-References.md +++ b/docs/project/references.md @@ -1,3 +1,8 @@ +--- +title: Miscellaneous References +--- + + ### Web References These are just some references for people to build some background knowledge into getting Linux working on Apple Silicon. diff --git a/docs/Trivia.md b/docs/project/trivia.md similarity index 89% rename from docs/Trivia.md rename to docs/project/trivia.md index 258b9f4c..9eb349eb 100644 --- a/docs/Trivia.md +++ b/docs/project/trivia.md @@ -1,3 +1,7 @@ +--- +title: Platform Trivia +--- + A list of random fun trivia about this platform and its legacy. # iPhone legacy @@ -7,7 +11,7 @@ When an M1 Mac Mini is booted without a display connected, or unconditionally as Then this happens: -![Framebuffer](assets/m1_iphone_5_fb.png) +![Framebuffer](../assets/m1_iphone_5_fb.png) ## Just can't let go of Samsung @@ -39,8 +43,8 @@ The DisplayPort to HDMI bridge chip in the Mac Mini and 14"/16" MacBook Pros (MD ## Help me! -The Mac’s [SecureROM](SW-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. -If you start the Mac in [DFU mode](Glossary.md#d), the LED will be amber instead of white. +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. +If you start the Mac in [DFU mode](glossary.md#d), the LED will be amber instead of white. 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… diff --git a/docs/When-will-Asahi-Linux-be-done.md b/docs/project/when-will-asahi-be-done.md similarity index 93% rename from docs/When-will-Asahi-Linux-be-done.md rename to docs/project/when-will-asahi-be-done.md index 73b902c5..c50ff879 100644 --- a/docs/When-will-Asahi-Linux-be-done.md +++ b/docs/project/when-will-asahi-be-done.md @@ -1,4 +1,8 @@ -If you're after the support status of a specific feature, [Feature Support](Feature-Support.md) has a list of all major hardware included in the Apple Silicon Macs, as well as its level of support. +--- +title: When Will Asahi Be Done? +--- + +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. ## Why you shouldn't ask this question on IRC @@ -26,7 +30,7 @@ Next, we consider the case of someone who is actively testing bleeding edge driv 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. ## What this means for you -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](Feature-Support.md) to decide if the time is right for you to try out Linux on Apple Silicon. +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. ## A note on new hardware diff --git a/docs/SW-AGX-driver-notes.md b/docs/sw/agx-driver-notes.md similarity index 98% rename from docs/SW-AGX-driver-notes.md rename to docs/sw/agx-driver-notes.md index d8a35390..b208a1d5 100644 --- a/docs/SW-AGX-driver-notes.md +++ b/docs/sw/agx-driver-notes.md @@ -1,6 +1,10 @@ +--- +title: AGX Driver Notes +--- + ## General docs * [Alyssa's Driver Survival Guide](https://rosenzweig.io/AlyssasDriverSurvivalGuide.txt) -* [HW-AGX](HW-AGX.md) (somewhat outdated) +* [AGX](../hw/soc/agx.md) (somewhat outdated) ## Git links * [Upstream Mesa](https://gitlab.freedesktop.org/mesa/mesa) ([merge requests](https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests?label_name%5B%5D=asahi)) @@ -107,4 +111,4 @@ Other: * [ ] Hook up firmware KTrace to Linux tracing * [ ] Complete the VM management (arbitrary subrange maps/unmaps) * [ ] Performance counters -* [ ] M2 Pro/Max support \ No newline at end of file +* [ ] M2 Pro/Max support diff --git a/docs/SW-Speakers.md b/docs/sw/audio-userspace.md similarity index 99% rename from docs/SW-Speakers.md rename to docs/sw/audio-userspace.md index 29d9e767..99d48859 100644 --- a/docs/SW-Speakers.md +++ b/docs/sw/audio-userspace.md @@ -1,3 +1,7 @@ +--- +title: Userspace Audio Stack +--- + # Speaker support in Asahi Linux Currently supported models: @@ -57,4 +61,4 @@ You can watch speakersafetyd in action by using `sudo journalctl -fu speakersafe Requirements according to [asahi-audio](https://github.com/AsahiLinux/asahi-audio)'s [README.md](https://github.com/AsahiLinux/asahi-audio/blob/main/README.md). -The correct deployment order is asahi-audio/speakersafetyd > (whatever you use to get those installed for users, e.g. metapackage) > kernel. If you push the kernel first before asahi-audio, users will get either a nonfunctional (if no speakersafetyd) or functional but bad-sounding (if speakersafetyd is installed) raw speaker device with no DSP. \ No newline at end of file +The correct deployment order is asahi-audio/speakersafetyd > (whatever you use to get those installed for users, e.g. metapackage) > kernel. If you push the kernel first before asahi-audio, users will get either a nonfunctional (if no speakersafetyd) or functional but bad-sounding (if speakersafetyd is installed) raw speaker device with no DSP. diff --git a/docs/Broken-Software.md b/docs/sw/broken-software.md similarity index 99% rename from docs/Broken-Software.md rename to docs/sw/broken-software.md index a2ab0648..acf396a6 100644 --- a/docs/Broken-Software.md +++ b/docs/sw/broken-software.md @@ -1,3 +1,7 @@ +--- +title: Broken Software +--- + This page lists software that is known not to work correctly on Apple Silicon machines. We publish it in the hope that it incentivizes inclined members of the community to contribute fixes for the affected packages upstream, bettering the AArch64 software ecosystem for everyone. diff --git a/docs/Delete-an-Installation.md b/docs/sw/deleting-an-install.md similarity index 98% rename from docs/Delete-an-Installation.md rename to docs/sw/deleting-an-install.md index a9247935..8a036898 100644 --- a/docs/Delete-an-Installation.md +++ b/docs/sw/deleting-an-install.md @@ -1,3 +1,7 @@ +--- +title: Deleting an installation +--- + # This is for default vanilla Asahi installs. These steps do not apply for custom partitioning setups. ## Do not use Diskutil GUI @@ -103,4 +107,4 @@ diskutil apfs resizeContainer disk 0 ``` ### Errors? Need More Background Information? -[Partitioning cheatsheet](Partitioning-cheatsheet.md) +[Partitioning cheatsheet](partitioning-cheatsheet.md) diff --git a/docs/SW-DT-bindings.md b/docs/sw/devicetree-bindings.md similarity index 92% rename from docs/SW-DT-bindings.md rename to docs/sw/devicetree-bindings.md index 3925eec6..3265aff2 100644 --- a/docs/SW-DT-bindings.md +++ b/docs/sw/devicetree-bindings.md @@ -1,3 +1,7 @@ +--- +title: Devicetree Bindings +--- + ### PMGR - 'apple,t6000-pmgr' - 'apple,t8103-pmgr' @@ -46,4 +50,4 @@ Soon to be used by OpenBSD; not submitted upstream yet - 'apple,t8103-nvme-ans2' - 'apple,nvme-ans2' -Not submitted upstream yet \ No newline at end of file +Not submitted upstream yet diff --git a/docs/sw/getting-started.md b/docs/sw/getting-started.md new file mode 100644 index 00000000..e4f40225 --- /dev/null +++ b/docs/sw/getting-started.md @@ -0,0 +1,5 @@ +--- +title: Getting Started +--- + +Obsolete, you want [Developer Quickstart](../platform/dev-quickstart.md) diff --git a/docs/Kernel-config-notes-for-distros.md b/docs/sw/kernel-config.md similarity index 98% rename from docs/Kernel-config-notes-for-distros.md rename to docs/sw/kernel-config.md index b7e6925a..cdcf176f 100644 --- a/docs/Kernel-config-notes-for-distros.md +++ b/docs/sw/kernel-config.md @@ -1,3 +1,7 @@ +--- +title: Apple Silicon Kernel Config Options +--- + Your kernel configuration will need to include the Asahi-specific drivers. As of linux-asahi-6.12.4-1, this list is: ``` @@ -129,5 +133,3 @@ CONFIG_APPLE_MFI_FASTCHARGE=m ``` 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. - -For a reference kernel configuration, see [here](Reference-Asahi-kernel-config.md). diff --git a/docs/SW-Linux-NVME.md b/docs/sw/linux-bringup-nvme.md similarity index 97% rename from docs/SW-Linux-NVME.md rename to docs/sw/linux-bringup-nvme.md index b3fd4e61..927d9695 100644 --- a/docs/SW-Linux-NVME.md +++ b/docs/sw/linux-bringup-nvme.md @@ -1,3 +1,7 @@ +--- +title: Linux Bringup: NVME +--- + # USB drive boot ## The easy way * 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. @@ -23,7 +27,7 @@ sudo cp /usr/bin/qemu-aarch64-static debinst/usr/bin * Install the rootfs you created above onto the drive `sudo cp -a debinst/. /mnt/img` * Unmount the drive `sudo umount /mnt/img` ### Boot with USB drive as root - * Back to [booting over USB cable](SW-Linux.md#running-linux-via-usb-cable) + * Back to [booting over USB cable](linux-bringup.md#running-linux-via-usb-cable) * Make sure you have the latest m1n1.macho loaded `python3 proxyclient/tools/chainload.py build/m1n1.macho` * Build a kernel with builtin features (check for =m and change to =y in .config) * In particular need CONFIG_EXT4_FS=y is needed to boot! diff --git a/docs/SW-Linux-USBKeyboard.md b/docs/sw/linux-bringup-usb-keyboard.md similarity index 87% rename from docs/SW-Linux-USBKeyboard.md rename to docs/sw/linux-bringup-usb-keyboard.md index 7983fa51..27c23cd3 100644 --- a/docs/SW-Linux-USBKeyboard.md +++ b/docs/sw/linux-bringup-usb-keyboard.md @@ -1,3 +1,7 @@ +--- +title: Linux Bringup: USB Keyboard +--- + # Linux USB keyboard * Got a USB keyboard working with an ramdisk root filesystem. * By booting the [Asahi dart/dev kernel](https://github.com/AsahiLinux/linux/tree/dart/dev) with USB3 XHCD, DWC3 and DART et cetera @@ -6,6 +10,6 @@ * 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``` * 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. * 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. -![Linux running on M1 macbook with input via external USB keyboard](assets/linuxOnM1.png) +![Linux running on M1 macbook with input via external USB keyboard](../assets/linuxOnM1.png) - * You can go one step further and try [booting a USB drive](SW-Linux-USB-drive.md) + * You can go one step further and try [booting a USB drive](linux-bringup-usb.md) diff --git a/docs/SW-Linux-USB-drive.md b/docs/sw/linux-bringup-usb.md similarity index 98% rename from docs/SW-Linux-USB-drive.md rename to docs/sw/linux-bringup-usb.md index 62b2cb86..24302a22 100644 --- a/docs/SW-Linux-USB-drive.md +++ b/docs/sw/linux-bringup-usb.md @@ -1,3 +1,7 @@ +--- +title: Linux Bringup: USB +--- + ## root as USB drive * Inspired by [Alyssa's tomshardware article](https://www.tomshardware.com/news/apple-m1-debian-linux) * Make an **arm64** root filesystem as per [debian rootfs](https://www.debian.org/releases/stretch/arm64/apds03.html.en) diff --git a/docs/SW-Linux-WiFi.md b/docs/sw/linux-bringup-wifi.md similarity index 81% rename from docs/SW-Linux-WiFi.md rename to docs/sw/linux-bringup-wifi.md index e518f9fc..65cc0d7e 100644 --- a/docs/SW-Linux-WiFi.md +++ b/docs/sw/linux-bringup-wifi.md @@ -1,3 +1,7 @@ +--- +title: Linux Bringup: WiFi +--- + # WiFi Support ## Under MacOS grab the WiFi firmware as per [Glanzmann's notes](https://tg.st/u/asahi.txt) * Clone the installer @@ -7,14 +11,14 @@ * Grab the firmware into a tar file `python3 -m firmware.wifi /usr/share/firmware/wifi /tmp/linux-firmware.tar` ## Install firmware - * Under Linux booted via [USB drive](SW-Linux-USB-drive.md) or [nvme](SW-Linux-NVME.md) rootfs Create the firmware directory: + * Under Linux booted via [USB drive](linux-bringup-usb.md) or [NVMe](linux-bringup-nvme.md) rootfs Create the firmware directory: `sudo mkdir -p /usr/lib/firmware` * Install the wifi firmware you extracted earlier `sudo tar -C /usr/lib/firmware -xf firmware.tar` * Install any other networking / WiFi packages you will need. e.g. wpasupplicant ## Enable WiFi * 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 - * Before you boot that kernel via [m1n1 over USB](SW-Linux.md#directly) - run this script to enable the WiFi hardware + * Before you boot that kernel via [m1n1 over USB](linux-bringup.md#directly) - run this script to enable the WiFi hardware `python3 ./proxyclient/experiments/pcie_enable_devices.py` * There are other ways to do this - this what I did under Debian linux * Now after the linux kernel has booted you should be able to see a WiFi device (wlan0) via the usual tools diff --git a/docs/SW-Linux-X11.md b/docs/sw/linux-bringup-x11.md similarity index 90% rename from docs/SW-Linux-X11.md rename to docs/sw/linux-bringup-x11.md index 3c32271b..b55cc676 100644 --- a/docs/SW-Linux-X11.md +++ b/docs/sw/linux-bringup-x11.md @@ -1,3 +1,7 @@ +--- +title: Linux Bringup: X11 +--- + # Running X11 * You can run a non-accelerated X11 if you build the kernel with `CONFIG_DRM_FBDEV_EMULATION=y` @@ -17,4 +21,4 @@ * For a web browser install firefox as Chrome requires special kernel paging support (not available at this time) `sudo apt install firefox-esr` -(![X11 running on Macbook Air 2020](assets/mba-xorg-fbdev.png)) +(![X11 running on Macbook Air 2020](../assets/mba-xorg-fbdev.png)) diff --git a/docs/SW-Linux.md b/docs/sw/linux-bringup.md similarity index 95% rename from docs/SW-Linux.md rename to docs/sw/linux-bringup.md index f84dde1f..3a7871c1 100644 --- a/docs/SW-Linux.md +++ b/docs/sw/linux-bringup.md @@ -1,3 +1,7 @@ +--- +title: Linux Bringup +--- + # Building Linux * See github linux [Asahi Kernel](https://github.com/AsahiLinux/linux) for the latest Asahi kernel patched for M1 support * In particular according to [Dec 2021 progress report](https://asahilinux.org/2021/12/progress-report-oct-nov-2021/) you can try the [asahi branch](https://github.com/AsahiLinux/linux/tree/asahi) which "...is a bleeding edge kernel ... in a usable enough state that we would like people to test..." @@ -26,13 +30,13 @@ cp ../linux/arch/arm64/boot/dts/apple/t8103-j274.dtb t8103-j274.dtb ### keyboard + nvme working * Snapshot of [rev a2281d64fdbc](https://github.com/amworsley/AsahiLinux/tree/asahi-kbd) with config such as [this one](https://raw.githubusercontent.com/amworsley/asahi-wiki/main/images/config-keyboard+nvme) ## Boot with your USB cables plugged in - * Plug your USB cables/hubs/adapters **before** booting your Mac as m1n1/linux doesn't do the USB low level PHY setup yet. Let the iBoot do this when it boots to m1n1 you installed via your [setup of boot to m1n1](Developer-Quickstart.md#setup) + * Plug your USB cables/hubs/adapters **before** booting your Mac as m1n1/linux doesn't do the USB low level PHY setup yet. Let the iBoot do this when it boots to m1n1 you installed via your [setup of boot to m1n1](../platform/dev-quickstart.md#setup) * If m1n1 C code has been updated since the set up you should chain load the new .macho image ``` python3.9 proxyclient/tools/chainload.py build/m1n1.macho ``` # Running Linux via USB cable - * Connecting [USB Type-C to Type A/C cable](Developer-Quickstart.md#usb-gadget-mode-using-a-standard-usb-cable) to M1 Mac provides two USB serial interfaces on the other computer![USB Type-C to Type A cable connecting M1 MacBookAir and 2012 MacBootAir Pro](assets/usb-setup.png) + * Connecting [USB Type-C to Type A/C cable](../platform/dev-quickstart.md#usb-gadget-mode-using-a-standard-usb-cable) to M1 Mac provides two USB serial interfaces on the other computer![USB Type-C to Type A cable connecting M1 MacBookAir and 2012 MacBootAir Pro](../assets/usb-setup.png) * This can be connected to via the python proxy tool to boot up Linux directly or load up a macho binary like an updated m1n1 version or combined with a Linux image * Get a 27Mb initrd from debian arm64 installer ``` @@ -385,12 +389,12 @@ Still running 21 # Root filesystem options - * [initrd + USB keyboard](SW-Linux-USBKeyboard.md#linux-usb-keyboard) - * [USB drive boot](SW-Linux-USB-drive.md) - * [USB Drive to NVME partition](SW-Linux-NVME.md) + * [initrd + USB keyboard](linux-bringup-usb-keyboard.md#linux-usb-keyboard) + * [USB drive boot](linux-bringup-usb.md) + * [USB Drive to NVME partition](linux-bringup-nvme.md) # Other features - * [WiFi Support](SW-Linux-WiFi.md) - * [X11 Support](SW-Linux-X11.md) + * [WiFi Support](linux-bringup-wifi.md) + * [X11 Support](linux-bringup-x11.md) # Missing * Sound * Power management - do **NOT** shut the lid diff --git a/docs/m1n1-Developer-Guide.md b/docs/sw/m1n1-dev-guide.md similarity index 96% rename from docs/m1n1-Developer-Guide.md rename to docs/sw/m1n1-dev-guide.md index 0f7561ad..e6dd76ef 100644 --- a/docs/m1n1-Developer-Guide.md +++ b/docs/sw/m1n1-dev-guide.md @@ -1,3 +1,7 @@ +--- +title: m1n1 Developer Guide +--- + (Not written yet, just throwing some stuff in) ## Boot protocol diff --git a/docs/SW-Hypervisor.md b/docs/sw/m1n1-hypervisor.md similarity index 98% rename from docs/SW-Hypervisor.md rename to docs/sw/m1n1-hypervisor.md index 8fff7fc4..aa4080da 100644 --- a/docs/SW-Hypervisor.md +++ b/docs/sw/m1n1-hypervisor.md @@ -1,3 +1,7 @@ +--- +title: m1n1 Hypervisor +--- + # Running macOS under the m1n1 hypervisor 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. @@ -61,7 +65,7 @@ Check that `Install macOS Monterey.app` in the `applications` folder is ~12GB. 1. Start into 1tr and start a terminal. 2. Disable most security feature in the boot policy: `bputil -nkcas`; use `diskutil info [disk name]` to get UUID. 3. Disable SIP (bputil resets it): `csrutil disable`. -4. Install [m1n1](m1n1-User-Guide.md) as custom boot object: +4. Install [m1n1](m1n1-user-guide.md) as custom boot object: kmutil configure-boot \ -c build/m1n1.bin \ diff --git a/docs/m1n1-User-Guide.md b/docs/sw/m1n1-user-guide.md similarity index 97% rename from docs/m1n1-User-Guide.md rename to docs/sw/m1n1-user-guide.md index 6a68a312..95e3e16c 100644 --- a/docs/m1n1-User-Guide.md +++ b/docs/sw/m1n1-user-guide.md @@ -1,3 +1,7 @@ +--- +title: m1n1 User Guide +--- + m1n1 is the bootloader developed by the Asahi Linux project to bridge the Apple (XNU) boot ecosystem to the Linux boot ecosystem. GitHub: [AsahiLinux/m1n1](https://github.com/AsahiLinux/m1n1) @@ -13,7 +17,7 @@ GitHub: [AsahiLinux/m1n1](https://github.com/AsahiLinux/m1n1) * Configuration statements * Chainloads another version of itself from a FAT32 partition (if configured to do so) -Proxy mode enables a huge toolset of developer features, from reducing your Linux kernel test cycle to 7 seconds, to live hardware probing and experimentation, to a hypervisor capable of running macOS or Linux and tracing hardware accesses in real time while providing a virtual UART over USB. See the [m1n1 Developer Guide](m1n1-Developer-Guide.md) for that. This guide only describes trivial proxy use cases. +Proxy mode enables a huge toolset of developer features, from reducing your Linux kernel test cycle to 7 seconds, to live hardware probing and experimentation, to a hypervisor capable of running macOS or Linux and tracing hardware accesses in real time while providing a virtual UART over USB. See the [m1n1 Developer Guide](m1n1-dev-guide.md) for that. This guide only describes trivial proxy use cases. ## Building @@ -152,7 +156,7 @@ If given no payloads, or if booting the payloads fails, m1n1 will fall back to p ## Proxy mode -Proxy mode provides a USB device interface (available on all Thunderbolt ports) for debugging. To use it, connect your target device to your host device with a USB cable (e.g. a USB-C to USB-A cable, with the C side on the m1n1 target). See the [m1n1 Developer Guide](m1n1-Developer-Guide.md) for all the crazy details. These are just some simple examples of what you can do. +Proxy mode provides a USB device interface (available on all Thunderbolt ports) for debugging. To use it, connect your target device to your host device with a USB cable (e.g. a USB-C to USB-A cable, with the C side on the m1n1 target). See the [m1n1 Developer Guide](m1n1-dev-guide.md) for all the crazy details. These are just some simple examples of what you can do. When in proxy mode, a Linux host will see two USB TTY ACM devices, typically /dev/ttyACM0 & /dev/ttyACM1. (In macOS this will be /dev/cu.usbmodemP_01 and /dev/cu.usbmodemP_03). The first one is the proper proxy interface, while the second one is reserved for use by the hypervisor's virtual UART feature. You should set the `M1N1DEVICE` environment variable to the path to the right device. @@ -204,7 +208,7 @@ $ ./proxyclient/tools/run_guest_kernel.sh [kernel build root] [boot args] [initr ### Running a macOS kernel as a m1n1 hypervisor guest -See [SW-Hypervisor](SW-Hypervisor.md) +See [m1n1 Hypervisor](m1n1-hypervisor.md) ### Backdoor proxy mode in stage 1 release builds diff --git a/docs/RE:Kernelcache.md b/docs/sw/macos-kernelcache.md similarity index 99% rename from docs/RE:Kernelcache.md rename to docs/sw/macos-kernelcache.md index 37a1d322..7a67264e 100644 --- a/docs/RE:Kernelcache.md +++ b/docs/sw/macos-kernelcache.md @@ -1,3 +1,7 @@ +--- +title: macOS Kernelcache +--- + # READ THIS BEFORE PROCEEDING FURTHER **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.** diff --git a/docs/Partitioning-cheatsheet.md b/docs/sw/partitioning-cheatsheet.md similarity index 99% rename from docs/Partitioning-cheatsheet.md rename to docs/sw/partitioning-cheatsheet.md index 3cf82283..37735703 100644 --- a/docs/Partitioning-cheatsheet.md +++ b/docs/sw/partitioning-cheatsheet.md @@ -1,3 +1,7 @@ +--- +title: Partitioning Cheatsheet +--- + # WARNING: NEVER DELETE THE `Apple_APFS_Recovery` PARTITION The last partition on your disk, listed as type `Apple_APFS_Recovery` in diskutil, contains critical system recovery components. **If you delete this partition accidentally, macOS upgrades will cease to work, and any other problem with your system will leave it unbootable and require a factory restore and complete wipe**. Restoring this partition without a full machine wipe is [a major pain in the ass](https://www.reddit.com/r/AsahiLinux/comments/1fmnzm5/guide_how_to_fix_failed_to_find_sfr_recovery/). Do NOT, under any circumstances, mess with this partition. @@ -228,4 +232,4 @@ The second one is this: ``` mkdir /Volumes/efi mount -t msdos /dev/disk0s4 /Volumes/efi -``` \ No newline at end of file +``` diff --git a/docs/perf-on-M1-systems.md b/docs/sw/profiling.md similarity index 98% rename from docs/perf-on-M1-systems.md rename to docs/sw/profiling.md index 181d778a..34f2ae4c 100644 --- a/docs/perf-on-M1-systems.md +++ b/docs/sw/profiling.md @@ -1,3 +1,7 @@ +--- +title: Profiling Linux Software +--- + `perf stat` works on Asahi Linux on bare metal, using Apple's proprietary performance counters (which are supported in the kernel). 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. @@ -47,4 +51,4 @@ You can also get more counters other than cycles/instructions, by specifying the 0.000301000 seconds user 0.000000000 seconds sys -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. \ No newline at end of file +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. diff --git a/docs/macOS-Sonoma-Boot-Failures.md b/docs/sw/sonoma-display-bug.md similarity index 99% rename from docs/macOS-Sonoma-Boot-Failures.md rename to docs/sw/sonoma-display-bug.md index 99f14c08..358c5534 100644 --- a/docs/macOS-Sonoma-Boot-Failures.md +++ b/docs/sw/sonoma-display-bug.md @@ -1,3 +1,7 @@ +--- +title: macOS Sonoma Display Bug +--- + ## CRITICAL UPDATE With macOS 14.1.1, 14.2 beta 2, ~~and (likely) 13.6.2~~, Apple "fixed" the bug by making the ProMotion setting not change the boot-time screen mode. diff --git a/docs/SW-Speakers-Test-Cases.md b/docs/sw/speaker-stress-tests.md similarity index 92% rename from docs/SW-Speakers-Test-Cases.md rename to docs/sw/speaker-stress-tests.md index 329b4e95..72d7f733 100644 --- a/docs/SW-Speakers-Test-Cases.md +++ b/docs/sw/speaker-stress-tests.md @@ -1,5 +1,9 @@ +--- +title: Speaker stress tests +--- + * [Laufey - From The Start](https://www.youtube.com/watch?v=lSD_L-xic9o) - good bankstown test case, bass/guitar really stress the behavior * [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 * [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. * [可愛くてごめん 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? -* [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. \ No newline at end of file +* [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. diff --git a/docs/Tethered-boot-setup-on-macOS.md b/docs/sw/tethered-boot-macos-host.md similarity index 99% rename from docs/Tethered-boot-setup-on-macOS.md rename to docs/sw/tethered-boot-macos-host.md index 3a424f78..3d33cfe4 100644 --- a/docs/Tethered-boot-setup-on-macOS.md +++ b/docs/sw/tethered-boot-macos-host.md @@ -1,3 +1,7 @@ +--- +title: Tethered Boot: macOS host machine +--- + # macOS-hosted tethered boot setup This guide will give more details about tethered boot prerequisites setup for a macOS host. diff --git a/docs/Tethered-Boot-Setup-For-Developers.md b/docs/sw/tethered-boot.md similarity index 95% rename from docs/Tethered-Boot-Setup-For-Developers.md rename to docs/sw/tethered-boot.md index 72ed812b..9bee1cc7 100644 --- a/docs/Tethered-Boot-Setup-For-Developers.md +++ b/docs/sw/tethered-boot.md @@ -1,3 +1,7 @@ +--- +title: Tethered Boot +--- + ## Introduction This guide will walk you through the steps required to set up your Apple Silicon Mac for booting a Linux kernel in a dual boot environment with macOS. @@ -7,10 +11,10 @@ This guide is intended specifically for kernel developers and advanced users who * An Apple Silicon Mac with _at least_ **macOS 12.3** installed and configured * You must have a password-protected administrator account. Typically, this will be the first account you created when setting up the machine for the first time. -* A host machine of any architecture running a GNU/Linux distribution (macOS is also supported, but less well tested see [Tethered-Boot-Setup-on-macOS](Tethered-boot-setup-on-macOS.md)) +* A host machine of any architecture running a GNU/Linux distribution (macOS is also supported, but less well tested see [Tethered Boot Setup on macOS](tethered-boot-macos-host.md)) * Both `GCC` and `Clang/LLVM` AArch64 cross-toolchains are supported. -If you are interested in low-level access to the SoC via its debug UART, you will also require a real, physical serial port solution. See [Low-level-serial-debug](Low-level-serial-debug.md) for more information on this. This is not necessary for general kernel development or reverse-engineering, and most developers will find the virtual serial port offered by the m1n1 hypervisor to be adequate for everything (unless you're debugging KVM and can't use it). +If you are interested in low-level access to the SoC via its debug UART, you will also require a real, physical serial port solution. See [Serial Debug](../hw/soc/serial-debug.md) for more information on this. This is not necessary for general kernel development or reverse-engineering, and most developers will find the virtual serial port offered by the m1n1 hypervisor to be adequate for everything (unless you're debugging KVM and can't use it). ## Preparation steps diff --git a/docs/U-Boot.md b/docs/sw/u-boot.md similarity index 94% rename from docs/U-Boot.md rename to docs/sw/u-boot.md index 392e039d..4a4bd091 100644 --- a/docs/U-Boot.md +++ b/docs/sw/u-boot.md @@ -1,12 +1,16 @@ +--- +title: Das U-Boot +--- + U-Boot is the default payload for m1n1 stage 2, and is used to provide a standard preboot environment familiar to AArch64 developers. External boot is not supported with the native Apple Silicon boot tooling, making U-Boot a hard necessity for providing a PC-like boot environment. This page explains how we use U-Boot and how to manually build and install it. It is assumed that you are working on an Apple Silicon machine using a well-supported distro, meaning either -Asahi itself or one listed at [SW-Alternative Distros](SW-Alternative-Distros.md). +Asahi itself or one listed at [Alternative Distros](../alt/alt-distros.md). Do note that the process for building and installing U-Boot listed here is for documentation and development purposes only. If you are an Asahi user and not interested in hacking on U-Boot or m1n1, they are managed automatically -via `pacman`. The same should be true for all (most) distros listed at [SW-Alternative Distros](SW-Alternative-Distros.md). +via `pacman`. The same should be true for all (most) distros listed at [Alternative Distros](../alt/alt-distros.md). ## Standard boot flow We make use of U-Boot's UEFI implementation to load and execute a UEFI binary located at `/EFI/BOOT/BOOTAA64.EFI` @@ -24,8 +28,8 @@ do things like boot off external media, execute arbitrary UEFI code, load and ju * 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. ## Prerequisites -* An Apple Silicon machine running Asahi or a distro listed at [SW-Alternative Distros](SW-Alternative-Distros.md) -* A clean build of m1n1, see the [m1n1 User Guide](m1n1-User-Guide.md) +* An Apple Silicon machine running Asahi or a distro listed at [Alternative Distros](../alt/alt-distros.md) +* A clean build of m1n1, see the [m1n1 User Guide](m1n1-user-guide.md) * The Apple DTBs from `AsahiLinux/linux`. Compiling these is out of scope for this document. * The Asahi EFI System Partition mounted at `/boot/efi/`. diff --git a/docs/Undoing-early-speaker-support-hacks.md b/docs/sw/undoing-early-speaker-hacks.md similarity index 98% rename from docs/Undoing-early-speaker-support-hacks.md rename to docs/sw/undoing-early-speaker-hacks.md index 16f19a5c..01801e57 100644 --- a/docs/Undoing-early-speaker-support-hacks.md +++ b/docs/sw/undoing-early-speaker-hacks.md @@ -1,3 +1,7 @@ +--- +title: Undoing Early Speaker Hacks +--- + ### Introduction You are probably here because you tried to enable your speakers early, and a change in config between when you did this and the public release of speaker support broke something. You were @@ -58,4 +62,4 @@ the default kernel command line, `modprobe.d`, or somewhere else. Reboot when th ### Required speaker codec settings are not being applied This can happen if you are on an old kernel, or you have manually set `snd_soc_tas2764.apple_quirks` to some nonstandard value. As above, remove any reference to this module parameter, update your kernel, -then reboot. \ No newline at end of file +then reboot. diff --git a/mkdocs.yml b/mkdocs.yml index fc3177b7..90869a37 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,36 +5,36 @@ repo_url: https://github.com/AsahiLinux/docs repo_name: AsahiLinux/docs nav: - - Overview: index.md + - Home: index.md - Feature Support: - - Overview: Feature-Support.md - - M1 Series Feature Support: M1-Series-Feature-Support.md - - M2 Series Feature Support: M2-Series-Feature-Support.md - - M3 Series Feature Support: M3-Series-Feature-Support.md - - M4 Series Feature Support: M4-Series-Feature-Support.md + - Overview: platform/feature-support/overview.md + - M1 Series Feature Support: platform/feature-support/m1.md + - M2 Series Feature Support: platform/feature-support/m2.md + - M3 Series Feature Support: platform/feature-support/m3.md + - M4 Series Feature Support: platform/feature-support/m4.md - Project related: - - Glossary: Glossary.md - - FAQ: FAQ.md - - When will Asahi Linux be done?: When-will-Asahi-Linux-be-done.md - - References: Project-References.md + - Glossary: project/glossary.md + - FAQ: project/faq.md + - When will Asahi Linux be done?: project/when-will-asahi-be-done.md + - References: project/references.md - Platform documentation: - - Apple Silicon Subsystems: Apple-Silicon-Subsystems.md - - Apple Platform Security Crash Course: Apple-Platform-Security-Crash-Course.md - - Devices: Devices.md - - Codenames: Codenames.md - - Display Controllers: Display-Controllers.md + - Apple Silicon Subsystems: platform/subsystems.md + - Apple Platform Security Crash Course: platform/security.md + - Devices: hw/devices/device-list.md + - Codenames: hw/soc/soc-codenames.md + - Display Controllers: hw/soc/display-controllers.md - For users: - Fedora Asahi Remix Documentation : https://docs.fedoraproject.org/en-US/fedora-asahi-remix/ - - Broken Software: Broken-Software.md - - Alternative Distros: SW-Alternative-Distros.md + - Broken Software: sw/broken-software.md + - Alternative Distros: alt/alt-distros.md - For developers: - - Yaks in need of shaving (HELP WANTED!): Yaks-in-need-of-shaving.md - - Tethered Boot Setup (For Developers): Tethered-Boot-Setup-For-Developers.md - - m1n1:User Guide Boot loader: m1n1-User-Guide.md - - Hypervisor: SW-Hypervisor.md - - U-Boot: U-Boot.md - - Devicetree bindings: SW-DT-bindings.md - - Open OS ecosystem on Apple Silicon Macs: Open-OS-Ecosystem-on-Apple-Silicon-Macs.md + - Yaks in need of shaving (HELP WANTED!): project/help-wanted.md + - Tethered Boot Setup (For Developers): sw/tethered-boot.md + - m1n1:User Guide Boot loader: sw/m1n1-user-guide.md + - Hypervisor: sw/m1n1-hypervisor.md + - U-Boot: sw/u-boot.md + - Devicetree bindings: sw/devicetree-bindings.md + - Open OS ecosystem on Apple Silicon Macs: platform/open-os-interop.md theme: name: material @@ -87,9 +87,6 @@ markdown_extensions: - pymdownx.tilde plugins: - - redirects: - redirect_maps: - Software-known-to-have-issues-with-16k-page-size.md: Broken-Software.md - search - social: cards_layout_options: