raspberrypi · ghost · Jan 20, 2021 · Jan 20, 2021 · Jan 20, 2021 · Jan 20, 2021
diff --git a/hardware/README.md b/hardware/README.md
@@ -1,10 +1,8 @@
-# Raspberry Pi Hardware
+# Raspberry Pi hardware
 
-Technical information about Raspberry Pi hardware, including official add-ons and the Pi itself.
+Technical information about Raspberry Pi hardware, including official add-ons.
 
-## Contents
-
-- [Raspberry Pi](raspberrypi/README.md)
+- [Raspberry Pi computers](raspberrypi/README.md)
 - [Camera Module](camera/README.md)
 - [Compute Module](computemodule/README.md)
 - [General HAT information](https://github.com/raspberrypi/hats/blob/master/README.md) (Links to our HAT github repository)

diff --git a/hardware/raspberrypi/README.md b/hardware/raspberrypi/README.md
@@ -1,48 +1,49 @@
-# Raspberry Pi hardware
+# Raspberry Pi computers
 
-The hardware in the Raspberry Pi
+Technical reference for Raspberry Pi computers.
 
 - [Schematics](schematics/README.md)
-    - Schematics for the Raspberry Pi
+
 - [Datasheets](datasheets.md)
-    - Datasheets for the Raspberry Pi
-- [BCM2835](bcm2835/README.md)
-    - The Broadcom processor used in Raspberry Pi 1 and Zero
-- [BCM2836](bcm2836/README.md)
-    - The Broadcom processor used in Raspberry Pi 2
-- [BCM2837](bcm2837/README.md)
-    - The Broadcom processor used in Raspberry Pi 3 (and later Raspberry Pi 2)
-- [BCM2837B0](bcm2837b0/README.md)
-    - The Broadcom processor used in Raspberry Pi 3B+ and 3A+
-- [BCM2711](bcm2711/README.md)
-    - The Broadcom processor used in Raspberry Pi 4B
-- [SPI Boot EEPROM (Pi4)](booteeprom.md)
-    - The boot EEPROM used in Raspberry Pi 4B
-- [Boot Diagnostics Display (Pi4)](boot_diagnostics.md)
-    - The boot diagnostics display on Raspberry Pi 4B
+
+- [BCM2835](bcm2835/README.md) - Raspberry Pi 1 and Zero
+
+- [BCM2836](bcm2836/README.md) - Raspberry Pi 2
+
+- [BCM2837](bcm2837/README.md) - Raspberry Pi 3 (and later Raspberry Pi 2)
+
+- [BCM2837B0](bcm2837b0/README.md) - Raspberry Pi 3B+ and 3A+
+
+- [BCM2711](bcm2711/README.md) - Raspberry Pi 4B and 400
+
+- [SPI Boot EEPROM (Pi 4, 400)](booteeprom.md) - Raspberry Pi 4B and 400
+
+- [Boot diagnostics display](boot_diagnostics.md) -  Raspberry Pi 4B and 400
+
 - [Boot modes](bootmodes/README.md)
-    - A description of the available BCM2835/6/7 boot modes
+
 - [Mechanical drawings](mechanical/README.md)
-    - Mechanical drawings of the Raspberry Pi
+
 - [Power](power/README.md)
-    - Powering the Raspberry Pi
+
 - [USB](usb/README.md)
-    - USB on the Raspberry Pi
-- [GPIO](gpio/README.md)
-    - General Purpose Input/Output pins on the Raspberry Pi
-- [SPI](spi/README.md)
-    - SPI on the Raspberry Pi
-- [DPI (Parallel/RGB Display)](dpi/README.md)
-    - DPI on the Raspberry Pi
-- [CSI-2 (Camera interface)](../../linux/software/libcamera/csi-2-usage.md)
-    - Using the CSI-2 interface on the Raspberry Pi
-- [Peripheral addresses](peripheral_addresses.md)
-    - How to access peripheral addresses using the bcm_host helpers
-- [Standard conformity documentation](conformity.md)
-    - Conformance documentation for the various standards bodies
-- [Revision codes](revision-codes/README.md)
-    - Raspberry Pi revision code reference
-- [OTP bit definitions](otpbits.md)
-    - Register and bit definitions for the One-Time Programmable (OTP) memory on the Raspberry Pi
+
+- [GPIO](gpio/README.md) - general purpose input/output pins
+
+- [SPI](spi/README.md) - serial peripheral interface
+
+- [DPI (Parallel/RGB Display)](dpi/README.md) - display parallel interface
+
+- [CSI-2 (Camera interface)](../../linux/software/libcamera/csi-2-usage.md) - camera serial interface 2
+
+- [Peripheral addresses](peripheral_addresses.md) - using `bcm_host` helpers
+
+- [Product compliance and safety](conformity.md)
+
+- [Revision code reference](revision-codes/README.md)
+
+- [OTP register and bit definitions](otpbits.md)
+
 - [Processor frequency and thermal management](frequency-management.md)
-    - Information on how the Raspberry Pi manages CPU frequencies and heat dissipation
+
+
diff --git a/hardware/raspberrypi/bcm2711/README.md b/hardware/raspberrypi/bcm2711/README.md
@@ -1,29 +1,11 @@
 # BCM2711
 
-This is the Broadcom chip used in the Raspberry Pi 4 Model B. The architecture of the BCM2711 is a considerable upgrade on that used by the SoCs in earlier Pi models. It continues the quad-core CPU design of the BCM2837, but uses the more powerful ARM A72 core. It has a greatly improved GPU feature set with much faster input/output, due to the incorporation of a PCIe link that connects the USB 2 and USB 3 ports, and a natively attached Ethernet controller. It is also capable of addressing more memory than the SoCs used before.
+Used on the Raspberry Pi 4B, 400 and Compute Module 4.
 
-The ARM cores are capable of running at up to 1.5 GHz, making the Pi 4 about 50% faster than the Raspberry Pi 3B+. The new VideoCore VI 3D unit now runs at up to 500 MHz. The ARM cores are 64-bit, and while the VideoCore is 32-bit, there is a new Memory Management Unit, which means it can access more memory than previous versions.
+The architecture of the BCM2711 is a considerable upgrade on that used by the SoCs in earlier Pi models. It continues the quad-core CPU design of the BCM2837, but uses the more powerful ARM A72 core. It has a greatly improved GPU feature set with much faster input/output, due to the incorporation of a PCIe link that connects the USB 2 and USB 3 ports, and a natively attached Ethernet controller. It is also capable of addressing more memory than previous SoCs.
 
-The BCM2711 chip continues to use the heat spreading technology started with the BCM2837B0, which provides better thermal management. 
-
-A datasheet for the BCM2711 can be found [here](https://datasheets.raspberrypi.org/bcm2711/bcm2711-peripherals.pdf).
-
-## Some technical details
-
-**Processor:**  Quad-core Cortex-A72 (ARM v8) 64-bit SoC @ 1.5 GHz. See [Wikipedia page](https://en.wikipedia.org/wiki/ARM_Cortex-A72) on the A72 for more details.
-
-**Memory:** Accesses up to 8GB LPDDR4-2400 SDRAM (depending on model)
+The ARM cores are clocked at 1.5GHz on the Pi 4B and 1.8GHz on the Pi 400. The new VideoCore VI 3D unit runs at up to 550 MHz. The ARM cores are 64-bit, and while the VideoCore is 32-bit, it has its own MMU, which allows it to access more memory than previous SoCs.
 
-**Caches:** 32 KB data + 48 KB instruction L1 cache per core. 1MB L2 cache.
-
-**Multimedia:** H.265 (4Kp60 decode); H.264 (1080p60 decode, 1080p30 encode); OpenGL ES, 3.0 graphics
-
-**I/O:** PCIe bus, onboard Ethernet port, 2 × DSI ports (only one exposed on Raspberry Pi 4B), 2 × CSI ports (only one exposed on Raspberry Pi 4B), up to 6 × I2C, up to 6 × UART (muxed with I2C), up to 6 × SPI (only five exposed on Raspberry Pi 4B), dual HDMI video output, composite video output.
-
-
-See the following documentation sections for information about the previous Raspberry Pi chips:
+The BCM2711 chip continues to use the heat spreading technology started with the BCM2837B0, which provides better thermal management. 
 
-* Raspberry Pi 3+ chip [BCM2837B0](../bcm2837b0/README.md)
-* Raspberry Pi 3 chip [BCM2837](../bcm2837/README.md)
-* Raspberry Pi 2 chip [BCM2836](../bcm2836/README.md)
-* Raspberry Pi 1 chip [BCM2835](../bcm2835/README.md)
+- [BCM2711 Datasheet](https://datasheets.raspberrypi.org/bcm2711/bcm2711-peripherals.pdf)
diff --git a/hardware/raspberrypi/bcm2835/README.md b/hardware/raspberrypi/bcm2835/README.md
@@ -1,13 +1,12 @@
 # BCM2835
 
-This is the Broadcom chip used in the Raspberry Pi Model A, B, B+, the Compute Module, and the Raspberry Pi Zero.
-
-Please refer to:
+Used on Raspberry Pi 1, Compute Module 1 and Zero.
 
 - [Peripheral specification](BCM2835-ARM-Peripherals.pdf)
    - **Note:** This document contains a number of errors. A list of currently known errata and some additional information can be found [here](https://elinux.org/BCM2835_datasheet_errata).
+
 - [GPU documentation](https://docs.broadcom.com/docs/12358545) and [open-source driver](https://docs.broadcom.com/docs/12358546)
+
 - [ARM1176 processor](https://www.arm.com/products/processors/classic/arm11/arm1176.php)
-- [ARM1176JZF-S](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0301h/index.html)
 
-Also see the Raspberry Pi 2 Model B's chip, [BCM2836](../bcm2836/README.md).
+- [ARM1176JZF-S](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0301h/index.html)
diff --git a/hardware/raspberrypi/bcm2836/README.md b/hardware/raspberrypi/bcm2836/README.md
@@ -1,12 +1,9 @@
 # BCM2836
 
-The Broadcom chip used in the Raspberry Pi 2 Model B
+Used on Raspberry Pi 2.
 
 The underlying architecture in BCM2836 is identical to BCM2835. The only significant difference is the removal of the ARM1176JZF-S processor and replacement with a quad-core Cortex-A7 cluster.
 
-Please refer to:
-
 - [BCM2836 ARM-local peripherals](QA7_rev3.4.pdf)
-- [Cortex-A7 MPcore Processor Reference Manual](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0464f/index.html)
 
-Also see the chip used in the Raspberry Pi Model A, B, B+, the Compute Module, and the Raspberry Pi Zero, [BCM2835](../bcm2835/README.md)
+- [Cortex-A7 MPcore Processor Reference Manual](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0464f/index.html)
diff --git a/hardware/raspberrypi/bcm2837/README.md b/hardware/raspberrypi/bcm2837/README.md
@@ -1,11 +1,7 @@
 # BCM2837
 
-This is the Broadcom chip used in the Raspberry Pi 3, and in later models of the Raspberry Pi 2. The underlying architecture of the BCM2837 is identical to the BCM2836. The only significant difference is the replacement of the ARMv7 quad core cluster with a quad-core ARM Cortex A53 (ARMv8) cluster.
+Used on Raspberry Pi 3, Compute Module 3 and later versions of the Raspberry Pi 2.
 
-The ARM cores run at 1.2GHz, making the device about 50% faster than the Raspberry Pi 2. The VideoCore IV runs at 400MHz.
-
-Please refer to the following BCM2836 document for details on the ARM peripherals specification, which also applies to the BCM2837.
+The underlying architecture of the BCM2837 is identical to the BCM2836. The only significant difference is the replacement of the ARMv7 quad-core cluster with a quad-core ARM Cortex A53 (ARMv8) cluster.
 
 - [BCM2836 ARM-local peripherals](../bcm2836/QA7_rev3.4.pdf)
-
-Also see the Raspberry Pi 2's chip [BCM2836](../bcm2836/README.md) and the Raspberry Pi 1's chip [BCM2835](../bcm2835/README.md).
diff --git a/hardware/raspberrypi/bcm2837b0/README.md b/hardware/raspberrypi/bcm2837b0/README.md
@@ -1,15 +1,7 @@
 # BCM2837B0
 
-This is the Broadcom chip used in the Raspberry Pi 3B+ and 3A+. The underlying architecture of the BCM2837B0 is identical to the BCM2837A0 chip used in other versions of the Pi. The ARM core hardware is the same, only the frequency is rated higher.
+Used on the Raspberry Pi 3B+,  3A+ and Computer Module 3+.
 
-The ARM cores are capable of running at up to 1.4GHz, making the 3B+/3A+ about 17% faster than the original Raspberry Pi 3. The VideoCore IV runs at 400MHz. The ARM core is 64-bit, while the VideoCore IV is 32-bit.
+The underlying architecture of the BCM2837B0 is identical to the previous revision of the BCM2837. The only significant difference is the improved cooling, including metal heat spreader, which permits a higher clock speed. By contrast, BCM2835, BCM2836 and revision A0 of the BCM2837 use black plastic packages.
 
-The BCM2837B0 chip is packaged slightly differently to the BCM2837A0, and most notably includes a heat spreader for better thermals. These allow higher clock frequencies (or running at lower voltages to reduce power consumption), and more accurate monitoring and control of the chip's temperature.
-
-[This post on the Raspberry Pi blog](https://www.raspberrypi.org/blog/raspberry-pi-3-model-bplus-sale-now-35/) goes into further detail about the BCM2837B0 chip.
-
-Also see the following documents for information about the previous Raspberry Pi chips:
-
-* Raspberry Pi 3 chip [BCM2837](../bcm2837/README.md)
-* Raspberry Pi 2 chip [BCM2836](../bcm2836/README.md)
-* Raspberry Pi 1 chip [BCM2835](../bcm2835/README.md)
+See [this blog post](https://www.raspberrypi.org/blog/raspberry-pi-3-model-bplus-sale-now-35/) for further details.
diff --git a/hardware/raspberrypi/boot_diagnostics.md b/hardware/raspberrypi/boot_diagnostics.md
@@ -1,29 +1,33 @@
-## Boot Diagnostics on the Raspberry Pi 4
+## Boot diagnostics on the Raspberry Pi 4 and 400
 
-Starting with version 2020-04-16 of the Raspberry Pi 4 bootloader, diagnostic information can be displayed at boot time on an HDMI display. To see this diagnostic information, power down the Raspberry Pi 4, remove the SD card, then power back up. A diagnostic display similar to below should appear on the attached display.
+The bootloader EEPROM on the Pi 4 and 400 contains a diagnostic display which can be used to help troubleshoot certain types of boot problems: it is not an interactive bootloader. If you require an interactive bootloader, consider using a tool such as NOOBS or U-Boot.
+
+The diagnostic display is output on both HDMI ports, but only after a delay. This means it is not normally visible, however you can force it to be shown by booting the Pi with no boot device present. Note that early versions of the bootloader did not contain the diagnostic display.
 
 ![Boot Diagnostics Screen](bootloader-diagnostics.png)
 
 This diagnostics page will also appear if the bootloader is unable to boot from an inserted SD card, or is unable to network boot; for example, if there is no bootable image on the card, or it is defective, or the network boot parameters are incorrect.
 
-Once the diagnostics page is displayed, a reboot is only possible by power cycling the device (i.e. unplug then re-plug the power supply).
-
 The top line describes the model of Pi and its memory capacity. The QR code is a link to the [Downloads Page](https://raspberrypi.org/downloads).
 
-The diagnostic information is as follows:
+The information displayed is as follows:
 
-| Line: | Information |
+| Line | Information |
 | ---- | ----------- |
-| bootloader | Bootloader version - build date |
-| board      | Board revision - Serial Number - Ethernet MAC address | 
-| boot       | mode: (ROM boot mode - 6 SPI), order: EEPROM config [BOOT_ORDER](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2711_bootloader_config.md), RSTS: PM_RSTS register |
-| SD CID	   | SD Card Identifier defined by SD-CARD manufacturer |
-| part	     | Master Boot Record primary partitions type:LBA |
-| fw	       | Filename for start.elf and fixup.dat if present (e.g. start4x.elf, fixup4x.dat) |
-| net	       | Network boot: - Link status (up/down) client IP address (ip), Subnet (sn), Default gateway (gw) |
-| tftp       | Network boot: TFTP server IP address|
+| bootloader | Bootloader version,  build date |
+| board      | Board revision, serial number, Ethernet MAC address | 
+| boot       | Boot mode currently being attempted, boot order read from EEPROM config - see [boot order documentation](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2711_bootloader_config.md), RSTS: PM_RSTS register |
+| SD         | SD card detected status, contents of CID (card identification) register |
+| part	     | MBR partitions for boot mode currently being attempted |
+| fw	       | Filename for start.elf and fixup.dat firmware, if present (e.g. start4x.elf, fixup4x.dat) |
+| net	       | Network boot: link status (up/down), client IP address (ip), subnet (sn), default gateway (gw) |
+| tftp       | Network boot: TFTP server IP address |
+
+
+### Configuration options
 
+- `DISABLE_HDMI` - prevent the diagnostic display being shown
 
-This display can be disabled using the DISABLE_HDMI option, see [Pi4 Bootloader Configuration](./bcm2711_bootloader_config.md).
+- `HDMI_DELAY` - set how long the bootloader waits before showing the diagnostic display
 
-N.B. This is purely for diagnosing boot failures; it is not an interactive bootloader. If you require an interactive bootloader, consider using a tool such as NOOBS or U-Boot.
+See [Pi 4 Bootloader Configuration](./bcm2711_bootloader_config.md) for details.
diff --git a/hardware/raspberrypi/conformity.md b/hardware/raspberrypi/conformity.md
@@ -1,6 +1,6 @@
 # Product compliance and safety
 
-All Raspberry Pi products have undergone extensive compliance testing, and copies of the relevant certificates and conformity documents are available to download from the table below. 											
+All Raspberry Pi products have undergone extensive compliance testing; copies of the relevant certificates and conformity documents are available to download below. 											
 
 
 | Model           | Declaration of Conformity | Local and regional approval certificates |
@@ -36,19 +36,14 @@ All Raspberry Pi products have undergone extensive compliance testing, and copie
 
 The PCBs used in Raspberry Pi devices adhere to UL94-V0. Note that this applies to the PCBs **only**. 
 
-## Safety/User Guide Leaflets 
+## Product safety leaflets
 
-| Model           | Safety Leaflet |
-|:---------------:|:--------------:|
-| 3A+/3B+ | [Leaflet](./compliance/rpi_SAFE_3plus_1p3.pdf) |
-| 4B      | [Leaflet](./compliance/rpi_SAFE_4b_1p2.pdf) |
+'Safety and user guide' leaflets supplied with each device:
 
-## The Raspberry Pi Integrator Programme
+- [Raspberry Pi 3A+ and 3B+](./compliance/rpi_SAFE_3plus_1p3.pdf)
 
-The programme provides access to the same test engineers who worked on our Raspberry Pis during their compliance testing. It connects the user to a dedicated team at UL that assesses and tests the user’s product, facilitated by their in-depth knowledge of Raspberry Pi. The team at UL work closely with the Raspberry Pi engineering team, so any unexpected issues that may arise during testing can be resolved quickly. Through the programme, UL will streamline the testing and certification process, which will in turn decrease the amount of time necessary to launch the product. Our Integrator Programme is openly available, it comes with no added cost beyond the usual testing fees at UL, and there are companies already taking advantage of it.
+- [Raspberry Pi 4B](./compliance/rpi_SAFE_4b_1p2.pdf)
 
-Please contact [email protected] for more details of the Integrator Programme.
+## Support for industrial customers
 
-## Get your product on the market more quickly										
-
-We have put the Integrator Programme in place in the hope of eliminating the burden of navigating complicated compliance issues and making it easier for companies to bring new, exciting products to consumers. With simplified testing, companies and individuals can get products to market in less time and with lower overhead costs.
+For more information about the support available to industrial customers, including the Raspberry Pi Integrator Programme, visit the [industry section of our website](https://www.raspberrypi.org/for-industry/).
diff --git a/hardware/raspberrypi/datasheets.md b/hardware/raspberrypi/datasheets.md
@@ -1,17 +1,17 @@
 ## Datasheets
 
-### SoC's
+### SoCs used in Raspberry Pi computers
 
-The following datasheets are available for the SoC (System On Chip - the main processing chip) devices used on the Raspberry Pi platform.
+Datasheets for Broadcom system-on-chip devices:
 
-[BCM2835](bcm2835/BCM2835-ARM-Peripherals.pdf) - The SoC used on the Raspberry Pi 0 and 1. This datasheet is also applicable to the BCM2836 and BC2837 SoCs (used on the Pi2 and Pi3 respectively), as they use the same VideoCore IV GPU.
+- [BCM2835 ARM peripherals guide](bcm2835/BCM2835-ARM-Peripherals.pdf) - applicable to BCM2835, BCM2836, BCM2837
 
-[BCM2836 ARM-local peripherals](bcm2836/QA7_rev3.4.pdf) - ARM A7 peripheral datasheet for the BCM2836. This document is also applicable to the ARM A53's on the BCM2837.
+- [BCM2836 ARM-local peripherals](bcm2836/QA7_rev3.4.pdf) - ARM A7 peripheral datasheet for BCM2836. Also applicable to the ARM A53s on the BCM2837.
 
-[BCM2711](bcm2711/rpi_DATA_2711_1p0.pdf) - The SoC used on the Raspberry Pi 4.
+- [BCM2711 Datasheet](bcm2711/rpi_DATA_2711_1p0.pdf)
 
 
-### Specific Devices
+### Raspberry Pi products
 
 [Compute Module 3](../computemodule/datasheets/rpi_DATA_CM3plus_1p0.pdf)