From 1a741343e74713a93b1590f2fe2a80a307a7a50c Mon Sep 17 00:00:00 2001 From: Christopher Seidl Date: Tue, 10 Mar 2026 11:26:24 +0100 Subject: [PATCH 1/2] Fix for SDCMSIS-1019 --- Documentation/Doxygen/dap.dxy.in | 2 +- Documentation/Doxygen/gen_doc.sh | 4 +- Documentation/Doxygen/src/mainpage.md | 50 +++++++++---------- Documentation/Doxygen/src/ref_dap.txt | 39 +++++++++++++++ .../Doxygen/style_template/layout.xml | 2 +- 5 files changed, 68 insertions(+), 29 deletions(-) diff --git a/Documentation/Doxygen/dap.dxy.in b/Documentation/Doxygen/dap.dxy.in index d0d1ce7..ca8e869 100644 --- a/Documentation/Doxygen/dap.dxy.in +++ b/Documentation/Doxygen/dap.dxy.in @@ -48,7 +48,7 @@ PROJECT_NAME = CMSIS-DAP # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = "Version 2.1.2" +PROJECT_NUMBER = "Version 2.1.3" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewers a diff --git a/Documentation/Doxygen/gen_doc.sh b/Documentation/Doxygen/gen_doc.sh index 4f5ba84..6d818cf 100755 --- a/Documentation/Doxygen/gen_doc.sh +++ b/Documentation/Doxygen/gen_doc.sh @@ -13,13 +13,13 @@ set -o pipefail # Set version of gen pack library # For available versions see https://github.com/Open-CMSIS-Pack/gen-pack/tags. # Use the tag name without the prefix "v", e.g., 0.7.0 -REQUIRED_GEN_PACK_LIB="0.11.3" +REQUIRED_GEN_PACK_LIB="0.13.0" DIRNAME=$(dirname "$(readlink -f "$0")") GENDIR=../html REQ_DXY_VERSION="1.13.2" -RUN_LINKCHECKER=1 +RUN_LINKCHECKER=0 function usage() { echo "Usage: $(basename "$0") [-h] [-s] [-c ]" diff --git a/Documentation/Doxygen/src/mainpage.md b/Documentation/Doxygen/src/mainpage.md index da78e85..8f9fa93 100644 --- a/Documentation/Doxygen/src/mainpage.md +++ b/Documentation/Doxygen/src/mainpage.md @@ -1,11 +1,11 @@ # Overview {#mainpage} -Many Arm Cortex processors implement CoreSight Debug Access Port ([DAP](https://developer.arm.com/documentation/102585/0000/what-is-a-debug-access-port)) that equips them with powerful on-chip debug and trace capabilities. **CMSIS-DAP** standardizes and simplifies access to this functionalilty for embedded software developers. +Many Arm Cortex processors implement CoreSight Debug Access Port ([DAP](https://developer.arm.com/documentation/102585/0000/what-is-a-debug-access-port)) that equips them with powerful on-chip debug and trace capabilities. **CMSIS-DAP** standardizes and simplifies access to this functionality for embedded software developers. **CMSIS-DAP** is a protocol specification and a firmware implementation that enables standardized communication between two sides: - - On one side an Arm Cortex-based processor where an embedded application is executed, - - and on the other side a software debug tool that runs on a host computer. +- On one side an Arm Cortex-based processor where an embedded application is executed, +- and on the other side a software debug tool that runs on a host computer. CMSIS-DAP support can be implemented in a standalone debug unit, or also as a component integrated on a development board. The figure below illustrates the concept: @@ -13,7 +13,7 @@ CMSIS-DAP support can be implemented in a standalone debug unit, or also as a co Connection with the target processor is possible over the physical interfaces supported by the CoreSight DAP: a 5-pin JTAG or a 2-pin Serial Wired Debug (SWD) interface. Additionally it can expose access to a UART for serial-to-USB communication. CMSIS-DAP supports target devices that contain one or more Arm Cortex cores. -For communication with the debugging program the USB connection is used. A broad set of \ref DAP_Commands_gr enables uniform support for CMSIS-DAP independendent on the actual probe. +For communication with the debugging program the USB connection is used. A broad set of \ref DAP_Commands_gr enables uniform support for CMSIS-DAP independent on the actual probe. The \ref dap_firmware provides a template implementation of the CMSIS-DAP concept as well as several example projects for popular debug units. @@ -25,18 +25,18 @@ Debug probes can be validated for compliance to CMSIS-DAP using the scripts expl ## Features and Benefits {#dap_benefits} - - Provides a standardized interface for debuggers. Interfaces to many standard debuggers is available. - - Access to CoreSight registers of all Cortex processor architectures (Cortex-A/R/M). - - Connects via 5-pin JTAG or 2-pin Serial Wire Debug (SWD). - - Supports multi-core debugging. - - Supports Serial Wire Output (SWO) of Cortex-M devices. - - Easy to deploy to debug units based on Cortex-M microcontrollers. - - Debug unit may be integrated on an evaluation board. - - Using USB bulk transfers avoids driver installation on host PC. - - Supports time-critical JTAG or SWD command execution. - - Supports Test Domain Timer for time measurement using the debug unit. - - Supports UART communication port, which can be routed to USB COM Port (optional) or native CMSIS-DAP commands (new in CMSIS-DAP Version 2.1.0). - - Flexible customization is possible with vendor-specific commands. +- Provides a standardized interface for debuggers. Interfaces to many standard debuggers is available. +- Access to CoreSight registers of all Cortex processor architectures (Cortex-A/R/M). +- Connects via 5-pin JTAG or 2-pin Serial Wire Debug (SWD). +- Supports multi-core debugging. +- Supports Serial Wire Output (SWO) of Cortex-M devices. +- Easy to deploy to debug units based on Cortex-M microcontrollers. +- Debug unit may be integrated on an evaluation board. +- Using USB bulk transfers avoids driver installation on host PC. +- Supports time-critical JTAG or SWD command execution. +- Supports Test Domain Timer for time measurement using the debug unit. +- Supports UART communication port, which can be routed to USB COM Port (optional) or native CMSIS-DAP commands (new in CMSIS-DAP Version 2.1.0). +- Flexible customization is possible with vendor-specific commands. ## Access to CMSIS-DAP {#dap_access} @@ -57,20 +57,20 @@ CMSIS-DAP has a well-established support in popular embedded software developmen **Software Development Tools and Frameworks:** - - [Arm Keil MDK](https://www.keil.arm.com/) - - [IAR Embedded Workbench for Arm](https://www.iar.com/ewarm) - - [SEGGER Embedded Studio](https://www.segger.com/products/development-tools/embedded-studio/) - - [PlatformIO](https://platformio.org/) - - [PyOCD](https://pyocd.io/) - - [OpenOCD](https://openocd.org/) +- [Arm Keil MDK](https://www.keil.arm.com/) +- [IAR Embedded Workbench for Arm](https://www.iar.com/ewarm) +- [SEGGER Embedded Studio](https://www.segger.com/products/development-tools/embedded-studio/) +- [PlatformIO](https://platformio.org/) +- [PyOCD](https://pyocd.io/) +- [OpenOCD](https://openocd.org/) Also many development tools from chip vendors rely on CMSIS-DAP protocol for communication with devices. **Debug adapters:** - - [Arm ULINKplus](https://developer.arm.com/Tools%20and%20Software/ULINKplus) - - [SEGGER J-Link](https://www.segger.com/products/debug-probes/j-link/) - - On-board debug adapters from many popular chip vendors. +- [Arm ULINKplus](https://developer.arm.com/Tools%20and%20Software/ULINKplus) +- [SEGGER J-Link](https://www.segger.com/products/debug-probes/j-link/) +- On-board debug adapters from many popular chip vendors. \ref dap_firmware provides the source code, examples and guidelines for enabling CMSIS-DAP on custom debug units. diff --git a/Documentation/Doxygen/src/ref_dap.txt b/Documentation/Doxygen/src/ref_dap.txt index 820424e..6e26523 100644 --- a/Documentation/Doxygen/src/ref_dap.txt +++ b/Documentation/Doxygen/src/ref_dap.txt @@ -166,6 +166,45 @@ The Transfer Commands allow to: - Configure the parameters for information exchange with CoreSight registers. - Transfer (read or write) a single data word or a data block with CoreSight registers. - Terminate an active data transfer. + +The \a Match \a Retry parameter configured by \ref DAP_TransferConfigure directly affects how \ref DAP_Transfer +processes read operations that use the match mask and value match features. + +When a transfer uses the \a value \a match mechanism, the \a match \a mask previously set in the same \ref DAP_Transfer +request is applied to the value read from the target register. The firmware compares (Register_Value & Match_Mask) with +the provided Match_Value on each read. If the masked value does not equal the expected value, the controller will +automatically retry the read until either the masked value matches or the configured \a Match \a Retry count is +exhausted. If the retry limit is reached without a match, Bit 4 (\a Value \a Mismatch) is set in the response and the +\ref DAP_Transfer command aborts. This behavior is governed by the \a Match \a Retry parameter documented in +\ref DAP_TransferConfigure (see Match Retry: Number of retries on reads with Value Match in DAP_Transfer). + +A common use case for this mechanism is polling the Cortex-M debug registers via SWD. For example, reading a core +register through the Debug Core Register Selector (DCRSR) requires writing the register identifier and then polling +DHCSR until the S_REGRDY bit indicates the result is ready. The match mask/value match mechanism in \ref DAP_Transfer +can implement this pattern without explicit looping in the host: + +- Call \ref DAP_TransferConfigure to set the retry behavior. Typical implementations use defaults of Idle Cycles = 0, + WAIT Retry = 100, and Match Retry set to a value sufficient for the expected polling duration. The Match Retry count + need only be set once; it persists until reconfigured. + +- Issue a \ref DAP_Transfer with a Transfer Count of at least two transfers in the same request. The first transfer + writes the match mask (using the Match Mask bit set in the request). The mask defines which bits in the read value + are relevant for comparison (for example, selecting the S_REGRDY bit). The second transfer performs the actual read + with the Value Match bit set and includes the expected Match_Value in the transfer data. + +By arranging the mask and value in a single \ref DAP_Transfer request, the firmware will repeatedly execute the read +until the masked value matches or the retry limit is reached. The match mask remains in effect for subsequent transfers +in the same request. Additional match value reads can follow within the same \ref DAP_Transfer request up to the +protocol limit of 255 transfers, subject to USB packet size constraints. Combining multiple mask/value match pairs in +this way can reduce USB overhead compared to separate transfers per read. + +This value match and retry mechanism applies only to \ref DAP_Transfer; it is not supported by \ref DAP_TransferBlock. +There is no separate time-based timeout; the effective delay is determined by the configured Match Retry count and the +speed of the underlying debug interface. + +For long sequences of transfers that must execute without USB round-trips between operations, the +\ref DAP_QueueCommands_gr API exists; however, for typical polling reads using match mask/value match, queuing is not +required. */ diff --git a/Documentation/Doxygen/style_template/layout.xml b/Documentation/Doxygen/style_template/layout.xml index 0369032..950badd 100644 --- a/Documentation/Doxygen/style_template/layout.xml +++ b/Documentation/Doxygen/style_template/layout.xml @@ -4,7 +4,7 @@ - + From dd871b7e22d7fcd4f11e7f1555c25052e49f4226 Mon Sep 17 00:00:00 2001 From: Christopher Seidl Date: Thu, 12 Mar 2026 14:16:51 +0100 Subject: [PATCH 2/2] Incorporated required changes --- Documentation/Doxygen/dap.dxy.in | 2 +- Documentation/Doxygen/src/ref_dap.txt | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/Documentation/Doxygen/dap.dxy.in b/Documentation/Doxygen/dap.dxy.in index ca8e869..d0d1ce7 100644 --- a/Documentation/Doxygen/dap.dxy.in +++ b/Documentation/Doxygen/dap.dxy.in @@ -48,7 +48,7 @@ PROJECT_NAME = CMSIS-DAP # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = "Version 2.1.3" +PROJECT_NUMBER = "Version 2.1.2" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewers a diff --git a/Documentation/Doxygen/src/ref_dap.txt b/Documentation/Doxygen/src/ref_dap.txt index 6e26523..af9b7e0 100644 --- a/Documentation/Doxygen/src/ref_dap.txt +++ b/Documentation/Doxygen/src/ref_dap.txt @@ -167,6 +167,8 @@ The Transfer Commands allow to: - Transfer (read or write) a single data word or a data block with CoreSight registers. - Terminate an active data transfer. +### Match Retry Mechanism + The \a Match \a Retry parameter configured by \ref DAP_TransferConfigure directly affects how \ref DAP_Transfer processes read operations that use the match mask and value match features. @@ -178,6 +180,8 @@ exhausted. If the retry limit is reached without a match, Bit 4 (\a Value \a Mis \ref DAP_Transfer command aborts. This behavior is governed by the \a Match \a Retry parameter documented in \ref DAP_TransferConfigure (see Match Retry: Number of retries on reads with Value Match in DAP_Transfer). +### Usage Example + A common use case for this mechanism is polling the Cortex-M debug registers via SWD. For example, reading a core register through the Debug Core Register Selector (DCRSR) requires writing the register identifier and then polling DHCSR until the S_REGRDY bit indicates the result is ready. The match mask/value match mechanism in \ref DAP_Transfer @@ -192,6 +196,8 @@ can implement this pattern without explicit looping in the host: are relevant for comparison (for example, selecting the S_REGRDY bit). The second transfer performs the actual read with the Value Match bit set and includes the expected Match_Value in the transfer data. +### Efficient use of DAP Transfers for Core Register Reads + By arranging the mask and value in a single \ref DAP_Transfer request, the firmware will repeatedly execute the read until the masked value matches or the retry limit is reached. The match mask remains in effect for subsequent transfers in the same request. Additional match value reads can follow within the same \ref DAP_Transfer request up to the