/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\mainpage Firmware for CoreSight Debug Access Port

<b>CMSIS-DAP</b> is a <b>protocol</b> specification and a implementation of a <b>firmware</b> that supports access to the
<a href="https://developer.arm.com/documentation/102585/0000/what-is-a-debug-access-port" target="_blank"><b>CoreSight Debug Access Port (DAP)</b></a>.

The various Arm Cortex processors provide
<a href="https://developer.arm.com/ip-products/system-ip/coresight-debug-and-trace" target="_blank"><b>CoreSight Debug and Trace</b></a>.
CMSIS-DAP supports target devices that contain one or more Cortex processors. A device provides a Debug Access Port (DAP)
typically either with a 5-pin JTAG or with a 2-pin Serial Wired Debug (SWD) interface that connects to a debug unit.
CMSIS-DAP is the interface firmware for a debug unit that connects the debug port to USB. Debuggers that execute on a host
computer connect via USB and the Debug Unit to the device which runs the application software.

\image html "CMSIS_DAP_INTERFACE.png"

Benefits of CMSIS-DAP
---------------------
 - 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).
 
CMSIS-DAP firmware
==================
The CMSIS-DAP firmware is provided as source code and is fully configurable to a new debug unit. A source code template and
several reference implementations for popular debug units are provided. Refer to \ref DAP_Config_gr for more information.

The CMSIS-DAP firmware stack is composed of the following components:

  - CMSIS-DAP firmware that interfaces to JTAG or SWD pins using standard I/O pins of the Cortex-M device.
  - CMSIS-Driver USART that connects:
    - the UART of the Cortex-M device to the SWO output from the target.
    - an additional UART of the Cortex-M device to the UART from the target.
  - USB stack that interfaces to the USB port of the host computer using:
    - a custom class (for USB bulk endpoints),
    - the CDC ACM class to export USB COM Port.
  - The USB Device middleware may require CMSIS-RTOS and a CMSIS-Driver USB.
  
In the examples provided, the MDK-Middleware USB stack has been used. However, it is possible to use alternative USB stacks.

\note

- CMSIS-DAP v1.x is \a deprecated and <i>not recommended for new designs</i>.
- Use \ref BulkUSB "CMSIS-DAP v2.x" instead that provides high-speed SWO trace streaming and does not require driver
  installation in modern operating systems (Mac OS, Linux, Windows). Refer to \ref dap_install for more information.

Validation
----------
CMSIS-DAP compliant debug units must be validated using the scripts provided in  \ref DAP_Validate_gr.

The CMSIS-DAP firmware is provided in the following directory structure.

Directory                             | Description
:-------------------------------------|:------------------------------------------------------
.\\CMSIS\\DAP\\Firmware\\Config       | CMSIS-DAP firmware configuration 
.\\CMSIS\\DAP\\Firmware\\Examples     | CMSIS-DAP firmware adapted to various debug units
.\\CMSIS\\DAP\\Firmware\\Include      | CMSIS-DAP firmware header file
.\\CMSIS\\DAP\\Firmware\\Source       | CMSIS-DAP firmware source code
.\\CMSIS\\DAP\\Firmware\\Template     | Interface templates for MDK-Middleware
.\\CMSIS\\DAP\\Firmware\\Validation   | Validation project

<hr>

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\page dap_install Installing CMSIS-DAP enabled debug adapters

Using CMSIS-DAP v2 removes the necessity to install separate drivers on Mac OS, Linux, and Windows (8 and above) for the
debug adapter.

\section udevrules Additional requirements for Linux

On Linux, permission to access USB devices from user space must be explicitly granted via udev rules. Exemplary udev rules
are available in the <a href="https://github.com/pyocd/pyOCD/tree/main/udev" target="_blank">pyOCD GitHub repo</a> that
allow to access common debug probes without requiring it to be run as root.

\section win7 Additional requirements for Windows 7

For Windows 7, the CMSIS-DAP v2 device will install automatically if the PC is connected to the Internet and device
installation settings are set to automatically download and install drivers for devices. The installed device will be seen
in the Device Manager under Universal Serial Bus devices as a WinUSB Device.

If no Internet connection is available or you want the device to show with a different name in the Device Manager, you
should provide an .inf file. Refer to \ref wininf "USB Driver and *.inf file" for more information.

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\page dap_revisionHistory Revision History of CMSIS-DAP

<table class="cmtable" summary="Revision History">
    <tr>
      <th>Version</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>V2.1.2</td>
      <td>
         Fix \ref DAP_Transfer handling when transfer fails
      </td>
    </tr>
    <tr>
      <td>V2.1.1</td>
      <td>
         Allow default clock frequency to use fast clock mode
      </td>
    </tr>
    <tr>
      <td>V2.1.0</td>
      <td>
         Added: \ref DAP_uart_gr to support target communication via extra UART\n
         Added: UART Receive/Transmit Buffer Size values in the command \ref DAP_Info \n
         Added: Target Board Vendor and Target Board Name strings in the command \ref DAP_Info \n
         Added: Product Firmware Version string in the command \ref DAP_Info \n
         Changed: String encoding in \ref DAP_Info from ASCII to UTF-8
      </td>
    </tr>
    <tr>
      <td>V2.0.0</td>
      <td>
         Changed: Communication via USB bulk endpoints to achieve high-speed transfer rates\n
         Added: Streaming SWO via separate \ref BulkUSB "USB bulk endpoint"\n
         Added: \ref DAP_SWO_Transport extended with transport mode 2 - Send trace data via separate \ref BulkUSB "USB bulk endpoint" 
      </td>
    </tr>
    <tr>
      <td>V1.3.0</td>
      <td>
         Added: Target Board Vendor and Target Board Name strings in the command \ref DAP_Info \n
         Added: Product Firmware Version string in the command \ref DAP_Info \n
         Changed: String encoding in \ref DAP_Info from ASCII to UTF-8
      </td>
    </tr>
    <tr>
      <td>V1.2.0</td>
      <td>
         Added: \ref DAP_SWD_Sequence to enable SWD multi-drop target selection \n
         Added: Test Domain Timer values in the commands \ref DAP_Info, \ref DAP_Transfer
      </td>
    </tr>
    <tr>
      <td>V1.1.0</td>
      <td>
         Added: \ref DAP_swo_gr to support Serial Wire Output (SWO) in UART mode\n
         Added: \ref DAP_atomic_gr support for executing time critical DAP commands
      </td>
    </tr>
    <tr>
      <td>V1.0.0</td>
      <td>Version 1.0.0 was never released; version number skipped.</td>
    </tr>
    <tr>
      <td>V0.02</td>
      <td>Renamed \b DAP_LED to \ref DAP_HostStatus.</td>
    </tr>
    <tr>
      <td>V0.01</td>
      <td>Beta Release.</td>
    </tr>
</table>
*/