diff --git a/docs/alt/boot-process-guide.md b/docs/alt/boot-process-guide.md index acc20117..02504302 100644 --- a/docs/alt/boot-process-guide.md +++ b/docs/alt/boot-process-guide.md @@ -42,7 +42,7 @@ The PARTUUID of the EFI system partition assigned to the currently booted OS is Here's where it gets a bit hairy. m1n1, u-boot, Linux, and the device trees have somewhat complex and subtle version interdependencies. * m1n1 stage 2 is in charge of some hardware init, and patching in dynamic values into the device trees. This means that newer kernel hardware support often depends on a m1n1 update, either to initialize things or to add more device tree data, or both. - * In general, we prefer to keep Linux drivers simple and put "magic" init (e.g. random magic sets of register writes, which Apple loves to describe in their variant of a DT) in m1n1. Same with things related to the memory controller, clock configurations that we can reasonably leave static, etc. The exception is when Linux has no choice but to do this dynamically at runtime. Apple likes to leave way too much to the XNU kernel (which m1n1 replaces), including ridiculous things like turning on the system-level L3 cache, and we don't want Linux to have to deal with that. This also highly increases our chances of existing kernels working (at least partially) on newer SoCs/platforms with only DT changes, which is good for e.g. forward-compatibility of distro install images. For example, PCIe on M2 required no driver-level changes, only changes to the m1n1 initialization. + * In general, we prefer to keep Linux drivers simple and put "magic" init (e.g. random magic sets of register writes, which Apple loves to describe in their variant of a DT) in m1n1. Same with things related to the memory controller, clock configurations that we can reasonably leave static, etc. The exception is when Linux has no choice but to do this dynamically at runtime. Apple likes to leave way too much to the XNU kernel (which m1n1 replaces), including ridiculous things like turning on the system-level L3 cache, and we don't want Linux to have to deal with that. This also highly increases our chances of existing kernels working (at least partially) on newer SoCs/platforms with only DT changes, which is good for e.g. forward-compatibility of distro install images. For example, PCIe on M2 required no driver-level changes, only changes to the m1n1 initialization. * U-Boot generally doesn't change much once properly brought up on any given SoC, and only cares about a subset of DT info. * Linux needs DT data to bring up hardware, so new hardware needs DT updates. Our canonical DT repository is part of our Linux tree itself, but remember changes here often need m1n1 (stage 2) updates to make things actually work. diff --git a/docs/hw/cpu/system-registers.md b/docs/hw/cpu/system-registers.md index fe3edeb1..ae094c7e 100644 --- a/docs/hw/cpu/system-registers.md +++ b/docs/hw/cpu/system-registers.md @@ -679,25 +679,25 @@ The AArch64 FEAT_AFT feature implements equivalent support, but Apple implemente #### MIDR_EL1 (ARM standard) * [15:4] PartNum - * 1: Alcatraz Cyclone (A7 / H6P) - * 2: Fiji Typhoon (A8 / H7P) - * 3: Capri Typhoon (A8X / H7G) - * 4: Malta / Elba Twister (TSMC A9 / A9X / H8P / H8G) - * 5: Maui Twister (Samsung A9 / H8P) - * 6: Cayman / Gibraltar Hurricane-Zephyr (A10 / T2 / H9P / H9M Fusion core) - * 7: Myst Hurricane-Zephyr (A10X / H9G Fusion core) - * 8: Skye Monsoon (A11 / H10 p-core) - * 9: Skye Mistral (A11 / H10 e-core) - * 11: Cyprus Vortex (A12 / H11P p-core) - * 12: Cyprus Tempest (A12 / H11P e-core) - * 15: M9 (S4/S5) - * 16: Aruba Vortex (A12X/Z / H11G p-core) - * 17: Aruba Tempest (A12X/Z / H11G e-core) - * 18: Cebu Lightning (A13 / H12 p-core) - * 19: Cebu Thunder (A13 / H12 e-core) - * 34: M1 Icestorm (H13G e-core) - * 35: M1 Firestorm (H13G p-core) - * 38: Turks (S6 / M10) + * 1: Alcatraz Cyclone (A7 / H6P) + * 2: Fiji Typhoon (A8 / H7P) + * 3: Capri Typhoon (A8X / H7G) + * 4: Malta / Elba Twister (TSMC A9 / A9X / H8P / H8G) + * 5: Maui Twister (Samsung A9 / H8P) + * 6: Cayman / Gibraltar Hurricane-Zephyr (A10 / T2 / H9P / H9M Fusion core) + * 7: Myst Hurricane-Zephyr (A10X / H9G Fusion core) + * 8: Skye Monsoon (A11 / H10 p-core) + * 9: Skye Mistral (A11 / H10 e-core) + * 11: Cyprus Vortex (A12 / H11P p-core) + * 12: Cyprus Tempest (A12 / H11P e-core) + * 15: M9 (S4/S5) + * 16: Aruba Vortex (A12X/Z / H11G p-core) + * 17: Aruba Tempest (A12X/Z / H11G e-core) + * 18: Cebu Lightning (A13 / H12 p-core) + * 19: Cebu Thunder (A13 / H12 e-core) + * 34: M1 Icestorm (H13G e-core) + * 35: M1 Firestorm (H13G p-core) + * 38: Turks (S6 / M10) * [31:24] Implementer (0x61 = 'a' = Apple) diff --git a/docs/hw/soc/agx.md b/docs/hw/soc/agx.md index 02146071..bbffae29 100644 --- a/docs/hw/soc/agx.md +++ b/docs/hw/soc/agx.md @@ -68,9 +68,9 @@ Data structures: see [channels.py](https://github.com/AsahiLinux/m1n1/blob/main/ #### CPU->GPU channels * Work Channels: four groups (0-3), each with three channels, one per GPU work type - * TA (Tile Accelerator; vertex processing) - * 3D (3D; pixel processing) - * CP (Compute) + * TA (Tile Accelerator; vertex processing) + * 3D (3D; pixel processing) + * CP (Compute) TODO: there is probably some priority scheme for work submitted to different channels. @@ -79,14 +79,14 @@ Data structures: see [channels.py](https://github.com/AsahiLinux/m1n1/blob/main/ #### GPU->CPU channels * Event: work-related event notifications - * Work completion flag events + * Work completion flag events * These have a 128-bit array indicating which event indices are firing - * Fault notifications + * Fault notifications * GPU faults seem to be quite poorly handled as a stop-the-world process; macOS actually goes off dumping GPU MMIO registers directly, and the firmware seems to be quite clueless as to what to do. * Statistics messages - * We ignore these. The firmware will complain once if the buffer overflows, but it's harmless. + * We ignore these. The firmware will complain once if the buffer overflows, but it's harmless. * Firmware syslogs - * This one is weird in that there are multiple sub-channels for some reason, with control structures laid out contiguously. + * This one is weird in that there are multiple sub-channels for some reason, with control structures laid out contiguously. * An unknown channel (tracing?) ### GPU contexts @@ -181,14 +181,14 @@ Note: this is all summarized and glosses over tons of unknown/fixed/magic number * Timestamp 3 ptr * Unknown buffer 2 (empty) * Embedded structures: - * Tiler parameters (tile counts/etc) - * TA work struct 2 + * Tiler parameters (tile counts/etc) + * TA work struct 2 * TVB tilemap ptr * TVB list ptr * Three small buffers passed from userspace (alyssa calls these "deflake") * Command encoder ptr (i.e. actual gfx pipeline to run, from userspace) * Pipeline window base (4GiB window into VAs used for 32-bit shader pointers) - * TA work struct 3 + * TA work struct 3 * One of the deflake ptrs * Encoder ID (unique ID, GPU likely does not care) * "Unknown buffer" (the one with incrementing numbers, from userspace) @@ -270,7 +270,7 @@ This blocks 3D until TA is done. Unclear what black magic makes partial renders * Timestamp 2 ptr * Timestamp 3 ptr * Embedded structures: - * 3D work struct 1 + * 3D work struct 1 * Some floats? * Depth clear value * Stencil clear value diff --git a/docs/platform/dev-quickstart.md b/docs/platform/dev-quickstart.md index 62c25e84..61273051 100644 --- a/docs/platform/dev-quickstart.md +++ b/docs/platform/dev-quickstart.md @@ -319,7 +319,7 @@ $ M1N1DEVICE=/dev/ttyACM0 $ export M1N1DEVICE $ python3 proxyclient/tools/shell.py ``` - * Can start up a terminal program on the 2nd tty which linux console output can be made to go to + * Can start up a terminal program on the 2nd tty which linux console output can be made to go to ``` picocom /dev/ttyACM1 ``` diff --git a/docs/platform/open-os-interop-old.md b/docs/platform/open-os-interop-old.md index 0524c370..044e870e 100644 --- a/docs/platform/open-os-interop-old.md +++ b/docs/platform/open-os-interop-old.md @@ -17,12 +17,12 @@ An OS on an Apple Silicon machine, as seen by Apple's tooling, means a portion o For third-party OSes, we propose the following GPT partition structure per OS: 1. APFS container partition ("stub macOS") (~2.5GB) with: - * iBoot2, firmware, XNU kernel, RecoveryOS (all required by the platform) - * m1n1 as fuOS kernel, with chainloading config pointing to the EFI partition - * ~empty root/data filesystem subvolumes + * iBoot2, firmware, XNU kernel, RecoveryOS (all required by the platform) + * m1n1 as fuOS kernel, with chainloading config pointing to the EFI partition + * ~empty root/data filesystem subvolumes 2. EFI system partition (FAT32) (~512MB) with: - * m1n1 stage 2 + device trees + U-Boot - * GRUB or another UEFI OS loader boot the target kernel + * m1n1 stage 2 + device trees + U-Boot + * GRUB or another UEFI OS loader boot the target kernel 3. root/boot/etc. partitions (OS-specific) Rationale: this arrangement pairs together a third-party OS with an APFS-resident OS as seen by Apple's tooling, and allows users to use the native boot picker (with a11y support). It avoids potential trouble down the road which could come from having multiple OSes attempt to manage the SEP under a shared OS context. It also lets us have independent secure-boot chains for OSes (once that is implemented), with the fuOS image containing the root of trust for subsequent boot stages, bridged to the machine chain of trust by the user with their machine owner credentials during installation. @@ -41,39 +41,39 @@ A typical boot of a reference Linux system will go as follows, continuing on fro * iBoot2 loads the custom kernel, which is a build of m1n1 * m1n1 stage 1 runs and - * Parses the Apple Device Tree (ADT) to obtain machine-specific information - * Performs additional hardware initialization (machine-specific) + * Parses the Apple Device Tree (ADT) to obtain machine-specific information + * Performs additional hardware initialization (machine-specific) * E.g. memory controller details, USB-C charging, HDMI display (on Mac Mini) - * Displays its logo on the screen (replacing the Apple logo) - * Loads its embedded configuration, which directs it to chainload from a FAT32 partition - * Initializes the NVMe controller - * Searches the GPT for the partition configured for chainloading, by PARTUUID. - * Mounts the partition as FAT32 - * Searches for the filename configured for chainloading and loads it - * Shuts down the NVMe controller - * Chainloads to the loaded instance of m1n1 (as a raw binary blob), including forwarding any /chosen property configurations found in its embedded config. + * Displays its logo on the screen (replacing the Apple logo) + * Loads its embedded configuration, which directs it to chainload from a FAT32 partition + * Initializes the NVMe controller + * Searches the GPT for the partition configured for chainloading, by PARTUUID. + * Mounts the partition as FAT32 + * Searches for the filename configured for chainloading and loads it + * Shuts down the NVMe controller + * Chainloads to the loaded instance of m1n1 (as a raw binary blob), including forwarding any /chosen property configurations found in its embedded config. * m1n1 stage 2 runs and - * Parses the Apple Device Tree (ADT) to obtain machine-specific information - * Re-initializes hardware, including anything stage 1 did not do (e.g. due to it being older) - * Searches its embedded payloads to find Device Trees and an embedded U-Boot image - * Selects an embedded Device Tree (FDT) appropriate for the current platform - * Personalizes the FDT with dynamic information transplanted from the ADT - * Performs any other hardware initialization to prepare the machine environment for Linux - * Loads the embedded U-Boot image and jumps to it + * Parses the Apple Device Tree (ADT) to obtain machine-specific information + * Re-initializes hardware, including anything stage 1 did not do (e.g. due to it being older) + * Searches its embedded payloads to find Device Trees and an embedded U-Boot image + * Selects an embedded Device Tree (FDT) appropriate for the current platform + * Personalizes the FDT with dynamic information transplanted from the ADT + * Performs any other hardware initialization to prepare the machine environment for Linux + * Loads the embedded U-Boot image and jumps to it * U-Boot runs and - * Parses the FDT - * Initializes the keyboard for input - * Initializes NVMe - * Prompts the user to break into a shell if requested - * Mounts the appropriate EFI System Partition - * Brings up basic EFI services - * Locates the default EFI bootloader in the ESP, e.g. GRUB, and boots it + * Parses the FDT + * Initializes the keyboard for input + * Initializes NVMe + * Prompts the user to break into a shell if requested + * Mounts the appropriate EFI System Partition + * Brings up basic EFI services + * Locates the default EFI bootloader in the ESP, e.g. GRUB, and boots it * GRUB runs and - * Uses EFI disk access services to mount the /boot filesystem (could be the ESP itself, could be something else) - * Locates its configuration file and additional components - * Presents the user with a boot menu, using EFI console/input services - * Loads the kernel and initramfs from /boot - * Jumps to the kernel + * Uses EFI disk access services to mount the /boot filesystem (could be the ESP itself, could be something else) + * Locates its configuration file and additional components + * Presents the user with a boot menu, using EFI console/input services + * Loads the kernel and initramfs from /boot + * Jumps to the kernel * The Linux kernel boots as it would on any other UEFI+FDT platform This boot chain is designed to progressively bring the system closer to a "typical" ARM64 machine, so that subsequent layers have to worry less about the particulars of Apple Silicon machines. @@ -122,11 +122,11 @@ 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.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. + * 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. * We want to add this as a feature to the online installer, e.g. "create a bootable USB installer" instead of actually doing the install. * Packaging as a macOS app (this would already be part of USB install modes anyway) - * Though this runs into GateKeeper issues with unsigned downloads if downloaded "normally" by users from a browser... + * Though this runs into GateKeeper issues with unsigned downloads if downloaded "normally" by users from a browser... ## Firmware provisioning @@ -150,8 +150,8 @@ The stub OS installer collects available platform firmware from the IPSW, and pa * firmware.tar: Tarball containing the firmware, in a structure compatible with the `/lib/firmware` hierarchy (e.g. `brcm/foo.bin`). * manifest.txt: A text file containing lines of the following two forms: - * `LINK ` : hard link - * `FILE SHA256 `: file + * `LINK ` : hard link + * `FILE SHA256 `: file These files are then placed in the EFI system partition under the `vendorfw` directory. diff --git a/docs/platform/open-os-interop.md b/docs/platform/open-os-interop.md index 1baa51e7..44e40353 100644 --- a/docs/platform/open-os-interop.md +++ b/docs/platform/open-os-interop.md @@ -17,12 +17,12 @@ An OS on an Apple Silicon machine, as seen by Apple's tooling, means a portion o For third-party OSes, we propose the following GPT partition structure per OS: 1. APFS container partition ("stub macOS") (~2.5GB) with: - * iBoot2, firmware, XNU kernel, RecoveryOS (all required by the platform) - * m1n1 as fuOS kernel, with chainloading config pointing to the EFI partition - * ~empty root/data filesystem subvolumes + * iBoot2, firmware, XNU kernel, RecoveryOS (all required by the platform) + * m1n1 as fuOS kernel, with chainloading config pointing to the EFI partition + * ~empty root/data filesystem subvolumes 2. EFI system partition (FAT32) (~512MB) with: - * m1n1 stage 2 + device trees + U-Boot - * GRUB or another UEFI OS loader boot the target kernel + * m1n1 stage 2 + device trees + U-Boot + * GRUB or another UEFI OS loader boot the target kernel 3. root/boot/etc. partitions (OS-specific) Rationale: this arrangement pairs together a third-party OS with an APFS-resident OS as seen by Apple's tooling, and allows users to use the native boot picker (with a11y support). It avoids potential trouble down the road which could come from having multiple OSes attempt to manage the SEP under a shared OS context. It also lets us have independent secure-boot chains for OSes (once that is implemented), with the fuOS image containing the root of trust for subsequent boot stages, bridged to the machine chain of trust by the user with their machine owner credentials during installation. @@ -41,39 +41,39 @@ A typical boot of a reference Linux system will go as follows, continuing on fro * iBoot2 loads the custom kernel, which is a build of m1n1 * m1n1 stage 1 runs and - * Parses the Apple Device Tree (ADT) to obtain machine-specific information - * Performs additional hardware initialization (machine-specific) + * Parses the Apple Device Tree (ADT) to obtain machine-specific information + * Performs additional hardware initialization (machine-specific) * E.g. memory controller details, USB-C charging, HDMI display (on Mac Mini) - * Displays its logo on the screen (replacing the Apple logo) - * Loads its embedded configuration, which directs it to chainload from a FAT32 partition - * Initializes the NVMe controller - * Searches the GPT for the partition configured for chainloading, by PARTUUID. - * Mounts the partition as FAT32 - * Searches for the filename configured for chainloading and loads it - * Shuts down the NVMe controller - * Chainloads to the loaded instance of m1n1 (as a raw binary blob), including forwarding any /chosen property configurations found in its embedded config. + * Displays its logo on the screen (replacing the Apple logo) + * Loads its embedded configuration, which directs it to chainload from a FAT32 partition + * Initializes the NVMe controller + * Searches the GPT for the partition configured for chainloading, by PARTUUID. + * Mounts the partition as FAT32 + * Searches for the filename configured for chainloading and loads it + * Shuts down the NVMe controller + * Chainloads to the loaded instance of m1n1 (as a raw binary blob), including forwarding any /chosen property configurations found in its embedded config. * m1n1 stage 2 runs and - * Parses the Apple Device Tree (ADT) to obtain machine-specific information - * Re-initializes hardware, including anything stage 1 did not do (e.g. due to it being older) - * Searches its embedded payloads to find Device Trees and an embedded U-Boot image - * Selects an embedded Device Tree (FDT) appropriate for the current platform - * Personalizes the FDT with dynamic information transplanted from the ADT - * Performs any other hardware initialization to prepare the machine environment for Linux - * Loads the embedded U-Boot image and jumps to it + * Parses the Apple Device Tree (ADT) to obtain machine-specific information + * Re-initializes hardware, including anything stage 1 did not do (e.g. due to it being older) + * Searches its embedded payloads to find Device Trees and an embedded U-Boot image + * Selects an embedded Device Tree (FDT) appropriate for the current platform + * Personalizes the FDT with dynamic information transplanted from the ADT + * Performs any other hardware initialization to prepare the machine environment for Linux + * Loads the embedded U-Boot image and jumps to it * U-Boot runs and - * Parses the FDT - * Initializes the keyboard for input - * Initializes NVMe - * Prompts the user to break into a shell if requested - * Mounts the appropriate EFI System Partition - * Brings up basic EFI services - * Locates the default EFI bootloader in the ESP, e.g. GRUB, and boots it + * Parses the FDT + * Initializes the keyboard for input + * Initializes NVMe + * Prompts the user to break into a shell if requested + * Mounts the appropriate EFI System Partition + * Brings up basic EFI services + * Locates the default EFI bootloader in the ESP, e.g. GRUB, and boots it * GRUB runs and - * Uses EFI disk access services to mount the /boot filesystem (could be the ESP itself, could be something else) - * Locates its configuration file and additional components - * Presents the user with a boot menu, using EFI console/input services - * Loads the kernel and initramfs from /boot - * Jumps to the kernel + * Uses EFI disk access services to mount the /boot filesystem (could be the ESP itself, could be something else) + * Locates its configuration file and additional components + * Presents the user with a boot menu, using EFI console/input services + * Loads the kernel and initramfs from /boot + * Jumps to the kernel * The Linux kernel boots as it would on any other UEFI+FDT platform This boot chain is designed to progressively bring the system closer to a "typical" ARM64 machine, so that subsequent layers have to worry less about the particulars of Apple Silicon machines. @@ -122,11 +122,11 @@ 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.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. + * 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. * We want to add this as a feature to the online installer, e.g. "create a bootable USB installer" instead of actually doing the install. * Packaging as a macOS app (this would already be part of USB install modes anyway) - * Though this runs into GateKeeper issues with unsigned downloads if downloaded "normally" by users from a browser... + * Though this runs into GateKeeper issues with unsigned downloads if downloaded "normally" by users from a browser... ## Firmware provisioning @@ -155,8 +155,8 @@ The stub OS installer collects available platform firmware from the IPSW, and pa * The firmwares in `/lib/firmware` hierarchy format, under the `vendorfw` subdirectory (e.g. `/vendorfw/brcm/foo.bin`). * `/vendorfw/.vendorfw.manifest`: A text file containing lines of the following two forms: - * `LINK ` : hard link - * `FILE SHA256 `: file + * `LINK ` : hard link + * `FILE SHA256 `: file This cpio is named `firmware.cpio` and placed in the EFI system partition under the `vendorfw` directory. diff --git a/docs/platform/stock-partition-layout.md b/docs/platform/stock-partition-layout.md index 0bcedc6d..2a5b85fe 100644 --- a/docs/platform/stock-partition-layout.md +++ b/docs/platform/stock-partition-layout.md @@ -5,19 +5,19 @@ title: Stock SSD Partition Layout # Summary * **disk0**: main SSD - * **disk0s1 = disk1**: "iBootSystemContainer" - system-wide boot data + * **disk0s1 = disk1**: "iBootSystemContainer" - system-wide boot data * **disk1s1**: "iSCPreboot" - boot policies, system firmware (NOR) version metadata, SEP firmware (sometimes), AP tickets * **disk1s2**: "xARTS" - SEP trusted storage * **disk1s3**: "Hardware" - logs, factory data cache, activation-related files * **disk1s4**: "Recovery" - empty - * **disk0s2 = disk3**: "Container" - macOS install + * **disk0s2 = disk3**: "Container" - macOS install * **disk3s1**: "System" - OS (root filesystem, sealed) * **disk3s2**: "Preboot" - iBoot2 (OS loader), iBoot-loaded firmwares, Darwin kernelcache, firmwares, devicetree, other preboot stuff * **disk3s3**: "Recovery" - OS-paired RecoveryOS: iBoot2, firmwares, Darwin kernelcache, ramdisk image * **disk3s4**: "Update" - macOS update temp storage and logs * **disk3s5**: "Data" - user data (root filesystem, merged). This volume's UUID defines the identity of the OS install. * **disk3s6**: "VM" - swap partition (when needed) - * **disk0s3 = disk2**: "RecoveryOSContainer" - System RecoveryOS + * **disk0s3 = disk2**: "RecoveryOSContainer" - System RecoveryOS * **disk2s1**: "Recovery" - one or more sets of {iBoot2 (OS loader), Darwin kernelcache, firmwares, devicetree, other preboot stuff} * **disk2s2**: "Update" - system firmware update temp storage and logs diff --git a/docs/sw/linux-bringup-nvme.md b/docs/sw/linux-bringup-nvme.md index 927d9695..5ee65169 100644 --- a/docs/sw/linux-bringup-nvme.md +++ b/docs/sw/linux-bringup-nvme.md @@ -14,32 +14,32 @@ mkdir debinst sudo debootstrap --arch arm64 --foreign bullseye debinst http://ftp.au.debian.org/debian/ sudo cp /usr/bin/qemu-aarch64-static debinst/usr/bin ``` - * Login via a chroot to a bash prompt:`sudo LANG=C.UTF-8 chroot debinst qemu-aarch64-static /bin/bash` - * Then complete the 2nd stage `/debootstrap/debootstrap --second-stage` - * While your there install any other packages you want: `apt install file screenfetch procps` - * For ssh install an ssh server `apt install openssh-server` - * Allow root login via ssh by setting `PermitRootLogin yes` via `vi /etc/ssh/sshd_config` - * Most important set the root password `passwd` + * Login via a chroot to a bash prompt:`sudo LANG=C.UTF-8 chroot debinst qemu-aarch64-static /bin/bash` + * Then complete the 2nd stage `/debootstrap/debootstrap --second-stage` + * While your there install any other packages you want: `apt install file screenfetch procps` + * For ssh install an ssh server `apt install openssh-server` + * Allow root login via ssh by setting `PermitRootLogin yes` via `vi /etc/ssh/sshd_config` + * Most important set the root password `passwd` ### Install rootfs onto USB drive - * Plug in your USB drive and create a partition with fdisk (assumes drive is /dev/sdb) `sudo fdisk /dev/sdb` - * Format partition (assumes it's the first one) `sudo mkfs.ext4 /dev/sdb1` - * Mount the drive some where like /mnt/img `sudo mount /dev/sdb1 /mnt/img` - * Install the rootfs you created above onto the drive `sudo cp -a debinst/. /mnt/img` - * Unmount the drive `sudo umount /mnt/img` + * Plug in your USB drive and create a partition with fdisk (assumes drive is /dev/sdb) `sudo fdisk /dev/sdb` + * Format partition (assumes it's the first one) `sudo mkfs.ext4 /dev/sdb1` + * Mount the drive some where like /mnt/img `sudo mount /dev/sdb1 /mnt/img` + * 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](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) + * 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! - * Try this [Asahi linux snapshot](https://github.com/amworsley/AsahiLinux/tree/asahi-kbd) and this [config](https://raw.githubusercontent.com/amworsley/asahi-wiki/main/images/config-keyboard+nvme) - * Then boot the gzipp'ed image with the USB drive. I had to plug the drive in the 2nd USB type-C port on the MBA (MacBook Air) through a Type-C to USB-Type A HUB. - * Be-aware when I plugged in a lower speed USB device (keyboard) it reset the HUB and corrupted my USB drive. So don't use a keyboard, a Type-A to Type-C dongle worked fine - * Over the USB cable load the new kernel and boot with the USB drive as the root filesystem: + * Try this [Asahi linux snapshot](https://github.com/amworsley/AsahiLinux/tree/asahi-kbd) and this [config](https://raw.githubusercontent.com/amworsley/asahi-wiki/main/images/config-keyboard+nvme) + * Then boot the gzipp'ed image with the USB drive. I had to plug the drive in the 2nd USB type-C port on the MBA (MacBook Air) through a Type-C to USB-Type A HUB. + * Be-aware when I plugged in a lower speed USB device (keyboard) it reset the HUB and corrupted my USB drive. So don't use a keyboard, a Type-A to Type-C dongle worked fine + * Over the USB cable load the new kernel and boot with the USB drive as the root filesystem: ``` python3 proxyclient/tools/linux.py -b 'earlycon console=tty0 console=tty0 debug net.ifnames=0 rw root=/dev/sda1 rootdelay=5 rootfstype=ext4' Image.gz t8103-j313.dtb ``` - * The root filesystem is in first partition of the drive (/dev/sda1) and it's a MBA (t8103-j313.dtb) - * If your booting something different check the .dts file in **arch/arm64/boot/dts/apple/** by looking at the value of the **model** field + * The root filesystem is in first partition of the drive (/dev/sda1) and it's a MBA (t8103-j313.dtb) + * If your booting something different check the .dts file in **arch/arm64/boot/dts/apple/** by looking at the value of the **model** field ### Install rootfs in the nvme * Under MacOS you need to create some free space as per [Glanzmann's notes](https://tg.st/u/asahi.txt) * Be very careful you know exactly what partition you specify this is just an **example** your numbers may vary diff --git a/docs/sw/linux-bringup-usb-keyboard.md b/docs/sw/linux-bringup-usb-keyboard.md index 27c23cd3..80f3a55c 100644 --- a/docs/sw/linux-bringup-usb-keyboard.md +++ b/docs/sw/linux-bringup-usb-keyboard.md @@ -8,7 +8,7 @@ title: Linux Bringup: USB Keyboard * Can use this [Linux config file for M1 MacBook Air with USB](https://github.com/amworsley/asahi-wiki/blob/main/images/config-jannau-iso9660-noR.gz) as a base (doesn't enable gadget mode) * Modifying the initrd to just run /bin/sh (edit /init) * 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. + * 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) diff --git a/docs/sw/linux-bringup-wifi.md b/docs/sw/linux-bringup-wifi.md index 65cc0d7e..cc6f7c7e 100644 --- a/docs/sw/linux-bringup-wifi.md +++ b/docs/sw/linux-bringup-wifi.md @@ -24,7 +24,7 @@ title: Linux Bringup: WiFi * Now after the linux kernel has booted you should be able to see a WiFi device (wlan0) via the usual tools `ip a l` * You can start networking the usual Linux tools e.g. - * Edit the configuration file: + * Edit the configuration file: ``` auto wlan0 iface wlan0 inet dhcp diff --git a/docs/sw/linux-bringup.md b/docs/sw/linux-bringup.md index 3a7871c1..69f317ed 100644 --- a/docs/sw/linux-bringup.md +++ b/docs/sw/linux-bringup.md @@ -30,14 +30,14 @@ 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](../platform/dev-quickstart.md#setup) - * If m1n1 C code has been updated since the set up you should chain load the new .macho image +* 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](../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 +* 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 ``` wget https://deb.debian.org/debian/dists/buster/main/installer-arm64/current/images/netboot/debian-installer/arm64/initrd.gz @@ -66,13 +66,13 @@ find . | cpio -o -H newc | gzip -c -9 >| /pathto/initrd-new.gz ``` ## Under Hypervisor - * Running Linux under m1n1 hypervisor lets you inspect the memory/stop/start and even do a stack trace - * Create a .macho combined image (run_guest.py only accepts .macho) +* Running Linux under m1n1 hypervisor lets you inspect the memory/stop/start and even do a stack trace +* Create a .macho combined image (run_guest.py only accepts .macho) ``` cat build/m1n1.macho Image.gz build/dtb/apple-j274.dtb initramfs.cpio.gz > m1n1-payload.macho ``` - * Load it with run_guest +* Load it with run_guest ``` python3.9 proxyclient/tools/run_guest.py -S m1n1-payload.macho ``` @@ -187,7 +187,7 @@ Skip: msr ACC_CFG_EL1, x1 = d ``` - * Once it is running use **^C** to get a debug shell +* Once it is running use **^C** to get a debug shell ``` ... Skip: msr CYC_OVRD_EL1, x1 = 2000000 @@ -197,7 +197,7 @@ Skip: msr ACC_CFG_EL1, x1 = d Entering debug shell >>> ``` - * Then get a stack trace (with symbols) after loading System.map file of the kernel and setting the PAC_MASK (pointer protection mask) +* Then get a stack trace (with symbols) after loading the `System.map` file of the kernel and setting the `PAC_MASK` (pointer protection mask) ``` >>> load_system_map('../linux/System.map') >>> hv.pac_mask = 0xfffff00000000000 @@ -212,7 +212,7 @@ Stack trace: - 0xffff8000103d0c7c (arch_call_rest_init+0xc) - 0xffff8000103d11f0 (start_kernel+0x528) ``` - * Disassemble addresses before the program counter +* Disassemble addresses before the program counter ``` >>> disassemble_at(p.hv_translate(hv.ctx.elr, True) - 32, 64) 81f6fdc04: d53cd042 mrs x2, tpidr_el2 @@ -232,7 +232,7 @@ Stack trace: 81f6fdc3c: 97fffff7 bl 81f6fdc18 <_start+0x14> 81f6fdc40: a8c17bfd ldp x29, x30, [sp], #16 ``` - * Dump out register %0 from the last exception to the hypervisor +* Dump out register %0 from the last exception to the hypervisor ``` >>> hv.ctx.regs[0] 0xffff0003ccaf21e0 @@ -389,12 +389,12 @@ Still running 21 # Root filesystem options - * [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) +* [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](linux-bringup-wifi.md) - * [X11 Support](linux-bringup-x11.md) +* [WiFi Support](linux-bringup-wifi.md) +* [X11 Support](linux-bringup-x11.md) # Missing - * Sound - * Power management - do **NOT** shut the lid +* Sound +* Power management - do **NOT** shut the lid diff --git a/docs/sw/m1n1-user-guide.md b/docs/sw/m1n1-user-guide.md index 95e3e16c..96bba804 100644 --- a/docs/sw/m1n1-user-guide.md +++ b/docs/sw/m1n1-user-guide.md @@ -11,10 +11,10 @@ GitHub: [AsahiLinux/m1n1](https://github.com/AsahiLinux/m1n1) * Initializes hardware * Puts up a pretty logo * Loads embedded (appended) payloads, which can be: - * Device Trees (FDTs), with automatic selection based on the platform - * Initramfs images (compressed CPIO archives) - * Kernel images in Linux ARM64 boot format (optionally compressed) - * Configuration statements + * Device Trees (FDTs), with automatic selection based on the platform + * Initramfs images (compressed CPIO archives) + * Kernel images in Linux ARM64 boot format (optionally compressed) + * 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-dev-guide.md) for that. This guide only describes trivial proxy use cases. diff --git a/docs/sw/macos-kernelcache.md b/docs/sw/macos-kernelcache.md index 7a67264e..c3096b9e 100644 --- a/docs/sw/macos-kernelcache.md +++ b/docs/sw/macos-kernelcache.md @@ -26,8 +26,8 @@ Again, **only proceed if you have talked to us first about this**. * From suggestion by **davidrysk** there are some MacOS kernel images already available at **/System/Library/Kernels/kernel.release.t8020** * Below shows dumping the macho header with Marcan's script [machodump.py](https://gist.github.com/marcan/e1808a2f4a5e1fc562357550a770afb1) in order to get the offsets to disassemble the code: - * Note: This requires the **construct** python package but the debian buster packages didn't work (python 3 or 2) or even a github version - * I had to use the pypi install via pip3: + * Note: This requires the **construct** python package but the debian buster packages didn't work (python 3 or 2) or even a github version + * I had to use the pypi install via pip3: ``` apt install python3-pip pip3 install construct diff --git a/docs/sw/partitioning-cheatsheet.md b/docs/sw/partitioning-cheatsheet.md index 37735703..81f5ecdd 100644 --- a/docs/sw/partitioning-cheatsheet.md +++ b/docs/sw/partitioning-cheatsheet.md @@ -31,7 +31,7 @@ If you broke your OS recovery, you might find yourself in a boot loop, even as y ## Physical disk layout on Apple Silicon * The NVMe drive has namespaces. You only care about the primary one, that's `disk0` on macOS or `nvme0n1` on Linux. - * The others are used for kernel panic logs and stuff like that. That's pretty low level stuff you don't have to care about. This is an NVMe thing, like "low-level partitions". Just don't think too much about it. + * The others are used for kernel panic logs and stuff like that. That's pretty low level stuff you don't have to care about. This is an NVMe thing, like "low-level partitions". Just don't think too much about it. * The primary namespace is formatted as a GPT partition table, same as on most Linux/Windows/Intel Mac systems these days * The GPT contains partitions, which can be traditional ones (FAT32, HFS+, Linux...) or APFS containers * An APFS container contains multiple logical volumes sharing disk space @@ -56,11 +56,11 @@ For Asahi Linux, we do not install alongside macOS in the same container, becaus So the installer will (for a normal Asahi Linux = Arch Linux ARM install) create three partitions: * A 2.5GB APFS container, containing the bits of iBoot/macOS we need to boot the machine including a copy of recoveryOS - * m1n1 stage 1 is installed here + * m1n1 stage 1 is installed here * A 500MB EFI System Partition - * m1n1 stage 2, U-Boot, and the GRUB core image live here + * m1n1 stage 2, U-Boot, and the GRUB core image live here * A Linux ext4 partition filling up the rest of the space - * GRUB modules and the Linux kernel/initramfs live here + * GRUB modules and the Linux kernel/initramfs live here To uninstall, you need to delete all three. @@ -91,18 +91,18 @@ Partitions in system disk (disk0): This shows: * One APFS container (380GB) containing 6 volumes (not listed) which comprise one macOS 12.3 install ("Macintosh HD"). Note: "Macintosh HD" is actually the name of the System subvolume, and this is how macOS itself displays volumes. - * If you had another macOS install sharing space in the same container, it would be listed as another `OS:` line under the same partition. - * disk3s1 is the *volume* for this macOS system, which means `disk3` is the virtual disk that represents this APFS container partition - * The UUID is the Volume Group ID of this OS, which is the primary identifier for it (e.g. how the machine finds it to boot it, how you select it in `bputil` prompts, the associated subdirectory name within the Preboot and Recovery subvolumes, and more) + * If you had another macOS install sharing space in the same container, it would be listed as another `OS:` line under the same partition. + * disk3s1 is the *volume* for this macOS system, which means `disk3` is the virtual disk that represents this APFS container partition + * The UUID is the Volume Group ID of this OS, which is the primary identifier for it (e.g. how the machine finds it to boot it, how you select it in `bputil` prompts, the associated subdirectory name within the Preboot and Recovery subvolumes, and more) * One APFS container (2.5GB) containing 4 volumes which is actually an Asahi Linux bootloader stub, using macOS 12.3 as its base version, named "Asahi Linux" - * If the install were complete, this would show your m1n1 stage 1 version. However, because it is not, it is listed as `incomplete install` until you reboot into it holding down the power button and complete the second step of installation. - * disk4s2 is the *volume* for this stub's system, which means `disk4` is the virtual disk that represents this APFS container partition + * If the install were complete, this would show your m1n1 stage 1 version. However, because it is not, it is listed as `incomplete install` until you reboot into it holding down the power button and complete the second step of installation. + * disk4s2 is the *volume* for this stub's system, which means `disk4` is the virtual disk that represents this APFS container partition * One EFI system partition (FAT32) * One Linux Filesystem partition (ext4 in this case, but the specific FS isn't identified/shown) * Some free space (unpartitioned) - note that the installer represents this as its own "partition" - * `diskutil` instead likes to refer to free space by the partition identifier of the partition right before it in physical disk order, which is needless to say quite confusing and error-prone. We figure giving it its own number makes more sense. + * `diskutil` instead likes to refer to free space by the partition identifier of the partition right before it in physical disk order, which is needless to say quite confusing and error-prone. We figure giving it its own number makes more sense. * The System Recovery partition (always exists last), which contains 2 APFS volumes and has one instance of recoveryOS installed (version 12.3). - * You don't want to touch this, but we show it since knowing what version of recoveryOS is present is useful. There could be a fallback version too. + * You don't want to touch this, but we show it since knowing what version of recoveryOS is present is useful. There could be a fallback version too. Note how it tells you that you are currently booted into the *Macintosh HD* OS (`[B ]`), but that the default boot OS is set to Asahi Linux (`[ *]`). If you were to run this from recoveryOS, it'd be shown as a `[R*]` (running the recoveryOS that is part of your default boot OS), unless you ended up falling back to System Recovery, in which case the boot mark would be in the last line, starting `[R ] recoveryOS...`. @@ -149,18 +149,18 @@ This shows the physical partitions in the order they are present on disk0 first: * `disk0` (shown as type "GUID_partition_scheme") actually represents the whole disk (500GB) * `disk0s1` is the iBoot System Container (type `Apple_APFS_ISC`), not shown in the Installer output - * This is actually an APFS container with more subvolumes, but `diskutil` itself hides those details from you too! - * This stores a bunch of system-critical information, you don't want to mess with it + * This is actually an APFS container with more subvolumes, but `diskutil` itself hides those details from you too! + * This stores a bunch of system-critical information, you don't want to mess with it * `disk0s2` is the first APFS container, which holds the "Macintosh HD" macOS volume - * Note how it says "Container disk3" to indicate this is shown as the virtual/synthesized `disk3` disk. + * Note how it says "Container disk3" to indicate this is shown as the virtual/synthesized `disk3` disk. * `disk0s5` is the Asahi Linux bootloader stub - * The partition index is out of order! This is logically after `disk0s2` and also in that position in the GPT. These partition numbers don't mean anything, it's whatever macOS feels like assigning that day. - * This is virtual disk `disk4`. + * The partition index is out of order! This is logically after `disk0s2` and also in that position in the GPT. These partition numbers don't mean anything, it's whatever macOS feels like assigning that day. + * This is virtual disk `disk4`. * `disk0s4` is the FAT32 EFI System Partition (displayed as type `EFI`, and with name `EFI - ASAHI` because it gets truncated for these) * `disk0s7` is the Linux root partition (displayed as type `Linux filesystem`) * Then there's some free space * `disk0s3` is the System Recovery partition (type `Apple_APFS_Recovery`) - * Really, don't mess with this. It is the only way to recover locally if your OS is broken. + * Really, don't mess with this. It is the only way to recover locally if your OS is broken. After this, you can see the two APFS containers broken out into volumes, each as their own virtual disk: `disk3` and `disk4`. In fact, there are two more: `disk1` is the iBoot System Container (backed by `disk0s1`) and `disk2` is the System Recovery (backed by `disk0s3`), but these are hidden from diskutil output. Remember, the numbering may/will be different for you! diff --git a/docs/sw/tethered-boot-macos-host.md b/docs/sw/tethered-boot-macos-host.md index 3d33cfe4..b76b45d3 100644 --- a/docs/sw/tethered-boot-macos-host.md +++ b/docs/sw/tethered-boot-macos-host.md @@ -11,10 +11,10 @@ This guide will give more details about tethered boot prerequisites setup for a Host's requirements: * Any Apple computer running a decently recent MacOs version - * Enough disk space on the host for installing and commpiling software - * a freee USB port on the host - * a USB-A/USB-C or USB-C/USB-C cable - * [prerequisites installed](#installing-prerequisite-software) + * Enough disk space on the host for installing and commpiling software + * a free USB port on the host + * a USB-A/USB-C or USB-C/USB-C cable + * [prerequisites installed](#installing-prerequisite-software) Tested with: diff --git a/docs/sw/tethered-boot.md b/docs/sw/tethered-boot.md index 9bee1cc7..cf52a9d0 100644 --- a/docs/sw/tethered-boot.md +++ b/docs/sw/tethered-boot.md @@ -10,9 +10,9 @@ This guide is intended specifically for kernel developers and advanced users who ## Hardware Requirements * 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. + * 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-macos-host.md)) - * Both `GCC` and `Clang/LLVM` AArch64 cross-toolchains are supported. + * 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 [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).