/**************************************************************************************************/
/**
\defgroup DAP_Config_gr Firmware configuration

CMSIS-DAP is designed for debug units with a Cortex-M microcontroller.

The CMSIS-DAP firmware can be deployed to a debug unit that is based on Cortex-M processor-based microcontroller.

\image html "CMSIS_DAP_Debug_Unit.png" "CMSIS-DAP debug unit Hardware"

The picture below shows the setup with an isolation adapter.

\image html "CMSIS_DAP_Debug_Unit_ISO.png" "CMSIS-DAP debug unit with isolation adapter"

Hardware requirements
---------------------
The CMSIS-DAP firmware is designed for debug units that fulfil the following hardware
requirements:
  - Cortex-M processor-based microcontroller.
  - CPU Clock: 48 MHz or higher; microcontroller must have a SYSTICK timer.
  - RAM: 8 KB or more.
  - Flash ROM: 16 KB or more.
  - Full-speed or High-speed USB Device peripheral.
  - 7 standard I/O pins for JTAG/SWD interface.
  - Optionally, 2 I/O pins for status LEDs.
  - Optionally, a UART to support SWO capturing (Rx pin connected to SWO).
  - Optionally, a UART to support an additional UART communication port (for printf debugging).
  
CMSIS-DAP firmware
------------------
The CMSIS-DAP firmware can be configured for a new debug unit using at least the 
<a href="https://www.keil.com/mdk5" target="_blank">Keil MDK-Plus or MDK-Professional Edition</a>.
Reference implementations are provided as source code with complete project files
and may be used as starting point for the firmware deployment to a new debug unit.

The folder <b>.\\Firmware\\Config</b> contains a template of the \b DAP_config.h configuration file.
Various adaptations for different target hardware are provided.

Folders and Files                     | Description
------------------------------------- | -----------------------------------------------------------------------
.\\Firmware\\Examples\\LPC-Link2      | CMSIS-DAP firmware using USB bulk transfers adapted to the NXP LPC-Link2 debug unit.
.\\Firmware\\Examples\\MCU-LINK       | CMSIS-DAP firmware using USB bulk transfers adapted to the NXP MCU-LINK debug unit.

The CMSIS-DAP firmware is designed to execute on a debug unit that is using a Cortex-M processor-based microcontroller. To
deploy the firmware to a new debug unit copy an existing firmware adaptation to a new folder. For example, copy the folder
.\\Firmware\\Examples\\MCU-LINK to a folder called .\\Firmware\\MyDebugUnit.

To following steps describe the adaptation of the CMSIS-DAP firmware to a new debug unit:
1. \ref DAP_ConfigMCU_gr :  Select the microcontroller and replace the CMSIS-Core (Cortex-M) files.
2. \ref DAP_ConfigIO_gr : Adapt the I/O ports and specify other parameters for the debug unit.
3. \ref DAP_ConfigUSB_gr : Adapt the USB peripheral to the microcontroller.
4. \ref DAP_USART_SWO_gr : Optionally, you may add a CMSIS-Driver USART to interface to SWO.
5. \ref DAP_USART_COM_gr : Optionally, you may add a CMSIS-Driver USART to interface to UART communication port.
6. \ref DAP_Vendor_gr : Optionally, you may add vendor specific commands to the debug unit.
7. \ref DAP_ConfigFlash_gr : Program the adapted firmware to the Flash ROM of the new debug unit.
8. \ref DAP_Validate_gr : Validate the CMSIS-DAP firmware of the new debug unit.
@}
**************************************************************************************************/

/**
\defgroup DAP_ConfigMCU_gr Debug Unit Processor
\ingroup DAP_Config_gr
@{
CMSIS-DAP firmware runs on debug units with a Cortex-M microcontroller.

The CMSIS-DAP firmware is designed to execute on a debug unit that is using a Cortex-M processor-based microcontroller.

The following steps describe how to change the microcontroller in the CMSIS-DAP firmware project:

1. In the µVision IDE, open the project file <b>.\\Firmware\\MyDebugUnit\\CMSIS_DAP.uvprojx</b>.
2. Open the <b>Project - Options - Device</b> dialog and select the microcontroller of the new debug unit.
4. Optionally, you may modify the project file <b>Target</b> name and the file <b>Abstract.txt</b> to reflect the new debug unit.

\image html "MDK_Device.png" "Select the microcontroller"

In MDK, changing the microcontroller adds relevant software components for the new target. However, depending on the
availability you may need to replace some components with custom implementations.

\image html "RTE.png" "Replace missing software components"


@}
**************************************************************************************************/

/**
\defgroup DAP_ConfigIO_gr Configure I/O ports and debug unit
\ingroup DAP_Config_gr
@{
DAP_config.h configures I/O ports and debug unit hardware parameters.

The CMSIS-DAP firmware configuration file \b DAP_config.h provides the interface functions and configuration
parameters for the hardware of the CMSIS-DAP debug unit.
@}
**************************************************************************************************/

/**
\defgroup DAP_ConfigUSB_gr Configure USB peripheral
\ingroup DAP_Config_gr
@{
CMSIS-DAP firmware communicates via USB with the host computer. The USB communication is implemented via MDK-Middleware
components that access the USB peripheral of the microcontroller.

The CMSIS-DAP v2 firmware uses \ref BulkUSB "USB bulk endpoints" that provide high-speed communication. In addition,
\ref USB_CDC is used to enable USB COM port.

For the USB interface it is important to provide correct configuration information for the USB peripheral as described in this section.

The following steps describe how to change and configure the USB peripheral in the CMSIS-DAP firmware project:

1. In the <b>Project Window</b>, the group <b>USB</b> contains USB interface with the relevant configuration files.
2. Open the file <b>usb_config_0.c</b> in the editor and select <b>Configuration Wizard</b> as edit mode; then change the following settings:
  - <b>USB Device 0 - High-speed</b>: enable this option only for a high-speed USB peripheral; disable for full-speed USB.
  - Update <b>Device Settings - Vendor ID</b> which is provided by the <a href="http://www.usb.org/developers/vendor/" target="_blank">USB Implementers Forum</a>.
  - Update <b>Device Settings - Product ID</b> to provide a unique identification for the debug unit.
  - Update <b>Device Settings - Device Release Number</b> to indicate the revision of the adaptation.
  - Update <b>String Settings - Manufacturer String</b> to reflect the vendor of the debug unit. This setting should match the <b>Vendor ID</b>.
  - Update <b>String Settings - Product String</b> to indicate the debug unit. Note that "CMSIS-DAP" must be part of that string to allow identification by debuggers (or part of interface string for USB composite device).
  - Optionally each debug unit may provide a unique <b>Serial Number String</b>. If the <b>String Settings - Serial Number String</b> is not provided, only one debug unit can be connected at the same time to a host computer since it is impossible to identify multiple debug units.

  
\note 
  - The USB Device setting high-speed / full-speed USB must be reflected in the \b DAP_config.h file as described under \ref DAP_Config_gr.
  - The <b>String Settings - Product String</b> must contain "CMSIS-DAP" somewhere in the string. This is used by the debuggers to identify a CMSIS-DAP compliant debug unit that is connected to a host computer.

<br>
\image html "MDK_USB.png" "Adapt the USB Peripheral to the microcontroller"

\page BulkUSB Communication via USB bulk endpoints

CMSIS-DAP v2 uses USB bulk endpoints and is therefore faster than the deprecated v1. Optionally, support for streaming SWO
trace is provided via an additional USB endpoint.

This configuration requires custom class support with the interface setting:
- Class Code: 0xFF (Vendor specific)
- Subclass: 0x00
- Protocol code: 0x00

\note This interface enables also <a href="https://wicg.github.io/webusb/" target="_blank">WebUSB</a> technology that is used in web browsers to connect to a debug adapter connected to your PC.

Depending on the configuration, it uses the following USB endpoints which should be configured in the interface descriptor in this order:
  - Endpoint 1: Bulk Out – used for commands received from host PC.
  - Endpoint 2: Bulk In – used for responses send to host PC.
  - Endpoint 3: Bulk In (optional) – used for streaming SWO trace (if enabled with \ref SWO_STREAM).

\image html "MDK_USB_Custom.png" "Configuration settings for the USB custom class"

\note These settings allow support in Windows (8 and above), Mac OS, and Linux without further drivers. Some additional
settings are required to automatically install CMSIS-DAP enabled debug adapters in these operating systems.


<b>Additional settings for Microsoft Windows</b>
<br><br>
For automatic installation of a CMSIS-DAP v2 enabled debug adapter in Windows, use the following WinUSB GUID in the USB
custom class:
\code
{CDB3B5AD-293B-4663-AA36-1AAE46463776}
\endcode

The picture below shows the WinUSB GIUD configuration of the USB custom class:

\image html "MDK_USB_Custom_WinUSBGIUD.png" "Adapt CMSIS-DAP to the WinUSB class"

\anchor wininf
<b>USB Driver and *.inf file</b>
<br><br>
Windows 8 and above does not require a WinUSB driver provided that the USB firmware stack supports Microsoft descriptors. 
CMSIS-DAP v2 device should be configured as WCID (Windows Compatible ID) device which provides extra information to a Windows system
to facilitate automated driver installation. 
<br><br>
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.
<br><br>
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 and sign it to generate .cat files. More information is available from Microsoft under the topic  
<a href="https://technet.microsoft.com/en-us/library/dd919238(v=ws.10).aspx" target="_blank">Steps for Signing a Device Driver Package</a>.
<br>

The following CMSIS_DAP_v2.inf file should be provided for an Windows 7 host PC.

\verbinclude Firmware/Template/CMSIS_DAP_v2.inf

\page USB_CDC Communication Device Class

CMSIS-DAP v2 supports also a UART communication port optionally routed to a USB COM port which is implemented by a USB
Communication Device Class (CDC) device. 
<br><br>

The picture below shows the configuration of the USB CDC class.
<br>

\image html "MDK_USB_CDC.png" "Configuration of USB CDC class"

@}
**************************************************************************************************/

/**
\defgroup DAP_ConfigFlash_gr Flash program the firmware
\ingroup DAP_Config_gr
@{
The CMSIS-DAP firmware is programmed into the Flash ROM of a debug unit.

Once the CMSIS-DAP firmware is configured, it needs to be programmed into the Flash ROM of the new debug unit. MDK provides
Flash algorithms for many Cortex-M based microcontrollers and therefore you may use the Flash programming facilities that


are provide in µVision. Once Flash programming is configured, you may use the µVision menu item <b>Flash - Download</b>.

\image html "MDK_Flash.png" "Download CMSIS-DAP firmware to new debug unit using MDK"
@}
**************************************************************************************************/
/**
\defgroup DAP_USART_SWO_gr Connect SWO trace
@{
\brief Optionally, you may add a CMSIS-Driver USART to interface to SWO.
\details
A CMSIS-Driver USART can be used to capture the trace output on the SWO pin using a UART RX input on the
microcontroller. UART Serial Wire Output (SWO) trace can be enabled and configured in the header DAP_Config.h.
\#define SWO_UART is used to enable the UART SWO and \#define SWO_UART_DRIVER
is used to configure USART Driver instance number (Driver_USART#).
<br><br>
Refer to \ref DAP_Config_Debug_gr for more information.
@}
**************************************************************************************************/
/**
\defgroup DAP_USART_COM_gr Connect UART communication port
@{
\brief Optionally, you may add a CMSIS-Driver USART to interface to UART communication port.
\details
A CMSIS-Driver USART can be used to receive data from the target and transmit data to the target using
UART RX and TX pins on the microcontroller. The UART communication port can be enabled and configured in the header
DAP_Config.h. \#define DAP_UART is used to enable the UART communication port and \#define DAP_UART_DRIVER
is used to configure USART Driver instance number (Driver_USART#).
<br><br>
Refer to \ref DAP_Config_Debug_gr for more information.
@}
**************************************************************************************************/

/**
\defgroup DAP_Validate_gr Validate the debug unit operation
@{
A CMSIS-DAP conforming debug unit must be validated.

A validation project for Arm Keil MDK is provided in the folder <b>.\\Firmware\\Validation\\MDK5</b>.
The <b>Validation.uvprojx</b> project contains a simple application that needs to be adapted to the target hardware
connected to the debug unit. Once the adaptation is complete, you may open a Command window and
call the batch file <b>test.bat</b> (optionally with the path to the µVision executable):

\image html "MDK_Validation.png" "Validate debug unit using target hardware and Arm Keil MDK"

The batch file will create a \c test_results.txt and \c test.log file in the project directory.
@}
**************************************************************************************************/

/**
\defgroup DAP_Commands_gr CMSIS-DAP Commands
**************************************************************************************************/

/**
\defgroup DAP_Vendor_gr CMSIS-DAP Vendor Commands
@{
Extend CMSIS-DAP firmware with commands.

The CMSIS-DAP firmware may be extended with commands that are specific to a debug unit.
Vendor Commands may implement additional functionality such as interfaces to serial printf-style communication.
The RDDI-DAP interface offers the function \c CMSIS_DAP_Commands to exchange information with vendor-specific commands.
@}
**************************************************************************************************/