USB host/device boot - various improvements (#1126)

* Mention in bold that USB host boot only available on Pi 3 and 2v1.2

* Mention in bold that USB host boot only available on Pi 3 and 2v1.2

* Fix: USB *mass storage* boot only on 3 and 2v1.2

Page previously did not specify type of USB boot. Other Pi models do support USB *DEVICE* boot, so the previous sentence was incorrect.

* Mention only Pi 3 and 2v1.2 can do net boot, correct a sub-heading

* Make mention of which Pi models can do USB host boot consistent with other pages

And more accurate: some Pi 2Bs -> Pi 2B version 1.2

* Fix capitalisation in page heading

* Make page title consistent with link from hardware/raspberrypi/README.md

* Revert "Make page title consistent with link from hardware/raspberrypi/README.md"

This reverts commit 44ecfbf.

* Make page title consistent with link from hardware/raspberrypi/bootmodes/README.md

* bootmodes/device.md - improve page heading, improve wording

* Change warning about which Pi's can do USB boot

* Add Pi A and 3A+ to USB device mode boot docs

* 3A+ cannot net boot (no NIC)

* bootmodes/host.md: explain 3A+ can do MSD, not netboot

* 3A+ cannot net boot (no NIC) (take 2)

* bootmodes/README.md - fix up some wording around USB host boot

* use lurch's wording

* capitalise Ethernet to match other instances

* clarify / simplify wording

* Improve accuracy

* Combine BCM2837A0 and B0 variants into single page

* add B0 variant Pi models

* Revert "add B0 variant Pi models"

This reverts commit 65eb7e5.

* Revert "Combine BCM2837A0 and B0 variants into single page"

This reverts commit 18d0680.

* bootflow.md - this page only applies to 2837-based Pi's add relevant content for other Pi's and make this clear at the top of the page.

* tweak: move period outside link

* fix markup

* MSD -> mass storage device

* MSD -> mass storage device (take 2)

* tweak wording

* msd.md - standardise heading

* fix typo

* Don't say that USB device boot is enabled on all Pi's, since it doesn't actually work on them all

* fix wording

* fix wording

* mention OTP bit for USB device mode is enabled by default, but don't say "on all models of Pi"

* fix wording

* Update device.md

* some models -> above models of Pi

* fix wording "the required built in net iface" -> "a built in..."

* Minor changes in copy-edit

* Minor changes in copy-edit

* Minor changes in copy-edit

* Minor changes in copy-edit

* Minor changes in copy-edit

* V minor change in copy-edit

Author: andrum99

hardware/raspberrypi/bootmodes/README.md

@@ -17,13 +17,13 @@ The Raspberry Pi has a number of different stages of booting. This document expl
 [GPIO boot mode](gpio.md)
 
 ## Special bootcode.bin-only boot mode
-USB host and Ethernet boot can be performed by BCM2837-based Raspberry Pis (these are all Pi 3 models, and some Pi 2Bs). In addition, all Raspberry Pi models can use a new bootcode.bin-only method to enable USB host and Ethernet booting.
+USB host and Ethernet boot can be performed by BCM2837-based Raspberry Pis - that is, Pi 2B version 1.2, Pi 3B, and Pi 3B+ (Raspberry Pi 3A+ cannot net boot since it does not have a built-in Ethernet interface). In addition, all Raspberry Pi models can use a new bootcode.bin-only method to enable USB host boot.
 
-Just format an SD card as FAT32 and copy on the latest [bootcode.bin](https://github.com/raspberrypi/firmware/raw/master/boot/bootcode.bin). 
+Format an SD card as FAT32 and copy on the latest [bootcode.bin](https://github.com/raspberrypi/firmware/raw/master/boot/bootcode.bin). The SD card must be present in the Pi for it to boot. Once bootcode.bin is loaded from the SD card, the Pi continues booting using USB host mode.
 
-This is useful for the Raspberry Pi 1, 2, and Zero models, which are based on the BCM2835 and BCM2836 devices, and in situations where a Pi 3 fails to boot (the latest bootcode.bin includes additional bugfixes for the Pi 3, compared to the boot code burned into the BCM2837).
+This is useful for the Raspberry Pi 1, 2, and Zero models, which are based on the BCM2835 and BCM2836 chips, and in situations where a Pi 3 fails to boot (the latest bootcode.bin includes additional bugfixes for the Pi 3B, compared to the boot code burned into the BCM2837A0).
 
-If you have a problem with a mass storage device still not working even with this bootcode.bin, then please add a new file 'timeout' to the SD card. This should extend the time it waits for the mass storage device to initialise to six seconds.
+If you have a problem with a mass storage device still not working, even with this bootcode.bin, then please add a new file 'timeout' to the SD card. This will extend to six seconds the time for which it waits for the mass storage device to initialise.
 
 ## bootcode.bin UART enable
 

hardware/raspberrypi/bootmodes/bootflow.md

@@ -1,6 +1,8 @@
-# Boot flow for models prior to the Raspberry Pi 4
+# Boot sequence
 
-The flow of boot begins with reading the OTP to decide on the valid boot modes enabled. By default, this is SD card boot followed by USB device boot. Subsequently, the boot ROM checks to see if the GPIO boot mode OTP bits have been programmed — one to enable GPIO boot mode and one to select the bank of GPIOs it uses to disable boot modes (low = GPIOs 22-26, high = GPIOs 39-43). This makes it possible to use a hardware switch to choose between different boot modes if there is more than one available.
+**The following boot sequence applies to the BCM2837-based models of Raspberry Pi only. On all other models, the Pi will try [SD card boot](sdcard.md), followed by [USB device mode boot](device.md).**
+
+The boot sequence begins with reading the OTP to determine which boot modes are enabled. By default, this is SD card boot followed by USB device boot. Subsequently, the boot ROM checks to see whether the GPIO boot mode OTP bits have been programmed — one to enable GPIO boot mode, and one to select the bank of GPIOs it uses to disable boot modes (low = GPIOs 22-26, high = GPIOs 39-43). This makes it possible to use hardware attached to the GPIO connector to choose between different boot modes.
 
 The GPIO boot mode OTP bits can be programmed by adding `program_gpio_bootmode=n` to `config.txt`, where n is `1` to select the low bank (22-26) or `2` to select the high bank (39-43). Once added, boot the device, then power-cycle it (rebooting is not sufficient). You should expect it to no longer boot (all boot modes will be disabled by default). Apply a pull-up to the required pin to enable the required boot mode. After programming, the `config.txt` setting can be removed.
 

hardware/raspberrypi/bootmodes/device.md

@@ -1,13 +1,16 @@
-# Device boot
+# USB device boot mode
 
-The following devices can boot through the special device boot mode:
+The following devices can boot using USB device boot mode:
 
-* Pi CM
-* Pi CM3
+* Pi Compute Module 
+* Pi Compute Module 3
 * Pi Zero
 * Pi Zero W
+* Pi A
+* Pi A+
+* Pi 3A+
 
-When this boot mode is activated (usually after a failure to boot from the SD card), it switches to a USB device and awaits a USB reset from the host. Example code showing how the host needs to talk to the Pi can be found [here](https://github.com/raspberrypi/usbboot).
+When this boot mode is activated (usually after a failure to boot from the SD card), the Raspberry Pi puts its USB port into device mode and awaits a USB reset from the host. Example code showing how the host needs to talk to the Pi can be found [here](https://github.com/raspberrypi/usbboot).
 
 The host first sends a structure to the device down control endpoint 0. This contains the size and signature for the boot (security is not enabled so no signature is required). Secondly, code is transmitted down endpoint 1 (bootcode.bin).  Finally, the device will reply with a success code of:
 

hardware/raspberrypi/bootmodes/host.md

@@ -1,4 +1,6 @@
-# USB Host boot mode
+# USB host boot mode
+
+**USB host boot is available on Raspberry Pi 3B, 3B+, 3A+, and 2B v1.2 only. Raspberry Pi 3A+ only supports mass storage boot, not network boot.**
 
 The USB host boot mode follows this sequence:
 
@@ -12,11 +14,11 @@ The USB host boot mode follows this sequence:
         * If VID == SMSC && PID == 9500
           * Add device to Ethernet device list
         * If class interface == mass storage class
-          * Add device to MSD device list
+          * Add device to mass storage device list
 * Else
   * Enumerate single device
-* Go through MSD device list
-  * [Boot from MSD](msd.md)
+* Go through mass storage device list
+  * [Boot from mass storage device](msd.md)
 * Go through Ethernet device list
   * [Boot from Ethernet](net.md)
 

hardware/raspberrypi/bootmodes/msd.md

@@ -1,6 +1,6 @@
-# How to boot from a USB mass storage device on a Raspberry Pi
+# USB mass storage device boot
 
-**USB boot is available on the Raspberry Pi 3B, 3B+, 3A+ and Raspberry Pi 2B v1.2 models only.**
+**USB mass storage boot is available on Raspberry Pi 3B, 3B+, 3A+, and 2B v1.2 only.**
 
 This tutorial explains how to boot your Raspberry Pi from a USB mass storage device such as a flash drive or USB hard disk. Be warned that this feature is experimental and does not work with all USB mass storage devices. See [this blog post](https://www.raspberrypi.org/blog/pi-3-booting-part-i-usb-mass-storage-boot/) from Gordon Hollingworth for an explanation of why some USB mass storage devices don't work, as well as for some background information.
 

hardware/raspberrypi/bootmodes/net.md

@@ -1,6 +1,8 @@
 # Network booting
 
-This section describes how network booting works. We also have a [tutorial about setting up a working bootable system](net_tutorial.md). Network booting works only for the wired adapter built into certain models of Raspberry Pi. Booting over wireless LAN is not supported, nor is booting from any other wired network device.
+**Network booting is available on Raspberry Pi 3B, 3B+, and 2B v1.2 only.**
+
+This section describes how network booting works. We also have a [tutorial about setting up a working bootable system](net_tutorial.md). Network booting works only for the wired adapter built into the above models of Raspberry Pi. Booting over wireless LAN is not supported, nor is booting from any other wired network device.
 
 To network boot, the boot ROM does the following:
 
@@ -22,7 +24,7 @@ To get the serial number for the device you can either try this boot mode and se
 
 If you put all your files into the root of your tftp directory then all following files will be accessed from there.
 
-## Debugging the NFS boot mode
+## Debugging the network boot mode
 
 The first thing to check is that the OTP bit is correctly programmed. To do this, you need to add `program_usb_boot_mode=1` to config.txt and reboot (with a standard SD card that boots correctly into Raspbian). Once you've done this, you should be able to do:
 

hardware/raspberrypi/bootmodes/usb.md

@@ -1,14 +1,12 @@
 # USB boot modes
 
-There are two separate boot modes for USB: 
+There are two separate boot modes for USB (available only on certain models): 
 
 * [USB device boot](device.md)
 * [USB host boot](host.md) with boot options:
   * [USB mass storage boot](msd.md)
   * [Network boot](net.md)
 
-Note that network boot is only possible on Raspberry Pi models that have a built-in wired Ethernet interface.
-
-The choice between the two boot modes is made by the firmware at boot time when it reads the OTP bits. There are two bits to control USB boot: the first enables device boot and is enabled by default on all Raspberry Pi computers. The second bit enables USB host boot; if this bit is also set, then the processor reads the OTGID pin to decide whether to boot as a host (driven to zero as on the Raspberry Pi Model B) or as a device (left floating). The Pi Zero has access to this pin through the OTGID pin on the USB connector, and the Compute Module has access to this pin on the edge connector.
+The choice between the two boot modes is made by the firmware at boot time when it reads the OTP bits. There are two bits to control USB boot: the first enables USB device boot and is enabled by default. The second enables USB host boot; if the USB host boot mode bit is set, then the processor reads the OTGID pin to decide whether to boot as a host (driven to zero as on the Raspberry Pi Model B) or as a device (left floating). The Pi Zero has access to this pin through the OTGID pin on the USB connector, and the Compute Module has access to this pin on the edge connector.
 
 There are also OTP bits that allow certain GPIO pins to be used for selecting which boot modes the Pi should attempt to use.