format error fixes docs

imrank03 · Jun 5, 2022 · c7397c5 · c7397c5
1 parent 86d4d01
commit c7397c5
Show file tree

Hide file tree

Showing 9 changed files with 64 additions and 61 deletions.
diff --git a/book.toml b/book.toml
@@ -5,13 +5,8 @@ multilingual = false
 src = "src"
 title = "rustBoot Documentation"
 
-# [preprocessor]
-
-# [preprocessor.mermaid]
-# command = "mdbook-mermaid"
-
-# [preprocessor.svgbob2]
-# font_family = "Lucida Console"
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
 
 [output]
 

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -14,8 +14,7 @@
 - [Architecture](./architecture.md)
     - [rustBoot Images](arch/images.md)
     - [rustBoot Partitions](arch/partitions.md)
-    - [rustBoot Secure-Boot Flow](arch/boot_flow.md)
-    - [rustBoot Secure-Update Flow](arch/update_flow.md)
+    - [Secure-Boot & Update](arch/secure_boot_update.md)
     - [Signing Utilities](arch/signing_utilities.md)
 
 # Usage

diff --git a/src/arch/boot_flow.md b/src/arch/boot_flow.md
diff --git a/src/arch/images.md b/src/arch/images.md
@@ -62,7 +62,7 @@ Each tag represents some information about the firmware. `rustBoot` requires the
 >    - if it isn't signed or if it cannot be verified using the included the [`authentication-type`](images.md#tags).
 
 ## FIT-image format
-rustBoot leverages Uboot's [`flattened-uImage-tree`](https://raw.githubusercontent.com/u-boot/u-boot/master/doc/uImage.FIT/howto.txt) format when booting the linux kernel. 
+rustBoot leverages Uboot's [`flattened-uImage-tree`](https://raw.githubusercontent.com/u-boot/u-boot/master/doc/uImage.FIT/howto.txt) format to boot the linux kernel. 
 
 The FIT format is essentially an extension of  the [`device-tree`](https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.4-rc1) format. FIT allows us to combine multiple binaries such as the kernel, ramdisk, device-tree-blob etc. into a single image. 
 
@@ -72,7 +72,7 @@ A typical rustBoot fit-image contains 4 items in the following order
 - &nbsp; initrd
 - &nbsp; rbconfig
 
-**Here's an example fit-image source file :** It is also referred to as an image-tree source file or `.its` file.
+**Here's an example fit-image source file :** It is also referred to as an `image-tree` source file or `.its` file.
 
 ```json
 /dts-v1/;
@@ -163,21 +163,21 @@ As shown in the example above, a rustBoot compliant fit-image contains 4 items -
 - `rbconfig` - this is rustBoot's kernel configuraton. A simple `txt` file to add kernel command-line arguments.
 
 You can retrieve the first 3 (i.e. kernel, fdt, ramdisk) from a pre-built OS image: 
-- Maintainers of a particular linux distribution provide pre-built OS images. These images usually contain several partitions such as - 
+- Maintainers of a linux distribution provide pre-built OS images. These images usually contain several partitions such as - 
     - `boot:` contains the bootloader, kernel, dtb, ramdisk and other stuff
     - `system:` contains the root file system 
     - `others:` may contain other partitions for things such as storage etc.
 - simply download an OS image or a pre-built linux distribution from the maintainers website.
-    - In this example, I'll be using the `apertis` distribution.
-- it’s usually a compressed (zImage) format. Decompress it using a tool like unarchiver to get a disk image.  
+    - in this example, I'll be using the [`apertis`](https://www.apertis.org/download/) distribution.
+- it’s usually a compressed (zImage) format, decompress it using a tool like unarchiver to get a disk image.  
 - use `partx --show` to list all partitions
 ```powershell
 $ partx --show __linux_image_filepath__
 NR  START     END SECTORS SIZE NAME UUID
  1   8192  532479  524288 256M      9730496b-01
  2 532480 3661823 3129344 1.5G      9730496b-02
 ```
-In the above case, the first partition with a size of 256MB contains our boot-files. It's usually named `boot`. We can calculate the offset to `boot` volume/partition with the following command 
+In the above case, the first partition with a size of 256MB contains the boot-files. It's usually named `boot`. We can calculate the offset to the `boot` volume/partition with the following command 
 ```powershell
 $ bc
 bc 1.07.1
@@ -193,19 +193,24 @@ For details type `warranty'.
 mount the partition as an `ext4` file-system (or `fat` file-system, whichever)
 ```
 $ sudo mkdir /mnt/other
-$ sudo mount -v -o offset=272629760 -t ext4 /_path_to_file_image/__filename__.img /mnt/other
+$ sudo mount -v -o offset=4194304 -t ext4 /_path_to_file_image/__filename__.img /mnt/other
 mount: /dev/loop0 mounted on /mnt/other.
 
 Check mounted image
 
 $ ls /mnt/other
 ```
-Finally copy the `dtb`, `ramdisk` and `vmlinuz` image (i.e. kernel) from the mounted partition to a new folder. You can give it any name you want. I'll use `pkg` in this example.
+ Copy the `dtb`, `ramdisk` and `vmlinuz` image (i.e. kernel) from the mounted partition to a new folder. You can give it any name you want. I'll use `pkg` for this example.
 > vmlinuz is a PE (portable executable) i.e. we can jump to it and it will in-turn jump to the kernel's entry point.  
 
-After storing all 4 items in the `pkg` folder, you can build a fit-image by running the following commands. 
-- the `.its` file is the input to `mkimage` 
-- and the `.itb` filename is the generated fit-image, stored in the same `pkg` folder. 
+`rbconfig:` Lastly, create a file named `rbconfig.txt` in the pkg folder. This file will be used by rustBoot to pass command-line parameters to the linux kernel. 
+
+Here's an example of the `rbconfig.txt` file -
+```powershell
+bootargs="root=UUID=64bc182a-ca9d-4aa1-8936-d2919863c22a rootwait ro plymouth.ignore-serial-consoles fsck.mode=auto fsck.repair=yes cma=128M"
+```
+
+When you have added all 4 items to the `pkg` folder, you can build a fit-image by running the following commands. 
 
 **On a mac:** 
 ```powershell
@@ -219,7 +224,11 @@ and then run
 
 ```powershell
 mkimage -f rpi4-apertis.its rpi4-test-apertis.itb
+```
+> - the input to `mkimage` is an `.its` file.  
+> - and `.itb` filename we've specified is the name given to the generated fit-image (that's stored in the `pkg` folder). 
 
+```
 Output:
 
 rpi4-apertis.its:65.37-70.6: Warning (unit_address_vs_reg): /configurations/bootconfig/signature@1: node has a unit name, but no reg or ranges property
@@ -278,7 +287,7 @@ Created:         Sat Jun  4 13:18:45 2022
   Sign value:   00
   Timestamp:    unavailable
 ```
-The `.itb` file is our fit-image. It does not contain a signature yet i.e. it is not signed. You'll notice `sign-value` field is empty. 
+This `.itb` file is our fit-image. It does not contain a signature yet i.e. it is not signed - notice the `sign-value` field is empty. 
 ### Signing fit-images
 rustBoot fit-images are signed with `ecdsa256`. The signature includes the kernel, fdt, initrd and rbconfig. 
 
@@ -290,6 +299,6 @@ Signing a rustBoot fit-image involves 2 steps:
 > - By default, valid rustBoot images are always signed.
 > - It will fail to boot an image
 >   - if the image fails fit-validation i.e. if its not a properly formatted fit-image or if the fit-parser cant find the specified default config or its components. 
->   - if it isn't signed or if it cannot be verified using the included algo.
+>   - if it isn't signed or if it cannot be verified using the specified algo.
 > - rustBoot's fit parser currently supports the following architectures
 >   - `Aarch64`
diff --git a/src/arch/partitions.md b/src/arch/partitions.md
@@ -39,13 +39,13 @@ BOOT, UPDATE, SWAP addresses and SECTOR_SIZE, PARTITION_SIZE values can be set v
 > - The `BOOT` partiton is the only partition from which we can boot a firmware image. The firmware image must be linked so that its entry-point is at address `256 + BOOT_PARTITION_ADDRESS`.
 > - `BOOT` firmware is responsible for downloading a new firmware image via a secure channel and installing it in the `UPDATE` partition. To trigger an update, the `BOOT` firmware updates the `status byte` of the `UPDATE` partition and performs a reboot. This will allow the bootloader to `swap the contents` of `BOOT` partition with that of the `UPDATE` partition. 
 
-## Linux System Updates:
+## Linux system partitions:
 
-To boot into linux systems, rustBoot includes support for the fat32 file-system. 
+To boot into a linux system, rustBoot includes support for the fat32 file-system. 
 
 Boot-storage media must contain a fat32 partition 
-- of at least 150 MiB to accomodate the bootloader, boot + update fit-images and other vendor-specific boot files.
-- in order to integrate rustBoot, you can either implement the `BlockDevice` trait for your board's boot-storage media `controller` or simply use an existing implementation included in the repo.
+- of at least 150 MiB to accomodate the bootloader, boot + update fit-images and other vendor-specific boot files and
+- to add rustBoot support for your board, you can either implement the `BlockDevice` trait for your board's boot-storage media `controller` or simply use an existing implementation from the repo.
 
 > **note:** rustBoot comes with batteries-included. It provides `rusty` implementations for basic peripherals such as flash, uart, crypto, gpio (out of the box) along with the necessary arch-specific initialization routines.
 > - for example: the rustBoot implementation for `rpi4` includes bare-metal drivers for the on-board emmc controller, gpio and uart peripherals. 
diff --git a/src/arch/secure_boot_update.md b/src/arch/secure_boot_update.md
@@ -0,0 +1 @@
+# Secure Boot & Update
diff --git a/src/arch/signing_utilities.md b/src/arch/signing_utilities.md
@@ -13,20 +13,21 @@ To sign a fit-image, rustBoot's [image signing utility](https://github.com/nihal
 - a raw signing-key or ecdsa private key
 - the ecdsa curve-type - (nistp256 only for now).
 
-Here's an example for how to sign a fit-image:
+Simply run the following command from root directory of the rustBoot project. 
+```
+cargo run ../boards/bootloaders/rpi4/apertis/rpi4-test-apertis.itb ../boards/rbSigner/keygen/ecc256.der nistp256
+```
+In the above example:
 - `../boards/bootloaders/rpi4/apertis/rpi4-test-apertis.itb` is the path to my fit-image 
 - `../boards/rbSigner/keygen/ecc256.der` is the path to my `test` signing-key
 - `nistp256` is the type ecdsa curve I'd like to use. Its the only one supported for now.
 
-Simply run the following command from root directory of the rustBoot project. 
 ```
-cargo run ../boards/bootloaders/rpi4/apertis/rpi4-test-apertis.itb ../boards/rbSigner/keygen/ecc256.der nistp256
-
 Output: 
 
     Finished dev [unoptimized + debuginfo] target(s) in 0.04s
      Running `/Users/nihal.pasham/devspace/rust/projects/prod/rustBoot/target/debug/rbsigner ../boards/bootloaders/rpi4/apertis/rpi4-test-apertis.itb ../boards/rbSigner/keygen/ecc256.der nistp256`
 signature: ecdsa::Signature<NistP256>([64, 147, 93, 99, 241, 5, 118, 167, 156, 150, 203, 234, 74, 207, 182, 243, 129, 143, 38, 2, 107, 85, 114, 145, 178, 163, 33, 153, 2, 100, 0, 114, 135, 18, 174, 183, 194, 110, 24, 186, 33, 36, 39, 105, 116, 74, 8, 118, 171, 237, 30, 108, 64, 205, 206, 14, 110, 226, 43, 143, 180, 193, 19, 33])
 bytes_written: 62202019
 ```
-In this case, the `signed fit-image` will be stored at the following path - `../boards/bootloaders/rpi4/apertis/signed-rpi4-apertis.itb`
+In the above example, the `signed fit-image` will be stored at the following path - `../boards/bootloaders/rpi4/apertis/signed-rpi4-apertis.itb`
diff --git a/src/arch/update_flow.md b/src/arch/update_flow.md