boards: nxp: imxrt10xx: update debugging section to use common snippets

danieldegrasse · nashif · commit e3794fd0f234 · 2024-06-18T14:34:47.000-04:00
Update iMXRT10xx board debug sections to use common snippets, which
describe debug configuration settings shared between all these boards.
This should help avoid documentation falling out of date in the future.

Signed-off-by: Daniel DeGrasse &lt;daniel.degrasse@nxp.com&gt;
diff --git a/boards/nxp/common/opensda-debug.rst b/boards/nxp/common/opensda-debug.rst
@@ -0,0 +1,39 @@
+:orphan:
+
+.. nxp-opensda-probes
+
+A debug probe is used for both flashing and debugging the board. This board has
+an :ref:`opensda-onboard-debug-probe`. The default firmware present on this
+probe is the :ref:`opensda-daplink-onboard-debug-probe`.
+
+Based on the host tool installed, please use the following instructions
+to setup your debug probe:
+
+* :ref:`jlink-debug-host-tools`: `Using J-Link on NXP OpenSDA Boards`_
+* :ref:`linkserver-debug-host-tools`: `Using DAPLink on NXP OpenSDA Boards`_
+* :ref:`pyocd-debug-host-tools`: `Using DAPLink on NXP OpenSDA Boards`_
+
+Using DAPLink on NXP OpenSDA Boards
+-----------------------------------
+
+1. If the debug firmware has been modified, follow the instructions provided at
+   :ref:`opensda-daplink-onboard-debug-probe` to reprogram the default debug
+   probe firmware on this board.
+#. Ensure the SWD isolation jumpers are populated
+
+Using J-Link on NXP OpenSDA Boards
+----------------------------------
+
+There are two options: the onboard debug circuit can be updated with Segger
+J-Link firmware, or a :ref:`jlink-external-debug-probe` can be attached to the
+board.
+
+To update the onboard debug circuit, please do the following:
+
+1. If the debug firmware has been modified, follow the instructions provided at
+   :ref:`opensda-jlink-onboard-debug-probe` to reprogram the default debug
+   probe firmware on this board.
+#. Ensure the SWD isolation jumpers are removed.
+
+To attach an external J-Link probe, ensure the SWD isolation jumpers are
+removed, and connect the external probe to the JTAG/SWD header.
diff --git a/boards/nxp/common/rt1xxx-lpclink2-debug.rst b/boards/nxp/common/rt1xxx-lpclink2-debug.rst
@@ -0,0 +1,45 @@
+:orphan:
+
+.. rt1xxx-lpclink2-probes
+
+A debug probe is used for both flashing and debugging the board. This board has
+an :ref:`lpc-link2-onboard-debug-probe`. The default firmware present on this
+probe is the :ref:`lpclink2-daplink-onboard-debug-probe`.
+
+Based on the host tool installed, please use the following instructions
+to setup your debug probe:
+
+* :ref:`jlink-debug-host-tools`:
+  `Using J-Link with LPC-Link2 Probe`_
+* :ref:`linkserver-debug-host-tools`:
+  `Using CMSIS-DAP with LPC-Link2 Probe`_
+* :ref:`pyocd-debug-host-tools`:
+  `Using CMSIS-DAP with LPC-Link2 Probe`_
+
+Using CMSIS-DAP with LPC-Link2 Probe
+------------------------------------
+
+1. Follow the instructions provided at
+   :ref:`lpclink2-cmsis-onboard-debug-probe` to reprogram the default debug
+   probe firmware on this board.
+#. Ensure the SWD isolation jumpers are populated
+
+Using J-Link with LPC-Link2 Probe
+---------------------------------
+
+There are two options: the onboard debug circuit can be updated with Segger
+J-Link firmware, or a :ref:`jlink-external-debug-probe` can be attached to the
+EVK.
+
+To update the onboard debug circuit, please do the following:
+
+1. Switch the power source for the EVK to a different source than the
+   debug USB, as the J-Link firmware does not power the EVK via the
+   debug USB.
+#. Follow the instructions provided at
+   :ref:`lpclink2-jlink-onboard-debug-probe` to reprogram the default debug
+   probe firmware on this board.
+#. Ensure the SWD isolation jumpers are populated.
+
+To attach an external J-Link probe, ensure the SWD isolation jumpers are
+removed, then connect the probe to the external JTAG/SWD header
diff --git a/boards/nxp/mimxrt1010_evk/doc/index.rst b/boards/nxp/mimxrt1010_evk/doc/index.rst
@@ -159,45 +159,26 @@ and the remaining are not used.
 Programming and Debugging
 *************************
 
-Build and flash applications as usual (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
+This board supports 3 debug host tools. Please install your preferred host
+tool, then follow the instructions in `Configuring a Debug Probe`_ to
+configure the board appropriately.
 
-Configuring a Debug Probe
-=========================
-
-A debug probe is used for both flashing and debugging the board. This board is
-configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`,
-however the :ref:`pyocd-debug-host-tools` do not yet support programming the
-external flashes on this board so you must reconfigure the board for one of the
-following debug probes instead.
-
-:ref:`jlink-external-debug-probe`
--------------------------------------------
-
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
-
-Attach a J-Link 10-pin connector to J55. Check that jumpers J61 and J62 are
-**off** (they are on by default when boards ship from the factory) to ensure
-SWD signals are disconnected from the OpenSDA microcontroller.
+* :ref:`linkserver-debug-host-tools` (Default, Supported by NXP)
+* :ref:`jlink-debug-host-tools` (Supported by NXP)
+* :ref:`pyocd-debug-host-tools` (Not supported by NXP)
 
-Using LinkServer
-----------------
+Once the host tool and board are configured, build and flash applications
+as usual (see :ref:`build_an_application` and :ref:`application_run` for more
+details).
 
-Install the :ref:`linkserver-debug-host-tools` and make sure they are in your
-search path. To use LinkServer the on board CMSIS-DAP firmware need updated with
-LPCScrypt installed with LinkServer.
-
-To enter board debuger FW update mode, connect J22 first, and power cycle board.
-For more details please refer to `Debug_Probe_Firmware_Programming.pdf`, which is
-installed with LinkServer.
-
-.. code-block:: console
+Configuring a Debug Probe
+=========================
 
-    :Ubuntu/Mac: scripts/program_CMSIS
-    :Windows: scripts/program_CMSIS.cmd
+For the RT1010, J61/J62 are the SWD isolation jumpers, J22 is the DFU
+mode jumper, and J16 is the 10 pin JTAG/SWD header.
 
-You may also se the ``-r linkserver`` option with West to use the LinkServer.
+.. include:: ../../common/rt1xxx-lpclink2-debug.rst
+   :start-after: rt1xxx-lpclink2-probes
 
 Configuring a Console
 =====================
diff --git a/boards/nxp/mimxrt1015_evk/doc/index.rst b/boards/nxp/mimxrt1015_evk/doc/index.rst
@@ -161,40 +161,26 @@ and the remaining are not used.
 Programming and Debugging
 *************************
 
-Build and flash applications as usual (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
+This board supports 3 debug host tools. Please install your preferred host
+tool, then follow the instructions in `Configuring a Debug Probe`_ to
+configure the board appropriately.
 
-Configuring a Debug Probe
-=========================
-
-A debug probe is used for both flashing and debugging the board. This board is
-configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`.
+* :ref:`linkserver-debug-host-tools` (Default, Supported by NXP)
+* :ref:`jlink-debug-host-tools` (Supported by NXP)
+* :ref:`pyocd-debug-host-tools` (Not supported by NXP)
 
-Using LinkServer: :ref:`opensda-daplink-onboard-debug-probe`
-------------------------------------------------------------
+Once the host tool and board are configured, build and flash applications
+as usual (see :ref:`build_an_application` and :ref:`application_run` for more
+details).
 
-Install the :ref:`linkserver-debug-host-tools` and make sure they are in your
-search path.  LinkServer works with the default CMSIS-DAP firmware included in
-the on-board debugger.
-
-Linkserver is the default runner. You may also se the ``-r linkserver`` option
-with West to use the LinkServer runner.
-
-.. code-block:: console
-
-   west flash
-   west debug
-
-
-External JLink: :ref:`jlink-external-debug-probe`
--------------------------------------------------
+Configuring a Debug Probe
+=========================
 
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
+For the RT1015, J47/J48 are the SWD isolation jumpers, J42 is the DFU
+mode jumper, and J34 is the 10 pin JTAG/SWD header.
 
-Attach a J-Link 10-pin connector to J55. Check that jumpers J47 and J48 are
-**off** (they are on by default when boards ship from the factory) to ensure
-SWD signals are disconnected from the OpenSDA microcontroller.
+.. include:: ../../common/rt1xxx-lpclink2-debug.rst
+   :start-after: rt1xxx-lpclink2-probes
 
 Configuring a Console
 =====================
diff --git a/boards/nxp/mimxrt1020_evk/doc/index.rst b/boards/nxp/mimxrt1020_evk/doc/index.rst
@@ -219,53 +219,26 @@ remaining are not used.
 Programming and Debugging
 *************************
 
-Build and flash applications as usual (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
+This board supports 3 debug host tools. Please install your preferred host
+tool, then follow the instructions in `Configuring a Debug Probe`_ to
+configure the board appropriately.
 
-Configuring a Debug Probe
-=========================
-
-A debug probe is used for both flashing and debugging the board. This board is
-configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`,
-however the :ref:`pyocd-debug-host-tools` do not yet support programming the
-external flashes on this board so you must reconfigure the board for one of the
-following debug probes instead.
-
-Using LinkServer
-----------------
+* :ref:`linkserver-debug-host-tools` (Default, Supported by NXP)
+* :ref:`jlink-debug-host-tools` (Supported by NXP)
+* :ref:`pyocd-debug-host-tools` (Not supported by NXP)
 
-Install the :ref:`linkserver-debug-host-tools` and make sure they are in your
-search path.  LinkServer works with the default CMSIS-DAP firmware included in
-the on-board debugger.
-
-Linkserver is the default runner. You may also se the ``-r linkserver`` option
-with West to use the LinkServer runner.
-
-.. code-block:: console
+Once the host tool and board are configured, build and flash applications
+as usual (see :ref:`build_an_application` and :ref:`application_run` for more
+details).
 
-   west flash
-   west debug
-
-JLink (on-board): :ref:`opensda-jlink-onboard-debug-probe`
-----------------------------------------------------------
-
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
-
-Follow the instructions in :ref:`opensda-jlink-onboard-debug-probe` to program
-the `OpenSDA J-Link MIMXRT1020-EVK Firmware`_. Check that jumpers J27 and J28
-are **on** (they are on by default when boards ship from the factory) to ensure
-SWD signals are connected to the OpenSDA microcontroller.
-
-External JLink: :ref:`jlink-external-debug-probe`
--------------------------------------------------
+Configuring a Debug Probe
+=========================
 
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
+For the RT1020, J47/J48 are the SWD isolation jumpers, J42 is the DFU
+mode jumper, and J16 is the 20 pin JTAG/SWD header.
 
-Attach a J-Link 20-pin connector to J16. Check that jumpers J27 and J28 are
-**off** (they are on by default when boards ship from the factory) to ensure
-SWD signals are disconnected from the OpenSDA microcontroller.
+.. include:: ../../common/rt1xxx-lpclink2-debug.rst
+   :start-after: rt1xxx-lpclink2-probes
 
 Configuring a Console
 =====================
diff --git a/boards/nxp/mimxrt1024_evk/doc/index.rst b/boards/nxp/mimxrt1024_evk/doc/index.rst
@@ -206,27 +206,21 @@ remaining are not used.
 Programming and Debugging
 *************************
 
-Build and flash applications as usual (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
+This board supports 2 debug host tools. Please install your preferred host
+tool, then follow the instructions in `Configuring a Debug Probe`_ to
+configure the board appropriately.
+
+* :ref:`jlink-debug-host-tools` (Default, Supported by NXP)
+* :ref:`pyocd-debug-host-tools` (Not supported by NXP)
 
 Configuring a Debug Probe
 =========================
 
-A debug probe is used for both flashing and debugging the board. This board is
-configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`,
-however the :ref:`pyocd-debug-host-tools` do not yet support programming the
-external flashes on this board so you must reconfigure the board for one of the
-following debug probes instead.
-
-:ref:`jlink-external-debug-probe`
----------------------------------
-
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
+For the RT1024, J47/J48 are the SWD isolation jumpers, J42 is the DFU
+mode jumper, and J55 is the 10 pin JTAG/SWD header.
 
-Attach a J-Link 10-pin connector to J55. Check that jumpers J47 and J48 are
-**off** (they are on by default when boards ship from the factory) to ensure
-SWD signals are disconnected from the OpenSDA microcontroller.
+.. include:: ../../common/rt1xxx-lpclink2-debug.rst
+   :start-after: rt1xxx-lpclink2-probes
 
 Configuring a Console
 =====================
diff --git a/boards/nxp/mimxrt1040_evk/doc/index.rst b/boards/nxp/mimxrt1040_evk/doc/index.rst
@@ -184,58 +184,29 @@ Serial Port
 The MIMXRT1040 SoC has eight UARTs. ``LPUART1`` is configured for the console,
 and the remaining UARTs are not used.
 
-
 Programming and Debugging
 *************************
 
-Build and flash applications as usual (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
-
-Configuring a Debug Probe
-=========================
+This board supports 3 debug host tools. Please install your preferred host
+tool, then follow the instructions in `Configuring a Debug Probe`_ to
+configure the board appropriately.
 
-Programming and Debugging
-*************************
+* :ref:`jlink-debug-host-tools` (Default, Supported by NXP)
+* :ref:`linkserver-debug-host-tools` (Supported by NXP)
+* :ref:`pyocd-debug-host-tools` (Not supported by NXP)
 
-Build and flash applications as usual (see :ref:`build_an_application` and
-:ref:`application_run` for more details).
+Once the host tool and board are configured, build and flash applications
+as usual (see :ref:`build_an_application` and :ref:`application_run` for more
+details).
 
 Configuring a Debug Probe
 =========================
 
-A debug probe is used for both flashing and debugging the board. This board is
-configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`,
-however the :ref:`pyocd-debug-host-tools` do not yet support programming the
-external flashes on this board so you must reconfigure the board for one of the
-following debug probes instead.
-
-Option 1: :ref:`opensda-jlink-onboard-debug-probe` (Recommended)
-----------------------------------------------------------------
-
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
-
-Check that jumpers J9 and J10 are **on** to ensure SWD signals are connected to
-the OpenSDA microcontroller. Then, follow the instructions in `NXP AN13206`_ to
-program a JLink based firmware to the LPC4322 based debugger on this board.
-
-Once the JLink based firmware is present on this board, the SOC will no longer
-be powered via the USB connection to J1. Move J40 to short pins 3 and 4 in
-order to use J48 for USB power, and connect another USB cable to power the SoC.
-LED D16 should illuminate to indicate the board is powered, and it should now be
-possible to program the SoC.
-
-Option 2: :ref:`jlink-external-debug-probe`
--------------------------------------------
-
-Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
-path.
+For the RT1040, J9/J10 are the SWD isolation jumpers, J12 is the DFU
+mode jumper, and J2 is the 20 pin JTAG/SWD header.
 
-The board can be programmed using the :ref:`jlink-external-debug-probe`,
-provided the onboard debug circuit's SWD signals are isolated from the MCU.
-To do so, ensure that jumpers J9 and J10 are **off** (they are on by default
-when the board ships from the factory). The external probe's 20 pin connector
-can then be connected to J2 to program the SOC.
+.. include:: ../../common/rt1xxx-lpclink2-debug.rst
+   :start-after: rt1xxx-lpclink2-probes
 
 Configuring a Console
 =====================
diff --git a/boards/nxp/mimxrt1050_evk/doc/index.rst b/boards/nxp/mimxrt1050_evk/doc/index.rst
diff --git a/boards/nxp/mimxrt1060_evk/doc/index.rst b/boards/nxp/mimxrt1060_evk/doc/index.rst
diff --git a/boards/nxp/mimxrt1064_evk/doc/index.rst b/boards/nxp/mimxrt1064_evk/doc/index.rst
