Merge pull request #3824 from raspberrypi/develop

Roll out latest changes to production

.github/workflows/build.yml

@@ -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.9.0
+        uses: carlosperate/arm-none-eabi-gcc-action@v1.9.1
       - name: Install Doxygen
         run: |
           wget https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz

.gitmodules

@@ -8,5 +8,6 @@
 	branch = master
 
 [submodule "doxygentoasciidoc"]
-	path = doxygentoasciidoc
+	path = lib/doxygentoasciidoc
 	url = https://github.com/raspberrypi/doxygentoasciidoc.git
+	branch = main

Gemfile

@@ -31,7 +31,7 @@ install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
 end
 
 # Performance-booster for watching directories on Windows
-gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?
+gem "wdm", "~> 0.2.0", :install_if => Gem.win_platform?
 
 gem "nokogiri", "~> 1.16"
 

Gemfile.lock

@@ -57,7 +57,7 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    nokogiri (1.16.6)
+    nokogiri (1.16.7)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
     pathutil (0.16.2)
@@ -87,7 +87,7 @@ GEM
     tzinfo-data (1.2024.1)
       tzinfo (>= 1.0.0)
     unicode-display_width (2.5.0)
-    wdm (0.1.1)
+    wdm (0.2.0)
     webrick (1.8.1)
 
 PLATFORMS
@@ -103,7 +103,7 @@ DEPENDENCIES
   thread_safe (~> 0.3.5)
   tzinfo (~> 2.0)
   tzinfo-data
-  wdm (~> 0.1.0)
+  wdm (~> 0.2.0)
 
 BUNDLED WITH
    2.3.22

Makefile

@@ -16,6 +16,7 @@ AUTO_NINJABUILD = $(BUILD_DIR)/autogenerated.ninja
 
 PICO_SDK_DIR = lib/pico-sdk
 PICO_EXAMPLES_DIR = lib/pico-examples
+DOXYGEN_TO_ASCIIDOC_DIR = lib/doxygentoasciidoc
 ALL_SUBMODULE_CMAKELISTS = $(PICO_SDK_DIR)/CMakeLists.txt $(PICO_EXAMPLES_DIR)/CMakeLists.txt
 DOXYGEN_PICO_SDK_BUILD_DIR = build-pico-sdk-docs
 DOXYGEN_XML_DIR = $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined/docs/doxygen/xml
@@ -26,7 +27,7 @@ JEKYLL_CMD = bundle exec jekyll
 
 .DEFAULT_GOAL := html
 
-.PHONY: clean run_ninja clean_ninja html serve_html clean_html build_doxygen_html clean_doxygen_html build_doxygen_adoc clean_doxygen_adoc fetch_submodules clean_submodules clean_everything
+.PHONY: clean run_ninja clean_ninja html serve_html clean_html build_doxygen_xml clean_doxygen_xml build_doxygen_adoc clean_doxygen_adoc fetch_submodules clean_submodules clean_everything
 
 $(BUILD_DIR):
 	@mkdir -p $@
@@ -51,20 +52,20 @@ $(PICO_EXAMPLES_DIR)/CMakeLists.txt: | $(PICO_SDK_DIR)/CMakeLists.txt $(PICO_EXA
 	git submodule update --init $(PICO_EXAMPLES_DIR)
 
 # Initialise doxygentoasciidoc submodule
-doxygentoasciidoc/__main__.py:
-	git submodule update --init doxygentoasciidoc
+$(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py:
+	git submodule update --init $(DOXYGEN_TO_ASCIIDOC_DIR)
 
-fetch_submodules: $(ALL_SUBMODULE_CMAKELISTS)
+fetch_submodules: $(ALL_SUBMODULE_CMAKELISTS) $(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py
 
 # Get rid of the submodules
 clean_submodules:
 	git submodule deinit --all
 
 # Create the pico-sdk Doxygen XML files
 $(DOXYGEN_XML_DIR) $(DOXYGEN_XML_DIR)/index.xml: | $(ALL_SUBMODULE_CMAKELISTS) $(DOXYGEN_PICO_SDK_BUILD_DIR)
-	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined -D PICO_EXAMPLES_PATH=../$(PICO_EXAMPLES_DIR) -D PICO_PLATFORM=combined-docs
-	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2040 -D PICO_EXAMPLES_PATH=../$(PICO_EXAMPLES_DIR) -D PICO_PLATFORM=rp2040
-	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2350 -D PICO_EXAMPLES_PATH=../$(PICO_EXAMPLES_DIR) -D PICO_PLATFORM=rp2350
+	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined -D PICO_EXAMPLES_PATH=../../$(PICO_EXAMPLES_DIR) -D PICO_NO_PICOTOOL=1 -D PICO_PLATFORM=combined-docs
+	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2040 -D PICO_EXAMPLES_PATH=../../$(PICO_EXAMPLES_DIR) -D PICO_NO_PICOTOOL=1 -D PICO_PLATFORM=rp2040
+	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2350 -D PICO_EXAMPLES_PATH=../../$(PICO_EXAMPLES_DIR) -D PICO_NO_PICOTOOL=1 -D PICO_PLATFORM=rp2350
 	$(MAKE) -C $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined docs
 	$(MAKE) -C $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2040 docs
 	$(MAKE) -C $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2350 docs
@@ -79,13 +80,14 @@ clean_doxygen_xml:
 	rm -rf $(DOXYGEN_PICO_SDK_BUILD_DIR)
 
 # create the sdk adoc and the json file
-$(ASCIIDOC_DOXYGEN_DIR)/picosdk_index.json $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc: $(ASCIIDOC_DOXYGEN_DIR) $(DOXYGEN_XML_DIR)/index.xml doxygentoasciidoc/__main__.py doxygentoasciidoc/cli.py doxygentoasciidoc/nodes.py doxygentoasciidoc/helpers.py | $(BUILD_DIR)
+$(ASCIIDOC_DOXYGEN_DIR)/picosdk_index.json $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc: $(ASCIIDOC_DOXYGEN_DIR) $(DOXYGEN_XML_DIR)/index.xml $(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py $(DOXYGEN_TO_ASCIIDOC_DIR)/cli.py $(DOXYGEN_TO_ASCIIDOC_DIR)/nodes.py $(DOXYGEN_TO_ASCIIDOC_DIR)/helpers.py | $(BUILD_DIR) $(DOXYGEN_TO_ASCIIDOC_DIR)/requirements.txt
 	$(MAKE) clean_ninja
-	python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/index.xml > $(ASCIIDOC_DOXYGEN_DIR)/all_groups.adoc
-	python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/indexpage.xml -c > $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc
-	python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/examples_page.xml -c > $(ASCIIDOC_DOXYGEN_DIR)/examples_page.adoc
+	pip3 install -r $(DOXYGEN_TO_ASCIIDOC_DIR)/requirements.txt
+	PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/index.xml -o $(ASCIIDOC_DOXYGEN_DIR)/all_groups.adoc
+	PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/indexpage.xml -c -o $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc
+	PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/examples_page.xml -c -o $(ASCIIDOC_DOXYGEN_DIR)/examples_page.adoc
 	python3 $(SCRIPTS_DIR)/postprocess_doxygen_adoc.py $(ASCIIDOC_DOXYGEN_DIR)
-	-cp $(DOXYGEN_XML_DIR)/*.png $(ASCIIDOC_DOXYGEN_DIR)
+	-cp $(DOXYGEN_XML_DIR)/*.png $(ASCIIDOC_DOXYGEN_DIR) 2>/dev/null || true
 
 build_doxygen_adoc: $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc
 
@@ -94,7 +96,7 @@ clean_doxygen_adoc:
 	if [ -d $(ASCIIDOC_DOXYGEN_DIR) ]; then $(MAKE) clean_ninja; fi
 	rm -rf $(ASCIIDOC_DOXYGEN_DIR)
 
-clean_everything: clean_submodules clean_doxygen_html clean
+clean_everything: clean_submodules clean_doxygen_xml clean
 
 # AUTO_NINJABUILD contains all the parts of the ninjabuild where the rules themselves depend on other files
 $(AUTO_NINJABUILD): $(SCRIPTS_DIR)/create_auto_ninjabuild.py $(DOCUMENTATION_INDEX) $(SITE_CONFIG) | $(BUILD_DIR)

README.md

@@ -10,7 +10,7 @@ Instructions on how to checkout the `documentation` repo, and then install the t
 
 ### Checking out the Repository
 
-Install `git` if you don't already have it, and check out the `documentation` repo as follows,
+Install `git` if you don't already have it, and check out the `documentation` repo as follows:
 ```
 $ git clone https://github.com/raspberrypi/documentation.git
 $ cd documentation
@@ -22,13 +22,13 @@ $ cd documentation
 
 This works on both regular Debian or Ubuntu Linux — and has been tested in a minimal Docker container — and also under Raspberry Pi OS if you are working from a Raspberry Pi.
 
-You can install the necessary dependencies on Linux as follows,
+You can install the necessary dependencies on Linux as follows:
 
 ```
 $ sudo apt install -y ruby ruby-dev python3 python3-pip make ninja-build
 ```
 
-then add these lines to the bottom of your `$HOME/.bashrc`,
+then add these lines to the bottom of your `$HOME/.bashrc`:
 ```
 export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"
 export PATH="$PATH:$GEM_HOME/bin"
@@ -157,14 +157,20 @@ $ make clean
 
 ### Building with Doxygen
 
-If you want to build the Pico C SDK Doxygen documentation alongside the main documentation site you can do so with,
+If you want to build the Pico C SDK Doxygen documentation alongside the main documentation site you will need to install some additional dependencies:
+
+```
+$ sudo apt install -y cmake gcc-arm-none-eabi doxygen graphviz
+```
+
+and then you can build the documentation with:
 
 ```
 $ make build_doxygen_adoc
 $ make
 ```
 
-and clean up afterwards by using,
+You clean up afterwards by using:
 
 ```
 $ make clean_everything

documentation/asciidoc/computers/camera/rpicam_still.adoc

@@ -118,7 +118,7 @@ First, create a directory where you can store your time lapse photos:
 $ mkdir timelapse
 ----
 
-Run the following command to create a time lapse over 30 seconds, recording a photo every two seconds, saving output into `image0001.jpg` through `image0014.jpg`:
+Run the following command to create a time lapse over 30 seconds, recording a photo every two seconds, saving output into `image0000.jpg` through `image0013.jpg`:
 
 [source,console]
 ----

documentation/asciidoc/computers/configuration/device-tree.adoc

@@ -824,7 +824,7 @@ The loading of overlays at runtime is a recent addition to the kernel, and at th
 [[part3.6]]
 ==== Supported overlays and parameters
 
-Please refer to the https://github.com/raspberrypi/firmware/blob/master/boot/firmware/overlays/README[README] file found alongside the overlay `.dtbo` files in `/boot/firmware/overlays`. It is kept up-to-date with additions and changes.
+For a list of supported overlays and parameters, see the https://github.com/raspberrypi/firmware/blob/master/boot/overlays/README[README] file found alongside the overlay `.dtbo` files in `/boot/firmware/overlays`. It is kept up-to-date with additions and changes.
 
 [[part4]]
 === Firmware parameters

documentation/asciidoc/computers/processors/bcm2712.adoc

@@ -1,8 +1,8 @@
 == 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.
+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. 4GB and 8GB Raspberry Pi 5 models use the BCM2712**C1** stepping.
 
-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.
+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 ×1 and ×4 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: 
 
@@ -23,4 +23,8 @@ Headline features include:
 ** 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.
+In aggregate, the new features present in BCM2712 deliver a performance uplift of 2-3× over Raspberry Pi 4 for common CPU or I/O-intensive use cases.
+
+=== BCM2712D0
+
+The **D0** stepping of BCM2712 removes unused functionality from BCM2712C1. There is no functional difference between the C1 and D0 steppings. Physically, the packages use the same amount of space.

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

@@ -174,8 +174,10 @@ a|
 ^.^a|
 .Raspberry Pi 5
 image::images/5.jpg[alt="Raspberry Pi 5"]
-| xref:processors.adoc#bcm2712[BCM2712]
+| xref:processors.adoc#bcm2712[BCM2712] (2GB version uses xref:processors.adoc#bcm2712[BCM2712D0])
 a|
+2GB
+
 4GB
 
 8GB | 40-pin GPIO header
@@ -333,10 +335,6 @@ Models with the *H* suffix have header pins pre-soldered to the GPIO header. Mod
 |===
 | Model | SoC | Memory | Storage | GPIO | Wireless Connectivity
 
-a|
-.Raspberry Pi Pico 2
-image::images/pico-2.png[alt="Raspberry Pi Pico 2"]
-| xref:../microcontrollers/silicon.adoc#rp2350[RP2350] | 520KB | 2MB | 40-pin GPIO header (unpopulated) ^| none
 a|
 .Raspberry Pi Pico
 image::images/pico.png[alt="Raspberry Pi Pico"]
@@ -359,6 +357,10 @@ image::images/pico-wh.png[alt="Raspberry Pi Pico WH"]
 a|
 * 2.4GHz single-band 802.11n Wi-Fi (10Mb/s)
 * Bluetooth 5.2, Bluetooth Low Energy (BLE)
+a|
+.Raspberry Pi Pico 2
+image::images/pico-2.png[alt="Raspberry Pi Pico 2"]
+| xref:../microcontrollers/silicon.adoc#rp2350[RP2350] | 520KB | 2MB | 40-pin GPIO header (unpopulated) ^| none
 
 |===
 

requirements.txt

@@ -1,3 +1,3 @@
-pyyaml == 6.0.1
+pyyaml == 6.0.2
 lxml
 beautifulsoup4

scripts/create_build_adoc_doxygen.py

@@ -16,9 +16,8 @@ def check_no_markdown(filename):
         asciidoc = re.sub(r'----\n.*?\n----', '', asciidoc, flags=re.DOTALL)
         # strip out pass-through blocks
         asciidoc = re.sub(r'\+\+\+\+\n.*?\n\+\+\+\+', '', asciidoc, flags=re.DOTALL)
-        # This is messing up the c code blocks
-        # if re.search(r'(?:^|\n)#+', asciidoc):
-        #     raise Exception("{} contains a Markdown-style header (i.e. '#' rather than '=')".format(filename))
+        if re.search(r'(?:^|\n)#+', asciidoc):
+            raise Exception("{} contains a Markdown-style header (i.e. '#' rather than '=')".format(filename))
         if re.search(r'(\[.+?\]\(.+?\))', asciidoc):
             raise Exception("{} contains a Markdown-style link (i.e. '[title](url)' rather than 'url[title]')".format(filename))
 

scripts/create_output_supplemental_data.py

@@ -6,24 +6,24 @@
 import re
 
 def get_release_version(doxyfile_path):
-	version = "unknown"
-	with open(doxyfile_path) as f:
-		doxy_content = f.read()
-	version_search = re.search(r"(\nPROJECT_NUMBER\s*=\s*)([\d.]+)", doxy_content)
-	if version_search is not None:
-		version = version_search.group(2)
-	return version
+    version = "unknown"
+    with open(doxyfile_path) as f:
+        doxy_content = f.read()
+    version_search = re.search(r"(\nPROJECT_NUMBER\s*=\s*)([\d.]+)", doxy_content)
+    if version_search is not None:
+        version = version_search.group(2)
+    return version
 
 def write_new_data_file(output_json_file, data_obj):
-	f = open(output_json_file, 'w')
-	f.write(json.dumps(data_obj))
-	f.close()
+    f = open(output_json_file, 'w')
+    f.write(json.dumps(data_obj))
+    f.close()
 
 if __name__ == "__main__":
-	# read the doxygen config file
-	doxyfile_path = sys.argv[1]
-	# output the new data file
-	output_json_file = sys.argv[2]
-	version = get_release_version(doxyfile_path)
-	data_obj = {"pico_sdk_release": version}
-	write_new_data_file(output_json_file, data_obj)
+    # read the doxygen config file
+    doxyfile_path = sys.argv[1]
+    # output the new data file
+    output_json_file = sys.argv[2]
+    version = get_release_version(doxyfile_path)
+    data_obj = {"pico_sdk_release": version}
+    write_new_data_file(output_json_file, data_obj)