CMSIS-DAP: Update documentation (UART communication)

CMSIS/DoxyGen/DAP/dap.dxy

@@ -38,7 +38,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.0-alpha-spec"
+PROJECT_NUMBER         = "Version 2.1.0"
 
 # 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 viewer a

CMSIS/DoxyGen/DAP/src/dap.txt

@@ -30,6 +30,7 @@ Benefits of CMSIS-DAP
  - USB using HID (Human Interface Device) driver class that avoids driver installation on host PC.
  - Supports time-critical JTAG or SWD command execution (new in CMSIS-DAP Version 1.10). 
  - Supports Test Domain Timer for time measurement using the debug unit (new in CMSIS-DAP Version 1.2.0)
+ - 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
 ==================
@@ -40,8 +41,14 @@ Refer to \ref DAP_Config_gr for more information.
 The CMSIS-DAP Software Stack is composed of the following components:
 
   - CMSIS-DAP Firmware that interfaces to JTAG or SWD Debug 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.
-  - USB Communication Stack that interfaces to the USB Port of the Host Computer using the HID or custom class.
+  - CMSIS-Driver USART that connects:
+    - UART of the Cortex-M device to the SWO output from the target,
+    - additional UART of the Cortex-M device to the UART from the target.
+    .
+  - USB Communication Stack that interfaces to the USB Port of the Host Computer using:
+    - HID or custom class,
+    - CDC ACM class to export USB COM Port.
+    .
   - The USB Device middleware may require CMSIS-RTOS and a CMSIS-Driver USB.
   
 \image html "CMSIS_DAP_SWStack.png" "CMSIS-DAP Software Stack"
@@ -74,6 +81,12 @@ CMSIS-DAP compliant Debug Units must be validated using the scripts provided in
       <th>Version</th>
       <th>Description</th>
     </tr>
+    <tr>
+      <td>V2.1.0</td>
+      <td>
+         Added: \ref DAP_uart_gr to support target communication via extra UART
+      </td>
+    </tr>
     <tr>
       <td>V2.0.0</td>
       <td>

CMSIS/DoxyGen/DAP/src/dap_USB_cmds.txt

@@ -180,14 +180,14 @@ The \ref DAP_atomic_gr are only available when \ref DAP_Info with ID=0xF0 (Capab
 
 /**************************************************************************************************/
 /** 
-\defgroup DAP_uart_gr UART Commands
+\defgroup DAP_uart_gr UART COM Commands
 \ingroup DAP_Commands_gr
 \brief Target communication via extra UART.
 
-CMSIS-DAP debug unit can be extended to support a separate UART ports that connects to the target. Such a UART communication
+CMSIS-DAP debug unit can be extended to support a separate UART port that connects to the target. Such a UART communication
 is typically used for printf-style debugging, but the usage is not limited to that.  CMSIS-DAP supports UART communication via:
-  - dedicated CMSIS-DAP commands: connects seamless to (Cloud) IDEs that integrate a printf viewer.
-  - via standard USB COM port: for any data communication, i.e. to transmit training data sets for machine learning.
+  - dedicated CMSIS-DAP commands: connects seamlessly to (Cloud) IDEs that integrate a printf viewer.
+  - via standard USB COM port (optional): for any data communication, i.e. to transmit training data sets for machine learning.
 
 The following CMSIS-DAP commands are added to support UART communication:
  - \ref DAP_UART_Transport : \copybrief DAP_UART_Transport
@@ -294,6 +294,11 @@ Time synchronisation via Test Domain Timer:
 SWO Streaming Trace support:
  - Info0 - Bit 6: <b>1 = SWO Streaming Trace</b> is implemented (0 = not implemented).
  
+UART Communication Port support:
+ - Info0 - Bit 7: <b>1 = UART Communication Port</b> is implemented (0 = not implemented).
+
+UART Communication via USB COM Port support:
+ - Info1 - Bit 0: <b>1 = USB COM Port</b> is implemented (0 = not implemented). 
  
 <hr>
  
@@ -1396,7 +1401,7 @@ Send \ref DAP_SWJ_Pins in fourth packet which executes queued commands and comma
 DAP_UART_Transport (0x1F):
 -------------------------
 
-Sets the UART transport mode for reading and sending data.
+Sets the UART transport mode for receiving and transmitting data.
 
 <b>DAP_UART_Transport Request:</b>
 \code
@@ -1409,9 +1414,9 @@ Sets the UART transport mode for reading and sending data.
   - 0 - Transport data via USB COM Port (default).
   - 1 - Transport data via DAP_UART_Transfer command.
 
-\note By default, data is transported via the USB COM port. In this case, the UART is 
-      controlled via a terminal (for example Putty), which can configure the 
-      UART (data bits, party, baudrate ...) and transfer data.
+\note By default, data is transported via the USB COM Port (if implemented). In this case, 
+      the UART is controlled via a terminal (for example Putty), which can configure the 
+      UART (data bits, party, baudrate ...) and transfer the data.
 
 \note When transport data via DAP_UART_Transfer command is enabled, CMSIS-DAP takes 
       control over the UART and automatically starts receiving data from the target.
@@ -1448,7 +1453,7 @@ Sets the UART configuration (only for transport via DAP_UART_Transfer command).
 
 - <b>Control</b>: Parameter values are compatible with CMSIS-Driver USART Interface in asynchronous mode and
   without flow control:
-  - Bit 2..0: Data bits: 5 = 5 Data bits, 6 = 6 Data bits, 7 = 7 Data bits, 0 = 8 Data bits (default), 1 = 9 Data bits
+  - Bit 2..0: Data bits: 5 = 5 Data bits, 6 = 6 Data bits, 7 = 7 Data bits, 0 = 8 Data bits (default)
   - Bit 3:    reserved (0)
   - Bit 5..4: Parity: 0 = None (default), 1 = Even, 2 = Odd
   - Bit 7..6: Stop bits: 0 = 1 Stop bit (default), 1 = 2 Stop bits
@@ -1479,12 +1484,12 @@ Sets the UART configuration (only for transport via DAP_UART_Transfer command).
 /** 
 \defgroup DAP_UART_Transfer DAP_UART_Transfer
 \ingroup DAP_uart_gr
-\brief Write (output) and Read (input) data via target UART interface.
+\brief Transfer data via UART.
 
 DAP_UART_Transfer (0x21):
 -------------------------
 
-Exchange data via the UART interface.
+Transmit (output) and Receive (input) data via target UART.
 
 <b>DAP_UART_Transfer Request:</b>
 
@@ -1494,11 +1499,11 @@ Exchange data via the UART interface.
  |******|*********|+++++++++++++++|
 \endcode
 
-- <b>Request</b>: Number of bytes to send to the target device via UART.
-  - Bit 9..0: Length: Number of bytes in <b>Transmit data</b>.
+- <b>Request</b>: Number of bytes to transmit to the target device via UART.
+  - Bit 9..0: Length: Number of bytes in <b>Transmit data</b> (Maximum Length = 509).
   - Bit 15..10: reserved (0)
   
-- <b>Transmit data</b>: Bytes to send to the target device via UART.
+- <b>Transmit data</b>: Bytes to transmit to the target device via UART.
 
 <b>DAP_UART_Transfer Response:</b>
 
@@ -1509,13 +1514,13 @@ Exchange data via the UART interface.
 \endcode
 
 - <b>Response</b>: Number of bytes received from the target device via UART and response status. 
-  - Bit 9..0: Length: Number of bytes in <b>Receive data</b>.
+  - Bit 9..0: Length: Number of bytes in <b>Receive data</b> (Maximum Length = 509).
   - Bit 10: reserved (0)
   - Bit 11: 1 = UART transmitter busy. Next transmit can be started when this bit is cleared.
-  - Bit 12: 1 = Data lost during transmit operation. Transmit was started when UART transmitter was busy. Automatically cleared on next successful transmit operation.
-  - Bit 13: 1 = Data lost during receive operation. Automatically cleared on next successful receive operation.
-  - Bit 14: 1 = Framing error detected during receive. Automatically cleared on next successful receive operation.
-  - Bit 15: 1 = Parity error detected during receive. Automatically cleared on next successful receive operation.
+  - Bit 12: 1 = Data lost detected during transmit. Transmit was started when UART transmitter was busy. Automatically cleared on read.
+  - Bit 13: 1 = Data lost detected during receive. Automatically cleared on read.
+  - Bit 14: 1 = Framing error detected. Automatically cleared on read.
+  - Bit 15: 1 = Parity error detected. Automatically cleared on read.
   
 - <b>Receive data</b>: Bytes received from the target device via UART.
 

CMSIS/DoxyGen/DAP/src/dap_config.txt

@@ -23,6 +23,7 @@ requirements:
   - 7 standard I/O pins for JTAG/SWD Device Interface.
   - optional 2 I/O pins for Status LEDs.
   - optional UART to support SWO capturing (Rx pin connected to SWO)
+  - optional UART to support UART Communication Port
   
 CMSIS-DAP Firmware
 ------------------
@@ -36,8 +37,8 @@ Various adaptations for different target hardware are provided.
 
 Folders and Files                       | Description
 --------------------------------------- | ----------------------------------------------------------------------------------------------------------------
-.\\Firmware\\Example\\V1\\LPC-Link-II   | CMSIS-DAP Firmware using USB HID adapted to the NXP LPC-Link-II Debug Unit that is part of the LPCxpresso-II platform.
-.\\Firmware\\Example\\V2\\LPC-Link-II   | CMSIS-DAP Firmware using WinUSB adapted to the NXP LPC-Link-II Debug Unit that is part of the LPCxpresso-II platform.
+.\\Firmware\\Examples\\LPC-Link-II\\V1  | CMSIS-DAP Firmware using USB HID adapted to the NXP LPC-Link-II Debug Unit that is part of the LPCxpresso-II platform.
+.\\Firmware\\Examples\\LPC-Link-II\\V2  | CMSIS-DAP Firmware using WinUSB adapted to the NXP LPC-Link-II Debug Unit that is part of the LPCxpresso-II platform.
 
 The CMSIS-DAP Firmware is designed to execute on a Debug Unit that is using a Cortex-M0, Cortex-M0+, Cortex-M3, or Cortex-M4 
 processor-based microcontroller. To deploy the firmware to a new Debug Unit copy an existing firmware adaptation to a new folder.
@@ -47,10 +48,11 @@ To following steps describe the adaptation of the CMSIS-DAP Firmware to a new De
 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_gr : Optional you may add a CMSIS-Driver USART to interface to SWO.
-5. \ref DAP_Vendor_gr : Optional you may add vendor specific commands to the Debug Unit.
-6. \ref DAP_ConfigFlash_gr : Program the adapted firmware to the Flash ROM of the new Debug Unit.
-7. \ref DAP_Validate_gr : Validate the CMSIS-DAP firmware of the new Debug Unit.
+4. \ref DAP_USART_SWO_gr : Optional you may add a CMSIS-Driver USART to interface to SWO.
+5. \ref DAP_USART_COM_gr : Optional you may add a CMSIS-Driver USART to interface to UART Communication Port.
+6. \ref DAP_Vendor_gr : Optional 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.
 @}
 **************************************************************************************************/
 
@@ -103,6 +105,8 @@ The CMSIS-DAP Firmware is able to communicate with the host computer using one o
   - \ref USBHID (Human Interface Device) does not require any USB driver installation.
   - \ref WinUSB provides higher speed communication but may require an *.inf file for USB installation. 
 
+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:
@@ -178,6 +182,16 @@ 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 UART Communication Port optionally routed to USB COM Port 
+which is implemented through USB Communication Device Class (CDC). 
+<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"
 
 @}
 **************************************************************************************************/
@@ -198,16 +212,28 @@ Once Flash programming is configured you may use the uVision menu item <b>Flash
 @}
 **************************************************************************************************/
 /**
-\defgroup DAP_USART_gr Connect SWO Trace
+\defgroup DAP_USART_SWO_gr Connect SWO Trace
 @{
 \brief Optional 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. To use a UART for SWO capturing, it is required to set the \#define SWO_UART to 1.
+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#).
+Refer to \ref DAP_Config_Debug_gr for more information.
+@}
+**************************************************************************************************/
+/**
+\defgroup DAP_USART_COM_gr Connect UART Communication Port
+@{
+\brief Optional 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. 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#).
 Refer to \ref DAP_Config_Debug_gr for more information.
 
-The actual USART Driver instance is defined in the source file <b>SWO.c</b> using the \#define USART_PORT.
-You may change this define with a compiler option.
 @}
 **************************************************************************************************/