Merge pull request #3137 from raspberrypi/pi5-merge

Initial merge of partial documentation

documentation/asciidoc/computers/processors.adoc

@@ -8,4 +8,6 @@ include::processors/bcm2837b0.adoc[]
 
 include::processors/bcm2711.adoc[]
 
+include::processors/bcm2712.adoc[]
+
 include::processors/rp3a0.adoc[]

documentation/asciidoc/computers/processors/bcm2712.adoc

@@ -0,0 +1,26 @@
+== BCM2712
+
+Broadcom BCM2712 is the 16nm application processor at the heart of Raspberry Pi 5. It is the successor to the BCM2711 device used in Raspberry Pi 4, and shares many common architectural features with other devices in the BCM27xx family, used on earlier Raspberry Pi products.
+
+Built around a quad-core Arm Cortex-A76 CPU cluster, clocked at up to 2.4GHz, with 512KB per-core L2 caches and a 2MB shared L3 cache, it integrates an improved 12-core VideoCore VII GPU; a hardware video scaler and HDMI controller capable of driving dual 4kp60 displays; and a Raspberry Pi-developed HEVC decoder and Image Signal Processor. A 32-bit LPDDR4X memory interface provides up to 17GB/s of memory bandwidth, while x1 and x4 PCI Express interfaces support high-bandwidth external peripherals; on Raspberry Pi 5 the latter is used to connect to the Raspberry Pi RP1 south bridge, which provides the bulk of the external-facing I/O functionality on the platform.
+
+Headline features include: 
+
+* Quad-core Arm Cortex-A76 @ 2.4GHz
+** ARMv8-A ISA
+** 64KByte I and D caches
+** 512KB L2 per core, 2MB shared L3
+* New Raspberry Pi-developed ISP
+** 1 gigapixel/sec
+* Improved HVS and display pipeline
+** Dual 4Kp60 support
+* VideoCore V3D VII
+** ~2-2.5× faster (more hardware, 1GHz versus 600MHz on Pi 4)
+** OpenGL ES 3.1, Vulkan 1.3
+* 4Kp60 HEVC hardware decode
+** Other CODECs run in software
+** H264 1080p24 decode ~10–20% of CPU
+** H264 1080p60 decode ~50–60% of CPU
+** H264 1080p30 encode (from ISP) ~30–40% CPU
+
+In aggregate, the new features present in BCM2712 deliver a performance uplift of 2-3x over Raspberry Pi 4 for common CPU or I/O-intensive use cases.

documentation/asciidoc/computers/raspberry-pi-5.adoc

@@ -0,0 +1,20 @@
+
+include::raspberry-pi-5/introduction.adoc[]
+
+include::raspberry-pi-5/rp1.adoc[]
+
+include::raspberry-pi-5/power-supply.adoc[]
+
+include::raspberry-pi-5/cooling.adoc[]
+
+include::raspberry-pi-5/pcie.adoc[]
+
+include::raspberry-pi-5/mipi.adoc[]
+
+include::raspberry-pi-5/uart.adoc[]
+
+include::raspberry-pi-5/rtc.adoc[]
+
+include::raspberry-pi-5/poe.adoc[]
+
+include::raspberry-pi-5/schematics.adoc[]

documentation/asciidoc/computers/raspberry-pi-5/cooling.adoc

@@ -0,0 +1,47 @@
+
+== Cooling Raspberry Pi 5
+
+Raspberry Pi 5 has been designed to handle typical client workloads, uncased, with no active cooling. However for heavier loads there are two official options when it comes to cooling your Raspberry Pi 5. Both of these plug into the four-pin JST fan connector located in the upper right of the board between the 40-pin GPIO header and the USB 2 ports.
+
+Both of the available official accessories are actively managed by the Raspberry Pi firmware: at 60°C the fan will be turned on, at 67.5°C fan speed increases, and finally at 75°C the fan increases to full speed. When the temperature drops back below these limits the fan will spin down automatically.
+
+NOTE: The USB ports and fan connector both pull from the same 1.6A current limit.
+
+=== Official Case
+
+.The official Case for Raspberry Pi 5
+image::images/case.jpg[alt="Case with integrated fan for Raspberry Pi 5",width="70%"]
+
+The official case for Raspberry Pi 5 comes with an integrated fan. HATs can be fitted diretly on top of Raspberry Pi 5 by removing the fan, or on top of the fan by use of 14mm high standoffs and a 19mm GPIO extender. These are available separately from Authorised Resellers.
+
+The integrated 2.79 (max) CFM fan has fluid dynamic bearings selected for low noise and an extended operating lifetime. Air is drawn in through a 360-degree slot under the lid and blown over a heatsink attached to the BCM2712, and exhausted through connector apertures and vents in the base.
+
+=== Active Cooler
+
+.The Active Cooler for Raspberry Pi 5
+image::images/active-cooler.jpg[alt="Active Cooler for Raspberry Pi 5",width="70%"]
+
+The active cooler is a single-piece annodized aluminium heatsink with a integrated blower. It has pre-applied thermal pads for heat transfer, and is mounted to the Raspberry Pi 5 board directly using spring-loaded push pings, and connects to the same 4-pin JST connector as the case fan.
+
+A radial blower, again selected for low noise and extended operating lifetime, pushes air through an extruded and milled aluminium heatsink. The cooling performance of the Active Cooler is somewhat superior to the Fan Case, making it particularly suitable for overclockers.
+
+NOTE: Blowers are electromechanical systems that direct air towards a specific direction using a fan and designated channels. While fans displace large volumes of air and promote circulation within a designated area, blowers provide a degree of air pressurization to drive it out and forward.
+
+=== Thermals
+
+A stress test was started on all four cores of the Raspberry Pi 5 to load the CPU. Maximum power consumption on Raspberry Pi 5 with all four cores running is between 11 to 12W.
+
+Two main thermal management regimes were examined during ; no cooling, and managed active cooling using the new Active Cooler. The Raspberry Pi 5 was not placed inside a case. Instead, temperatures were observed while the board was sitting in the open air on the lab bench. 
+
+.Graph of CPU temeprature against time. 
+image::images/thermals.png[alt="Graphs of CPU temperature against time",width="100%"]
+
+With no cooling, we see an idle temperature of approximately 65°C, with a maximum temperature above 85°C during extended testing leading to sustained thermal throttling after the temperature reported by the processor rises above throttling limits. 
+
+Due to the passive heatsink with the Active Cooler fitted we see a much lower idle temperature, around 45°C. During extended testing under load the fan of the Cooler spins up at low speed to stabilise the CPU temperature at 60°C, with a maximum temperatures of 62 to 63°C being seen during the tests.
+
+Noise levels of between 35 to 40 dB were measured during the load test while the fan was in operation. The observed low noise levels were due to the low speeds of the blower. At no point during the extended stress testing require the fan spin up to full speed to maintain temperature control of the Raspberry Pi.
+
+Raspberry Pi 5 has been designed to handle typical client workloads, uncased, with no active cooling. For normal use adding cooling is therefore optional, although performace may improve with active cooling. However a heavy continuous load, such as rebuilding the Linux kernel, will force the new Raspberry Pi 5 into thermal throttling. For heavy loads thermal throttling can extend processing times and passive cooling is probably insufficient thermal management for heavy loads which extend beyond ~200 seconds of duration, with active cooling necessary to prevent thermal throttling from occurring. 
+
+Cooling of any type isn't mandatory, no harm will come to the Raspberry Pi if left uncooled, and while throttling under heavy load a Raspberry Pi 5 is still faster than an unthrottled Raspberry Pi 4. 

documentation/asciidoc/computers/raspberry-pi-5/introduction.adoc

@@ -0,0 +1,68 @@
+
+== Introduction
+
+.Raspberry Pi 5
+image::images/pi5-labelled.png[alt="Labelled diagram of the Raspberry Pi 5",width="100%"]
+
+Featuring a 64-bit quad-core Arm Cortex-A76 processor running at 2.4GHz, Raspberry Pi 5 delivers a ×2 to ×3 increase in CPU performance relative to Raspberry Pi 4. Alongside a substantial uplift in graphics performance from an 800MHz VideoCore VII GPU; dual 4Kp60 display output over HDMI; and state-of-the-art camera support from a rearchitected Raspberry Pi Image Signal Processor, it provides a smooth desktop experience for consumers, and opens the door to new applications for industrial customers.
+
+For the first time, this is a full-size Raspberry Pi computer using silicon built in-house at Raspberry Pi. The RP1 provides the bulk of the I/O capabilities for Raspberry Pi 5, and delivers a step change in peripheral performance and functionality. Aggregate USB bandwidth is more than doubled, yielding faster transfer speeds to external UAS drives and other high-speed peripherals; the dedicated two-lane 1Gbps MIPI camera and display interfaces present on earlier models have been replaced by a pair of four-lane 1.5Gbps MIPI transceivers, tripling total bandwidth, and supporting any combination of up to two cameras or displays; peak SD card performance is doubled, through support for the SDR104 high-speed mode; and for the first time the platform exposes a single-lane PCI Express 2.0 interface, providing support for high-bandwidth peripherals.
+
+=== Key features
+
+Key features include:
+
+* Quad Arm Cortex-A76 @ 2.4GHz
+* 512KB per-core L2 caches
+* 2MB L3 cache
+* 4GB or 8GB LPDDR4X-4267 SDRAM
+* Dual 4kp60 HDMI display output with HDR support
+* 4kp60 HEVC decoder
+* VideoCore VII graphics, with OpenGL-ES 3.1, Vulkan 1.2
+* Raspberry Pi Image Sensor Pipeline (ISP)
+* Raspberry Pi connector for PCIe (1 x 2.0 port, additional HAT required)
+* 802.11ac dual-band Wi-Fi
+* Bluetooth 5.0 (with BLE support)
+* Gigabit Ethernet
+* 2x USB 3.0 (capable of simultaneous full throughput)
+* 2x USB 2.0
+* PoE support (additional HAT required)
+* Dual 4-lane MIPI CSI/DSI transceivers, supporting
+** 2x display; or
+** 2x camera; or
+** 1x display + 1x camera
+* Raspberry Pi 40-pin GPIO header
+* Fan connector
+* Real Time Clock (RTC)
+** RTC battery connector
+* Power button
+
+=== Power button
+
+The Raspberry Pi 5 has a power button. However, when you plug your Raspberry Pi into power it will automatically turn on without having to push the button. 
+
+While your Raspberry Pi is running you can initiate a clean shutdown by pressing the Power Button, and then releasing it. If you want to force a hard shutdown, you should press and hold the Power Button.
+
+If the Raspberry Pi board is powered, but turned off, pressing the power button will restart the board.
+
+Default shutdown wattage is around 1 to 1.4W, this can be decreased by manually editing the EEPROM configuration, `sudo rpi-eeprom-config -e` and change the settings to:
+
+[source]
+----
+BOOT_UART=1
+POWER_OFF_ON_HALT=1
+BOOT_ORDER=0xf416
+----
+
+This should drop the shutdown power consumption to around 0.01W.
+
+=== Updating your firmware
+
+While firmware updates are rare, if you run into a problem with your Raspberry Pi you may want to check to see if one is available. You can do so as below:
+
+[source,bash]
+----
+sudo apt update
+sudo apt upgrade
+sudo rpi-eeprom-update -a
+----

documentation/asciidoc/computers/raspberry-pi-5/mipi.adoc

@@ -0,0 +1,28 @@
+
+== MIPI CSI/DSI connectors
+
+The CSI and DSI ports found on previous models of Rasbpberry Pi have been combined into two multi-purpose CSI/DSI ports. To fit onto the board these now using the denser connector pinout prevously only found on Raspberry Pi Zero. You can connect either two displays, or two cameras (or one camera and one display) to these ports.
+
+NOTE: The Compute Module cable adaptors, see https://datasheets.raspberrypi.com/cmcda/cmcda-schematics.pdf[schematics] and https://datasheets.raspberrypi.com/cmcda/RPi-CMCDA-1P1.zip[design files], can be used.
+
+=== Cameras cables
+
+.Camera cables
+image::images/camera-cables.jpg[alt="Camera cables",width="70%"]
+
+There are three Flat Flexible Cable (FFC) available to connect CSI cameras to the Raspberry Pi 5:
+
+* 200 mm camera cable Standard to Mini
+* 300 mm camera cable Standard to Mini
+* 500 mm camera cable Standard to Mini
+
+=== Displays cables
+
+.Display cables
+image::images/display-cables.jpg[alt="Display cables",width="70%"]
+
+There are three Flat Flexible Cable (FFC) available to connect DSI displays to the Raspberry Pi 5:
+
+* 200 mm display cable Standard to Mini
+* 300 mm display cable Standard to Mini
+* 500 mm display cable Standard to Mini

documentation/asciidoc/computers/raspberry-pi-5/pcie.adoc

@@ -0,0 +1,14 @@
+
+== Raspberry Pi connector for PCIe
+
+
+=== Enabling PCIe
+
+You can enable the PCIe by setting "dtparam=pciex1" or "dtaparam=nvme" in the `config.txt` file. If you see,
+
+[source]
+----
+brcm-pcie 1000110000.pcie: link down
+----
+
+then the driver is enabled.

documentation/asciidoc/computers/raspberry-pi-5/poe.adoc

@@ -0,0 +1,5 @@
+
+== Power over Ethernet (PoE) connector
+
+.The Raspberry Pi PoE+ HAT for Raspberry Pi 5
+image::images/poe-prototype.jpg[alt="The PoE+ HAT for Raspberry Pi 5,width="70%"]

documentation/asciidoc/computers/raspberry-pi-5/power-supply.adoc

@@ -0,0 +1,73 @@
+
+== Powering Raspberry Pi 5
+
+Raspberry Pi manufactuer two different USB-C power supplies. 
+
+The first is the Raspberry Pi 15W USB-C Power Supply, this is the recommended supply for Raspberry Pi 4 and Raspberry Pi 400. The second Raspberry Pi 27W USB-C Power Supply, this provides up to 5A current at +5.1V, and it is the recommended supply for Raspberry Pi 5.
+
+The USB-C standard, used by the Raspberry Pi 4 supply, is limited to 5V at 3A, for a total power output of 15W. The USB-PD standard allows higher voltages and currents to be negotiated via software but requires an appropriate Power Management Integrated Circuit (PMIC) which is only present on Raspberry Pi 5. Additionally these supplies requires you to use a suitable USB-PD compatible cables. 
+
+NOTE: It's not possible to use older USB "dumb" cables and connectors to provide more than 15W even with a USB-PD capable supply.
+
+While any USB-PD capable phone charges advertise greater than 15W of power. However, virtually all of them achieve this by increasing the voltage instead of providing more current at +5V. 
+
+If you are using a power supply that cannot provide 5A at +5V on first boot you will be warned by the operating system that the current draw to peripherals will be restricted.
+
+.On screen warning of under-voltage event
+image::images/firstboot-powerwarning.png[alt="On screen warning of under-voltage event in Raspberry Pi OS",width="70%"]
+
+We recommend the official Raspberry Pi Power Supply, which has been specifically designed to consistently provide +5V despite rapid fluctuations in current draw. Those fluctuations in demand are something that happens a lot when you’re using peripherals with the Raspberry Pi and something that other supplies—designed to provide consistent current for charging cellphones—usually don’t cope with all that well. It also has an attached micro USB cable, which means that you don’t accidentally use a poor-quality cable—something that can be an issue.
+
+NOTE: Raspberry Pi 5 makes use of the Renesas DA9091 “Gilmour” power-management IC (PMIC). This integrates eight separate switch-mode power supplies to generate the various voltages required by the board, including a quad-phase core supply, capable of providing 20 amps of current to power the Cortex-A76 cores and other digital logic in BCM2712.
+
+=== USB Boot and Power Supplies
+
+By default, USB boot is not enabled with a 3A power supply. A warning message is displayed on the bootloader HDMI diagnostics screen and the bootloader will skip to the next boot mode.
+
+[source]
+----
+Trying partition: 0
+type: 32 lba: 8192 'mkfs.fat' ' bootfs     ' clusters 130554 (4)
+rsc 32 fat-sectors 1020 root dir cluster 2 sectors 0 entries 0
+FAT32 clusters 130554
+[MSD [01:00] 2.00 000000:02] autoboot.txt not found
+Trying partition: 0
+type: 32 lba: 8192 'mkfs.fat' ' bootfs     ' clusters 130554 (4)
+rsc 32 fat-sectors 1020 root dir cluster 2 sectors 0 entries 0
+FAT32 clusters 130554
+Read config.txt bytes     2109 hnd 0x10a
+[MSD [01:00] 2.00 000000:02] pieeprom.upd not found
+usb_max_current_enable default 0 max-current 900
+Read bcm2712-rpi-5-b.dtb bytes    71862 hnd 0x5101
+dt-match: compatible: raspberrypi,5-model-b match: brcm,bcm2712
+dt-match: compatible: brcm,bcm2712 match: brcm,bcm2712
+***
+USB boot requires high current (5 volt 5 amp) power supply.
+To disable this check set usb_max_current_enable=1 in config.txt
+or press the power button to temporarily enable usb_max_current_enable
+and continue booting.
+See https://rptl.io/rp5-power_supply for more information
+***
+----
+
+The bootloader will prompt to "press power button to continue" which effectively sets `usb_max_current_enable=1` for the current boot, temporarily to allow you to allow from USB. However unless your disk has its own external power supply it is possible that there may not be sufficient current available to your Raspberry Pi.
+
+=== Power supplies and Raspberry Pi OS
+
+The bootloader passes information about the power-supply via device-tree `/proc/device-tree/chosen/power`. Users would typically not read this directly.
+
+max_current:: The max current in mA
+uspd_power_data_objects:: A dump of the PDOs - debug for advanced users.
+usb_max_current_enable:: Whether the current limiter was set to high or low. 
+usb_over_current_detected:: Whether any USB over current occured during boot before transferring control to the OS.
+reset_event:: The PMIC reset reason e.g. watchdog, over or under voltage, over-temperature
+
+The PMIC has built-in ADCs that, amongst other things, can measure the supply voltage `EXT5V_V`
+
+[source,bash]
+----
+vcgencmd pmic_read_adc
+----
+
+NOTE: You can't see USB current or anything else connected directly to 5V because this bypasses the PMIC, so you should not expect this to add up to the wattage of the source power supply. However, it can be useful to monitor things like the core-voltage.
+

documentation/asciidoc/computers/raspberry-pi-5/rp1.adoc

@@ -0,0 +1,21 @@
+
+== RP1
+
+.Architecture of the RP1
+image::images/rp1.jpg[alt="Architecture diagram of the RP1",width="50%"]
+
+The RP1 is a 12 × 12mm, 0.65mm-pitch BGA, “southbridge” which provides the majority of the I/O capabilities for Raspberry Pi 5. Access to peripherals from BCM2712 is done via the RP1 on Raspberry Pi 5. It provides:
+
+* 4-lane PCIe 2.0 endpoint
+* Gigabit Ethernet MAC
+* (connection to external PHY using RGMII) 
+** 2 × USB 3 host controllers
+** Each has 1 × USB 3 and 1 × USB 2 port
+* More than double usable USB BW vs Pi 4
+* 2 × SDIO ports / eMMC (not used on Pi 5)
+* MIPI transceivers (4-lane, supporting DSI and CSI-2)
+** Video DAC (3-channel, supporting PAL/NTSC and VGA)
+* Only one channel (composite) used on Pi 5
+* Low-speed peripherals (SPI, UART, I2C, PWM, GPIO, I2S)
+* Delta Sigma PWM audio out
+

documentation/asciidoc/computers/raspberry-pi-5/rtc.adoc

@@ -0,0 +1,61 @@
+
+== Real Time Clock (RTC)
+
+The Raspberry Pi 5 includes an RTC module. This may be battery powered (e.g. 3V coin cell battery), connected to J5 (BAT) connector. However, it is still has uses without a battery.
+
+You can set a wake alarm and switch to a very low power state (e.g. 3mA). When alarm time is reached, it will power back on. You could imagine using this for periodic (e.g. time-lapse images) jobs.
+
+To support the low powered mode for wake up alarms you want this bootloader config:
+
+[source, bash]
+----
+POWER_OFF_ON_HALT=1
+WAKE_ON_GPIO=0
+----
+
+use this to edit them:
+
+[source,bash]
+----
+sudo -E rpi-eeprom-config --edit
+----
+
+You can test with:
+
+[source,bash]
+----
+echo +600 | sudo tee /sys/class/rtc/rtc0/wakealarm
+sudo halt
+----
+
+That will halt (in a very low power state) then wake and restart after 10 minutes.
+
+The RTC also provides the time on boot. e.g. in `dmesg`:
+
+[source,bash]
+----
+[    1.295799] rpi-rtc soc:rpi_rtc: setting system clock to 2023-08-16T15:58:50 UTC (1692201530)
+----
+
+which may be useful if you don't have an internet connection for getting time through NTP.
+
+[NOTE]
+====
+The current bootloader doesn't enable the RTC XOSC, until an update is released you can manually do this:
+
+[source, bash]
+----
+vcgencmd pmicwr 0x5003 1
+----
+
+This setting is persistent, so you should only have to do this once.
+====
+
+=== Adding a backup battery
+
+WARNING: We do not recommend using a primary Lithium cell for the RTC. 
+
+.Lithium-manganese rechargeable RTC battery
+image::images/rtc-battery.jpg[alt="Lithium-manganese rechargeable RTC battery",width="70%"]
+
+The official battery part is a rechargeable Lithium Manganese coin cell, with a pre-fitted two-pin JST plug and adhesive mounting pad. This is suitable for powering the Raspberry Pi 5 RTC when the main power supply for the board is disconnected.

documentation/asciidoc/computers/raspberry-pi-5/schematics.adoc

@@ -0,0 +1,4 @@
+
+== Schematics and mechanical drawings
+
+* https://datasheets.raspberrypi.com/rpi5/raspberry-pi-5-mechanical-drawing.pdf[Mechanical Drawings, PDF]