Clarify the use of OTP GPIO boot modes (raspberrypi#764)

* Clarify the use of OTP GPIO boot modes

Clarify the use of OTP GPIO boot modes, with warnings about the irreversibility of the settings and the bugs in older firmware.

* copy edits

* copy edits

* Squash typo correction

Author: pelwell

hardware/raspberrypi/bootmodes/bootflow.md

@@ -1,8 +1,12 @@
 # Boot flow
 
-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 `program_gpio_bootmode` OTP bit is 1 or 2. If it is, then it reads either GPIOs 22-26 (program_gpio_bootmode=1) or 39-43 (program_gpio_bootmode=2) and uses those bits to disable boot modes. This means it is possible to use a hardware switch to switch between different boot modes if there are more than one available.
+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.
 
-To set the boot mode option, just add 'program_gpio_bootmode=n' where n is 1 or 2 as above, into config.txt. Boot the device, then power cycle the device (reboot will not work). 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.
+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.
+
+N.B.:
+1. It is important to remember that, **once set, OTP bits can never be unset**, so think carefully before enabling this facility because it effectively makes 5 GPIOs unusable for other purposes. Also note that the bit assignments make it possible to switch from the low bank (22-26) to the high bank (39-43), **but not back again**, and that selecting the high bank is likely to produce a non-bootable Pi, unless you're using a Compute Module (any version).
+2. **Do not use `program_gpio_bootmode` unless your firmware is dated 20 Oct 2017 or later (`vcgencmd version`). Doing so will make it impossible to select the low bank of boot mode GPIOs.**
 
 Next the boot ROM checks each of the boot sources for a file called bootcode.bin; if it is successful it will load the code into the local 128K cache and jump to it. The overall boot mode process is as follows:
 
@@ -35,9 +39,9 @@ Next the boot ROM checks each of the boot sources for a file called bootcode.bin
 
 NOTES: 
 
-* If there is no SD card inserted, the SD boot mode takes five seconds to fail. To reduce this and fall back to USB more quickly, you can either insert an SD card with nothing on it or use the `program_gpio_bootmode` OTP to only enable USB.
+* If there is no SD card inserted, the SD boot mode takes five seconds to fail. To reduce this and fall back to USB more quickly, you can either insert an SD card with nothing on it or use the GPIO bootmode OTP setting described above to only enable USB.
 * The default pull for the GPIOs is defined on page 102 of the [ARM Peripherals datasheet](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2835/BCM2835-ARM-Peripherals.pdf). If the value at boot time does not equal the default pull, then that boot mode is enabled.
-* USB enumeration is a means of enabling power to the downstream devices on a hub, then waiting for the device to pull the D+ and D- lines to indicate if it is either USB 1 or USB 2. This can take time: on some devices it can take up to three seconds for a hard disk drive to spin up and start the enumeration process. Because this is the only way of detecting that the hardware is attached, we have to wait for a minimum amount of time (two seconds). If the device fails to respond after this maximum timeout, it is possible to increase the timeout to five seconds using `program_usb_timeout=1` in **config.txt**.
+* USB enumeration is a means of enabling power to the downstream devices on a hub, then waiting for the device to pull the D+ and D- lines to indicate if it is either USB 1 or USB 2. This can take time: on some devices it can take up to three seconds for a hard disk drive to spin up and start the enumeration process. Because this is the only way of detecting that the hardware is attached, we have to wait for a minimum amount of time (two seconds). If the device fails to respond after this maximum timeout, it is possible to increase the timeout to five seconds using `program_usb_timeout=1` in `config.txt`.
 * MSD takes precedence over Ethernet boot.
 * It is no longer necessary for the first partition to be the FAT partition, as the MSD boot will continue to search for a FAT partition beyond the first one.
 * The boot ROM also now supports GUID partitioning and has been tested with hard drives partitioned using Mac, Windows, and Linux.