Merge pull request #675 from raspberrypi/develop

Pogo pin replacement, checking scripts, layout rework for command tables

Author: katshann-raspberry

.github/workflows/check_cr.yml

@@ -0,0 +1,17 @@
+name: Check line endings
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check-line-endings:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Check line endings
+        run: |
+          scripts/check_line_endings.py
+

.gitignore

@@ -8,3 +8,5 @@ venv
 .venv
 .env
 .vscode
+live_urls.csv
+dead_urls.csv

Makefile

@@ -123,3 +123,7 @@ serve_html: run_ninja
 # Delete all the files created by the 'html' target
 clean_html:
 	rm -rf $(HTML_DIR)
+
+# Check external links in all adoc files.
+link_check:
+	python3 $(SCRIPTS_DIR)/link_check.py

documentation/asciidoc/accessories/cm5-programming-jig/about.adoc

@@ -43,7 +43,7 @@ This class delegates model execution to a separate thread to prevent camera stut
 The `TfStage` class implements all the `PostProcessingStage` member functions post-processing stages must normally implement, _except for_ ``Name``.
 All `TfStage`-derived stages must implement the ``Name`` function, and should implement some or all of the following virtual member functions:
 
-`void readExtras()`:: The base class reads the named model and certain other parameters like the `refresh_rate`. Use this function to read extra parameters for the derived stage and check that the loaded model is correct (for example, has right input and output dimensions).
+`void readExtras()`:: The base class reads the named model and certain other parameters like the `refresh_rate`. Use this function to read extra parameters for the derived stage and check that the loaded model is correct (for example, has right input and output dimensions).
 `void checkConfiguration()`:: The base class fetches the low resolution stream that TFLite operates on and the full resolution stream in case the derived stage needs it. Use this function to check for the streams required by your stage. If your stage can't access one of the required streams, you might skip processing or throw an error.
 `void interpretOutputs()`:: Use this function to read and interpret the model output. _Runs in the same thread as the model when the model completes_.
 `void applyResults()`::  Use this function to apply results of the model (could be several frames old) to the current frame. Typically involves attaching metadata or drawing. _Runs in the main thread, before frames are delivered_.

documentation/asciidoc/computers/camera/rpicam_apps_post_processing_writing.adoc

@@ -242,7 +242,7 @@ Default: ``
 
 If set to a non-zero value (in seconds), this property enables a hardware watchdog timer that is handed over to the operating system (OS) at boot. If the OS does not regularly "kick" or reset the watchdog, the system will be reset after the specified timeout.
 
-This property sets the `systemd` `watchdog.open_timeout` parameter, which controls how long the OS has to initialize and start servicing the watchdog. The value is passed to the OS via the kernel command line. For ongoing operation, the OS must also regularly reset the watchdog, typically controlled by the `RuntimeWatchdogSec` parameter in `systemd`. For more information, see https://www.freedesktop.org/software/systemd/man/latest/systemd-system.conf.html#RuntimeWatchdogSec=[systemd watchdog documentation].
+This property sets the `systemd` `watchdog.open_timeout` parameter, which controls how long the OS has to initialize and start servicing the watchdog. The value is passed to the OS via the kernel command line. For ongoing operation, the OS must also regularly reset the watchdog, typically controlled by the `RuntimeWatchdogSec` parameter in `systemd`. For more information, see https://www.freedesktop.org/software/systemd/man/latest/systemd-system.conf.html#RuntimeWatchdogSec=[systemd watchdog documentation].
 
 [NOTE]
 ====

documentation/asciidoc/computers/config_txt/boot.adoc

@@ -60,83 +60,62 @@ This section describes how to apply the default configuration when you build a k
 * xref:linux_kernel.adoc#configure-the-kernel[enable and disable kernel features]
 * xref:linux_kernel.adoc#patch-the-kernel[apply patches from another source]
 
-To prepare the default configuration, run the appropriate commands from the table below for your Raspberry Pi model.
+To prepare the default configuration, run the appropriate commands from the sections below depending on your architecture and Raspberry Pi model.
 
-[cols="8,<.^20a,60a"]
-|===
-| Architecture | Raspberry Pi Model | Command
+===== 64-bit architecture
 
-.12+^.^| 64-bit
-| 3
-.9+.^|
+[tabs]
+======
+Raspberry Pi 3, 3+, CM3, CM3+, Zero 2 W, 4, 400, CM4, CM4S::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel8
 $ make bcm2711_defconfig
 ----
-| Compute Module 3
-| 3+
-| Compute Module 3+
-| Zero 2 W
-| 4
-| 400
-| Compute Module 4
-| Compute Module 4S
-
 
-.^| 5
-.3+.^|
+Raspberry Pi 5, 500, 500+, CM5::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel_2712
 $ make bcm2712_defconfig
 ----
-| 500/500+
-| Compute Module 5
+======
 
-.14+^.^| 32-bit
-| 1
-.4+.^|
+===== 32-bit architecture
+
+[tabs]
+======
+Raspberry Pi 1, CM1, Zero, Zero W::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel
 $ make bcmrpi_defconfig
 ----
-| Compute Module 1
-| Zero
-| Zero W
 
-
-| 2
-.6+.^|
+Raspberry Pi 2, 3, 3+, CM3, CM3+, Zero 2 W::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel7
 $ make bcm2709_defconfig
 ----
-| 3
-| Compute Module 3
-| 3+
-| Compute Module 3+
-| Zero 2 W
 
-
-| 4
-.4+.^|
+Raspberry Pi 4, 400, CM4, CM4S::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel7l
 $ make bcm2711_defconfig
 ----
-| 400
-| Compute Module 4
-| Compute Module 4S
-|===
+======
 
 [NOTE]
 ====
@@ -292,78 +271,62 @@ This section describes how to apply the default configuration when you build a k
 * xref:linux_kernel.adoc#configure-the-kernel[enable and disable kernel features]
 * xref:linux_kernel.adoc#patch-the-kernel[apply patches from another source]
 
-Enter the following commands to build the sources and Device Tree files:
+To build the sources and Device Tree files, run the appropriate commands from the sections below depending on your architecture and Raspberry Pi model.
 
-[cols="8,<.^20a,60a"]
-|===
-| Target Architecture | Target Raspberry Pi Model | Command
+===== 64-bit architecture
 
-.12+^.^| 64-bit
-| 3
-.9+.^| [source,console]
+[tabs]
+======
+Raspberry Pi 3, 3+, CM3, CM3+, Zero 2 W, 4, 400, CM4, CM4S::
++
+[source,console]
 ----
 $ cd linux
 $ KERNEL=kernel8
 $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig
 ----
-| Compute Module 3
-| 3+
-| Compute Module 3+
-| Zero 2 W
-| 4
-| 400
-| Compute Module 4
-| Compute Module 4S
 
-.^| 5
-.3+.^|
+Raspberry Pi 5, 500, 500+, CM5::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel_2712
 $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2712_defconfig
 ----
-| 500/500+
-| Compute Module 5
+======
+
+===== 32-bit architecture
 
-.14+^.^| 32-bit
-| 1
-.4+.^| [source,console]
+[tabs]
+======
+Raspberry Pi 1, CM1, Zero, Zero W::
++
+[source,console]
 ----
 $ cd linux
 $ KERNEL=kernel
 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcmrpi_defconfig
 ----
-| Compute Module 1
-| Zero
-| Zero W
 
-| 2
-.6+.^|
+Raspberry Pi 2, 3, 3+, CM3, CM3+, Zero 2 W::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel7
 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2709_defconfig
 ----
-| 3
-| Compute Module 3
-| 3+
-| Compute Module 3+
-| Zero 2 W
 
-| 4
-.4+.^|
+Raspberry Pi 4, 400, CM4, CM4S::
++
 [source,console]
 ----
 $ cd linux
 $ KERNEL=kernel7l
 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2711_defconfig
 ----
-| 400
-| Compute Module 4
-| Compute Module 4S
-|===
+======
 
 [[cross-compiled-customisation]]
 ==== Customise the kernel version using `LOCALVERSION`

documentation/asciidoc/computers/linux_kernel/building.adoc

@@ -40,4 +40,4 @@ Vulnerability Spectre v2:             Mitigation; CSV2, BHB
 
 WARNING: The list above was correct as of April 2025 but may have been superseded. You should use `lscpu` on your Raspberry Pi to get up to date information. This is especially important when using a third-party operating system, as these may not include all the latest mitigations in their Linux kernel builds. The Arm processors used by Raspberry Pi Ltd do not use microcode, so all mitigations are at the kernel level.
 
-The vulnerability information reported by `lscpu` is based on the currently executing kernel's detection scheme. It may not accurately reflect the true vulnerability status of the hardware, especially if the OS lacks recent kernel updates. Further vulnerability information on the CPU vendor advisories can be obtained from https://support.arm.com/documentation/#cf-navigationhierarchiesproducts=Arm%20Security%20Center,CPU%20Product%20Security[Arm support] referencing the Vendor ID and Model name reported by `lscpu`.
+The vulnerability information reported by `lscpu` is based on the currently executing kernel's detection scheme. It may not accurately reflect the true vulnerability status of the hardware, especially if the OS lacks recent kernel updates. Further vulnerability information on the CPU vendor advisories can be obtained from https://support.arm.com/documentation/#cf-navigationhierarchiesproducts=Arm%20Security%20Center,CPU%20Product%20Security[Arm support] referencing the Vendor ID and Model name reported by `lscpu`.

documentation/asciidoc/computers/processors/bcm2712.adoc

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+
+SEARCH_PATHS = set(["documentation/asciidoc"])
+SEARCH_EXTENSIONS = set([".adoc"])
+
+def contains_cr(filepath):
+    with open(filepath, "rb") as fh:
+        return b"\r" in fh.read()
+
+if __name__ == "__main__":
+    bad_files = set()
+    for path in SEARCH_PATHS:
+        for root, dirs, files in os.walk(path):
+            for name in files:
+                if os.path.splitext(name)[1] in SEARCH_EXTENSIONS:
+                    filepath = os.path.join(root, name)
+                    if contains_cr(filepath):
+                        bad_files.add(filepath)
+
+    if bad_files:
+        print("The following files contain a CR character (please convert them to UNIX line-endings):")
+        print("\n".join(sorted(bad_files)))
+        sys.exit(1)