pyocd · autumn-qmj · May 22, 2023 · May 22, 2023 · May 23, 2023 · May 26, 2023
diff --git a/docs/api_examples.md b/docs/api_examples.md
@@ -10,6 +10,7 @@ This example shows basic connection, loading a firmware binary, and some simple
 #!/usr/bin/env python3
 from pyocd.core.helpers import ConnectHelper
 from pyocd.flash.file_programmer import FileProgrammer
+import time
 
 import logging
 logging.basicConfig(level=logging.INFO)

diff --git a/docs/builtin-targets.md b/docs/builtin-targets.md
@@ -6,6 +6,36 @@ title: Built-in targets
 
 <tr><th>Target Type Name</th><th>Vendor</th><th>Name</th></tr>
 
+    <tr><td><code>air001</code></td>
+    <td>AirM2M</td>
+    <td>Air001</td>
+    </tr>
+
+    <tr><td><code>air32f103xb</code></td>
+    <td>AirM2M</td>
+    <td>Air32F103xB</td>
+    </tr>
+
+    <tr><td><code>air32f103xc</code></td>
+    <td>AirM2M</td>
+    <td>Air32F103xC</td>
+    </tr>
+
+    <tr><td><code>air32f103xe</code></td>
+    <td>AirM2M</td>
+    <td>Air32F103xE</td>
+    </tr>
+
+    <tr><td><code>air32f103xg</code></td>
+    <td>AirM2M</td>
+    <td>Air32F103xG</td>
+    </tr>
+
+    <tr><td><code>air32f103xp</code></td>
+    <td>AirM2M</td>
+    <td>Air32F103xP</td>
+    </tr>
+
     <tr><td><code>cc3220sf</code></td>
     <td>Texas Instruments</td>
     <td>CC3220SF</td>
@@ -126,6 +156,16 @@ title: Built-in targets
     <td>CY8C6xxA</td>
     </tr>
 
+    <tr><td><code>hc32a460xe</code></td>
+    <td>HDSC</td>
+    <td>HC32F460xE</td>
+    </tr>
+
+    <tr><td><code>hc32a4a0xi</code></td>
+    <td>HDSC</td>
+    <td>HC32F4A0xI</td>
+    </tr>
+
     <tr><td><code>hc32f003</code></td>
     <td>HDSC</td>
     <td>HC32F003</td>
@@ -176,6 +216,16 @@ title: Built-in targets
     <td>HC32F196</td>
     </tr>
 
+    <tr><td><code>hc32f448xa</code></td>
+    <td>HDSC</td>
+    <td>HC32F448xA</td>
+    </tr>
+
+    <tr><td><code>hc32f448xc</code></td>
+    <td>HDSC</td>
+    <td>HC32F448xC</td>
+    </tr>
+
     <tr><td><code>hc32f451xc</code></td>
     <td>HDSC</td>
     <td>HC32F451xC</td>
@@ -546,6 +596,11 @@ title: Built-in targets
     <td>MAX32660</td>
     </tr>
 
+    <tr><td><code>max32666</code></td>
+    <td>Maxim</td>
+    <td>MAX32666</td>
+    </tr>
+
     <tr><td><code>max32670</code></td>
     <td>Maxim</td>
     <td>MAX32670</td>
@@ -668,7 +723,7 @@ title: Built-in targets
 
     <tr><td><code>nrf91</code></td>
     <td>Nordic Semiconductor</td>
-    <td>NRF9160</td>
+    <td>NRF91XX</td>
     </tr>
 
     <tr><td><code>rp2040</code></td>
@@ -691,6 +746,16 @@ title: Built-in targets
     <td>RTL8195AM</td>
     </tr>
 
+    <tr><td><code>rtl8762c</code></td>
+    <td>Realtek Semiconductor</td>
+    <td>RTL8762C</td>
+    </tr>
+
+    <tr><td><code>s32k344</code></td>
+    <td>NXP</td>
+    <td>S32K344</td>
+    </tr>
+
     <tr><td><code>s5js100</code></td>
     <td>Samsung</td>
     <td>S5JS100</td>
@@ -741,6 +806,21 @@ title: Built-in targets
     <td>STM32F767xx</td>
     </tr>
 
+    <tr><td><code>stm32h723xx</code></td>
+    <td>STMicroelectronics</td>
+    <td>STM32H723xx</td>
+    </tr>
+
+    <tr><td><code>stm32h743xx</code></td>
+    <td>STMicroelectronics</td>
+    <td>STM32H743xx</td>
+    </tr>
+
+    <tr><td><code>stm32h7b0xx</code></td>
+    <td>STMicroelectronics</td>
+    <td>STM32H7B0xx</td>
+    </tr>
+
     <tr><td><code>stm32l031x6</code></td>
     <td>STMicroelectronics</td>
     <td>STM32L031x6</td>

diff --git a/docs/command_reference.md b/docs/command_reference.md
@@ -368,6 +368,16 @@ ADDR DATA+
 Write 8-bit bytes to memory.
 </td></tr>
 
+<tr><td colspan="3"><b>Nrf91</b></td></tr>
+
+<tr><td>
+<a href="#nrf91-update-modem-fw"><tt>nrf91-update-modem-fw</tt></a>
+</td><td>
+[-f] mfw_nrf91xx_x.x.x.zip
+</td><td>
+Update modem firmware for an nRF91 target.
+</td></tr>
+
 <tr><td colspan="3"><b>Openocd_compatibility</b></td></tr>
 
 <tr><td>
@@ -992,6 +1002,14 @@ Write 64-bit double-words to memory. The data arguments are 64-bit words in big-
 Write 8-bit bytes to memory. The data arguments are 8-bit bytes. Can write to both RAM and flash. Flash writes are subject to minimum write size and alignment, and the flash page must have been previously erased.
 
 
+### Nrf91
+
+##### `nrf91-update-modem-fw`
+
+**Usage**: nrf91-update-modem-fw [-f] mfw_nrf91xx_x.x.x.zip \
+Update modem firmware for an nRF91 target. If -f is specified, modem firmware is written to the device, even if the correct version is already present.
+
+
 ### Openocd compatibility
 
 ##### `init`

diff --git a/docs/debug_probes.md b/docs/debug_probes.md
@@ -174,6 +174,10 @@ DAPLink firmware updates are available on the [daplink.io](https://daplink.io/)
 The Microchip (previously Atmel) EDBG probe firmware, at the time of this writing, provides a CMSIS-DAP v1 interface.
 On macOS, reading command responses always times out. The probe works on other OSes, however.
 
+### TI XDS110
+
+XDS110 firmware version 03.00.00.25 is known to have an issue when using multiple outstanding packets (the default setting). To work around this, set the `cmsis_dap.limit_packets` session option, e.g. `-Ocmsis_dap.limit_packets=1` on the command line. Earlier firmware versions most likely exhibit the issue; it is unknown whether it is fixed in more recent versions.
+
 
 ### PE Micro Cyclone and Multilink
 

diff --git a/docs/developer/board_ids.md b/docs/developer/board_ids.md
@@ -2,6 +2,11 @@
 title: Board IDs
 ---
 
+<div class="alert alert-warning">
+New CMSIS-DAP firmware releases should use the CMSIS-DAP v2.1 board and target identification features
+rather than board IDs.
+</div>
+
 This page documents the board IDs reported by certain [debug probes]({% link _docs/debug_probes.md %}) with which pyOCD can automatically identify a board and its target type.
 
 ## Introduction
@@ -20,11 +25,12 @@ Board ID definition:
   - There are multiple cases of boards from different vendors being incorrectly allocated in another vendor's namespace, so this cannot solely be relied upon. It's only really useful for grouping of IDs.
 - Reserved values::
   - "C0xx" is reserved for "community" boards, i.e. open source hardware and non-commercial projects.
+  - "D0xx" is reserved for boards that are not also Mbed platforms, mostly DAPLink firmware.
   - "0000" is reserved to mean "no on-board target". That is, the debug probe is standalone must be connected to the target with a cable.
 
 Currently these debug probe firmware support board IDs:
 - [DAPLink](https://daplink.io/), via the first 4 chars of the USB serial number
-- STLinkV2-1 and V3, via an `.htm` file on the associated USB mass storage volume.
+- STLinkV2-1 and V3, via an `.htm` file on the associated USB mass storage volume and an STLink protocol command.
 
 ## Lists
 
@@ -34,10 +40,17 @@ You can see the full list of public Mbed platforms at [https://os.mbed.com/api/v
 
 ## Getting a new ID
 
-To request a new board ID, fill out the form here: [https://os.mbed.com/request-board-id](https://os.mbed.com/request-board-id)
+There are two ways to get new board IDs:
+
+1. Post a request to the #daplink channel on the [pyOCD Slack workspace](https://pyocd.slack.com/) ([Join](https://join.slack.com/t/pyocd/shared_invite/zt-zqjv6zr5-ZfGAXl_mFCGGmFlB_8riHA)). We can allocate you a 0xDxxx board ID.
+
+2. For new Mbed OS platforms, request a new board ID by filling out the form here: [https://os.mbed.com/request-board-id](https://os.mbed.com/request-board-id)
 
 ## Moving forward
 
 Version 2.1 of the [CMSIS-DAP](https://arm-software.github.io/CMSIS_5/DAP/html/index.html) specification adds support for new [DAP_Info](https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Info.html) selectors that identify the board and target. The values returned by these selectors are required to match board and target identifiers in CMSIS-Packs.
 
 PyOCD supports the new CMSIS-DAP v2.1 info selectors and will use them in preference to a board ID if available. This works with any debug probe firmware compatible with CMSIS-DAP. Thus, any new CMSIS-DAP firmware projects should support v2.1 and the new DAP_Info selectors rather than implementing board IDs.
+
+The DAPLink open source CMSIS-DAP firmware has support for the v2.1 identifiers. We recommend using these identifiers rather than a board ID for any new DAPLink based firmware.
+
diff --git a/docs/developers_guide.md b/docs/developers_guide.md
@@ -60,7 +60,7 @@ If you switch branches, you may need to reinstall.
 
 Because the `develop` branch doesn't have version tags except older tags from the `develop` branch point,
 the version number of pyOCD might be significantly out of date. If this is an issue, you can override the
-version by setting the `SETUPTOOLS_SCM_PRETEND_VERSION` environmment variable to the desired version number
+version by setting the `SETUPTOOLS_SCM_PRETEND_VERSION` environment variable to the desired version number
 (without a "v" prefix).
 
 **Step 4.** Develop
@@ -122,3 +122,66 @@ Maintainers will cherry-pick commits between `main` and `develop` as necessary t
 If you have any questions about how best to submit changes or the branch policy, please ask in the
 [Slack](https://join.slack.com/t/pyocd/shared_invite/zt-zqjv6zr5-ZfGAXl_mFCGGmFlB_8riHA) workspace or
 [GitHub Discussions](https://github.com/pyocd/pyOCD/discussions). We'll be happy to help.
+
+
+## Debugging pyOCD
+
+### VS Code
+
+Debugging pyOCD launched by VS Code is straightforward, and is much like debugging any package.
+
+1. First, set up the pyOCD development and virtualenv as described above.
+
+2. Set up the launch config as follows.
+
+    - Set `pythonPath` to the python executable in the virtualenv.
+
+    - Set `module` to `pyocd.__main__`, to debug pyOCD entry point as a module. This works better than trying to debug the script `.../pyocd/__main__.py` as it ensures the relative module references inside pyOCD work correctly..
+
+    For instance, here is a VS Code launch config for pyOCD's gdbserver:
+
+        {
+            "name": "pyocd gdbserver",
+            "type": "python",
+            "request": "launch",
+            "module": "pyocd.__main__",
+            "console": "integratedTerminal",
+            "stopOnEntry": true,
+            "pythonPath": "/Users/username/projects/pyOCD/venv/bin/python3",
+            "showReturnValue": true,
+            "args": ["gdb", "-v"]
+        }
+
+
+It's also possible to debug pyOCD remotely. This is useful either for cases where it is launched by another tool and you cannot directly control the command line , or is on another machine.
+
+For remote debug, use a launch config like this:
+
+        {
+            "name": "Python: Attach using port",
+            "type": "python",
+            "request": "attach",
+            "port": 5678,
+        }
+
+If the pyOCD process is on another machine, add a `host` key to the launch config with the host name. (This defaults to localhost.)
+
+Install [debugpy](https://github.com/microsoft/debugpy/) with pip into your virtual environment.
+
+To remotely debug pyOCD from the command line, run it with the `debugpy` module. For instance, `python -m debugpy --listen 5678 -m pyocd gdb -v`. Additionally, `--wait-for-client` can be added after the port number to wait for the debug client to connect before running pyOCD.
+
+If you don't control pyOCD's launch, then `debugpy` can be called directly from pyOCD's code. Add the following code to pyocd. Inside `pyocd.__main__.PyOCDTool.run()` is a good location, though it can be done at module level in `__main__.py`.
+
+```py
+import debugpy
+debugpy.listen(5678)
+```
+
+To pause pyOCD's execution and wait for the debug client to connect, add this line as well:
+```py
+debugpy.wait_for_client()
+```
+
+
+
+
diff --git a/docs/docs.yml b/docs/docs.yml
@@ -0,0 +1,46 @@
+- title: Getting started
+  docs:
+  - installing
+  - installing_on_non_x86
+  - gdb_setup
+- title: User guide
+  docs:
+  - target_support
+  - debug_probes
+  - configuration
+  - open_cmsis_pack_support
+  - gdbserver
+  - user_scripts
+  - remote_probe_access
+  - configuring_logging
+  - security
+  - multicore_debug
+  - semihosting
+  - swo_swv
+  - memory_attributes
+  - target_family_notes
+  - faq
+- title: Reference
+  docs:
+  - terminology
+  - builtin-targets
+  - options
+  - command_reference
+  - env_vars
+- title: Python API
+  docs:
+  - api/architecture
+  - python_api
+  - api_examples
+  - api/using_session_options
+- title: Developers
+  docs:
+  - developers_guide
+  - adding_new_targets
+#  - how_to_build
+  - automated_tests
+  - title: Internal design
+    docs:
+    - architecture
+    - developer/board_ids
+    - remote_probe_protocol
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,20 @@
+---
+title: FAQ
+---
+
+### Common issues
+
+##### Debug probe is not available
+
+- Linux: Make sure udev is configured correctly to allow access to USB debug probes. PyOCD includes a set of predefined [udev config files](https://github.com/pyocd/pyOCD/tree/main/udev) for common probe. Alternatively, you can run pyocd using sudo, but this is strongly recommended against.
+- MacOS: Make sure another process hasn't taken ownership of the USB device.
+
+##### Getting "No ACK" errors when attempting to connect
+
+- A "No ACK" error means the target is not responding at all to SWD/JTAG transfers. This can be for a few reasons:
+    - The target is not powered on. Either the board isn't power up or the target is in a deep sleep mode.
+    - The SWD/JTAG pins haved been pinmuxed to different peripherals.
+    - The SWD or JTAG wire protocol being used isn't supported by the device.
+    - A target-specific reason, such as a proprietary connection procedure that hasn't been performed.
+- The method to gain debug control of a powered down or sleeping device is target dependent. However, it generally involves first waking the device, then halting the CPU before the resident firmware can place the device in a low power state. For many MCUs, these steps can be accomplished by telling pyOCD to connect while the reset pin is held asserted, eg connecting under reset. To use this mode, pass `--connect=under-reset`. On certain devices this won't work because the reset pin performs a cold reset that also resets debug logic. For these devices, please refer to the vendor's reference manual or programming manual.
+- A similar method to waking a sleeping device is needed to gain control of a device whose firmware changes the SWD/JTAG pinmux after it starts running. Connecting under reset also works in this case, if the device support it.