Update the top-level Readme.md to describe the '-d' programs

Add a few tidyups and a note about initramfs

Update the top-level Readme.md to describe the '-d' programs
Add a few tidyups and a note about initramfs
Tim Gover · Phil Elwell
1 parent 989a72c3
Showing 3 changed files with 57 additions and 8 deletions
Readme.md
msd/README.md
recovery/README.md
@@ -4,9 +4,9 @@ This is the USB MSD boot code which should work on the Raspberry Pi model A, Com
 Module 3, Compute Module 4 and Raspberry Pi Zero.
 The default behaviour when run with no arguments is to boot the Raspberry Pi with
-special firmware sot that it emulates USB Mass Storage Device (MSD). The host OS
-will treat this as a normal USB mass storage device and allowing the file-system
-to be accessed. If the storage has not been formatted then (default for Compute Module)
+special firmware so that it emulates USB Mass Storage Device (MSD). The host OS
+will treat this as a normal USB mass storage device allowing the file-system
+to be accessed. If the storage has not been formatted yet (default for Compute Module)
 then the [Raspberry Pi Imager App](https://www.raspberrypi.com/software/) can be
 used to install a new operating system.
@@ -21,11 +21,12 @@ For more information run `rpiboot -h`
 ### Linux / Cygwin / WSL
 Clone this on your Pi or a Linux machine.  
-Make sure that the system date is set correctly, otherwise, Git may produce an error.
+Make sure that the system date is set correctly, otherwise Git may produce an error.
 ```
 sudo apt install git libusb-1.0-0-dev
 git clone --depth=1 https://github.com/raspberrypi/usbboot
+cd usbboot
 make
 sudo ./rpiboot
 ```
@@ -58,6 +59,8 @@ or connecting the USB cable.
 On Compute Module 4 EMMC-DISABLE / nRPIBOOT (GPIO 40) must be fitted to switch the ROM to usbboot mode.
 Otherwise, the SPI EEPROM bootloader image will be loaded instead.
+
+<a name="extensions"></a>
 ## Compute Module 4 extensions
 In addition to the MSD functionality, there are a number of other utilities that can be loaded
 via RPIBOOT on Compute Module 4.
@@ -65,10 +68,18 @@ via RPIBOOT on Compute Module 4.
 | Directory | Description |
 | ----------| ----------- |
 | [recovery](recovery/README.md) | Updates the bootloader EEPROM on a Compute Module 4 |
+| [rpi-imager-embedded](rpi-imager-embedded/README.md) | Runs the embedded version of Raspberry Pi Imager on the target device |
+| [mass-storage-gadget](mass-storage-gadget/README.md) | Replacement for MSD firmware. Uses Linux USB gadgetfs drivers to export all block devices (e.g. NVMe, EMMC) as MSD devices |
 | [secure-boot-recovery](secure-boot-recovery/README.md) | Scripts that extend the `recovery` process to enable secure-boot, sign images etc |
 | [secure-boot-msd](secure-boot-msd/README.md) | Scripts for signing the MSD firmware so that it can be used on a secure-boot device |
 | [secure-boot-example](secure-boot-example/README.md) | Simple Linux initrd with a UART console.
+## Booting Linux
+The `RPIBOOT` protocol provides a virtual file-system to the Raspberry Pi bootloader and GPU firmware. It's therefore possible to
+boot Linux. To do this, you will need to copy all of the files from a Raspberry Pi boot partition plus create your own
+initramfs.
+On Raspberry Pi 4 / CM4 the recommended approach is to use a `boot.img` which is a FAT disk image containing
+the minimal set of files required from the boot partition.
 <a name="secure-boot"></a>
 ## Secure Boot
@@ -97,10 +108,10 @@ openssl genrsa 2048 &gt; private.pem
 * Please see the [secure boot MSD guide](secure-boot-msd/README.md) for instructions about to mount the EMMC via USB mass-storage once secure-boot has been enabled.
 ## Secure Boot - image creation
-Secure boot requires a boot.img FAT image to be created. This plus a signature file (boot.sig)
+Secure boot requires a `boot.img` FAT image to be created. This plus a signature file (boot.sig)
 must be placed in the boot partition of the Raspberry Pi.
-The contents of the boot.img are the files normally present in the Raspberry Pi OS boot
+The contents of the `boot.img` are the files normally present in the Raspberry Pi OS boot
 partition i.e. firmware, DTBs and kernel image. However, in order to reduce boot time
 it is advisable to remove unused files e.g. firmware or kernel images for Pi models.
@@ -112,11 +123,25 @@ package supports secure boot. To download the firmware files directly.
 A helper script (`make-boot-image`) is provided to automate the image creation process. This
 script depends upon the `mkfs.fat` and `losetup` tools and only runs on Linux.
+### Root file-system
+Normally, the Kernel modules and overlays for a secure-boot system would be provided
+in an [initramfs](https://www.raspberrypi.com/documentation/computers/config_txt.html#initramfs)
+and built with (buildroot)[https://buildroot.org/] or (yocto)[https://www.yoctoproject.org/].
+
+This ensures that all of the kernel modules and device tree dependencies are covered
+by the secure-boot signature.
+
+Since the `initramfs` is part of the `boot.img` it is possible to replace GPU firmware,
+kernel and dependencies in a single file update.
+
+Alternatively, for test/development the following instructions explain how a normal
+Raspberry Pi OS install can be modified to be booted with the secure-boot loader.
+
 #### Clone the Raspberry Pi OS boot files
 Copy the contents of `/boot` to a local directory called `secure-boot-files`
 #### Set the kernel root device
-Since the boot filesystem for the firmware is now in a signed disk image the OS cannot write to this.
+Since the boot file-system for the firmware is now in a signed disk image the OS cannot write to this.
 Therefore, any changes to `cmdline.txt` must be made before the `boot.img` file is signed.
 * Verify that `cmdline.txt` in `secure-boot-files` points to the correct UUID for the root file-system.
@@ -170,7 +195,7 @@ The RSA public key must be stored within the EEPROM so that it can be used by th
 By default, the RSA public key is automatically extracted from the private key PEM file. Alternatively,
 the public key may be specified separately via the `-p` argument to `update-pieeprom.sh` and `rpi-eeprom-config`.
-To extract the public key in PEM format from a private key PEM file run.
+To extract the public key in PEM format from a private key PEM file, run:  
 ```bash
 openssl rsa -in private.pem -pubout -out public.pem`
 ```
+This directory contains the second stage bootloader and firmware for
+booting the Raspberry Pi as a mass-storage device. The files here are
+embedded into the `rpiboot` executable as part of the build process.
+
+To load the files from this directory directly, run:  
+
+```bash
+cd msd
+../rpiboot -d .
+```
+To update the SPI EEPROM bootloader on a Compute Module 4.
+
+* Modify the EEPROM configuration as desired
+* Optionally, replace pieeprom.original.bin with a custom version. The default
+  version here is the latest stable release recommeded for use on Compute Module 4.
+
+N.B The `bootcode4.bin` file in this directory is actually the `recovery.bin`
+file used on Raspberry Pi 4 bootloader update cards.
+
+```bash
+cd recovery
+./update-pieeprom.sh
+../rpiboot -d .
+```