From 3800bd6d18525933bea932a30b965f3884451431 Mon Sep 17 00:00:00 2001 From: Davide Cavalca Date: Sun, 16 Feb 2025 17:29:33 -0800 Subject: [PATCH] Fix more broken links Signed-off-by: Davide Cavalca --- ...-guide.md => Distro-Boot-process-guide.md} | 4 ++-- ...Distro-Differences-from-Arch-Linux-ARM.md} | 0 docs/Feature-Support.md | 6 +++--- docs/Glossary.md | 3 +-- docs/HW-ASC.md | 2 +- docs/HW-CPU-debug-registers.md | 4 ++-- docs/Introduction-to-Apple-Silicon.md | 6 +++--- ...ct:References.md => Project-References.md} | 0 docs/SW-Boot.md | 20 +++++++++--------- {assets => docs/assets}/boot_picker.png | Bin {assets => docs/assets}/recoveryos.png | Bin 11 files changed, 22 insertions(+), 23 deletions(-) rename docs/{Distro:Boot-process-guide.md => Distro-Boot-process-guide.md} (99%) rename docs/{Distro:Differences-from-Arch-Linux-ARM.md => Distro-Differences-from-Arch-Linux-ARM.md} (100%) rename docs/{Project:References.md => Project-References.md} (100%) rename {assets => docs/assets}/boot_picker.png (100%) rename {assets => docs/assets}/recoveryos.png (100%) diff --git a/docs/Distro:Boot-process-guide.md b/docs/Distro-Boot-process-guide.md similarity index 99% rename from docs/Distro:Boot-process-guide.md rename to docs/Distro-Boot-process-guide.md index 66a25d81..81bc6507 100644 --- a/docs/Distro:Boot-process-guide.md +++ b/docs/Distro-Boot-process-guide.md @@ -1,6 +1,6 @@ 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 into our Arch Linux-based reference distro, see [Distro:Differences from Arch Linux ARM](Distro:Differences-from-Arch-Linux-ARM.md). +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 into our Arch Linux-based reference distro, see [Distro:Differences from Arch Linux ARM](Distro-Differences-from-Arch-Linux-ARM.md). ## Boot chain overview @@ -114,4 +114,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#firmware-provisioning](here|Open-OS-Ecosystem-on-Apple-Silicon-Macs#firmware-provisioning.md). \ No newline at end of file +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#firmware-provisioning](here|Open-OS-Ecosystem-on-Apple-Silicon-Macs#firmware-provisioning.md). diff --git a/docs/Distro:Differences-from-Arch-Linux-ARM.md b/docs/Distro-Differences-from-Arch-Linux-ARM.md similarity index 100% rename from docs/Distro:Differences-from-Arch-Linux-ARM.md rename to docs/Distro-Differences-from-Arch-Linux-ARM.md diff --git a/docs/Feature-Support.md b/docs/Feature-Support.md index fb5f109e..8e8294bd 100644 --- a/docs/Feature-Support.md +++ b/docs/Feature-Support.md @@ -1,8 +1,8 @@ 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](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](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](M3-Series-(M3,-M3-Pro,-M3-Max) Feature Support|M3-Series-Feature-Support.md) +- [M1 Series (M1, M1 Pro, M1 Max, M1 Ultra) Feature Support|M1-Series-Feature-Support](M1-Series-Feature-Support.md) +- [M2 Series (M2, M2 Pro, M2 Max, M2 Ultra) Feature Support|M2-Series-Feature-Support](M2-Series-Feature-Support.md) +- [M3 Series (M3, M3 Pro, M3 Max) Feature Support|M3-Series-Feature-Support](M3-Series-Feature-Support.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/Glossary.md b/docs/Glossary.md index 09b32c08..df02a123 100644 --- a/docs/Glossary.md +++ b/docs/Glossary.md @@ -48,7 +48,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 [HW-SPRR-and-GXF](HW-SPRR-and-GXF.md) ### H * **HFS+**: Hierarchical Filesystem+: Apple's previous filesystem, used for external storage. Not used for internal storage on M1 Macs. @@ -112,7 +112,6 @@ If you want to collect a large set of terms specific to a sub-field (such as GPU * **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 - * **TBT**: Thunderbolt Technology ### U diff --git a/docs/HW-ASC.md b/docs/HW-ASC.md index bf2dd0e0..445bcc67 100644 --- a/docs/HW-ASC.md +++ b/docs/HW-ASC.md @@ -53,7 +53,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](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|HW-AIC](HW-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-CPU-debug-registers.md b/docs/HW-CPU-debug-registers.md index fc2cf86c..e08ebf94 100644 --- a/docs/HW-CPU-debug-registers.md +++ b/docs/HW-CPU-debug-registers.md @@ -1,3 +1,3 @@ -The various CPU cores export entries in the [ADT|FW:ADT](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. +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. \ No newline at end of file +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/Introduction-to-Apple-Silicon.md b/docs/Introduction-to-Apple-Silicon.md index 39b2cba5..c1eb03a5 100644 --- a/docs/Introduction-to-Apple-Silicon.md +++ b/docs/Introduction-to-Apple-Silicon.md @@ -132,11 +132,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. -[https://github.com/AsahiLinux/docs/blob/main/assets/recoveryos.png|alt=recoveryOS](https://github.com/AsahiLinux/docs/blob/main/assets/recoveryos.png|alt=recoveryOS.md) +![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): -[https://github.com/AsahiLinux/docs/blob/main/assets/boot_picker.png|alt=Boot Picker](https://github.com/AsahiLinux/docs/blob/main/assets/boot_picker.png|alt=Boot-Picker.md) +![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. @@ -256,4 +256,4 @@ Notes: 9. Machines with embedded display only 10. Machines with HDMI port only -Many firmware sizes are compressed (many firmwares have large amounts of padding, making uncompressed sizes not very useful to gauge how much code there is). Where large firmwares are stored uncompressed, compressed sizes are also given for better comparison. The sizes should be taken as a rough guide only. \ No newline at end of file +Many firmware sizes are compressed (many firmwares have large amounts of padding, making uncompressed sizes not very useful to gauge how much code there is). Where large firmwares are stored uncompressed, compressed sizes are also given for better comparison. The sizes should be taken as a rough guide only. diff --git a/docs/Project:References.md b/docs/Project-References.md similarity index 100% rename from docs/Project:References.md rename to docs/Project-References.md diff --git a/docs/SW-Boot.md b/docs/SW-Boot.md index 89e0770e..b0b164cd 100644 --- a/docs/SW-Boot.md +++ b/docs/SW-Boot.md @@ -2,18 +2,18 @@ Apple Silicon devices seem to follow a boot flow very similar to modern iOS devi # Stage 0 (SecureROM) -This stage is located in the boot [ROM](./Glossary#R). Among others, it verifies, loads and executes normal stage 1 from [NOR](./Glossary#N). If this fails, it falls back to [DFU](./Glossary#D) and wait for an [iBSS](./Glossary#I) loader to be sent, before continuing with the [DFU](./Glossary#D) flow at stage 1. +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. # Normal flow ## Stage 1 (LLB/iBoot1) -This stage is the primary early loader, located in the on-board [NOR](./Glossary#N). This boot stage very roughly goes as follows: +This stage is the primary early loader, located in the on-board [NOR](Glossary.md#N). This boot stage very roughly goes as follows: -* Read the `boot-volume` variable from [NVRAM](./Glossary#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](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#S) command 11); - - If that is not available, get the local blessed hash ([SEP](./Glossary#S) command 14) + - 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) * 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 +45,17 @@ This stage is the primary early loader, located in the on-board [NOR](./Glossary - 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#F)): +* If loading a custom stage ([fuOS](Glossary.md#F)): - ... -If it fails at any point during this, it will either error out or fall back to [DFU](./Glossary#D), waiting for an iBEC loader to be sent, before continuing with the [DFU](./Glossary#D) flow at stage 2. +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. ## 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#D) flow +# [DFU](Glossary.md#D) flow ## Stage 1 (iBSS) @@ -65,7 +65,7 @@ This stage is sent to the device by the "reviving" host. It bootstraps, verifies # Modes -Once booted, the [AP](./Glossary#A) can be in one of several boot modes, as confirmed by the [SEP](./Glossary#S): +Once booted, the [AP](Glossary.md#A) can be in one of several boot modes, as confirmed by the [SEP](Glossary.md#S): | ID | Name | |----:|-------------------------------------------| @@ -76,4 +76,4 @@ Once booted, the [AP](./Glossary#A) can be in one of several boot modes, as conf | 4 | restoreOS | | 255 | unknown | -The [SEP](./Glossary#S) only allows execution of certain commands (such as editing the boot policy) in [1TR](./Glossary#1), or it will fail with error 11, "AP boot mode". \ No newline at end of file +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". diff --git a/assets/boot_picker.png b/docs/assets/boot_picker.png similarity index 100% rename from assets/boot_picker.png rename to docs/assets/boot_picker.png diff --git a/assets/recoveryos.png b/docs/assets/recoveryos.png similarity index 100% rename from assets/recoveryos.png rename to docs/assets/recoveryos.png