Merge pull request #4203 from raspberrypi/develop

Deploy to production

Author: mudge

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

@@ -20,7 +20,7 @@ To learn more about Compute Module 4 (CM4) and its corresponding IO Board, see t
 
 * https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf[CM4 datasheet]
 
-[.whitepaper, title="Configure 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]
+[.whitepaper, title="Configure the Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003470-WP-Configuring-the-Compute-Module-4.pdf]
 ****
 The Compute Module 4 is available in a number of different hardware configurations. Some use cases disable certain features that aren't required.
 
@@ -57,7 +57,7 @@ Raspberry Pi Compute Module 1 (CM1) and Compute Module 3 (CM3) are supported pro
 * https://datasheets.raspberrypi.com/cm/cm1-schematics.pdf[Schematics for CM1]
 * https://datasheets.raspberrypi.com/cm/cm3-schematics.pdf[Schematics for CM3]
 
-[.whitepaper, title="Transition from Compute Module 1 or Compute Module 3 to Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003469-WP/Transitioning-from-CM3-to-CM4.pdf]
+[.whitepaper, title="Transition from Compute Module 1 or Compute Module 3 to Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003469-WP-Transitioning-from-CM3-to-CM4.pdf]
 ****
 This white paper helps developers migrate from Compute Module 1 or Compute Module 3 to Compute Module 4.
 ****

documentation/asciidoc/computers/config_txt/boot.adoc

@@ -54,6 +54,12 @@ The following Raspberry Pi models support this flag:
 
 Flagship models since Raspberry Pi 5, Compute Modules since CM5, and Keyboard models since Pi 500 _only_ support the 64-bit kernel. Models that only support a 64-bit kernel ignore this flag.
 
+=== `armstub`
+
+`armstub` is the filename on the boot partition from which to load the Arm stub. The default Arm stub is stored in firmware and is selected automatically based on the Raspberry Pi model and various settings.
+
+The stub is a small piece of Arm code that is run before the kernel. Its job is to set up low-level hardware like the interrupt controller before passing control to the kernel.
+
 === `ramfsfile`
 
 `ramfsfile` is the optional filename on the boot partition of a `ramfs` to load.
@@ -173,6 +179,11 @@ By default, the PCIe x4 controller used by `RP1` is reset before starting the op
 
 Default: `1`
 
+[[sha256]]
+==== `sha256`
+
+If set to non-zero, enables the logging of SHA256 hashes for loaded files (the kernel, initramfs, Device Tree .dtb file, and overlays), as generated by the `sha256sum` utility. The logging output goes to the UART if enabled, and is also accessible via `sudo vclog --msg`. This option may be useful when debugging boot problems, but at the cost of potentially adding _many_ seconds to the boot time. Defaults to 0 on all platforms.
+
 [[uart_2ndstage]]
 ==== `uart_2ndstage`
 
@@ -287,9 +298,9 @@ Default: `1`
 
 === Secure Boot configuration properties
 
-[.whitepaper, title="How to use Raspberry Pi Secure Boot", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003466-WP/Boot-Security-Howto.pdf]
+[.whitepaper, title="How to use Raspberry Pi Secure Boot", subtitle="", link=https://pip.raspberrypi.com/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 our approach to implementing secure boot implementation, please see the https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004651-WP/Raspberry-Pi-4-Boot-Security.pdf[Raspberry Pi 4 Boot Security] whitepaper. The secure boot system is intended for use with `buildroot`-based OS images; using it with Raspberry Pi OS is not recommended or supported.
+This whitepaper describes how to implement secure boot on devices based on Raspberry Pi 4. For an overview of our approach to implementing secure boot implementation, please see the https://pip.raspberrypi.com/documents/RP-004651-WP-Raspberry-Pi-4-Boot-Security.pdf[Raspberry Pi 4 Boot Security] whitepaper. The secure boot system is intended for use with `buildroot`-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.

documentation/asciidoc/computers/config_txt/gpio.adoc

@@ -40,3 +40,30 @@ GPIO changes made through this mechanism do not have any direct effect on the ke
 
 Note also that there is a delay of a few seconds between power being applied and the changes taking effect - longer if booting over the network or from a USB mass storage device.
 
+=== `enable_jtag_gpio`
+
+Setting `enable_jtag_gpio=1` selects Alt4 mode for GPIO pins 22-27, and sets up some internal SoC connections, enabling the JTAG interface for the Arm CPU. It works on all models of Raspberry Pi.
+
+|===
+| Pin # | Function
+
+| GPIO22
+| `ARM_TRST`
+
+| GPIO23
+| `ARM_RTCK`
+
+| GPIO24
+| `ARM_TDO`
+
+| GPIO25
+| `ARM_TCK`
+
+| GPIO26
+| `ARM_TDI`
+
+| GPIO27
+| `ARM_TMS`
+|===
+
+

documentation/asciidoc/computers/config_txt/overclocking.adoc

@@ -352,7 +352,7 @@ The GPU core, CPU, SDRAM and GPU each have their own PLLs and can have unrelated
 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]
+[.whitepaper, title="Cooling a Raspberry Pi device", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003608-WP-Cooling-a-Raspberry-Pi-device.pdf]
 ****
 This white paper goes through the reasons why your Raspberry Pi may get hot and why you might want to cool it back down, offering options on the cooling process.
 ****

documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc

@@ -14,6 +14,8 @@ Changes to `config.txt` only take effect after a reboot. You can view the curren
 
 NOTE: Not all config settings can be retrieved using `vcgencmd`.
 
+Some legacy `config.txt` options are no longer officially supported. These are listed in xref:../computers/legacy_config_txt.adoc[Legacy config.txt options] and aren't included in this article.
+
 === File format
 
 The `config.txt` file is read by the early-stage boot firmware, so it uses a very simple file format: **a single `property=value` statement on each line, where `value` is either an integer or a string**. Comments may be added, or existing config values may be commented out and disabled, by starting a line with the `#` character.

documentation/asciidoc/computers/legacy_config_txt.adoc

@@ -2,8 +2,6 @@ include::legacy_config_txt/legacy.adoc[]
 
 include::legacy_config_txt/boot.adoc[]
 
-include::legacy_config_txt/gpio.adoc[]
-
 include::legacy_config_txt/overclocking.adoc[]
 
 include::legacy_config_txt/conditional.adoc[]

documentation/asciidoc/computers/legacy_config_txt/boot.adoc

@@ -29,12 +29,6 @@ WARNING: This setting is deprecated. Use `arm_64bit` instead to enable 64-bit ke
 
 Sets board-specific control bits.
 
-=== `armstub`
-
-`armstub` is the filename on the boot partition from which to load the ARM stub. The default ARM stub is stored in firmware and is selected automatically based on the Raspberry Pi model and various settings.
-
-The stub is a small piece of ARM code that is run before the kernel. Its job is to set up low-level hardware like the interrupt controller before passing control to the kernel.
-
 === `arm_peri_high`
 
 Set `arm_peri_high` to `1` to enable high peripheral mode on Raspberry Pi 4. It is set automatically if a suitable DTB is loaded.
@@ -75,17 +69,6 @@ The `boot_delay_ms` command means wait for a given number of milliseconds in `st
 
 On the Raspberry Pi 4B, if this value is set to `0` then the interrupts will be routed to the Arm cores using the legacy interrupt controller, rather than via the GIC-400. The default value is `1`.
 
-[[sha256]]
-=== `sha256`
-
-If set to non-zero, enables the logging of SHA256 hashes for loaded files (the kernel, initramfs, Device Tree .dtb file, and overlays), as generated by the `sha256sum` utility. The logging output goes to the UART if enabled, and is also accessible via `sudo vclog --msg`. This option may be useful when debugging boot problems, but at the cost of potentially adding _many_ seconds to the boot time. Defaults to 0 on all platforms.
-
-=== `uart_2ndstage`
-
-Setting `uart_2ndstage=1` causes the second-stage loader (`bootcode.bin` on devices prior to the Raspberry Pi 4, or the boot code in the  EEPROM for Raspberry Pi 4 devices) and the main firmware (`start*.elf`) to output diagnostic information to UART0.
-
-Be aware that output is likely to interfere with Bluetooth operation unless it is disabled (`dtoverlay=disable-bt`) or switched to the other UART (`dtoverlay=miniuart-bt`), and if the UART is accessed simultaneously to output from Linux, then data loss can occur leading to corrupted output. This feature should only be required when trying to diagnose an early boot loading problem.
-
 [[upstream_kernel]]
 === `upstream_kernel`
 

documentation/asciidoc/computers/legacy_config_txt/gpio.adoc

@@ -16,7 +16,7 @@ You can also launch VLC from the command line. For the examples below, we used a
 
 [source,console]
 ----
-$ wget --trust-server-names http://rptl.io/big-buck-bunny
+$ wget --trust-server-names http://rpltd.co/big-buck-bunny
 ----
 
 To play the clip in VLC from the command line, run the following command:
@@ -62,7 +62,7 @@ For the examples below, we used a short audio clip. To download this clip from R
 
 [source,console]
 ----
-$ wget --trust-server-names http://rptl.io/startup-music
+$ wget --trust-server-names http://rpltd.co/startup-music
 ----
 
 To play the clip in VLC from the command line, run the following command:

documentation/asciidoc/computers/os/playing-audio-and-video.adoc

@@ -4,6 +4,17 @@ Raspberry Pi OS is a free, Debian-based operating system optimised for the Raspb
 
 Because Raspberry Pi OS is derived from Debian, it follows a staggered version of the https://wiki.debian.org/DebianReleases[Debian release cycle]. Releases happen roughly every 2 years.
 
-The latest version of Raspberry Pi OS is based on https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/[Debian Bookworm]. The previous version was based on https://www.raspberrypi.com/news/raspberry-pi-os-debian-bullseye/[Debian Bullseye].
+The latest version of Raspberry Pi OS is based on https://www.raspberrypi.com/news/trixie-the-new-version-of-raspberry-pi-os/[Debian Trixie]. The previous version was based on https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/[Debian Bookworm].
 
-You can find images of Raspberry Pi OS at https://www.raspberrypi.com/software/operating-systems/[raspberrypi.com/software/operating-systems/]
+== Get Raspberry Pi OS
+
+Raspberry Pi OS is available through the xref:../computers/getting-started.adoc#raspberry-pi-imager[Raspberry Pi Imager].
+You can also find images of Raspberry Pi OS at https://www.raspberrypi.com/software/operating-systems/[raspberrypi.com/software/operating-systems/].
+
+We provide 64- and 32-bit versions of the OS in the following editions:
+
+* **Raspberry Pi OS with desktop.** This is the default version of Raspberry Pi OS shown in Raspberry Pi Imager. It includes applications such as the Chromium web browser, Firefox web browser, VLC media player, and the Thonny Python environment.
+* **Raspberry Pi OS with desktop and recommended software.** This is listed as "Raspberry Pi OS Full" in Raspberry Pi Imager. It also includes the LibreOffice suite, KiCad, a programming environment for Scratch, and many other applications.
+* **Raspberry Pi OS Lite.** This version doesn't include a graphical desktop experience. Use it for headless servers and similar use cases. We recommend this version for your Raspberry Pi 1, 2, and Zero computers.
+
+If you're already running a previous version of Raspberry Pi OS and want to instead use the latest major version, we recommend that you don't perform an in-place upgrade. Instead, start again with a new image. For more information, see <<upgrade-your-operating-system-to-a-new-major-version>>.