boards: raspberrypi: Aggregate debugging info to rpi_pico docs

Debugging information for RP2040/RP2350 is aggregated into the rpi pico
document, making other boards only refer to it.

Signed-off-by: TOKITA Hiroshi <tokita.hiroshi@gmail.com>
Co-authored-by: Benjamin Cabé <kartben@gmail.com>
Co-authored-by: Andrew Featherstone <andrew.featherstone@gmail.com>

Author: 3 people

boards/kws/pico2_spe/doc/index.rst

@@ -44,8 +44,19 @@ Programming and Debugging
 
 .. zephyr:board-supported-runners::
 
-As with the Pico-SPE, the SWD interface can be used to program and debug the
-device, e.g. using OpenOCD with the `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_ .
+As with the Pico-SPE, the SWD interface can be used to program and debug the device,
+e.g. using OpenOCD with the `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_ .
+
+The overall explanation regarding flashing and debugging is the same as for :zephyr:board:`rpi_pico`.
+Refer to :ref:`rpi_pico_programming_and_debugging` for more information. N.b. OpenOCD support requires using Raspberry Pi's forked version of OpenOCD.
+
+Below is an example of building and flashing the :zephyr:code-sample:`blinky` application.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/basic/blinky
+   :board: pico2_spe/rp2350a/m33
+   :goals: build flash
+   :flash-args: --openocd /usr/local/bin/openocd
 
 References
 **********

boards/kws/pico_spe/doc/index.rst

@@ -84,144 +84,19 @@ Programming and Debugging
 
 .. zephyr:board-supported-runners::
 
-Flashing
-========
+The SWD interface can be used to program and debug the device,
+e.g. using OpenOCD with the `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_ .
 
-Using SEGGER JLink
-------------------
+The overall explanation regarding flashing and debugging is the same as for :zephyr:board:`rpi_pico`.
+Refer to :ref:`rpi_pico_programming_and_debugging` for more information. N.b. OpenOCD support requires using Raspberry Pi's forked version of OpenOCD.
 
-You can Flash the pico_spe with a SEGGER JLink debug probe as described in
-:ref:`Building, Flashing and Debugging <west-flashing>`.
-
-Here is an example of building and flashing the :zephyr:code-sample:`blinky` application.
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/basic/blinky
-   :board: pico_spe
-   :goals: build
-
-.. code-block:: bash
-
-  west flash --runner jlink
-
-Using OpenOCD
--------------
-
-To use CMSIS-DAP, you must configure **udev**.
-
-Create a file in /etc/udev.rules.d with any name, and write the line below.
-
-.. code-block:: bash
-
-   ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000c", MODE="660", GROUP="plugdev", TAG+="uaccess"
-
-This example is valid for the case that the user joins to ``plugdev`` groups.
-
-The Pico-SPE has an SWD interface that can be used to program
-and debug the on board RP2040. This interface can be utilized by OpenOCD.
-To use it with the RP2040, OpenOCD version 0.12.0 or later is needed.
-
-If you are using a Debian based system (including RaspberryPi OS, Ubuntu. and more),
-using the `pico_setup.sh`_ script is a convenient way to set up the forked version of OpenOCD.
-
-Depending on the interface used (such as JLink), you might need to
-checkout to a branch that supports this interface, before proceeding.
-Build and install OpenOCD as described in the README.
-
-Here is an example of building and flashing the :zephyr:code-sample:`blinky` application.
+Below is an example of building and flashing the :zephyr:code-sample:`blinky` application.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/basic/blinky
    :board: pico_spe
    :goals: build flash
-   :gen-args: -DOPENOCD=/usr/local/bin/openocd -DOPENOCD_DEFAULT_PATH=/usr/local/share/openocd/scripts -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap
-
-Set the environment variables **OPENOCD** to :file:`/usr/local/bin/openocd`
-and **OPENOCD_DEFAULT_PATH** to :file:`/usr/local/share/openocd/scripts`. This should work
-with the OpenOCD that was installed with the default configuration.
-This configuration also works with an environment that is set up by the `pico_setup.sh`_ script.
-
-**RPI_PICO_DEBUG_ADAPTER** specifies what debug adapter is used for debugging.
-
-If **RPI_PICO_DEBUG_ADAPTER** was not assigned, ``cmsis-dap`` is used by default.
-The other supported adapters are ``raspberrypi-swd``, ``jlink`` and ``blackmagicprobe``.
-How to connect ``cmsis-dap`` and ``raspberrypi-swd`` is described in `Getting Started with Pico-SPE-Series`_.
-Any other SWD debug adapter maybe also work with this configuration.
-
-The value of **RPI_PICO_DEBUG_ADAPTER** is cached, so it can be omitted from
-``west flash`` and ``west debug`` if it was previously set while running
-``west build``.
-
-**RPI_PICO_DEBUG_ADAPTER** is used in an argument to OpenOCD as ``"source [find interface/${RPI_PICO_DEBUG_ADAPTER}.cfg]"``.
-Thus, **RPI_PICO_DEBUG_ADAPTER** needs to be assigned the file name of the debug adapter.
-
-You can also flash the board with the following
-command that directly calls OpenOCD (assuming a SEGGER JLink adapter is used):
-
-.. code-block:: console
-
-   $ openocd -f interface/jlink.cfg -c 'transport select swd' -f target/rp2040.cfg -c "adapter speed 2000" -c 'targets rp2040.core0' -c 'program path/to/zephyr.elf verify reset exit'
-
-Using UF2
----------
-
-If you don't have an SWD adapter, you can flash the Pico-SPE with
-a UF2 file. By default, building an app for this board will generate a
-:file:`build/zephyr/zephyr.uf2` file. If the Pico is powered on with the ``BOOTSEL``
-button pressed, it will appear on the host as a mass storage device. The
-UF2 file should be drag-and-dropped to the device, which will flash the Pico.
-
-Debugging
-=========
-
-The SWD interface can also be used to debug the board. To achieve this, you can
-either use SEGGER JLink or OpenOCD.
-
-Using SEGGER JLink
-------------------
-
-Use a SEGGER JLink debug probe and follow the instruction in
-:ref:`Building, Flashing and Debugging<west-debugging>`.
-
-
-Using OpenOCD
--------------
-
-Install OpenOCD as described for flashing the board.
-
-Here is an example for debugging the :zephyr:code-sample:`blinky` application.
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/basic/blinky
-   :board: pico_spe
-   :maybe-skip-config:
-   :goals: debug
-   :gen-args: -DOPENOCD=/usr/local/bin/openocd -DOPENOCD_DEFAULT_PATH=/usr/local/share/openocd/scripts -DRPI_PICO_DEBUG_ADAPTER=raspberrypi-swd
-
-As with flashing, you can specify the debug adapter by specifying **RPI_PICO_DEBUG_ADAPTER**
-at ``west build`` time. No needs to specify it at ``west debug`` time.
-
-You can also debug with OpenOCD and gdb launching from command-line.
-Run the following command:
-
-.. code-block:: console
-
-   $ openocd -f interface/jlink.cfg -c 'transport select swd' -f target/rp2040.cfg -c "adapter speed 2000" -c 'targets rp2040.core0'
-
-On another terminal, run:
-
-.. code-block:: console
-
-   $ gdb-multiarch
-
-Inside gdb, run:
-
-.. code-block:: console
-
-   (gdb) tar ext :3333
-   (gdb) file path/to/zephyr.elf
-
-You can then start debugging the board.
+   :flash-args: --openocd /usr/local/bin/openocd
 
 .. target-notes::
 

boards/pimoroni/pico_plus2/doc/index.rst

@@ -42,15 +42,16 @@ Programming and Debugging
 
 .. zephyr:board-supported-runners::
 
-The overall explanation regarding flashing and debugging is the same as or ``rpi_pico``.
-See :ref:`rpi_pico_flashing_using_openocd` and :ref:`rpi_pico_flashing_using_uf2`
-in ``rpi_pico`` documentation.
+The overall explanation regarding flashing and debugging is the same as or :zephyr:board:`rpi_pico`.
+See :ref:`rpi_pico_programming_and_debugging` in :zephyr:board:`rpi_pico` documentation. N.b. OpenOCD support requires using Raspberry Pi's forked version of OpenOCD.
+
+Below is an example of building and flashing the :zephyr:code-sample:`blinky` application.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/basic/blinky
-   :board: pico_plus2
+   :board: pico_plus2/rp2350b/m33
    :goals: build flash
-   :gen-args: -DOPENOCD=/usr/local/bin/openocd
+   :flash-args: --openocd /usr/local/bin/openocd
 
 .. target-notes::
 

boards/raspberrypi/rpi_pico/doc/index.rst

@@ -130,20 +130,11 @@ Raspberry Pi Pico's PIO is a programmable chip that can implement a variety of p
      - :kconfig:option:`CONFIG_LED_STRIP`
      - :dtcompatible:`worldsemi,ws2812-rpi_pico-pio`
 
-Programming and Debugging
-*************************
-
-.. zephyr:board-supported-runners::
-
-Applications for the ``rpi_pico`` board configuration can be built and
-flashed in the usual way (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
-
 System requirements
-===================
+*******************
 
 Prerequisites for the Pico W
-----------------------------
+============================
 
 Building for the Raspberry Pi Pico W requires the AIROC binary blobs
 provided by Infineon. Run the command below to retrieve those files:
@@ -156,47 +147,30 @@ provided by Infineon. Run the command below to retrieve those files:
 
    It is recommended running the command above after :file:`west update`.
 
-Debug Probe and Host Tools
---------------------------
+.. _rpi_pico_programming_and_debugging:
+
+Programming and Debugging
+*************************
+
+.. zephyr:board-supported-runners::
+
+Applications for the ``rpi_pico`` board configuration can be built and
+flashed in the usual way (see :ref:`build_an_application` and
+:ref:`application_run` for more details).
 
 Several debugging tools support the Raspberry Pi Pico.
 The `Raspberry Pi Debug Probe`_ is an easy-to-obtain CMSIS-DAP adapter
 officially provided by the Raspberry Pi Foundation,
 making it a convenient choice for debugging ``rpi_pico``.
+It can be used with ``openocd`` or ``pyocd``.
 
-It can be used with
-
-- :ref:`openocd-debug-host-tools`
-- :ref:`pyocd-debug-host-tools`
-
-OpenOCD is the default for ``rpi_pico``.
-
-- `SEGGER J-Link`_
-- `Black Magic Debug Probe <Black Magic Debug>`_
-
-can also be used.
-These are used with dedicated probes.
 
 Flashing
 ========
 
 The ``rpi_pico`` can flash with Zephyr's standard method.
 See also :ref:`Building, Flashing and Debugging<west-flashing>`.
 
-Here is an example of building and flashing the :zephyr:code-sample:`blinky` application.
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/basic/blinky
-   :board: rpi_pico
-   :goals: build
-
-.. code-block:: console
-
-  west flash --runner jlink
-
-
-.. _rpi_pico_flashing_using_openocd:
-
 Using OpenOCD
 -------------
 
@@ -216,13 +190,14 @@ Here is an example of building and flashing the :zephyr:code-sample:`blinky` app
    :zephyr-app: samples/basic/blinky
    :board: rpi_pico
    :goals: build flash
-   :gen-args: -DOPENOCD=/usr/local/bin/openocd -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap
+   :gen-args: -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap
+   :flash-args: --openocd /usr/local/bin/openocd
 
-Set the CMake option **OPENOCD** to :file:`/usr/local/bin/openocd`. This should work
+Set the flash runner option **--openocd** to :file:`/usr/local/bin/openocd`. This should work
 with the OpenOCD that was installed with the default configuration.
 This configuration also works with an environment that is set up by the `pico_setup.sh`_ script.
 
-**RPI_PICO_DEBUG_ADAPTER** specifies what debug adapter is used for debugging.
+In this sample, **RPI_PICO_DEBUG_ADAPTER** specifies which debug adapter is used for debugging.
 
 If **RPI_PICO_DEBUG_ADAPTER** was not set, ``cmsis-dap`` is used by default.
 The ``raspberrypi-swd`` and ``jlink`` are verified to work.
@@ -236,16 +211,40 @@ The value of **RPI_PICO_DEBUG_ADAPTER** is cached, so it can be omitted from
 **RPI_PICO_DEBUG_ADAPTER** is used in an argument to OpenOCD as ``"source [find interface/${RPI_PICO_DEBUG_ADAPTER}.cfg]"``.
 Thus, **RPI_PICO_DEBUG_ADAPTER** needs to be assigned the file name of the debug adapter.
 
-.. _rpi_pico_flashing_using_uf2:
+
+Using JLink or other supported tools
+------------------------------------
+
+You can Flash with a `SEGGER J-Link`_ debug probe as described in
+:ref:`Building, Flashing and Debugging <west-flashing>`.
+
+Here is an example of building and flashing the :zephyr:code-sample:`blinky` application.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/basic/blinky
+   :board: rpi_pico
+   :goals: build flash
+   :flash-args: --runner jlink
+
+You can also use other supported tools, such as `Black Magic Probe`_,
+by changing the ``-- runner`` option.
+
 
 Using UF2
 ---------
 
 If you don't have an SWD adapter, you can flash the Raspberry Pi Pico with
 a UF2 file. By default, building an app for this board will generate a
 :file:`build/zephyr/zephyr.uf2` file. If the Pico is powered on with the ``BOOTSEL``
-button pressed, it will appear on the host as a mass storage device. The
-UF2 file should be drag-and-dropped to the device, which will flash the Pico.
+button pressed, it will appear on the host as a mass storage device.
+Run the following command, or drag-and-drop the uf2 file to the device,
+which will flash the Pico.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/basic/blinky
+   :board: rpi_pico
+   :goals: flash
+   :flash-args: --runner uf2
 
 Debugging
 =========
@@ -260,15 +259,12 @@ the `Raspberry Pi Debug Probe`_.
    :board: rpi_pico
    :maybe-skip-config:
    :goals: debug
-   :gen-args: -DOPENOCD=/usr/local/bin/openocd -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap
+   :debug-args: --openocd /usr/local/bin/openocd
 
 The default debugging tool is ``openocd``.
 If you use a different tool, specify it with the ``--runner``,
 such as ``jlink``.
 
-If you use OpenOCD, see also the description about flashing :ref:`rpi_pico_flashing_using_uf2`
-for more information.
-
 
 .. target-notes::
 
@@ -293,5 +289,5 @@ for more information.
 .. _SEGGER J-Link:
    https://www.segger.com/products/debug-probes/j-link/
 
-.. _Black Magic Debug:
+.. _Black Magic Probe:
    https://black-magic.org/

boards/raspberrypi/rpi_pico2/doc/index.rst

@@ -42,8 +42,16 @@ Programming and Debugging
 
 .. zephyr:board-supported-runners::
 
-As with the Pico 1, the SWD interface can be used to program and debug the
-device, e.g. using OpenOCD with the `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_ .
+The overall explanation regarding flashing and debugging is the same as or :zephyr:board:`rpi_pico`.
+See :ref:`rpi_pico_programming_and_debugging` in :zephyr:board:`rpi_pico` documentation. N.b. OpenOCD support requires using Raspberry Pi's forked version of OpenOCD.
+
+Below is an example of building and flashing the :zephyr:code-sample:`blinky` application.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/basic/blinky
+   :board: rpi_pico2/rp2350a/m33
+   :goals: build flash
+   :flash-args: --openocd /usr/local/bin/openocd
 
 References
 **********