Merge pull request #3241 from raspberrypi/develop

Push to production

documentation/asciidoc/computers/camera/libcamera_apps_building.adoc

@@ -49,8 +49,7 @@ First install all the necessary dependencies for `libcamera`.
 NOTE: Raspberry Pi OS Lite users will first need to install the following additional packages if they have not done so previously:
 
 ----
-sudo apt install -y python3-pip git
-sudo pip3 install jinja2
+sudo apt install -y python3-pip git python3-jinja2
 ----
 
 All users should then install the following:
@@ -59,10 +58,8 @@ All users should then install the following:
 sudo apt install -y libboost-dev
 sudo apt install -y libgnutls28-dev openssl libtiff5-dev pybind11-dev
 sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5
-sudo apt install -y meson
-sudo apt install -y cmake
-sudo pip3 install pyyaml ply
-sudo pip3 install --upgrade meson
+sudo apt install -y meson cmake
+sudo apt install -y python3-yaml python3-ply
 ----
 
 In the `meson` commands below we have enabled the _gstreamer_ plugin. If you _do not_ need this you can set `-Dgstreamer=disabled` instead and the next pair of dependencies will not be required. But if you do leave _gstreamer_ enabled, then you will need the following:
@@ -79,23 +76,13 @@ git clone https://github.com/raspberrypi/libcamera.git
 cd libcamera
 ----
 
-Next we recommend that Raspberry Pi OS Lite users run
+Next, please run
 
 ----
-meson build --buildtype=release -Dpipelines=raspberrypi -Dipas=raspberrypi -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=disabled -Ddocumentation=disabled -Dpycamera=enabled
+meson setup build --buildtype=release -Dpipelines=rpi/vc4,rpi/pisp -Dipas=rpi/vc4,rpi/pisp -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=disabled -Ddocumentation=disabled -Dpycamera=enabled
 ----
 
-Users of Raspberry Pi OS can instead use
-
-----
-meson build --buildtype=release -Dpipelines=raspberrypi -Dipas=raspberrypi -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=enabled -Ddocumentation=disabled -Dpycamera=enabled
-----
-
-NOTE: As of 6th May 2023, there has been a directory restructuring in the upstream libcamera git tree (https://git.libcamera.org/). If users are building libcamera from this tree, please replace `-Dpipelines=raspberrypi -Dipas=raspberrypi` with `-Dpipelines=rpi/vc4 -Dipas=rpi/vc4` in the above commands. This directory restructuring has not yet made it into the Raspberry Pi libcamera repo (https://github.com/raspberrypi/libcamera.git), so the above commands should be used without modifications if using that repo.
-
-The only difference is that the latter also builds the `qcam` test application, which has dependencies on Qt and a desktop environment (after completing the `libcamera` build users can run `build/src/qcam/qcam` to verify that `libcamera` is functioning correctly).
-
-To complete the `libcamera` build, please run
+To complete the `libcamera` build, use
 
 ----
 ninja -C build   # use -j 2 on Raspberry Pi 3 or earlier devices
@@ -133,7 +120,7 @@ First fetch the necessary dependencies for `libcamera-apps`.
 
 ----
 sudo apt install -y cmake libboost-program-options-dev libdrm-dev libexif-dev
-sudo pip3 install ninja meson
+sudo apt install -y meson ninja-build
 ----
 
 The `libcamera-apps` build process begins with the following:

documentation/asciidoc/computers/camera/libcamera_differences.adoc

@@ -25,7 +25,7 @@ Whilst the `libcamera-apps` attempt to emulate most features of the legacy _Rasp
 
 * There are some differences in the metering, exposure and AWB options. In particular the legacy apps conflate metering (by which we mean the "metering mode") and the exposure (by which we now mean the "exposure profile"). With regards to AWB, to turn it off you have to set a pair of colour gains (e.g. `--awbgains 1.0,1.0`).
 
-* `libcamera` has no mechanism to set the AWB into "grey world" mode, which is useful for "NOIR" camera modules. However, tuning files are supplied which switch the AWB into the correct mode, so for example, you could use `libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json`.
+* `libcamera` has no mechanism to set the AWB into "grey world" mode, which is useful for "NOIR" camera modules. However, tuning files are supplied which switch the AWB into the correct mode, so for example, you could use `libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json` (for Pi 4 and earlier devices) or `libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json` (Pi 5 and later devices).
 
 * There is support for setting the exposure time (`--shutter`) and analogue gain (`--analoggain` or just `--gain`). There is no explicit control of the digital gain; you get this if the gain requested is larger than the analogue gain can deliver by itself.
 

documentation/asciidoc/computers/camera/libcamera_hello.adoc

@@ -29,18 +29,25 @@ Raspberry Pi's `libcamera` implementation includes a _tuning file_ for each diff
 
 For this reason it is sometimes necessary to override the default tuning file for a particular sensor.
 
-For example, the NOIR (no IR-filter) versions of sensors require different AWB settings to the standard versions, so the IMX219 NOIR should be run using
+For example, the NOIR (no IR-filter) versions of sensors require different AWB settings to the standard versions, so the IMX219 NOIR being used with a Pi 4 or earlier device should be run using
 
 [,bash]
 ----
-libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json
+libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json
 ----
 
-If you are using a Soho Enterprises SE327M12 module you should use
+Pi 5 (or later devices) use a different tuning file in a different folder, so here you would use
 
 [,bash]
 ----
-libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/se327m12.json
+libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json
+----
+
+If you are using a Soho Enterprises SE327M12 module with a Pi 4 you would use
+
+[,bash]
+----
+libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/se327m12.json
 ----
 
 Notice how this also means that users can copy an existing tuning file and alter it according to their own preferences, so long as the `--tuning-file` parameter is pointed to the new version.

documentation/asciidoc/computers/camera/libcamera_options_common.adoc

@@ -260,16 +260,18 @@ The `--roi` parameter implements what is commonly referred to as "digital zoom".
 Example `libcamera-hello --roi 0.25,0.25,0.5,0.5` will select exactly a quarter of the total number of pixels cropped from the centre of the image.
 
 ----
-	--hdr				Run the camera in HDR mode (supported cameras only)
+	--hdr				Run the camera in HDR mode <mode>
 ----
 
-The `--hdr` option causes the camera to be run in HDR (High Dynamic Range) mode. This option only works for certain supported cameras, including the _Raspberry Pi Camera Module 3_.
+The `--hdr` option causes the camera to be run in the HDR (High Dynamic Range) mode given by `<mode>`. On Pi 4 and earlier devices, this option only works for certain supported cameras, including the _Raspberry Pi Camera Module 3_, and on Pi 5 devices it can be used with all cameras. `<mode>` may take the following values:
 
-Example: `libcamera-still --hdr -o hdr.jpg` for capturing a still image, or `libcamera-vid --hdr -o hdr.h264` to capture a video.
+* `off` - HDR is disabled. This is the default value if the `--hdr` option is omitted entirely.
+* `auto` - If the sensor supports HDR, then the on-sensor HDR mode is enabled. Otherwise, on Pi 5 devices, the Pi 5's on-chip HDR mode will be enabled. On a Pi 4 or earlier device, HDR will be disabled if the sensor does not support it. This mode will be applied if the `--hdr` option is supplied without a `<mode>` value.
+* `single-exp` - On a Pi 5, the on-chip HDR mode will be enabled, even if the sensor itself supports HDR. On earlier devices, HDR (even on-sensor HDR) will be disabled.
 
-Use of the HDR option may generally cause different camera modes to be available, and this can be checked by comparing the output of `libcamera-hello --list-cameras` with `libcamera-hello --hdr --list-cameras`.
+Example: `libcamera-still --hdr -o hdr.jpg` for capturing a still image, or `libcamera-vid --hdr -o hdr.h264` to capture a video.
 
-Users may also supply `--hdr 0` or `--hdr 1`, where the former disables the HDR modes (and is equivalent to omitting the option entirely), and the latter is the same as using `--hdr` on its own.
+When sensors support on-sensor HDR, use of the that option may generally cause different camera modes to be available, and this can be checked by comparing the output of `libcamera-hello --list-cameras` with `libcamera-hello --hdr sensor --list-cameras`.
 
 NOTE: For the _Raspberry Pi Camera Module 3_, the non-HDR modes include the usual full resolution (12MP) mode as well as its half resolution 2x2 binned (3MP) equivalent. In the case of HDR, only a single half resolution (3MP) mode is available, and it is not possible to switch between HDR and non-HDR modes without restarting the camera application.
 

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

@@ -93,7 +93,7 @@ Make sure J4 (USB SLAVE BOOT ENABLE) / J2 (nRPI_BOOT) is set to the disabled pos
 The default bootloader configuration on CM4 is designed to support bringup and development on a https://www.raspberrypi.com/products/compute-module-4-io-board/[Compute Module 4 IO board] and the software version flashed at manufacture may be older than the latest release. For final products please consider:-
 
 * Selecting and verifying a specific bootloader release. The version in the `usbboot` repo is always a recent stable release.
-* Configuring the boot device (e.g. network boot). See `BOOT_ORDER` section in the xref:raspberry-pi.adoc#raspberry-pi-4-bootloader-configuration[bootloader configuration] guide.
+* Configuring the boot device (e.g. network boot). See `BOOT_ORDER` section in the xref:raspberry-pi.adoc#raspberry-pi-bootloader-configuration[bootloader configuration] guide.
 * Enabling hardware write protection on the bootloader EEPROM to ensure that the bootloader can't be modified on remote/inaccessible products.
 
 N.B. The Compute Module 4 ROM never runs `recovery.bin` from SD/EMMC and the `rpi-eeprom-update` service is not enabled by default. This is necessary because the EMMC is not removable and an invalid `recovery.bin` file would prevent the system from booting. This can be overridden and used with `self-update` mode where the bootloader can be updated from USB MSD or Network boot. However, `self-update` mode is not an atomic update and therefore not safe in the event of a power failure whilst the EEPROM was being updated.

documentation/asciidoc/computers/config_txt/boot.adoc

@@ -9,6 +9,8 @@ These options specify the firmware files transferred to the VideoCore GPU prior
 
 NOTE: Cut-down firmware (`start*cd.elf` and `fixup*cd.dat`) cannot be selected this way - the system will fail to boot.  The only way to enable the cut-down firmware is to specify `gpu_mem=16`. The cut-down firmware removes support for codecs and 3D as well as limiting the initial early-boot framebuffer to 1080p @  16bpp - although KMS can replace this with up-to 32bpp 4K framebuffer(s) at a later stage as with any firmware.
 
+NOTE: The Raspberry Pi 5 firmware is self-contained in the bootloader EEPROM.
+
 === `cmdline`
 
 `cmdline` is the alternative filename on the boot partition from which to read the kernel command line string; the default value is `cmdline.txt`.
@@ -17,6 +19,8 @@ NOTE: Cut-down firmware (`start*cd.elf` and `fixup*cd.dat`) cannot be selected t
 
 `kernel` is the alternative filename on the boot partition to use when loading the kernel. The default value on the Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1 is `kernel.img`. The default value on the Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+ is `kernel7.img`. The default value on the Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4 is `kernel8.img`, or `kernel7l.img` if `arm_64bit` is set to 0.
 
+The Raspberry Pi 5 firmware defaults to loading `kernel_2712.img` because this image contains optmizations specific to Raspberry Pi 5 (e.g. 16K page-size). If this file is not present then the common 64-bit kernel (`kernel8.img`) will be loaded instead.
+
 === `arm_64bit`
 
 If set to 1, the kernel will be started in 64-bit mode. Setting to 0 selects 32-bit mode.
@@ -29,6 +33,8 @@ NOTE: 64-bit kernels may be uncompressed image files or a gzip archive of an ima
 
 NOTE: The 64-bit kernel will only work on the Raspberry Pi 3, 3+, 4, 400, Zero 2 W and 2B rev 1.2, and Raspberry Pi Compute Modules 3, 3+ and 4.
 
+NOTE: Raspberry Pi 5 only supports 64-bit kernel so this parameter has been removed.
+
 === `ramfsfile`
 
 `ramfsfile` is the optional filename on the boot partition of a `ramfs` to load. 

documentation/asciidoc/computers/config_txt/conditional.adoc

@@ -131,6 +131,8 @@ Note that these settings apply only at boot, so the monitor must be connected at
 
 On the Raspberry Pi 4, if both HDMI ports are in use, then the EDID filter will be checked against both of them, and configuration from all matching conditional filters will be applied.
 
+NOTE: This setting is not available on Raspberry Pi 5.
+
 === The Serial Number Filter
 
 Sometimes settings should only be applied to a single specific Raspberry Pi, even if you swap the SD card to a different one. Examples include licence keys and overclocking settings (although the licence keys already support SD card swapping in a different way). You can also use this to select different display settings, even if the EDID identification above is not possible, provided that you don't swap monitors between your Raspberry Pis. For example, if your monitor doesn't supply a usable EDID name, or if you are using composite output (for which EDID cannot be read).