diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index dd343d7972..a81b5f78cb 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -32,7 +32,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.10.0 + uses: carlosperate/arm-none-eabi-gcc-action@v1.10.1 - name: Install Doxygen run: | wget https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz diff --git a/documentation/asciidoc/accessories/camera/external_trigger.adoc b/documentation/asciidoc/accessories/camera/external_trigger.adoc index b30140ca4b..642412d54d 100644 --- a/documentation/asciidoc/accessories/camera/external_trigger.adoc +++ b/documentation/asciidoc/accessories/camera/external_trigger.adoc @@ -21,17 +21,6 @@ We can use a Raspberry Pi Pico to provide the trigger. Connect any Pico GPIO pin image::images/pico_wiring.jpg[alt="Image showing Raspberry Pi Pico wiring",width="50%"] -==== Boot up the Raspberry Pi with the camera connected. - -Enable external triggering through superuser mode: - -[source,console] ----- -$ sudo su -$ echo 1 > /sys/module/imx296/parameters/trigger_mode -$ exit ----- - ==== Raspberry Pi Pico MicroPython Code [source,python] @@ -55,15 +44,37 @@ The low pulse width is equal to the shutter time, and the frequency of the PWM e NOTE: In this example, Pin 28 connects to the XTR touchpoint on the GS camera board. -=== Operation +=== Camera driver configuration + +This step is only necessary if you have more than one camera with XTR wired in parallel. + +Edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. + +Append this line: +[source] +---- +dtoverlay=imx296,always-on +---- +When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If both cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them ending with `,cam0`. + +If the external trigger will not be started right away, you also need to increase the libcamera timeout xref:camera.adoc#libcamera-configuration[as above]. + +=== Starting the camera + +Enable external triggering: + +[source,console] +---- +$ echo 1 | sudo tee /sys/module/imx296/parameters/trigger_mode +---- -Run the code on the Pico, and set the camera running: +Run the code on the Pico, then set the camera running: [source,console] ---- $ rpicam-hello -t 0 --qt-preview --shutter 3000 ---- -Every time that the Pico pulses the pin, it should generate a frame. To control the framerate, vary the duration between pulses. +Every time the Pico pulses the pin, it should capture a frame. However, if `--gain` and `--awbgains` are not set, some frames will be dropped to allow AGC and AWB algorithms to settle. -NOTE: When running `rpicam-apps`, always specify a fixed shutter duration to ensure the AGC does not adjust the camera's shutter speed. The duration does not matter, since it is actually controlled by the external trigger pulse. +NOTE: When running `rpicam-apps`, always specify a fixed shutter duration, to ensure the AGC does not try to adjust the camera's shutter speed. The value is not important, since it is actually controlled by the external trigger pulse. diff --git a/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc b/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc index 58734110cf..9561864ffb 100644 --- a/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc +++ b/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc @@ -1,102 +1,108 @@ == Synchronous Captures -Both the HQ Camera and the Global Shutter Camera, have support for synchronous captures. -Making use of the XVS pin (Vertical Sync) allows one camera to pulse when a frame capture is initiated. -The other camera can then listen for this sync pulse, and capture a frame at the same time as the other camera. +The High Quality (HQ) Camera supports synchronous captures. +One camera (the "source") can be configured to generate a pulse on its XVS (Vertical Sync) pin when a frame capture is initiated. +Other ("sink") cameras can listen for this pulse, and capture a frame at the same time as the source camera. -=== Using the HQ Camera +This method is largely superseded by xref:../computers/camera_software.adoc#software-camera-synchronisation[software camera synchronisation] which can operate over long distances without additional wires and has sub-millisecond accuracy. But when cameras are physically close, wired synchronisation may be used. -For correct operation, both cameras require a 1.65V pull up voltage on the XVS line, which is created by a potential divider through the 3.3V and GND pins on the Raspberry Pi. +NOTE: Global Shutter (GS) Cameras can also be operated in a synchronous mode. However, the source camera will record one extra frame. Instead, for GS Cameras we recommend using an xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger source]. You cannot synchronise a GS Camera and an HQ Camera. -image::images/synchronous_camera_wiring.jpg[alt="Image showing potential divider setup",width="50%"] +=== Connecting the cameras -Create a potential divider from two 10kΩ resistors to 3.3V and ground (to make 1.65V with an effective source impedance of 5kΩ). This can be connected to either Raspberry Pi. +Solder a wire to the XVS test point of each camera, and connect them together. -Solder the GND and XVS test points of each HQ Camera board to each other. +Solder a wire to the GND test point of each camera, and connect them together. -Connect the XVS wires to the 1.65V potential divider pull-up. +*For GS Cameras only,* you will also need to connect the XHS (Horizontal Sync) test point of each camera together. On any GS Camera that you wish to act as a sink, bridge the two halves of the MAS pad with solder. -==== Boot up both Raspberry Pis +NOTE: An earlier version of this document recommended an external pull-up for XVS. This is no longer recommended. Instead, ensure you have the latest version of Raspberry Pi OS and set the `always-on` property for all connected cameras. -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. +=== Driver configuration -Run the following commands to configure the sink: +You will need to configure the camera drivers to keep their 1.8V power supplies on when not streaming, and optionally to select the source and sink roles. -[source,console] +==== For the HQ Camera + +Edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. + +Append this line for a source camera: +[source] ---- -$ sudo su -$ echo 2 > /sys/module/imx477/parameters/trigger_mode -$ exit +dtoverlay=imx477,always-on,sync-source ---- -Run the following commands to configure the source: - -[source,console] +Or for a sink: +[source] ---- -$ sudo su -$ echo 1 > /sys/module/imx477/parameters/trigger_mode -$ exit +dtoverlay=imx477,always-on,sync-sink ---- -Run the following command to start the sink: +When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If two cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them ending with `,cam0`. + +Alternatively, if you wish to swap the cameras' roles at runtime (and they are not both connected to the same Raspberry Pi), omit `,sync-source` or `,sync-sink` above. Instead you can set a module parameter before starting each camera: +For the Raspbery Pi with the source camera: [source,console] ---- -$ rpicam-vid --frames 300 --qt-preview -o sink.h264 +$ echo 1 | sudo tee /sys/module/imx477/parameters/trigger_mode ---- -Run the following command to start the source: - +For the Raspberry Pi with the sink camera: [source,console] ---- -$ rpicam-vid --frames 300 --qt-preview -o source.h264 +$ echo 2 | sudo tee /sys/module/imx477/parameters/trigger_mode ---- +You will need to do this every time the system is booted. -Frames should be synchronous. Use `--frames` to ensure the same number of frames are captured, and that the recordings are exactly the same length. -Running the sink first ensures that no frames are missed. - -NOTE: The potential divider is needed to pull up the XVS pin to high whilst the source is in an idle state. This ensures that no frames are created or lost upon startup. The source whilst initialising goes from LOW to HIGH which can trigger a false frame. - -=== Use the GS Camera +==== For the GS Camera -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]. +Edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. -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. - -The wiring setup is identical to the xref:camera.adoc#using-the-hq-camera[HQ Camera method], except that you will also need to connect the XHS pins together. - -Create a potential divider from two 10kΩ resistors to 3.3V and ground (to make 1.65V with an effective source impedance of 5kΩ). This can be connected to either Raspberry Pi. - -Solder 2 wires to the XVS test points on each board and connect both of these wires together to the 1.65V potential divider. +For either a source or a sink, append this line: +[source] +---- +dtoverlay=imx296,always-on +---- +When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If two cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them ending with `,cam0`. -Solder the GND of each Camera board to each other. Also solder 2 wires to the XHS test points on each board and connect these. No pullup is needed for XHS pin. +On the GS Camera, the sink role is enabled by the MAS pin and cannot be configured by software ("trigger_mode" and "sync-sink" relate to the xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger method], and should _not_ be set for this method). -On the boards that you wish to act as sinks, solder the two halves of the MAS pad together. This tells the sensor to act as a sink, and will wait for a signal to capture a frame. +=== Libcamera configuration -==== Boot up source and sink +If the cameras are not all started within 1 second, the `rpicam` applications can time out. To prevent this, you must edit a configuration file on any Raspberry Pi(s) with sink cameras. -Run the following command to start the sink: +On Raspberry Pi 5 or CM5: +[source,console] +---- +$ cp /usr/share/libcamera/pipeline/rpi/pisp/example.yaml timeout.yaml +---- +On other Raspberry Pi models: [source,console] ---- -$ rpicam-vid --frames 300 -o sync.h264 +$ cp /usr/share/libcamera/pipeline/rpi/vc4/rpi_apps.yaml timeout.yaml ---- -Due to the limitations of the IMX296 sensor, the sink cannot record exactly the same number of frames as the source. **The source records one extra frame before the sink starts recording**. Because of this, you need to specify that the sink records one less frame with the `--frames` option. +Now edit the copy. In both cases, delete the `#` (comment) from the `"camera_timeout_value_ms":` line, and change the number to `60000` (60 seconds). -Wait at least two seconds before you start the source. +=== Starting the cameras -After waiting two seconds, run the following command to start the source: +Run the following commands to start the sink: [source,console] ---- -$ rpicam-vid --frames 299 -o sync.h264 +$ export LIBCAMERA_RPI_CONFIG_FILE=timeout.yaml +$ rpicam-vid --frames 300 --qt-preview -o sink.h264 ---- -Because the sink and source record a different number of frames, use `ffmpeg` to resync the videos. By dropping the first frame from the source, we then get two recordings with the same starting point and frame length: +Wait a few seconds, then run the following command to start the source: [source,console] ---- -$ ffmpeg -i source.h264 -vf select="gte(n\, 1)" source.h264 +$ rpicam-vid --frames 300 --qt-preview -o source.h264 ---- +Frames should be synchronised. Use `--frames` to ensure the same number of frames are captured, and that the recordings are exactly the same length. +Running the sink first ensures that no frames are missed. + +NOTE: When using the GS camera in synchronous mode, the sink will not record exactly the same number of frames as the source. **The source records one extra frame before the sink starts recording**. Because of this, you need to specify that the sink records one less frame with the `--frames` option. diff --git a/documentation/asciidoc/computers/camera/rpicam_options_common.adoc b/documentation/asciidoc/computers/camera/rpicam_options_common.adoc index 1f9f64b397..90e535ff8e 100644 --- a/documentation/asciidoc/computers/camera/rpicam_options_common.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_options_common.adoc @@ -571,3 +571,24 @@ The number of buffers to allocate for still image capture or for video recording ==== `viewfinder-buffer-count` As the `buffer-count` option, but applies when running in preview mode (that is `rpicam-hello` or the preview, not capture, phase of `rpicam-still`). + +==== `metadata` + +Save captured image metadata to a file or `-` for stdout. The fields in the metadata output will depend on the camera model in use. + +See also `metadata-format`. + +==== `metadata-format` + +Format to save the metadata in. Accepts the following values: + +* `txt` for text format +* `json` for JSON format + +In text format, each line will have the form + + key=value + +In JSON format, the output is a JSON object. + +This option does nothing unless `--metadata` is also specified. diff --git a/documentation/asciidoc/computers/config_txt/boot.adoc b/documentation/asciidoc/computers/config_txt/boot.adoc index 1d778deb47..b87ef830d3 100644 --- a/documentation/asciidoc/computers/config_txt/boot.adoc +++ b/documentation/asciidoc/computers/config_txt/boot.adoc @@ -189,6 +189,26 @@ If `erase_eeprom` is set to `1` then `recovery.bin` will erase the entire SPI EE Default: `0` +[[set_reboot_arg1]] +==== `set_reboot_arg1` +Raspberry Pi 5 only. + +Sets the value of `boot_arg1` to be passed via a reset-safe register to the bootloader after a reboot. +See xref:config_txt.adoc#boot_arg1[`boot_arg1`] for more details. +Default: `` + +[[set_reboot_order]] +==== `set_reboot_order` + +Raspberry Pi 5 only. + +Sets the value of xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] to be passed via a reset-safe register to the bootloader after a reboot. As with `tryboot`, this is a one-time setting and is automatically cleared after use. + +This property could be used to debug different xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] settings. Alternatively, it could be used in a provisioning system which has control over power and the `nRPIBOOT` GPIO to override the boot mode without specifying xref:config_txt.adoc#conditional-filters[conditional filter] statements in the EEPROM config. + +Default: `` + + [[eeprom_write_protect]] ==== `eeprom_write_protect` @@ -255,14 +275,21 @@ Default: `0` [[revoke_devkey]] ==== `revoke_devkey` -If this property is set to `1` then `recovery.bin` will write a value to OTP that prevents the ROM from loading old versions of the second stage bootloader which do not support `secure-boot`. This prevents `secure-boot` from being turned off by reverting to an older release of the bootloader. +Raspberry Pi 4 only. + +If this property is set to `1` then `recovery.bin` will write a value to OTP that prevents the ROM from loading old versions of the second stage bootloader which do not support `secure-boot`. This prevents `secure-boot` from being turned off by reverting to an older release of the bootloader. Therefore, this property must be set if `secure-boot` is enabled on production devices. + +This property is automatically is set by `recovery.bin` `2025/05/16` and newer if `program_pubkey=1`. + Default: `0` [[program_rpiboot_gpio]] ==== `program_rpiboot_gpio` -Compute Modules have a dedicated `nRPIBOOT` jumper to select `RPIBOOT` mode. Flagship and Keyboard Raspberry Pi devices with EEPROM lack a dedicated `nRPIBOOT` jumper. To select `RPIBOOT` mode on Flagship and Keyboard devices, pull one of the following GPIO pins low: +Raspberry Pi 4B and Raspberry Pi 400 only. + +Compute Module 4 and 4S have a dedicated `nRPIBOOT` jumper to select `RPIBOOT` mode. Raspberry Pi 4B and Raspberry Pi 400 lack a dedicated `nRPIBOOT` jumper so one of the following GPIOs must be selected for use as `nRPIBOOT`. * `2` * `4` @@ -271,11 +298,11 @@ Compute Modules have a dedicated `nRPIBOOT` jumper to select `RPIBOOT` mode. Fla * `7` * `8` -This property does not depend on `secure-boot`. However, you should verify that this GPIO configuration does not conflict with any HATs which might pull the GPIO low during boot. +The GPIO may be used as a general-purpose I/O pin after the OS has started. However, you should verify that this GPIO configuration does not conflict with any HATs which might pull the GPIO low during boot. -For safety, this property can _only_ be programmed via `RPIBOOT`. As a result, you must first clear the bootloader EEPROM using `erase_eeprom`. This causes the ROM to failover to `RPIBOOT` mode, which then allows this option to be set. +Although `secure-boot` requires this property to be set on Raspberry Pi 4B and Raspberry Pi 400, it does not depend on `secure-boot`. For example, `RPIBOOT` can be useful for automated testing. -On BCM2712, you can alternatively force `RPIBOOT` mode by holding down the power button while simultaneously connecting a USB-C power supply. +For safety, this OTP value can _only_ be programmed via `RPIBOOT`. As a result, you must first clear the bootloader EEPROM using `erase_eeprom`. The blank EEPROM causes the ROM to failover to `RPIBOOT` mode, which then allows this option to be set. Default: `{nbsp}` diff --git a/documentation/asciidoc/computers/config_txt/conditional.adoc b/documentation/asciidoc/computers/config_txt/conditional.adoc index f33a3d3206..f905c870e7 100644 --- a/documentation/asciidoc/computers/config_txt/conditional.adoc +++ b/documentation/asciidoc/computers/config_txt/conditional.adoc @@ -96,9 +96,6 @@ Some models of Raspberry Pi, including Zero, Compute Module, and Keyboard models The `[none]` filter prevents any settings that follow from being applied to any hardware. Although there is nothing that you can't do without `[none]`, it can be a useful way to keep groups of unused settings in config.txt without having to comment out every line. -=== The `[partition=N]` filter -This `partition` filter can be be used to select alternate boot flows according to the requested partition number (`sudo reboot N`) or via direct usage of the `PM_RSTS` watchdog register. - [source,ini] ---- # Bootloader EEPROM config. @@ -123,25 +120,108 @@ cmdline=cmdline-recovery.txt The raw value of the `PM_RSTS` register at bootup is available via `/proc/device-tree/chosen/bootloader/rsts` and the final partition number used for booting is available via `/proc/device-tree/chosen/bootloader/partition`. These are big-endian binary values. -=== The `[boot_partition=N]` filter -The `boot_partition` filter can be used to select alternate OS files (e.g. `cmdline.txt`) to be loaded, depending on which partition `config.txt` was loaded from after processing `autoboot.txt`. This is intended for use with an `A/B` boot-system with `autoboot.txt` where it is desirable to be able to have identical files installed to the boot partition for both the `A` and `B` images. +=== The expression filter + +The expression filter provides support for comparing unsigned integer "boot variables" to constants using a simple set of operators. It is intended to support OTA update mechanisms, debug and test. + +* The "boot variables" are `boot_arg1`, `boot_count`, `boot_partition` and `partition`. +* Boot variables are always lower case. +* Integer constants may either be written as decimal or as hex. +* Expression conditional filters have no side-effects e.g. no assignment operators. +* As with other filter types the expression filter cannot be nested. +* Use the `[all]` filter to reset expressions and all other conditional filter types. + +Syntax: +[source,ini] +---- +# ARG is a boot-variable +# VALUE and MASK are unsigned integer constants +[ARG=VALUE] # selected if (ARG == VALUE) +[ARG&MASK] # selected if ((ARG & VALUE) != 0) +[ARG&MASK=VALUE] # selected if ((ARG & MASK) == VALUE) +[ARGVALUE] # selected if (ARG > VALUE) + +---- + +==== `boot_arg1` +Raspberry Pi 5 and newer devices only. + +The `boot_arg1` variable is a 32-bit user defined value which is stored in a reset-safe register allowing parameters to be passed accross a reboot. + +Setting `boot_arg1` to 42 via `config.txt`: +[source,ini] +---- +set_reboot_arg1=42 +---- +The `set_reboot_arg1` property sets the value for the next boot. It does not change the current value as seen by the config parser. + +Setting `boot_arg1` to 42 via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003808c 8 8 1 42 +---- + +Reading `boot_arg1` via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003008c 8 8 1 0 +# Example output - boot_arg1 is 42 +# 0x00000020 0x80000000 0x0003008c 0x00000008 0x80000008 0x00000001 0x0000002a 0x0000000 +---- +The value of the `boot_arg1` variable when the OS was started can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/arg1` + +==== `boot_count` +Raspberry Pi 5 and newer devices only. + +The `boot_count` variable is an 8-bit value stored in a reset-safe register that is incremented at boot (wrapping back to zero at 256). It is cleared if power is disconnected. -Example `config.txt` - select the matching root filesystem for the `A/B` boot file-system. +To read `boot_count` via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003008d 4 4 0 +# Example - boot count is 3 +# 0x0000001c 0x80000000 0x0003008d 0x00000004 0x80000004 0x00000003 0x00000000 +---- + +Setting/clearing `boot_count` via vcmailbox: +[source,console] +---- +# Clear boot_count by setting it to zero. +sudo vcmailbox 0x0003808d 4 4 0 +---- +The value of `boot_count` when the OS was started can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/count` + +==== `boot_partition` +The `boot_partition` variable can be used to select alternate OS files (e.g. `cmdline.txt`) to be loaded, depending on which partition `config.txt` was loaded from after processing xref:config_txt.adoc#autoboot-txt[autoboot.txt]. This is intended for use with an `A/B` boot-system with `autoboot.txt` where it is desirable to be able to have identical files installed to the boot partition for both the `A` and `B` images. + +The value of the `boot_partition` can be different to the requested `partition` variable if it was overriden by setting `boot_partition` in xref:config_txt.adoc#autoboot-txt[autoboot.txt] or if the specified partion was not bootable and xref:raspberry-pi.adoc#PARTITION_WALK[PARTITION_WALK] was enabled in the EEPROM config. + +Example `config.txt` - select the matching root filesystem for the `A/B` boot file-system: [source,ini] ---- +# Use different cmdline files to point to different root filesystems based on which partition the system booted from. [boot_partition=1] -cmdline=cmdline_rootfs_a.txt +cmdline=cmdline_rootfs_a.txt # Points to root filesystem A [boot_partition=2] -cmdline=cmdline_rootfs_b.txt +cmdline=cmdline_rootfs_b.txt # Points to root filesystem B ---- +The value of `boot_partition` i.e. the partition used to boot the OS can be read from xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/partition` + +==== `partition` +The `partition` variable can be used to select alternate boot flows according to the requested partition number (`sudo reboot N`) or via direct usage of the `PM_RSTS` watchdog register. + + === The `[tryboot]` filter This filter succeeds if the `tryboot` reboot flag was set. It is intended for use in xref:config_txt.adoc#autoboot-txt[autoboot.txt] to select a different `boot_partition` in `tryboot` mode for fail-safe OS updates. +The value of `tryboot` at the start of boot can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/tryboot` + === The `[EDID=*]` filter When switching between multiple monitors while using a single SD card in your Raspberry Pi, and where a blank config isn't sufficient to automatically select the desired resolution for each one, this allows specific settings to be chosen based on the monitors' EDID names. diff --git a/documentation/asciidoc/computers/configuration/device-tree.adoc b/documentation/asciidoc/computers/configuration/device-tree.adoc index 45aa30698f..561ec68a29 100644 --- a/documentation/asciidoc/computers/configuration/device-tree.adoc +++ b/documentation/asciidoc/computers/configuration/device-tree.adoc @@ -833,7 +833,16 @@ For a list of supported overlays and parameters, see the https://github.com/rasp [[part4]] === Firmware parameters -The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/usage-model.html#runtime-configuration[/chosen] node to pass parameters between the bootloader and/or firmware and the operating system. Each property is stored as a 32-bit integer unless indicated otherwise. +The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/usage-model.html#runtime-configuration[/chosen] node to pass parameters between the bootloader and/or firmware and the operating system. + +* Each property is stored as a 32-bit unsigned integer unless indicated otherwise. +* Numbers in device-tree are stored in binary and are big-endian. + +Example shell command for reading a 32-bit unsigned integer property: +[source,console] +---- +printf "%d" "0x$(od "/proc/device-tree/chosen/bootloader/partition" -v -An -t x1 | tr -d ' ' )" +---- `overlay_prefix`:: _(string)_ The xref:config_txt.adoc#overlay_prefix[overlay_prefix] string selected by `config.txt`. @@ -849,8 +858,6 @@ The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/ ==== Common bootloader properties `/chosen/bootloader` -Each property is stored as a 32-bit integer unless indicated otherwise. - `boot-mode`:: The boot-mode used to load the kernel. See the xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] documentation for a list of possible boot-mode values. `partition`:: The partition number used during boot. If a `boot.img` ramdisk is loaded then this refers to partition that the ramdisk was loaded from rather than the partition number within the ramdisk. @@ -859,9 +866,17 @@ Each property is stored as a 32-bit integer unless indicated otherwise. `tryboot`:: Set to `1` if the `tryboot` flag was set at boot. +==== Boot variables `/chosen/bootloader` + +Raspberry Pi 5 only. + +`arg1`:: The value of the user defined reboot argument from the previous boot. See xref:config_txt.adoc#boot_arg1[boot_arg1] + +`count`:: The value of the 8-bit `boot_count` variable when the OS was started. See xref:config_txt.adoc#boot_count[boot_count] + ==== Power supply properties `/chosen/power` -Raspberry Pi 5 only. Each property is stored as a 32-bit integer unless indicated otherwise. +Raspberry Pi 5 only. `max_current`:: The maximum current in mA that the power supply can supply. The firmware reports the value indicated by the USB-C, USB-PD or PoE interfaces. For bench power supplies (e.g. connected to the GPIO header) define `PSU_MAX_CURRENT` in the bootloader configuration to indicate the power supply current capability. @@ -898,7 +913,7 @@ The format is defined by the https://usb.org/document-library/usb-power-delivery ==== BCM2711 and BCM2712 specific bootloader properties `/chosen/bootloader` -The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM bootloaders. Each property is stored as a 32-bit integer unless indicated otherwise. +The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM bootloaders. `build_timestamp`:: The UTC build time for the EEPROM bootloader. @@ -959,7 +974,7 @@ The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM boot ==== BCM2711 and BCM2712 USB boot properties `/chosen/bootloader/usb` -The following properties are defined if the system was booted from USB. These may be used to uniquely identify the USB boot device. Each property is stored as a 32-bit integer. +The following properties are defined if the system was booted from USB. These may be used to uniquely identify the USB boot device. `usb-version`:: The USB major protocol version (2 or 3). diff --git a/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc b/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc index 69ab3024ca..4ade8e9ca6 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc @@ -1,66 +1,12 @@ == Install tools -To use the Debug Probe, install the following tools. +To use the Debug Probe, OpenOCD and the GNU Project Debugger (GDB) are required. An Integrated Development Environment (IDE) may also be useful. -=== Install OpenOCD +On Raspberry Pi OS, most Linux variants, macOS, and Microsoft Windows, it is recommended to install our VS Code extension. This extension bundles OpenOCD, ARM toolchains, GDB, and register definitions for Pico-series microcontrollers. -You need to install OpenOCD. +See Chapter 3 of our https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Raspberry Pi Pico] guide. -To install OpenOCD, run the following command in a terminal: +Alternatively, tools can be manually installed by following Appendix C in the guide. -[source,console] ----- -$ sudo apt install openocd ----- +NOTE: Manual installation of the tools on Windows is not recommended. -To run OpenOCD, use the `openocd` command in your terminal. - -==== Install OpenOCD on macOS - -First, install the https://brew.sh/[Homebrew] package manager: - -[source,console] ----- -$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" ----- - -To install OpenOCD on macOS, run the following commands: - -[source,console] ----- -$ brew install openocd ----- - -To run OpenOCD, use the `openocd` command in your terminal. - -=== Install GDB - -We also need to install the GNU debugger (GDB). - -==== Linux - -Install `gdb-multiarch`: - -[source,console] ----- -$ sudo apt install gdb-multiarch ----- - -==== macOS - -Run the following command to install `gdb`: - -[source,console] ----- -$ brew install arm-none-eabi-gdb ----- - -You can safely ignore the request for "special privileges" messages on installation. - -==== MS Windows - -GDB is available as part of our https://github.com/raspberrypi/pico-setup-windows/releases/latest[Pico setup for Windows installer]. It is also included in the https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads[Arm GNU Toolchain Downloads]. - -Alternatively information about manual installation can be found in Chapter 9 and Appendix A of our https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Raspberry Pi Pico] book. - -NOTE: Manual installation of GDB on Windows is not recommended. diff --git a/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc b/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc index 1dcc14cee2..33a5f0a2f3 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc @@ -1,10 +1,12 @@ -== Serial Wire Debug (SWD) +== Starting a Debug Session -Serial Wire Debug (SWD) is a two-pin interface (https://developer.arm.com/documentation/101761/1-0/Debug-and-trace-interface/Serial-Wire-Debug-signals[SWDIO and SWCLK]) alternative to the JTAG four- or five-pin debugging interface standard. +The Debug Probe will let you load binaries via the SWD port and OpenOCD: you will not need to unplug, and then push-and-hold, the BOOTSEL button every time you push a new binary to your Pico. Using the Debug Probe to upload new binaries is an entirely hands-off affair. -=== Uploading new programs to your Pico +GDB is then used to debug the binary running on the Pico. -The Pico Debug Probe will let you load binaries via the SWD port and OpenOCD: you will not need to unplug, and then push-and-hold, the BOOTSEL button every time you push a new binary to your Pico. Using the Debug Probe uploading new binaries is an entirely hands off affair. +We recommend the use of the Raspberry Pi Pico VSCode extension, which integrates the use of OpenOCD and GDB, to upload and debug programs. See Chapter 4 of https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting started with Raspberry Pi Pico] for more information. + +=== Standalone program upload Once you have built a binary: @@ -15,9 +17,9 @@ $ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed NOTE: When you use the Debug Probe to upload a binary the ELF version of the file is used, not the UF2 file that you would use when you drag-and-drop. -=== Debugging with SWD +=== Standalone debug session -It'll also let you use `openocd` in server mode, and connect GDB, which gives you break points and "proper" debugging. +This will use `openocd` in server mode, and connect GDB, which gives you breakpoints and single-step over a console interface. [IMPORTANT] ====== @@ -35,10 +37,12 @@ $ make -j4 ---- In a debug build you will get more information when you run it under the debugger, as the compiler builds your program with the information to tell GDB what your program is doing. - -See Chapter 6 of https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting started with Raspberry Pi Pico] for more information. ====== +NOTE: For computers that are _not_ Raspberry Pis, a variant of GDB that can debug ARM processors is required. Use one of the following alternatives depending on your operating system and device: +* On Linux devices, use `gdb-multiarch`. +* On macOS and Windows devices, use `arm-none-eabi-gdb` from the toolchain on https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads[Arm's website] + To start an OpenOCD server, run the following command: [source,console] @@ -55,8 +59,3 @@ $ gdb blink.elf > monitor reset init > continue ---- - -GDB doesn't work on all platforms. Use one of the following alternatives instead of `gdb`, depending on your operating system and device: - -* On Linux devices that are _not_ Raspberry Pis, use `gdb-multiarch`. -* On macOS devices, use `arm-none-eabi-gdb`. diff --git a/jekyll-assets/_includes/footer.html b/jekyll-assets/_includes/footer.html index 62386da5c5..1296bcc74f 100644 --- a/jekyll-assets/_includes/footer.html +++ b/jekyll-assets/_includes/footer.html @@ -225,7 +225,7 @@