Fix nested lists

Fixes: #204

Signed-off-by: Davide Cavalca <[email protected]>

Author: davide125

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.
 

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)
 

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

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
 ```

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 <src> <tgt>` : hard link
-  * `FILE <name> SHA256 <hash>`: file
+    * `LINK <src> <tgt>` : hard link
+    * `FILE <name> SHA256 <hash>`: file
 
 These files are then placed in the EFI system partition under the `vendorfw` directory.