Skip to content

Commit

Permalink
Doc: Minor changes after review feedback.
Browse files Browse the repository at this point in the history
  • Loading branch information
vovamarch committed Oct 25, 2023
1 parent 4010486 commit 0cde134
Show file tree
Hide file tree
Showing 8 changed files with 193 additions and 24 deletions.
2 changes: 1 addition & 1 deletion Documentation/Doxygen/Doxygen_Templates/extra_navtree.css
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@
display:block;
position: absolute;
left: 0px;
width: 350px;
width: 340px;
}

.ui-resizable .ui-resizable-handle {
Expand Down
10 changes: 10 additions & 0 deletions Documentation/Doxygen/Doxygen_Templates/extra_stylesheet.css
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,7 @@ body, table, div, p, dl {
margin-bottom:0px;
padding-inline: 5px;
padding-bottom: 3px;
cursor: pointer;
}
.tile h2 {
Expand Down Expand Up @@ -1231,6 +1232,15 @@ address {
color: #293C63;
}
blockquote.doxtable {
margin-left:-7px;
margin-bottom: 6px;
padding-left: 3px;
border-left:4px solid;
border-color: #D0C000;
background-color: var(--page-background-color);
}
table.doxtable {
border-collapse:collapse;
margin-top: 4px;
Expand Down
155 changes: 155 additions & 0 deletions Documentation/Doxygen/Doxygen_Templates/resize.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
/*
@licstart The following is the entire license notice for the JavaScript code in this file.
The MIT License (MIT)
Copyright (C) 1997-2020 by Dimitri van Heesch
Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@licend The above is the entire license notice for the JavaScript code in this file
*/
var once=1;
function initResizable()
{
var cookie_namespace = 'doxygen';
var sidenav,navtree,content,header,barWidth=6,desktop_vp=768,titleHeight;

function readSetting(cookie)
{
if (window.chrome) {
var val = localStorage.getItem(cookie_namespace+'_width');
if (val) return val;
} else {
var myCookie = cookie_namespace+"_"+cookie+"=";
if (document.cookie) {
var index = document.cookie.indexOf(myCookie);
if (index != -1) {
var valStart = index + myCookie.length;
var valEnd = document.cookie.indexOf(";", valStart);
if (valEnd == -1) {
valEnd = document.cookie.length;
}
var val = document.cookie.substring(valStart, valEnd);
return val;
}
}
}
return 0;
}

function writeSetting(cookie, val)
{
if (window.chrome) {
localStorage.setItem(cookie_namespace+"_width",val);
} else {
var date = new Date();
date.setTime(date.getTime()+(10*365*24*60*60*1000)); // default expiration is one week
expiration = date.toGMTString();
document.cookie = cookie_namespace + "_" + cookie + "=" + val + "; SameSite=Lax; expires=" + expiration+"; path=/";
}
}

function resizeWidth()
{
var windowWidth = $(window).width() + "px";
var sidenavWidth = $(sidenav).outerWidth();
content.css({marginLeft:parseInt(sidenavWidth)+"px"});
if (typeof page_layout!=='undefined' && page_layout==1) {
footer.css({marginLeft:parseInt(sidenavWidth)+"px"});
}
writeSetting('width',sidenavWidth-barWidth);
}

function restoreWidth(navWidth)
{
var windowWidth = $(window).width() + "px";
content.css({marginLeft:parseInt(navWidth)+barWidth+"px"});
if (typeof page_layout!=='undefined' && page_layout==1) {
footer.css({marginLeft:parseInt(navWidth)+barWidth+"px"});
}
sidenav.css({width:navWidth + "px"});
}

function resizeHeight()
{
var headerHeight = header.outerHeight();
var footerHeight = footer.outerHeight();
var windowHeight = $(window).height();
var contentHeight,navtreeHeight,sideNavHeight;
if (typeof page_layout==='undefined' || page_layout==0) { /* DISABLE_INDEX=NO */
contentHeight = windowHeight - headerHeight - footerHeight;
navtreeHeight = contentHeight;
sideNavHeight = contentHeight;
} else if (page_layout==1) { /* DISABLE_INDEX=YES */
contentHeight = windowHeight - footerHeight;
navtreeHeight = windowHeight - headerHeight;
sideNavHeight = windowHeight;
}
content.css({height:contentHeight + "px"});
navtree.css({height:navtreeHeight + "px"});
sidenav.css({height:sideNavHeight + "px"});
if (location.hash.slice(1)) {
(document.getElementById(location.hash.slice(1))||document.body).scrollIntoView();
}
}

function collapseExpand()
{
var newWidth;
if (sidenav.width()>0) {
newWidth=0;
}
else {
var width = readSetting('width');
newWidth = (width>250 && width<$(window).width()) ? width : 250;
}
restoreWidth(newWidth);
var sidenavWidth = $(sidenav).outerWidth();
writeSetting('width',sidenavWidth-barWidth);
}

header = $("#top");
sidenav = $("#side-nav");
content = $("#doc-content");
navtree = $("#nav-tree");
footer = $("#nav-path");
$(".side-nav-resizable").resizable({resize: function(e, ui) { resizeWidth(); } });
$(sidenav).resizable({ minWidth: 0 });
$(window).resize(function() { resizeHeight(); });
var device = navigator.userAgent.toLowerCase();
var touch_device = device.match(/(iphone|ipod|ipad|android)/);
if (touch_device) { /* wider split bar for touch only devices */
$(sidenav).css({ paddingRight:'20px' });
$('.ui-resizable-e').css({ width:'20px' });
$('#nav-sync').css({ right:'34px' });
barWidth=20;
}
var width = readSetting('width');
if (width) { restoreWidth(width); } else { resizeWidth(); }
resizeHeight();
var url = location.href;
var i=url.indexOf("#");
if (i>=0) window.location.hash=url.substr(i);
var _preventDefault = function(evt) { evt.preventDefault(); };
$("#splitbar").bind("dragstart", _preventDefault).bind("selectstart", _preventDefault);
if (once) {
$(".ui-resizable-handle").dblclick(collapseExpand);
once=0
}
$(window).on('load',resizeHeight);
}
/* @license-end */
1 change: 1 addition & 0 deletions Documentation/Doxygen/gen_doc.sh
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ echo "\"${UTILITY_DOXYGEN}\" dap.dxy"
mkdir -p "${DIRNAME}/../html/search/"
cp -f "${DIRNAME}/Doxygen_Templates/search.css" "${DIRNAME}/../html/search/"
cp -f "${DIRNAME}/Doxygen_Templates/navtree.js" "${DIRNAME}/../html/"
cp -f "${DIRNAME}/Doxygen_Templates/resize.js" "${DIRNAME}/../html/"

sed -e "s/{datetime}/${datetime}/" "${DIRNAME}/Doxygen_Templates/footer.js.in" \
| sed -e "s/{year}/${year}/" \
Expand Down
19 changes: 10 additions & 9 deletions Documentation/Doxygen/src/Ref_dap.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,14 @@
/**************************************************************************************************/
/**************************************************************************************************/
/**
\defgroup DAP_ConfigIO_gr CMSIS-DAP Firmware Configuration

\ref dap_firmware gives an overview about CMSIS-DAP operation and guides through the steps for enabling the CMSIS-DAP firmware on a custom debug unit.

The configuration file \c DAP_config.h contains the interface functions and configuration parameters that need to be adapted in this process. The subsections in this group list and explain these configurations and functions in details.

*/

/**
\defgroup DAP_Commands_gr CMSIS-DAP Commands

Expand Down Expand Up @@ -1668,12 +1678,3 @@ Receive and Transmit data via target UART (only for transport via DAP).
- <b>Receive data</b>: Bytes received from the target device via UART.

*/
/**************************************************************************************************/
/**
\defgroup DAP_ConfigIO_gr CMSIS-DAP Firmware Configuration

\ref dap_firmware gives an overview about CMSIS-DAP operation and guides through the steps for enabling the CMSIS-DAP firmware on a custom debug unit.

The configuration file \c DAP_config.h contains the interface functions and configuration parameters that need to be adapted in this process. The subsections in this group list and explain these configurations and functions in details.

*/
12 changes: 7 additions & 5 deletions Documentation/Doxygen/src/dap_firmware.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,9 @@ The following steps describe how to change and configure the USB peripheral in t
- Update **String Settings - Product String** 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 **Serial Number String**. If the **String Settings - Serial Number String** 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 `DAP_config.h` file.
- The **String Settings - Product String** 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.
> **Note**
> - The USB Device setting high-speed / full-speed USB must be reflected in the `DAP_config.h` file.
> - The **String Settings - Product String** 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.
![Adapt the USB Peripheral to the microcontroller](./images/MDK_USB.png)

Expand All @@ -141,7 +141,8 @@ This configuration requires custom class support with the interface setting:
- Subclass: `0x00`
- Protocol code: `0x00`

\note This interface enables also [WebUSB](https://wicg.github.io/webusb/) technology that is used in web browsers to connect to a debug adapter connected to your PC.
> **Note**
> - This interface enables also [WebUSB](https://wicg.github.io/webusb/) 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.
Expand All @@ -150,7 +151,8 @@ Depending on the configuration, it uses the following USB endpoints which should

![Configuration settings for the USB custom class](./images/MDK_USB_Custom.png)

\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.
> **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.
**Additional settings for Microsoft Windows**

Expand Down
2 changes: 1 addition & 1 deletion Documentation/Doxygen/src/history.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ The table below provides information about the changes delivered with specific v
</tr>
<tr>
<td>V0.02</td>
<td>Renamed \b DAP_LED to \ref DAP_HostStatus.</td>
<td>Renamed **DAP_LED** to \ref DAP_HostStatus.</td>
</tr>
<tr>
<td>V0.01</td>
Expand Down
16 changes: 8 additions & 8 deletions Documentation/Doxygen/src/mainpage.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,24 @@
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.

**CMSIS-DAP** is a protocol specification and a firmware implementation that enables standardized communication between two sides:
- An Arm Cortex-based processor where an embedded application is executed, on one side,
- and a software debug tool that runs on a host computer, on the other side.
- 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:

![CMSIS-DAP Interface](./images/CMSIS_DAP_INTERFACE.png)

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). 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.
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.

The \ref dap_firmware provides a template implementation of the CMSIS-DAP concept as well as several example projects for popular debug units.

Debug probes can be validated for compliance to CMSIS-DAP using the scripts explained in \ref dap_validate.

\note
- CMSIS-DAP v1.x is \a deprecated and is not recommended for new designs.
- Use \ref dap_firmware "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_drv_install for more information.
> **Note**
> - CMSIS-DAP v1.x is \a deprecated and is not recommended for new designs.
> - Use \ref dap_firmware "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_drv_install for more information.
## Features and Benefits {#dap_benefits}

Expand Down Expand Up @@ -48,7 +48,7 @@ Directory | Description
📄 LICENSE | License Agreement (Apache 2.0)
📄 README.md | Repository description

For an overview of other CMSIS software components, tools and specifications see [CMSIS Documentation](https://arm-software.github.io/CMSIS_6/).
See [CMSIS Documentation](https://arm-software.github.io/CMSIS_6/) for an overview of CMSIS software components, tools and specifications.

## Supported Tools and Probes {#dap_ecosystem}

Expand All @@ -58,7 +58,7 @@ CMSIS-DAP has a well-established support in popular embedded software developmen
- [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/)
- [PlatfromIO](https://platformio.org/)
- [PlatformIO](https://platformio.org/)
- [PyOCD](https://pyocd.io/)
- [OpenOCD](https://openocd.org/)

Expand Down

0 comments on commit 0cde134

Please sign in to comment.