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..af9b7e0 100644 --- a/Documentation/Doxygen/src/ref_dap.txt +++ b/Documentation/Doxygen/src/ref_dap.txt @@ -166,6 +166,51 @@ 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. + +### 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. + +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). + +### 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 +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. + +### 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 +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 @@ - +