Merge pull request #332 from flatcar/chewi/dev-notes

Dev Guide Disk Layout additions

content/docs/latest/reference/developer-guides/sdk-disk-partitions.md

@@ -24,15 +24,17 @@ Flatcar Container Linux is designed to be reliably updated via a continuous stre
 For more information, [read more about the disk layout][chromium disk format] used by Chromium and ChromeOS, which inspired the layout used by Flatcar Container Linux.
 
 [OEM docs]: ../../installing/community-platforms/notes-for-distributors
-[chromium disk format]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/disk_format.md
+[chromium disk format]: https://www.chromium.org/chromium-os/developer-library/reference/device/disk-format/
 
 ## Mounted filesystems
 
 Flatcar Container Linux is divided into two main filesystems, a read-only `/usr` and a stateful read/write `/`.
 
 ### Read-only /usr
 
-The `USR-A` or `USR-B` partitions are interchangeable and one of the two is mounted as a read-only filesystem at `/usr`. After an update, Flatcar Container Linux will re-configure the GPT priority attribute, instructing the bootloader to boot from the passive (newly updated) partition. Here's an example of the priority flags set on an Amazon EC2 machine:
+The `USR-A` or `USR-B` partitions are interchangeable, and one of the two is mounted as a read-only filesystem at `/usr`.
+
+These partitions each include three flags that affect the boot process, `priority`, `tries`, and `successful`. Their behaviour is fully described in the [manual rollback documentation][manual rollback docs]. Their behaviour is implemented in an [add-gpt-partition-scheme GRUB patch][GRUB patches]. After an update, Flatcar Container Linux will re-configure the GPT priority attribute, instructing the bootloader to boot from the passive (newly updated) partition. Here's an example of the priority flags set on an Amazon EC2 machine:
 
 ```shell
 $ sudo cgpt show /dev/xvda
@@ -45,15 +47,23 @@ $ sudo cgpt show /dev/xvda
 
 Flatcar Container Linux images ship with the `USR-B` partition empty to reduce the image filesize. The first Flatcar Container Linux update will populate it and start the normal active/passive scheme.
 
+As described in the [supply chain documentation][supply chain docs], these partitions are validated for security using `dm-verity`. The verity hash is stored at a well-known but otherwise unused location within the kernel. The hash is written into the kernel by the [build_image script][verity hash code]. It is then automatically injected into the kernel command line by GRUB, as implemented in this [add-verity-hash GRUB patch][GRUB patches].
+
+The chosen partition is initially mounted at `/sysusr` by the initrd using [Flatcar-specific dracut modules][dracut modules]. Some boot process tools, such as Ignition, are too large to store in the initrd, so they are run from this mount point instead via wrappers generated by [this module][wrapper generator].
+
 The OEM partition is mounted at `/usr/share/oem`.
 
+[manual rollback docs]: ../../setup/debug/manual-rollbacks
+[GRUB patches]: https://github.com/flatcar/scripts/tree/main/sdk_container/src/third_party/coreos-overlay/sys-boot/grub/files
+[supply chain docs]: ../supply-chain
+[verity hash code]: https://github.com/flatcar/scripts/blob/17ea3f2265df0c146b4b811eb9fad1abe35b21a2/build_library/build_image_util.sh#L820-L827
+[dracut modules]: https://github.com/flatcar/bootengine/tree/flatcar-master/dracut
+[wrapper generator]: https://github.com/flatcar/bootengine/blob/flatcar-master/dracut/30ignition/module-setup.sh
+
 ### Stateful root
 
 All stateful data, including container images, is stored within the read/write filesystem mounted at `/`. On first boot, the ROOT partition and filesystem will expand to fill any remaining free space at the end of the drive.
 
 The data stored on the root partition isn't manipulated by the update process. In return, we do our best to prevent you from modifying the data in /usr.
 
 Due to the unique disk layout of Flatcar Container Linux, `umount -l /etc && rm -rf --one-file-system --no-preserve-root /` is an unsupported but valid operation to purge any OS data. On the next boot, the machine should just start from a clean state, but note that you should rather use the `flatcar-reset` tool for a proper reset, which also gives control of what data to keep.
-
-[provisioning]: ../../provisioning
-[boot process]: ../../provisioning/ignition/boot-process