Merge pull request #3129 from raspberrypi/develop

Push to production

Author: Alasdair Allan

.github/workflows/build.yml

@@ -23,7 +23,7 @@ jobs:
           echo "Pull requests based on master can only come from the develop branch of this repository"
           echo "Please check your base branch as it should be develop by default"
           exit 1
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3.9
@@ -39,7 +39,7 @@ jobs:
         with:
           version: 1.10.2
       - name: Install arm-none-eabi-gcc GNU Arm Embedded Toolchain
-        uses: carlosperate/arm-none-eabi-gcc-action@v1.6.3
+        uses: carlosperate/arm-none-eabi-gcc-action@v1.7.1
       - name: Install Doxygen
         run: |
           wget https://www.doxygen.nl/files/doxygen-1.9.6.linux.bin.tar.gz

documentation/asciidoc/accessories/camera/synchronous_cameras.adoc

@@ -18,7 +18,7 @@ Connect the XVS wires to the 1.65V potential divider pull up.
 
 ==== Boot up both Raspberry Pis
 
-The file `/sys/module/imx477/parameters/trigger_mode` determines which board outputs pulses, or waits to recieve pulses (source and sink).
+The file `/sys/module/imx477/parameters/trigger_mode` determines which board outputs pulses, or waits to receive pulses (source and sink).
 This parameter can only be altered in superuser mode.
 
 On the sink, run:
@@ -57,7 +57,7 @@ This ensures that no frames are created or lost upon startup. The source whilst
 
 === Using the GS Camera
 
-NOTE: The Global Shutter (GS) camera can also be operated in a synchonous mode. However, the source camera will record one extra frame. A much better alternative method to ensure that both cameras capture the same amount of frames is to use the xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger method].
+NOTE: The Global Shutter (GS) camera can also be operated in a synchronous mode. However, the source camera will record one extra frame. A much better alternative method to ensure that both cameras capture the same amount of frames is to use the xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger method].
 
 To operate as source and sink together, the Global Shutter Cameras also require connection of the XHS (horizontal sync) pins together. However, these do not need connection to a pullup resistor.
 

documentation/asciidoc/accessories/display/display_intro.adoc

@@ -2,6 +2,11 @@
 
 The Raspberry Pi Touch Display is an LCD display which connects to the Raspberry Pi through the DSI connector. In some situations, it allows for the use of both the HDMI and LCD displays at the same time (this requires software support).
 
+[.whitepaper, title="Implementing a DSI Driver on the Raspberry Pi", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003472-WP/Using-a-DSI-display.pdf]
+****
+This whitepaper is an introduction to writing a Display Serial Interface (DSI) driver for liquid crystal display (LCD) panels running under the Kernel Mode Setting (KMS) graphics system.
+****
+
 === Board Support
 
 The DSI display is designed to work with all models of Raspberry Pi, however early models that do not have mounting holes (the Raspberry Pi 1 Model A and B) will require additional mounting hardware to fit the HAT-dimensioned stand-offs on the display PCB.
@@ -136,4 +141,4 @@ Read our troubleshooting steps, tips, and tricks here: xref:display.adoc#trouble
 
 * Outer dimensions: 192.96 × 110.76mm
 * Viewable area: 154.08 × 85.92mm
-* https://datasheets.raspberrypi.com/display/7-inch-display-mechanical-drawing.pdf[Download mechanical drawing (PDF)]
+* https://datasheets.raspberrypi.com/display/7-inch-display-mechanical-drawing.pdf[Download mechanical drawing (PDF)]

documentation/asciidoc/computers/compute-module/cm-emmc-flashing.adoc

@@ -5,8 +5,6 @@
 The CM Provisioner is a web application designed to make programming a large number of Raspberry Pi Compute Module (CM) devices much easier and quicker. It is simple to install and simple to use. 
 
 It provides an interface to a database of kernel images that can be uploaded, along with the ability to use scripts to customise various parts of the installation during the flashing process. Label printing and firmware updating is also supported.
-
-This whitepaper assumes that the Provisioner server, software version 1.5 or newer, is running on a Raspberry Pi.
 ****
 
 The Compute Module has an on-board eMMC device connected to the primary SD card interface. This guide explains how to write data to the eMMC storage using a Compute Module IO board.

documentation/asciidoc/computers/compute-module/datasheet.adoc

@@ -13,6 +13,20 @@ There is also a KiCad PCB design set available:
 
 * https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip[Compute Module 4 IO Board KiCad files]
 
+[.whitepaper, title="Transitioning from CM3 to CM4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003469-WP/Transitioning-from-CM3-to-CM4.pdf]
+****
+This whitepaper is for those who wish to move from using a Raspberry Pi Compute Module (CM) 1 or 3 to a Raspberry Pi CM 4.
+
+From a software perspective, the move from Raspberry Pi CM 1/3 to Raspberry Pi CM 4 is relatively painless, as Raspberry Pi OS should work on all platforms.
+****
+
+[.whitepaper, title="Configuring the Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003470-WP/Configuring-the-Compute-Module-4.pdf]
+****
+The Raspberry Pi Compute Module 4 (CM 4) is available in a number of different hardware configurations. Sometimes it may be necessary to disable some of these features when they are not required.
+
+This document describes how to disable various hardware interfaces, in both hardware and software, and how to reduce the amount of memory used by the Linux operating system (OS).
+****
+
 === Older Products
 
 Raspberry Pi CM1, CM3 and CM3L are supported products with an End-of-Life (EOL) date no earlier than January 2026. The Compute Module 3+ offers improved thermal performance, and a wider range of Flash memory options.

documentation/asciidoc/computers/config_txt/overclocking.adoc

@@ -330,6 +330,10 @@ The GPU core, CPU, SDRAM and GPU each have their own PLLs and https://forums.ras
 To view the Raspberry Pi's current frequency in KHz, type: `cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq`. Divide the result by 1000 to find the value in MHz. Note that this frequency is the kernel _requested_ frequency, and it is possible that any throttling (for example at high temperatures) may mean the CPU is actually running more slowly than reported. An instantaneous measurement of the actual ARM CPU frequency can be retrieved using the vcgencmd `vcgencmd measure_clock arm`. This is displayed in Hertz.
 
 === Monitoring Core Temperature
+[.whitepaper, title="Cooling a Raspberry Pi device", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003608-WP/Cooling-a-Raspberry-Pi-device.pdf]
+****
+This whitepaper goes through the reasons why your Raspberry Pi may get hot and why you might want to cool it back down, and gives various options on achieving that cooling process.
+****
 
 To view the Raspberry Pi's temperature, type `cat /sys/class/thermal/thermal_zone0/temp`. Divide the result by 1000 to find the value in degrees Celsius. Alternatively, there is a vcgencmd, `vcgencmd measure_temp` that interrogates the GPU directly for its temperature.
 

documentation/asciidoc/computers/configuration/hdmi-config.adoc

@@ -15,6 +15,11 @@ If you are using legacy graphics drivers, or find yourself in circumstances wher
 
 NOTE: All the commands are documented fully in the xref:config_txt.adoc#video-options[config.txt] section of the documentation.
 
+[.whitepaper, title="Troubleshooting KMS HDMI output", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004341-WP/Troubleshooting-KMS-HDMI-output.pdf]
+****
+With the introduction of the KMS (Kernel Mode Setting) graphics driver, we are moving away from legacy firmware control of the video output system and towards a more open source graphics system. This document is intended to help with any issues that might arise when moving to the new system.
+****
+
 === HDMI Groups and Mode
 
 HDMI has two common groups: CEA (Consumer Electronics Association, the standard typically used by TVs) and DMT (Display Monitor Timings, the standard typically used by monitors). Each group advertises a particular set of modes, where a mode describes the resolution, frame rate, clock rate, and aspect ratio of the output.

documentation/asciidoc/computers/configuration/headless.adoc

@@ -6,6 +6,8 @@ If you haven't already imaged your Raspberry Pi, you can set up wireless network
 
 If you already have an image on the micro SD card, you can access the xref:configuration.adoc#the-boot-folder[boot folder] by inserting the card into a card reader on a Linux or Windows machine. Adding certain files to this folder will activate certain setup features on the first boot of the Raspberry Pi.
 
+If you plan on using VNC to access the desktop environment of your headless Raspberry Pi, use the `raspi-config` tool to set a xref:configuration.adoc#resolution[default display resolution].
+
 IMPORTANT: If you are installing Raspberry Pi OS, and intend to run it headless, you will need to create a new user account. Since you will not be able to create the user account xref:getting-started.adoc#configuration-on-first-boot[using the first-boot wizard] as it requires both a monitor and a keyboard, you *MUST* add a `userconf.txt` file to the boot folder to create a user on first boot or configure the OS with a user account using the xref:getting-started.adoc#advanced-options[Advanced Menu] in the Raspberry Pi Imager.
 
 === Configuring Networking
@@ -73,4 +75,3 @@ openssl passwd -6
 ----
 
 This will prompt you to enter your password, and verify it. It will then produce what looks like a string of random characters, which is actually an encrypted version of the supplied password.
-

documentation/asciidoc/computers/os/updating.adoc

@@ -118,6 +118,11 @@ sudo apt purge tree
 [[rpi-update]]
 === Using `rpi-update`
 
+[.whitepaper, title="Updating Pi firmware", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003476-WP/Updating-Pi-firmware.pdf]
+****
+In some circumstances it may be necessary to update the VideoCore firmware in a Raspberry Pi operating system (OS) image without going through the normal upgrade process. This whitepaper documents how to use the normal upgrade process, and also gives information on how to bypass the standard update process if it is not suitable.
+****
+
 `rpi-update` is a command line application that will update your Raspberry Pi OS kernel and VideoCore firmware to the latest pre-release versions.
 
 WARNING: Pre-release versions of software are not guaranteed to work. You should not use `rpi-update` on any system unless recommended to do so by a Raspberry Pi engineer. It may leave your system unreliable or even completely broken. It should not be used as part of any regular update process.

documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc

@@ -607,10 +607,25 @@ This option may be set to 0 to block self-update without requiring the EEPROM co
 Default: `1`
 
 === Secure Boot configuration properties in `config.txt`
+
+[.whitepaper, title="Raspberry Pi 4 Boot Security", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004651-WP/Raspberry-Pi-4-Boot-Security.pdf]
+****
+This whitepaper describes Raspberry Pi Ltd’s approach to boot security on the Raspberry Pi 4 family of devices, based on
+the BCM2711 system on a chip (SoC).
+****
+
+[.whitepaper, title="Boot security howto", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003466-WP/Boot-Security-Howto.pdf]
+****
+This whitepaper describes how to implement secure boot on devices based on Raspberry Pi 4. For an overview of the secure boot implementation, please see the Raspberry Pi 4 Boot Security whitepaper.
+
+The secure boot system is intended for use with buildroot (or similar)-based OS images; using it with Raspberry Pi OS is not recommended or supported.
+****
+
 The following `config.txt` properties are used to program the `secure-boot` OTP settings. These changes are irreversible and can only be programmed via `RPIBOOT` when flashing the bootloader EEPROM image.  This ensures that `secure-boot` cannot be set remotely or by accidentally inserting a stale SD card image.
 
 For more information about enabling `secure-boot` please see the https://github.com/raspberrypi/usbboot/blob/master/Readme.md#secure-boot[secure-boot readme] and the https://github.com/raspberrypi/usbboot/blob/master/secure-boot-example/README.md[secure-boot tutorial] in the https://github.com/raspberrypi/usbboot[USBBOOT] repo.
 
+
 [[program_pubkey]]
 ==== program_pubkey
 If this property is set to `1` then `recovery.bin` will write the hash of the public key in the EEPROM image to OTP.  Once set, the bootloader will reject EEPROM images signed with different RSA keys or unsigned images.

documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc

@@ -2,9 +2,7 @@
 
 [.whitepaper, title="Using a DPI Display on the Raspberry Pi", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003471-WP/Using-a-DPI-display.pdf]
 ****
-Display Parallel Interface (DPI) displays can be connected to Raspberry Pi devices via the 40-pin general-purpose input/output (GPIO) connector as an alternative to using the dedicated Display Serial Interface (DSI) or High-Definition Multimedia Interface (HDMI) ports. Many third-party DPI displays have been made available to take advantage of this. The Buster (and earlier) Raspberry Pi operating system (OS) and the legacy display stack used Raspberry Pi-specific parameters in config.txt to configure DPI displays. With the move to Bullseye and its use of the Kernel Mode Setting (KMS) graphics driver by default, these config.txt entries are no longer relevant as all control of the display pipeline has shifted to the Linux kernel.
-
-This whitepaper assumes that the Raspberry Pi is running the Raspberry Pi OS (Linux), and is fully up to date with the latest firmware and kernels.
+Display Parallel Interface (DPI) displays can be connected to Raspberry Pi devices via the 40-pin general-purpose input/output (GPIO) connector as an alternative to using the dedicated Display Serial Interface (DSI) or High-Definition Multimedia Interface (HDMI) ports.
 ****
 
 An up-to-24-bit parallel RGB interface is available on all Raspberry Pi boards with the 40 way header and the Compute Modules. This interface allows parallel RGB displays to be attached to the Raspberry Pi GPIO either in RGB24 (8 bits for red, green and blue) or RGB666 (6 bits per colour) or RGB565 (5 bits red, 6 green, and 5 blue).

documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc

@@ -121,6 +121,11 @@ This is the typical amount of power (in Ampere) drawn by different Raspberry Pi
 
 NOTE: For these measurements we used a standard Raspberry Pi OS image (current as of 26 Feb 2016, or June 2019 for the Raspberry Pi 4), at room temperature, with the Raspberry Pi connected to a HDMI monitor, USB keyboard, and USB mouse. The Raspberry Pi 3 Model B was connected to a wireless LAN access point, the Raspberry Pi 4 was connected to Ethernet. All these power measurements are approximate and do not take into account power consumption from additional USB devices; power consumption can easily exceed these measurements if multiple additional USB devices or a HAT are connected to the Raspberry Pi.
 
+[.whitepaper, title="Extra PMIC features on Raspberry Pi 4 and Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004340-WP/Extra-PMIC-features-on-Raspberry-Pi-4-and-Compute-Module-4.pdf]
+****
+A number of different PMIC devices have been used on both Raspberry Pi 4 and CM4. All the PMICs have provided extra functionality over and above that of voltage supply. This document describes how to access these features in software.
+****
+
 === Power Supply Warnings
 
 On all models of Raspberry Pi since the Raspberry Pi B+ (2014) except the Zero range, there is low-voltage detection circuitry that will detect if the supply voltage drops below 4.63V (+/- 5%). This will result in an entry added to the kernel log.
@@ -129,6 +134,13 @@ If you are seeing warnings, you should improve the power supply and/or cable, as
 
 Voltages can drop for a variety of reasons, for example if the power supply itself is inadequate, the power supply cable is made of too thin wires, or you have plugged in high demand USB devices.
 
+[.whitepaper, title="Making a more resilient file system", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003610-WP/Making-a-more-resilient-file-system.pdf]
+****
+Raspberry Pi devices are frequently used as data storage and monitoring devices, often in places where sudden power downs may occur. As with any computing device, power dropouts can cause storage corruption.
+
+This whitepaper provides some options on how to prevent data corruption under these and other circumstances by selecting appropriate file systems and setups to ensure data integrity.
+****
+
 === Back-powering
 
 The USB specification requires that USB devices must not supply current to upstream devices. If a USB device does supply current to an upstream device then this is called back-powering. Often this happens when a badly-made powered USB hub is connected, and will result in the powered USB hub supplying power to the host Raspberry Pi. This is not recommended since the power being supplied to the Raspberry Pi via the hub will bypass the protection circuitry built into the Raspberry Pi, leaving it vulnerable to damage in the event of a power surge.

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

@@ -20,4 +20,4 @@ The Powered by Raspberry Pi progamme provides a process for companies wanting to
 
 === Approved Design Partners
 
-Our list of https://www.raspberrypi.com/for-industry/design-partners/[approved design partners] provide a  set of consultancies that we work closely with and support so they can provide paid for design services across hardware, software, and mechanical.
+Our list of https://www.raspberrypi.com/for-industry/design-partners/[approved design partners] provide a  set of consultancies that we work closely with and support so they can provide paid for design services across hardware, software, and mechanical.

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

@@ -4,12 +4,12 @@ The Raspberry Pi is often used as part of another product. This documentation de
 
 === One-Time Programmable Settings
 
-[.whitepaper, title="Using the One-Time Programmable Memory on Raspberry Pi Single- Board Computers", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003611-WP/Using-the-One-time-programmable-memory-on-Raspberry-Pi-single-board-computers.pdf]
+[.whitepaper, title="Using the One-Time Programmable Memory on Raspberry Pi Single-Board Computers", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003611-WP/Using-the-One-time-programmable-memory-on-Raspberry-Pi-single-board-computers.pdf]
 ****
 All Raspberry Pi single-board computers (SBCs) have an inbuilt area of one-time programmable (OTP) memory, which is actually part of the main system on a chip (SoC). As its name implies, OTP memory can be written to (i.e. a binary 0 can be changed to a 1) only once. Once a bit has been changed to 1, it can never be returned to 0. One way of looking at the OTP is to consider each bit as a fuse. Programming involves deliberately blowing the fuse — an irreversible process as you cannot get inside the chip to replace it!
 
 
-This white paper assumes that the Raspberry Pi is running the Raspberry Pi operating system (OS), and is fully up to date with the latest firmware and kernels.
+This whitepaper assumes that the Raspberry Pi is running the Raspberry Pi operating system (OS), and is fully up to date with the latest firmware and kernels.
 ****
 
 There are a number of OTP values that can be used. To see a list of all the xref:raspberry-pi.adoc#otp-register-and-bit-definitions[OTP values], you can use:

documentation/asciidoc/microcontrollers/rp2040/rp2040_based_boards.adoc

@@ -2,7 +2,6 @@
 
 Designed by Raspberry Pi as both a development board, and as a reference design, the xref:raspberry-pi-pico.adoc[Raspberry Pi Pico] series is a family of RP2040-based boards. The Pico family currently consists of Raspberry Pi Pico (far left), Pico H (left), Pico W (right), and Pico WH (far right).
 
-
 image::images/pico_family.jpg[width="75%"]
 
 The design files for Raspberry Pi Pico and Pico W are available openly, with no limitations.