OpenSystemsDevelopment / usbboot

Commit 9c629d8745fd5a0c61439fe7ac6ba8e292b99051

Authored by Tim Gover
Committed by Phil Elwell
1 parent 989a72c3

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

Add a few tidyups and a note about initramfs
Inline Side-by-side
Showing 3 changed files with 57 additions and 8 deletions
Readme.md
  View file @9c629d8
... ... @@ -4,9 +4,9 @@ This is the USB MSD boot code which should work on the Raspberry Pi model A, Com
4 4 Module 3, Compute Module 4 and Raspberry Pi Zero.
5 5  
6 6 The default behaviour when run with no arguments is to boot the Raspberry Pi with
7   -special firmware sot that it emulates USB Mass Storage Device (MSD). The host OS
8   -will treat this as a normal USB mass storage device and allowing the file-system
9   -to be accessed. If the storage has not been formatted then (default for Compute Module)
  7 +special firmware so that it emulates USB Mass Storage Device (MSD). The host OS
  8 +will treat this as a normal USB mass storage device allowing the file-system
  9 +to be accessed. If the storage has not been formatted yet (default for Compute Module)
10 10 then the [Raspberry Pi Imager App](https://www.raspberrypi.com/software/) can be
11 11 used to install a new operating system.
12 12  
... ... @@ -21,11 +21,12 @@ For more information run `rpiboot -h`
21 21  
22 22 ### Linux / Cygwin / WSL
23 23 Clone this on your Pi or a Linux machine.
24   -Make sure that the system date is set correctly, otherwise, Git may produce an error.
  24 +Make sure that the system date is set correctly, otherwise Git may produce an error.
25 25  
26 26 ```
27 27 sudo apt install git libusb-1.0-0-dev
28 28 git clone --depth=1 https://github.com/raspberrypi/usbboot
  29 +cd usbboot
29 30 make
30 31 sudo ./rpiboot
31 32 ```
... ... @@ -58,6 +59,8 @@ or connecting the USB cable.
58 59 On Compute Module 4 EMMC-DISABLE / nRPIBOOT (GPIO 40) must be fitted to switch the ROM to usbboot mode.
59 60 Otherwise, the SPI EEPROM bootloader image will be loaded instead.
60 61  
  62 +
  63 +<a name="extensions"></a>
61 64 ## Compute Module 4 extensions
62 65 In addition to the MSD functionality, there are a number of other utilities that can be loaded
63 66 via RPIBOOT on Compute Module 4.
... ... @@ -65,10 +68,18 @@ via RPIBOOT on Compute Module 4.
65 68 | Directory | Description |
66 69 | ----------| ----------- |
67 70 | [recovery](recovery/README.md) | Updates the bootloader EEPROM on a Compute Module 4 |
  71 +| [rpi-imager-embedded](rpi-imager-embedded/README.md) | Runs the embedded version of Raspberry Pi Imager on the target device |
  72 +| [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 |
68 73 | [secure-boot-recovery](secure-boot-recovery/README.md) | Scripts that extend the `recovery` process to enable secure-boot, sign images etc |
69 74 | [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 |
70 75 | [secure-boot-example](secure-boot-example/README.md) | Simple Linux initrd with a UART console.
71 76  
  77 +## Booting Linux
  78 +The `RPIBOOT` protocol provides a virtual file-system to the Raspberry Pi bootloader and GPU firmware. It's therefore possible to
  79 +boot Linux. To do this, you will need to copy all of the files from a Raspberry Pi boot partition plus create your own
  80 +initramfs.
  81 +On Raspberry Pi 4 / CM4 the recommended approach is to use a `boot.img` which is a FAT disk image containing
  82 +the minimal set of files required from the boot partition.
72 83  
73 84 <a name="secure-boot"></a>
74 85 ## Secure Boot
... ... @@ -97,10 +108,10 @@ openssl genrsa 2048 &gt; private.pem
97 108 * 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.
98 109  
99 110 ## Secure Boot - image creation
100   -Secure boot requires a boot.img FAT image to be created. This plus a signature file (boot.sig)
  111 +Secure boot requires a `boot.img` FAT image to be created. This plus a signature file (boot.sig)
101 112 must be placed in the boot partition of the Raspberry Pi.
102 113  
103   -The contents of the boot.img are the files normally present in the Raspberry Pi OS boot
  114 +The contents of the `boot.img` are the files normally present in the Raspberry Pi OS boot
104 115 partition i.e. firmware, DTBs and kernel image. However, in order to reduce boot time
105 116 it is advisable to remove unused files e.g. firmware or kernel images for Pi models.
106 117  
... ... @@ -112,11 +123,25 @@ package supports secure boot. To download the firmware files directly.
112 123 A helper script (`make-boot-image`) is provided to automate the image creation process. This
113 124 script depends upon the `mkfs.fat` and `losetup` tools and only runs on Linux.
114 125  
  126 +### Root file-system
  127 +Normally, the Kernel modules and overlays for a secure-boot system would be provided
  128 +in an [initramfs](https://www.raspberrypi.com/documentation/computers/config_txt.html#initramfs)
  129 +and built with (buildroot)[https://buildroot.org/] or (yocto)[https://www.yoctoproject.org/].
  130 +
  131 +This ensures that all of the kernel modules and device tree dependencies are covered
  132 +by the secure-boot signature.
  133 +
  134 +Since the `initramfs` is part of the `boot.img` it is possible to replace GPU firmware,
  135 +kernel and dependencies in a single file update.
  136 +
  137 +Alternatively, for test/development the following instructions explain how a normal
  138 +Raspberry Pi OS install can be modified to be booted with the secure-boot loader.
  139 +
115 140 #### Clone the Raspberry Pi OS boot files
116 141 Copy the contents of `/boot` to a local directory called `secure-boot-files`
117 142  
118 143 #### Set the kernel root device
119   -Since the boot filesystem for the firmware is now in a signed disk image the OS cannot write to this.
  144 +Since the boot file-system for the firmware is now in a signed disk image the OS cannot write to this.
120 145 Therefore, any changes to `cmdline.txt` must be made before the `boot.img` file is signed.
121 146  
122 147 * 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
170 195 By default, the RSA public key is automatically extracted from the private key PEM file. Alternatively,
171 196 the public key may be specified separately via the `-p` argument to `update-pieeprom.sh` and `rpi-eeprom-config`.
172 197  
173   -To extract the public key in PEM format from a private key PEM file run.
  198 +To extract the public key in PEM format from a private key PEM file, run:
174 199 ```bash
175 200 openssl rsa -in private.pem -pubout -out public.pem`
176 201 ```
... ...
msd/README.md 0 → 100644
  View file @9c629d8
  1 +This directory contains the second stage bootloader and firmware for
  2 +booting the Raspberry Pi as a mass-storage device. The files here are
  3 +embedded into the `rpiboot` executable as part of the build process.
  4 +
  5 +To load the files from this directory directly, run:
  6 +
  7 +```bash
  8 +cd msd
  9 +../rpiboot -d .
  10 +```
... ...
recovery/README.md 0 → 100644
  View file @9c629d8
  1 +To update the SPI EEPROM bootloader on a Compute Module 4.
  2 +
  3 +* Modify the EEPROM configuration as desired
  4 +* Optionally, replace pieeprom.original.bin with a custom version. The default
  5 + version here is the latest stable release recommeded for use on Compute Module 4.
  6 +
  7 +N.B The `bootcode4.bin` file in this directory is actually the `recovery.bin`
  8 +file used on Raspberry Pi 4 bootloader update cards.
  9 +
  10 +```bash
  11 +cd recovery
  12 +./update-pieeprom.sh
  13 +../rpiboot -d .
  14 +```
... ...