Initial commit

external/CMSIS_5/CMSIS/DoxyGen/DAP/src/dap.txt

@@ -0,0 +1,171 @@
+/*=======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>
+*/

external/CMSIS_5/CMSIS/DoxyGen/DAP/src/dap_config.txt

@@ -0,0 +1,270 @@
+/**************************************************************************************************/
+/**
+\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.
+@}
+**************************************************************************************************/
+
+