blob: 743cb05a25d06a149dfb60789543a7204a7795af [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>Debug access sequences</title>
<title>CMSIS-Pack: Debug access sequences</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="cmsis.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="printComponentTabs.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 46px;">
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-Pack
&#160;<span id="projectnumber">Version 1.4.9</span>
</div>
<div id="projectbrief">Delivery Mechanism for Software Packs</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<div id="CMSISnav" class="tabs1">
<ul class="tablist">
<script type="text/javascript">
<!--
writeComponentTabs.call(this);
//-->
</script>
</ul>
</div>
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li class="current"><a href="pages.html"><span>Usage&#160;and&#160;Description</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('pdsc_SequenceNameEnum_pg.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Debug access sequences </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Debug access sequences define the activities of development tools to connect to a device using the debug channel for debugging, tracing, or flash programming. Several debug access sequences are pre-defined and executed in specific context. Refer to <a class="el" href="pdsc_family_pg.html#element_sequences">sequences</a> for details.</p>
<p>Software development tools should implement <a class="el" href="pdsc_SequenceNameEnum_pg.html#default_sequences">Default debug access sequences</a>. These default sequences can be overwritten by device specific sequences using the <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> element in the <a class="el" href="pdsc_family_pg.html#element_sequences">sequences</a> section of the PDSC file. Additionally, a PDSC file can contain user-defined sequences, for example to reuse access sequence fragments:</p>
<ul>
<li><a class="el" href="pdsc_SequenceNameEnum_pg.html#usage_of_sequences">Usage of debug access sequences</a> explains how the sequences are used from a development tool point of view.</li>
<li><a class="el" href="pdsc_SequenceNameEnum_pg.html#default_sequences">Default debug access sequences</a> lists all debug access sequences that are pre-defined by the CMSIS-Pack standard and shows the details of the default debug access sequences.</li>
<li><a class="el" href="pdsc_SequenceNameEnum_pg.html#writing_sequences">Writing debug access sequences</a> explains how to write custom debug access sequences. These can be used to either override default sequences or to define device specific sequences.</li>
</ul>
<h1><a class="anchor" id="usage_of_sequences"></a>
Usage of debug access sequences</h1>
<p>Pre-defined Debug Access Sequences are used in the following context:</p>
<ul>
<li><b>Connect Debugger to Device</b> is executed when debugging or flash programming with the target starts.</li>
<li><b>Reset Device</b> is executed to reset the target.</li>
<li><b>Verify Code</b> is executed to verify the content after flash programming.</li>
<li><b>Disconnect Debugger</b> is executed when debugging or flash programming with the target stops.</li>
</ul>
<p>The following diagrams show how the Debug Access Sequences are executed by a development tool.</p>
<p><b>Connect Debugger to Device</b> is executed when debugging or flash programming with the target starts.</p>
<div class="image">
<img src="DebugConnect.png" alt="DebugConnect.png"/>
</div>
<p><b>Reset Device</b> is executed to reset the target.</p>
<div class="image">
<img src="Reset.png" alt="Reset.png"/>
</div>
<p><b>Verify Code</b> is executed to verify the content after flash programming.</p>
<div class="image">
<img src="CodeVerify.png" alt="CodeVerify.png"/>
</div>
<p><b>Disconnect Debugger</b> is executed when debugging or flash programming with the target stops.</p>
<div class="image">
<img src="DebugDisconnect.png" alt="DebugDisconnect.png"/>
</div>
<h1><a class="anchor" id="default_sequences"></a>
Default debug access sequences</h1>
<p>Debug access sequences get defined in the <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> element. The following table lists the available pre-defined debug access sequences. <a class="el" href="pdsc_SequenceNameEnum_pg.html#default_sequences">Default debug access sequences</a> are executed if they are not overwritten using a <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> element. Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#usage_of_sequences">Usage of debug access sequences</a> for more information about the execution of these sequences.</p>
<p>For debug access sequences marked in <span class="XML-Token">ItalicRed</span>, no default sequence exists. The usage in a debug description requires a related <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> element to be present. The other sequences should be implemented in a development tool. They are executed when no sequence definition exists in the PDSC file.</p>
<dl class="section note"><dt>Note</dt><dd>Default debug access sequences read the System Control Space (SCS) of the processor and assume that the SCS offset is implemented as defined in the ARMv6-M/ARMv7-M/ARMv8-M architecture reference manual.</dd></dl>
<table class="cmtable" summary="Enumeration: SequenceNameEnum">
<tr>
<th>name= </th><th>Description </th></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortSetup">DebugPortSetup</a> </td><td>Prepare the target debug port for connection; is executed before acquiring access to the debug port.<br/>
May include for example an SWJ-DP switch sequence as defined in the ARM Debug Interface (ADI) Architecture Specification.<br/>
<b>This sequence must not contain debug port/access port register and target memory accesses other than:</b><ul>
<li><b>Reading the <em>DPIDR</em> debug port register to release an SWD connection from its line reset.</b></li>
<li><b>Writing the <em>TARGETSEL</em> debug port register (SWD protocol v2).</b> </li>
</ul>
</td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortStart">DebugPortStart</a> </td><td>Connect to the target debug port and power it up; is executed after DebugPortSetup.<br/>
The parent <b>debugport</b> is default debug port for this sequence.<br/>
<b>This sequence must not contain access port register and target memory accesses.</b> </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortStop">DebugPortStop</a> </td><td>Power down and disconnect from target debug port.<br/>
Executed as last step during target disconnect unless another debugger connection to this port is active. The parent <b>debugport</b> is default debug port for this sequence.<br/>
<b>This sequence must not contain access port register and target memory accesses.</b> </td></tr>
<tr>
<td class="XML-Token">DebugDeviceUnlock </td><td>Check if the device is in a locked state and unlock it. Use <b>query</b> command elements for user confirmation.<br/>
Executed after having powered up the debug port. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#debugCoreStart">DebugCoreStart</a> </td><td>Initialize core debug system.<br/>
Executed after having connected and powered up the default debug port for the connection. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#debugCoreStop">DebugCoreStop</a> </td><td>Uninitialize core debug system.<br/>
Executed as last step during disconnect before powering down any debug ports no longer required for concurrent connections. </td></tr>
<tr>
<td class="XML-Token">DebugCodeMemRemap </td><td>Remap memory to execution location.<br/>
Executed before verifying memory content after flash programming. This is required to replicate a memory remap of a device bootloader (that is not executed during debug connection). </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetSystem">ResetSystem</a> </td><td>Execute a system-wide reset via software mechanisms. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetProcessor">ResetProcessor</a> </td><td>Execute a processor reset via software mechanisms. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetHardware">ResetHardware</a> </td><td>Execute a system-wide reset via the dedicated debugger reset line, e.g. nRST. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetHardwareAssert">ResetHardwareAssert</a> </td><td>Assert a system-wide reset via the dedicated debugger reset line, e.g. nRST. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetHardwareDeassert">ResetHardwareDeassert</a> </td><td>Deassert a system-wide reset via the dedicated debugger reset line, e.g. nRST. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetCatchSet">ResetCatchSet</a> </td><td>Executed before a target reset to configure the vector catch to stop code execution after the reset.<br/>
The implementation of <b>ResetCatchSet</b> requires an implementation of <b>ResetCatchClear</b> to free any hardware resources used for stopping the core. </td></tr>
<tr>
<td class="XML-Token"><a class="el" href="pdsc_SequenceNameEnum_pg.html#resetCatchClear">ResetCatchClear</a> </td><td>Executed after a target reset to free hardware resources allocated by <b>ResetCatchSet</b>. </td></tr>
<tr>
<td class="XML-Token">FlashEraseDone </td><td>Executed after erasing flash memory. </td></tr>
<tr>
<td class="XML-Token">FlashProgramDone </td><td>Eexecuted after programming flash memory. </td></tr>
<tr>
<td class="XML-Token">TraceStart </td><td>Enable target trace capture.<br/>
Executed before the debugger powers up and configures standard CoreSight trace components, e.g. after the initial target connection as well as after a system-wide reset. </td></tr>
<tr>
<td class="XML-Token">TraceStop </td><td>Disable target trace capture.<br/>
Executed after the debugger disabled and powered down standard CoreSight trace components. </td></tr>
<tr>
<td class="XML-Token">RecoverySupportStart </td><td>Executed before step or run command to support recovery from a lost target connection, e.g. after a low power mode. </td></tr>
<tr>
<td class="XML-Token">RecoverySupportStop </td><td>Executed after step or run command in context of the <b>RecoverySupportStart</b> sequence. </td></tr>
<tr>
<td class="XML-Token">RecoveryAcknowledge </td><td>Debugger acknowledge after recovering from a lost target connection. Can be executed independently from a <b>RecoverySupportStart</b> sequence. </td></tr>
</table>
<h2>Pre-defined default debug access sequences </h2>
<p>The following sections the show the details of the pre-defined default debug access sequences.</p>
<h2><a class="anchor" id="debugPortSetup"></a>
DebugPortSetup</h2>
<p>Prepare the target debug port for connection.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;DebugPortSetup&quot;</span>&gt;</div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> __var isSWJ = ((__protocol &amp;amp; 0x00010000) != 0);</div>
<div class="line"> __var protType = __protocol &amp;amp; 0x0000FFFF;</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line"> &lt;!-- JTAG Protocol --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;protType == 1&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;isSWJ&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block atomic=<span class="stringliteral">&quot;1&quot;</span>&gt;</div>
<div class="line"> <span class="comment">// Ensure current debug interface is in reset state</span></div>
<div class="line"> DAP_SWJ_Sequence(51, 0x0007FFFFFFFFFFFF);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Execute SWJ-DP Switch Sequence SWD to JTAG (0xE73C)</span></div>
<div class="line"> <span class="comment">// Change if SWJ-DP uses deprecated switch code (0xAEAE)</span></div>
<div class="line"> DAP_SWJ_Sequence(16, 0xE73C);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Ensure JTAG interface is reset</span></div>
<div class="line"> DAP_SWJ_Sequence(6, 0x3F);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block atomic=<span class="stringliteral">&quot;1&quot;</span>&gt;</div>
<div class="line"> <span class="comment">// JTAG &quot;Soft&quot; Reset</span></div>
<div class="line"> DAP_JTAG_Sequence(6, 1, 0x3F);</div>
<div class="line"> DAP_JTAG_Sequence(1, 0, 0x01);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- SWD Protocol --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;protType == 2&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;isSWJ&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block atomic=<span class="stringliteral">&quot;1&quot;</span>&gt;</div>
<div class="line"> <span class="comment">// Ensure current debug interface is in reset state</span></div>
<div class="line"> DAP_SWJ_Sequence(51, 0x0007FFFFFFFFFFFF);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Execute SWJ-DP Switch Sequence JTAG to SWD (0xE79E)</span></div>
<div class="line"> <span class="comment">// Change if SWJ-DP uses deprecated switch code (0xEDB6)</span></div>
<div class="line"> DAP_SWJ_Sequence(16, 0xE79E);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Enter SWD Line Reset State</span></div>
<div class="line"> DAP_SWJ_Sequence(51, 0x0007FFFFFFFFFFFF); <span class="comment">// &amp;gt; 50 cycles SWDIO/TMS High</span></div>
<div class="line"> DAP_SWJ_Sequence(3, 0x00); <span class="comment">// At least 2 idle cycles (SWDIO/TMS Low)</span></div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;!isSWJ&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block atomic=<span class="stringliteral">&quot;1&quot;</span>&gt;</div>
<div class="line"> <span class="comment">// Enter SWD Line Reset State</span></div>
<div class="line"> DAP_SWJ_Sequence(51, 0x0007FFFFFFFFFFFF); <span class="comment">// &amp;gt; 50 cycles SWDIO/TMS High</span></div>
<div class="line"> DAP_SWJ_Sequence(3, 0x00); <span class="comment">// At least 2 idle cycles (SWDIO/TMS Low)</span></div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// Read DPIDR to enable SWD interface (SW-DPv1 and SW-DPv2)</span></div>
<div class="line"> ReadDP(0x0);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="debugPortStart"></a>
DebugPortStart</h2>
<p>Connect to the target debug port and power it up.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;DebugPortStart&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> __var SW_DP_ABORT = 0x0;</div>
<div class="line"> __var DP_CTRL_STAT = 0x4;</div>
<div class="line"> __var DP_SELECT = 0x8;</div>
<div class="line"> __var powered_down = 0;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Switch to DP Register Bank 0</span></div>
<div class="line"> WriteDP(DP_SELECT, 0x00000000);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Read DP CTRL/STAT Register and check if CSYSPWRUPACK and CDBGPWRUPACK bits are set</span></div>
<div class="line"> powered_down = ((ReadDP(DP_CTRL_STAT) &amp;amp; 0xA0000000) != 0xA0000000);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;powered_down&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// Request Debug/System Power-Up</span></div>
<div class="line"> WriteDP(DP_CTRL_STAT, 0x50000000);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Wait <span class="keywordflow">for</span> Power-Up Request to be acknowledged --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;(ReadDP(DP_CTRL_STAT) &amp;amp; 0xA0000000) != 0xA0000000&quot;</span> timeout=<span class="stringliteral">&quot;1000000&quot;</span>/&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// Request Debug Reset</span></div>
<div class="line"> WriteDP(DP_CTRL_STAT, 0x54000000);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Wait <span class="keywordflow">for</span> Debug Reset to be acknowledged, don<span class="stringliteral">&#39;t issue error on timeout to deal with improperly connected Debug Reset --&gt;</span></div>
<div class="line"><span class="stringliteral"> &lt;control while=&quot;(ReadDP(DP_CTRL_STAT) &amp;amp; 0xA8000000) != 0xA8000000&quot; timeout=&quot;300000&quot;/&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> &lt;!-- JTAG Specific Part of sequence --&gt;</span></div>
<div class="line"><span class="stringliteral"> &lt;control if=&quot;__protocol == 1&quot;&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> &lt;block&gt;</span></div>
<div class="line"><span class="stringliteral"> // Init AP Transfer Mode, Transaction Counter, and Lane Mask (Normal Transfer Mode, Include all Byte Lanes)</span></div>
<div class="line"><span class="stringliteral"> // Additionally clear STICKYORUN, STICKYCMP, and STICKYERR bits by writing &#39;</span>1<span class="stringliteral">&#39;</span></div>
<div class="line"><span class="stringliteral"> WriteDP(DP_CTRL_STAT, 0x50000F32);</span></div>
<div class="line"><span class="stringliteral"> &lt;/block&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> &lt;/control&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> &lt;!-- SWD Specific Part of sequence --&gt;</span></div>
<div class="line"><span class="stringliteral"> &lt;control if=&quot;__protocol == 2&quot;&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> &lt;block&gt;</span></div>
<div class="line"><span class="stringliteral"> // Init AP Transfer Mode, Transaction Counter, and Lane Mask (Normal Transfer Mode, Include all Byte Lanes)</span></div>
<div class="line"><span class="stringliteral"> WriteDP(DP_CTRL_STAT, 0x50000F00);</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> // Clear WDATAERR, STICKYORUN, STICKYCMP, and STICKYERR bits of CTRL/STAT Register by write to ABORT register</span></div>
<div class="line"><span class="stringliteral"> WriteDP(SW_DP_ABORT, 0x0000001E);</span></div>
<div class="line"><span class="stringliteral"> &lt;/block&gt;</span></div>
<div class="line"><span class="stringliteral"></span></div>
<div class="line"><span class="stringliteral"> &lt;/control&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral"> &lt;/control&gt;</span></div>
<div class="line"><span class="stringliteral"> </span></div>
<div class="line"><span class="stringliteral">&lt;/sequence&gt;</span></div>
</div><!-- fragment --><h2><a class="anchor" id="debugPortStop"></a>
DebugPortStop</h2>
<p>Power down and disconnect from target debug port.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;DebugPortStop&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> __var DP_CTRL_STAT = 0x4;</div>
<div class="line"> __var DP_SELECT = 0x8;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Switch to DP Register Bank 0</span></div>
<div class="line"> WriteDP(DP_SELECT, 0x00000000);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Power Down Debug port</span></div>
<div class="line"> WriteDP(DP_CTRL_STAT, 0x00000000);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="debugCoreStart"></a>
DebugCoreStart</h2>
<p>Initialize core debug system.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;DebugCoreStart&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// System Control Space (SCS) offset as defined in ARMv6-M/ARMv7-M.</span></div>
<div class="line"> </div>
<div class="line"> __var SCS_Addr = 0xE000E000;</div>
<div class="line"> __var DHCSR_Addr = SCS_Addr + 0xDF0;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Enable Core Debug via DHCSR</span></div>
<div class="line"> Write32(DHCSR_Addr, 0xA05F0001);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="debugCoreStop"></a>
DebugCoreStop</h2>
<p>Un-initialize core debug system.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;DebugCoreStop&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// System Control Space (SCS) offset as defined in ARMv6-M/ARMv7-M.</span></div>
<div class="line"> </div>
<div class="line"> __var SCS_Addr = 0xE000E000;</div>
<div class="line"> __var DHCSR_Addr = SCS_Addr + 0xDF0;</div>
<div class="line"> __var DEMCR_Addr = SCS_Addr + 0xDFC;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Disable Core Debug via DHCSR</span></div>
<div class="line"> Write32(DHCSR_Addr, 0xA05F0000);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Disable DWT and ITM blocks, DebugMonitor handler,</span></div>
<div class="line"> <span class="comment">// halting debug traps, and Reset Vector Catch.</span></div>
<div class="line"> Write32(DEMCR_Addr, 0x00000000);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetSystem"></a>
ResetSystem</h2>
<p>Execute a system-wide reset via software mechanisms.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetSystem&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// System Control Space (SCS) offset as defined in ARMv6-M/ARMv7-M.</span></div>
<div class="line"></div>
<div class="line"> __var SCS_Addr = 0xE000E000;</div>
<div class="line"> __var AIRCR_Addr = SCS_Addr + 0xD0C;</div>
<div class="line"> __var DHCSR_Addr = SCS_Addr + 0xDF0;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Execute SYSRESETREQ via AIRCR</span></div>
<div class="line"> Write32(AIRCR_Addr, 0x05FA0004);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line"> &lt;!-- Reset Recovery: Wait <span class="keywordflow">for</span> DHCSR.S_RESET_ST bit to clear on read --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;(Read32(DHCSR_Addr) &amp;amp; 0x02000000) == 0&quot;</span> timeout=<span class="stringliteral">&quot;500000&quot;</span>/&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetProcessor"></a>
ResetProcessor</h2>
<p>Execute a processor reset via software mechanisms.</p>
<dl class="section note"><dt>Note</dt><dd>This Default Debug Access Sequence is empty for ARMv6-M based processors.</dd></dl>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetProcessor&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// System Control Space (SCS) offset as defined in ARMv7-M.</span></div>
<div class="line"></div>
<div class="line"> __var SCS_Addr = 0xE000E000;</div>
<div class="line"> __var AIRCR_Addr = SCS_Addr + 0xD0C;</div>
<div class="line"> __var DHCSR_Addr = SCS_Addr + 0xDF0;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Execute VECTRESET via AIRCR</span></div>
<div class="line"> Write32(AIRCR_Addr, 0x05FA0001);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Reset Recovery: Wait <span class="keywordflow">for</span> DHCSR.S_RESET_ST bit to clear on read --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;(Read32(DHCSR_Addr) &amp;amp; 0x02000000) == 0&quot;</span> timeout=<span class="stringliteral">&quot;500000&quot;</span>/&gt;</div>
<div class="line"></div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetHardware"></a>
ResetHardware</h2>
<p>Execute a system-wide reset via the dedicated debugger reset line nRST.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetHardware&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> __var nReset = 0x80;</div>
<div class="line"> __var canReadPins = 0;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Deassert nRESET line</span></div>
<div class="line"> canReadPins = (DAP_SWJ_Pins(0x00, nReset, 0) != 0xFFFFFFFF);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Keep reset active <span class="keywordflow">for</span> 50 ms --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;1&quot;</span> timeout=<span class="stringliteral">&quot;50000&quot;</span>/&gt;</div>
<div class="line"></div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;canReadPins&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Assert nRESET line and wait max. 1s <span class="keywordflow">for</span> recovery --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;(DAP_SWJ_Pins(nReset, nReset, 0) &amp;amp; nReset) == 0&quot;</span> timeout=<span class="stringliteral">&quot;1000000&quot;</span>/&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;!canReadPins&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// Assert nRESET line</span></div>
<div class="line"> DAP_SWJ_Pins(nReset, nReset, 0);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Wait 100ms <span class="keywordflow">for</span> recovery <span class="keywordflow">if</span> nRESET not readable --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">while</span>=<span class="stringliteral">&quot;1&quot;</span> timeout=<span class="stringliteral">&quot;100000&quot;</span>/&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetHardwareAssert"></a>
ResetHardwareAssert</h2>
<p>Assert a system-wide reset line nRST.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetHardwareAssert&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> __var nReset = 0x80;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Deassert nRESET line to activate the hardware reset</span></div>
<div class="line"> DAP_SWJ_Pins(0, nReset, 0);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetHardwareDeassert"></a>
ResetHardwareDeassert</h2>
<p>De-Assert a system-wide reset line nRST.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetHardwareDeassert&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> __var nReset = 0x80;</div>
<div class="line"> __var canReadPins = 0;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Assert nRESET line and check if nRESET is readable</span></div>
<div class="line"> canReadPins = (DAP_SWJ_Pins(nReset, nReset, 0) != 0xFFFFFFFF);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line"> &lt;!-- Wait max. 1s <span class="keywordflow">for</span> nRESET to recover from reset <span class="keywordflow">if</span> readable--&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;canReadPins&quot;</span> <span class="keywordflow">while</span>=<span class="stringliteral">&quot;(DAP_SWJ_Pins(nReset, nReset, 0) &amp;amp; nReset) == 0&quot;</span> timeout=<span class="stringliteral">&quot;1000000&quot;</span>/&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;!-- Wait 100ms <span class="keywordflow">for</span> recovery <span class="keywordflow">if</span> nRESET not readable --&gt;</div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;!canReadPins&quot;</span> <span class="keywordflow">while</span>=<span class="stringliteral">&quot;1&quot;</span> timeout=<span class="stringliteral">&quot;100000&quot;</span>/&gt;</div>
<div class="line"></div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetCatchSet"></a>
ResetCatchSet</h2>
<p>Configure the target to stop code execution after a reset.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetCatchSet&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// System Control Space (SCS) offset as defined</span></div>
<div class="line"> <span class="comment">// in ARMv6-M/ARMv7-M. Reimplement this sequence</span></div>
<div class="line"> <span class="comment">// if the SCS is located at a different offset.</span></div>
<div class="line"></div>
<div class="line"> __var SCS_Addr = 0xE000E000;</div>
<div class="line"> __var DHCSR_Addr = SCS_Addr + 0xDF0;</div>
<div class="line"> __var DEMCR_Addr = SCS_Addr + 0xDFC;</div>
<div class="line"> __var value = 0;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Enable Reset Vector Catch in DEMCR</span></div>
<div class="line"> value = Read32(DEMCR_Addr);</div>
<div class="line"> Write32(DEMCR_Addr, (value | 0x00000001));</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Read DHCSR to clear potentially set DHCSR.S_RESET_ST bit</span></div>
<div class="line"> Read32(DHCSR_Addr);</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"></div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h2><a class="anchor" id="resetCatchClear"></a>
ResetCatchClear</h2>
<p>Free hardware resources allocated by ResetCatchSet.</p>
<div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;ResetCatchClear&quot;</span>&gt;</div>
<div class="line"></div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// System Control Space (SCS) offset as defined</span></div>
<div class="line"> <span class="comment">// in ARMv6-M/ARMv7-M. Reimplement this sequence</span></div>
<div class="line"> <span class="comment">// if the SCS is located at a different offset.</span></div>
<div class="line"> </div>
<div class="line"> __var SCS_Addr = 0xE000E000;</div>
<div class="line"> __var DEMCR_Addr = SCS_Addr + 0xDFC;</div>
<div class="line"> __var value = 0;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Disable Reset Vector Catch in DEMCR</span></div>
<div class="line"> value = Read32(DEMCR_Addr);</div>
<div class="line"> Write32(DEMCR_Addr, (value &amp;amp; (~0x00000001)));</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --><h1><a class="anchor" id="writing_sequences"></a>
Writing debug access sequences</h1>
<p>To override a default sequence or to create a custom (default) sequence, you need to write <a class="el" href="pdsc_family_pg.html#element_sequence">sequence</a> elements. The following sections show how to use the built-in debug access syntax, expressions, and debug access functions to create custom sequences.</p>
<h2><a class="anchor" id="DebugSyntaxRules"></a>
Debug access syntax rules</h2>
<p>Debug accesses are described in <b>block</b> elements of a debug access sequence (<b>sequence</b> element). The following syntax is used for this purpose:</p>
<ul>
<li>The contents of a <b>block</b> element is a series of statements.</li>
<li>Each statement must begin in a new line and is terminated by a <span class="XML-Token">;</span> character.</li>
<li>A typical statement consists of variable, followed by a <span class="XML-Token">=</span> character and an expression, where the <span class="XML-Token">=</span> character is an assignment of the <a class="el" href="pdsc_SequenceNameEnum_pg.html#ExpressionType">expression</a> result to the variable: <div class="fragment"><div class="line">variable = expression;</div>
</div><!-- fragment --></li>
<li>Alternatively, a statement can be a sole <a class="el" href="pdsc_SequenceNameEnum_pg.html#ExpressionType">expression</a> without storing its result to a variable. <div class="fragment"><div class="line">expression;</div>
</div><!-- fragment --></li>
<li>Comments begin with two slashes (<span class="XML-Token">//</span>) and end with a linebreak: <div class="fragment"><div class="line"><span class="comment">// Whole line is a comment</span></div>
<div class="line">variable = expression; <span class="comment">// Comment appended to statement</span></div>
</div><!-- fragment --></li>
<li>Variables must be defined using the keyword <span class="XML-Token">__var</span>. The definition must include an initalization of the variable: <div class="fragment"><div class="line">__var variable = 0;</div>
</div><!-- fragment --></li>
<li>Variables can be defined only once within a scope. Scopes beging with entering a debug access sequence or a <b>control</b> element. They are extended to child <b>control</b> elements. Variables of a parent scope can be modified. Leaving a scope destroys all variables defined in it.<br/>
<b><em>block</em> elements do not begin a new scope.</b> <div class="fragment"><div class="line">&lt;sequence name=<span class="stringliteral">&quot;MySequence&quot;</span>&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block info=<span class="stringliteral">&quot;Block 1&quot;</span>&gt;</div>
<div class="line"> __var condvar = 1;</div>
<div class="line"> __var myvar1 = 5;</div>
<div class="line"> __var myvar2 = 0;</div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;control <span class="keywordflow">if</span>=<span class="stringliteral">&quot;condvar&quot;</span>&gt;</div>
<div class="line"> &lt;block&gt;</div>
<div class="line"> <span class="comment">// __var myvar1 = 2; // Redefinition, not allowed!</span></div>
<div class="line"> __var myvar3 = 2;</div>
<div class="line"> myvar2 = myvar1 + myvar3; <span class="comment">// Assign value (5+2) = 7</span></div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> &lt;/control&gt;</div>
<div class="line"> </div>
<div class="line"> &lt;block info=<span class="stringliteral">&quot;Block 2&quot;</span>&gt;</div>
<div class="line"> myvar1 = myvar2 + 1; <span class="comment">// Variable myvar1 holds the value &#39;8&#39; after this statement</span></div>
<div class="line"> <span class="comment">// myvar2 = myvar3; // myvar3 does not exist in this scope, not allowed!</span></div>
<div class="line"> &lt;/block&gt;</div>
<div class="line"> </div>
<div class="line">&lt;/sequence&gt;</div>
</div><!-- fragment --></li>
<li>The debug access variables <b>__dp</b>, <b>__ap</b>, and <b>__errorcontrol</b> can be modified within a debug access sequence. An assigned value is held until leaving the sequence. Calling another sequence by the <b>Sequence</b> debug access function will push their values on a sequence execution stack. The values are restored when returning from such a call.</li>
</ul>
<h2><a class="anchor" id="ExpressionType"></a>
Expression rules</h2>
<p>Expressions are used in various places to describe one of the following:</p>
<ul>
<li>A value as assigned in a <a class="el" href="pdsc_SequenceNameEnum_pg.html#DebugSyntaxRules">debug access statement</a>.</li>
<li>A condition to use in the <b>if</b> attribute of a <b>control</b> element.</li>
<li>A condition to use in the <b>while</b> attribute of a <b>control</b> element.</li>
<li>A parameter to a debug access function as described below.</li>
</ul>
<p>An expression may consist of the following:</p>
<ul>
<li>Constant numbers in decimal and hexadecimal representation (prefix <span class="XML-Token">0x</span>).</li>
<li>Arithmetic operators such as <span class="XML-Token">+</span>, <span class="XML-Token">-</span>, <span class="XML-Token">*</span>, <span class="XML-Token">/</span>, and <span class="XML-Token">%</span>.</li>
<li>Bit-arithmetic operators such as <span class="XML-Token">&amp;</span>, <span class="XML-Token">|</span>, <span class="XML-Token">~</span>, <span class="XML-Token">^</span>, <span class="XML-Token">&gt;&gt;</span>, and <span class="XML-Token">&lt;&lt;</span>.</li>
<li>Comparison-operators such as <span class="XML-Token">==</span>, <span class="XML-Token">!=</span>, <span class="XML-Token">&lt;</span>, <span class="XML-Token">&gt;</span>, <span class="XML-Token">&lt;=</span>, and <span class="XML-Token">&gt;=</span>.</li>
<li>Logic operators such as <span class="XML-Token">!</span>, <span class="XML-Token">&amp;&amp;</span>, <span class="XML-Token">||</span>, and <span class="XML-Token">==</span>.</li>
<li>Conditional expression operations like:<div class="fragment"><div class="line">(x &lt; y) ? a : b </div>
</div><!-- fragment --></li>
<li>Precedence of sub-expressions is indicated by brackets (<span class="XML-Token">(</span>, <span class="XML-Token">)</span>). C-like precedence applies if brackets are omitted.</li>
<li>References to <a class="el" href="pdsc_family_pg.html#DebugVars">debug access variables</a> for evaluating debug settings.</li>
<li>Calls to <a class="el" href="pdsc_SequenceNameEnum_pg.html#DebugFunctions">debug access functions</a>.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd><ul>
<li>All values used in expressions resolve to 64-bit unsigned integer values.</li>
<li>All logic-operations and comparisons resolve to the value <span class="XML-Token">1</span> if true, to <span class="XML-Token">0</span> otherwise.</li>
<li>XML prohibits the use of the characters <span class="XML-Token">&amp;</span>, <span class="XML-Token">&lt;</span>, and <span class="XML-Token">&gt;</span>. Use the corresponding XML entity names instead: <span class="XML-Token">&amp;amp;</span>, <span class="XML-Token">&amp;lt;</span>, and <span class="XML-Token">&amp;gt;</span>.</li>
</ul>
</dd></dl>
<p>&#160;</p>
<h2><a class="anchor" id="DebugFunctions"></a>
Debug access functions</h2>
<p>Debug access functions can be called in expressions in order to interact with the target device and the user. Parameters to functions can again be expressions.<br/>
By default, a debugger must abort the execution of a debug access sequence if a function call fails. However, this behavior can be controlled from a sequence by the <b>__errorcontrol</b> <a class="el" href="pdsc_family_pg.html#DebugVars">debug access variable</a>.<br/>
<br/>
The following table describes the existing debug access functions, their parameters and the debug access variables which are evaluated for the function call.</p>
<table class="cmtable" summary="ExpressionType: debug access functions">
<tr>
<th>Function </th><th>Description </th></tr>
<tr>
<td style="white-space: nowrap"><pre>Sequence("name")</pre> </td><td><p class="starttd">Execute a debug access sequence. Calling a sequence by this function causes the modifiable debug access variables <b>__dp</b>, <b>__ap</b>, and <b>__errorcontrol</b> to be pushed on a sequence execution stack. Returning from such a call will restore the state of these variables.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>name: Name of the sequence to execute. It must be enclosed by quotes.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Read8(addr)</pre> </td><td><p class="starttd">Read an 8-bit value from target memory. <b>A device must support native 8-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to read from.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
The 8-bit value as read from target memory. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Read16(addr)</pre> </td><td><p class="starttd">Read an 16-bit value from target memory. <b>A device must support native 16-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to read from.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
The 16-bit value as read from target memory. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Read32(addr)</pre> </td><td><p class="starttd">Read an 32-bit value from target memory. <b>A device must support native 32-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to read from.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p><b>Return Value:</b><br/>
The 32-bit value as read from target memory.</p>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#resetSystem">ResetSystem</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Read64(addr)</pre> </td><td><p class="starttd">Read an 64-bit value from target memory. <b>A device must support native 64-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to read from.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
The 64-bit value as read from target memory. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>ReadAP(addr)</pre> </td><td><p class="starttd">Read a 32-bit value from an access port register.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: AP register address to read from. Addresses larger than <span class="XML-Token">0xF</span> automatically cause an AP register bank switch.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
The 32-bit value as read from the AP register. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>ReadDP(addr)</pre> </td><td><p class="starttd">Read a 32-bit value from a debug port register.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: DP register address to read from.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
</ul>
<p><b>Return Value:</b><br/>
The 32-bit value as read from the DP register.</p>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortSetup">DebugPortSetup</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Write8(addr, val)</pre> </td><td><p class="starttd">Write an 8-bit value to target memory. <b>A device must support native 8-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to write to.</li>
<li>val: Value to write.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Write16(addr, val)</pre> </td><td><p class="starttd">Write a 16-bit value to target memory. <b>A device must support native 16-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to write to.</li>
<li>val: Value to write.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Write32(addr, val)</pre> </td><td><p class="starttd">Write a 32-bit value to target memory. <b>A device must support native 32-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to write to.</li>
<li>val: Value to write.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>.</p>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#debugCoreStart">DebugCoreStart</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Write64(addr, val)</pre> </td><td><p class="starttd">Write a 64-bit value to target memory. <b>A device must support native 64-bit memory accesses for this function to succeed.</b><br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to write to.</li>
<li>val: Value to write.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>WriteAP(addr, val)</pre> </td><td><p class="starttd">Write a 32-bit value to an access port register. Addresses larger than 0xF automatically cause an AP register bank switch.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to write to.</li>
<li>val: Value to write.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
<li>__ap: The access port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>WriteDP(addr, val)</pre> </td><td><p class="starttd">Write a 32-bit value to a debug port register.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>addr: Memory address to write to.</li>
<li>val: Value to write.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
</ul>
<p><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>.</p>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortStart">DebugPortStart</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>DAP_Delay(delay)</pre> </td><td><p class="starttd">Debug probe command to wait for a specific delay.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>delay: Wait time in microseconds.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>DAP_WriteABORT(value)</pre> </td><td><p class="starttd">Debug probe command to write an abort request to the CoreSight ABORT register of the target debug port.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>value: 32-bit value to write into the CoreSight ABORT register.</li>
</ul>
<p><b>Debug Access Variables:</b><br/>
</p>
<ul>
<li>__dp: The debug port to use for this memory access.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>DAP_SWJ_Pins(pinout, pinselect, pinwait)</pre> </td><td><p class="starttd">Debug proble command to monitor and control the I/O Pins including the nRESET device reset line.<br/>
<b>I/O Pin Mapping</b> for <b>pinout</b>, <b>pinselect</b>, and <b>pinwait</b>:</p>
<ul>
<li>Bit 0: SWCLK/TCK</li>
<li>Bit 1: SWDIO/TMS</li>
<li>Bit 2: TDI</li>
<li>Bit 3: TDO</li>
<li>Bit 5: nTRST</li>
<li>Bit 7: nRESET</li>
</ul>
<p><br/>
The <b>pinwait</b> time is useful in systems where the nRESET pin is implemented as open-drain output. After nRESET is de-asserted by the debugger, external circuit may still hold the target Device under reset for a time. Using the <b>pinwait</b> time, the debugger may monitor selected I/O Pins and wait until they the expected value appears or a timeout expires.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>pinout: Value for selected output pins.</li>
<li>pinselect: Selects which output pins will be modified.</li>
<li>pinwait: Wait timeout for the selected output to stabilize. A debugger must extend this timeout to the closest possible time granularity.<ul>
<li>0 = no wait</li>
<li>1 .. 3000000 = time in microseconds (max 3s)</li>
</ul>
</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
The state of the I/O Pins at the end of this operation. If a debugger is not capable of monitoring the I/O Pins, it must return a value of <span class="XML-Token">0xFFFFFFFF</span>. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>DAP_SWJ_Clock(val)</pre> </td><td><p class="starttd">Debug probe command to set the clock frequency for JTAG and SWD communication mode.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>val: Maximum SWD/JTAG Clock (SWCLK/TCK) value in Hz.</li>
</ul>
<p><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>.</p>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#resetHardware">ResetHardware</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>DAP_SWJ_Sequence(cnt, val)</pre> </td><td><p class="starttd">Debug probe command to generate required SWJ sequences, e.g. for SWD/JTAG Reset, SWD&lt;-&gt;JTAG switch and Dormant operation.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>cnt: Number of bits in sequence: 1..64. Larger sequences need to be implemented by multiple subsequent <b>DAP_SWJ_Sequence</b> calls. Such a sequence of <b>DAP_SWJ_Sequence</b> commands must be encapsulated in an atomic <b>block</b> to ensure correct execution.</li>
<li>val: Sequence generated on SWDIO/TMS (with clock @SWCLK/TCK), LSB transmitted first.</li>
</ul>
<p><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>.</p>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortSetup">DebugPortSetup</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>DAP_JTAG_Sequence(cnt, tms, tdi)</pre> </td><td><p class="starttd">Debug probe command to generate a JTAG sequence with fixed TMS value and capture TDO.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>cnt: Length of the JTAG sequence (number of TCK cycles and TDI bits): 1..64</li>
<li>tms: Fixed TMS value: 0..1</li>
<li>tdi: Data generated on TDI with one bit per TCK cycle, LSB transmitted first.</li>
</ul>
<p class="endtd"><b>Return Value:</b><br/>
Data captured from TDO with one bit per TCK cycle, LSB captured first and padded with <span class="XML-Token">0</span>s. </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Query(type, "message", default)</pre> </td><td><p class="starttd">Query user input. The sequence execution stalls depending on the used <b>type</b>. If the debugger runs in a batch mode, this function returns the value <b>default</b>.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>type: Query type. Can be one of:<ul>
<li><span class="XML-Token">0</span> : <b>Query_Ok</b>, displays an informative message which has to be confirmed by the user. This type allows the result <b>OK</b>.</li>
<li><span class="XML-Token">1</span> : <b>Query_YesNo</b>, displays a query with the allowed results <b>Yes</b> and <b>No</b>.</li>
<li><span class="XML-Token">2</span> : <b>Query_YesNoCancel</b>, displays a query with the allowed results <b>Yes</b>, <b>No</b>, and <b>Cancel</b>.</li>
<li><span class="XML-Token">3</span> : <b>Query_OkCancel</b>, displays a query with the allowed results <b>OK</b> and <b>Cancel</b>.</li>
</ul>
</li>
<li>message: A constant string with the query message to display. It must not be an expression and it must be enclosed by quotes.</li>
<li>default: The default value to return if the debugger runs in batch mode. See <b>Return Values</b> for a list of allowed values.</li>
</ul>
<p><b>Return Value:</b><br/>
The result of the query. The user input maps to the following numbers:</p>
<ul>
<li>Error : <span class="XML-Token">0</span></li>
<li>OK : <span class="XML-Token">1</span></li>
<li>Cancel : <span class="XML-Token">2</span></li>
<li>Yes : <span class="XML-Token">3</span></li>
<li>No : <span class="XML-Token">4</span></li>
</ul>
<p class="endtd"><b>Code Example:</b><br/>
Refer to <a class="el" href="pdsc_SequenceNameEnum_pg.html#debugPortSetup">DebugPortSetup</a> </p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>QueryValue("message", default)</pre> </td><td><p class="starttd">Query input value from user. The sequence execution stalls until the user has entered a value or canceled the query. This function returns the <b>default</b> value if the user canceled the query or if the debugger runs in a batch mode.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>message: A constant string with the query message to display. It must not be an expression and it must be enclosed by quotes.</li>
<li>default: The default value to return if the user cancels the query or if the debugger runs in batch mode.</li>
</ul>
<p><b>Return Value:</b><br/>
The queried value.</p>
<p class="endtd"></p>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>Message(type, "format", ...)</pre> </td><td><p class="starttd">Outputs a message to a log window.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>type: Message type. Can be one of:<ul>
<li><span class="XML-Token">0</span> : <b>Info</b>, outputs an informative message.</li>
<li><span class="XML-Token">1</span> : <b>Warning</b>, outputs a warning.</li>
<li><span class="XML-Token">2</span> : <b>Error</b>, outputs an error. Sequence execution aborts.</li>
</ul>
</li>
<li>format: A constant string with the message format. It must not be an expression and it must be enclosed by quotes. The string has the following format:<br/>
<div class="fragment"><div class="line">%[flags][width][.precision]specifier</div>
</div><!-- fragment --><ul>
<li>Specifiers:<ul>
<li><span class="XML-Token">%u</span>: 32-bit unsigned decimal integer.</li>
<li><span class="XML-Token">%llu</span>: 64-bit unsigned decimal integer.</li>
<li><span class="XML-Token">%x</span>: 32-bit unsigned hexadecimal integer, lower case letters.</li>
<li><span class="XML-Token">%llx</span>: 64-bit unsigned hexadecimal integer, lower case letters.</li>
<li><span class="XML-Token">%X</span>: 32-bit unsigned hexadecimal integer, upper case letters.</li>
<li><span class="XML-Token">%llX</span>: 64-bit unsigned hexadecimal integer, upper case letters.</li>
<li><span class="XML-Token">%o</span>: 32-bit unsigned octal integer.</li>
<li><span class="XML-Token">%llo</span>: 64-bit unsigned octal integer.</li>
<li><span class="XML-Token">%b</span>: 32-bit unsigned binary integer.</li>
<li><span class="XML-Token">%llb</span>: 64-bit unsigned binary integer.</li>
<li><span class="XML-Token">%f</span>: Single-precision (32-bit) floating point value.</li>
<li><span class="XML-Token">%Lf</span>: Double-precision (64-bit) floating point value.</li>
<li><span class="XML-Token">%s</span>: Constant character string. Must not be an expression.</li>
<li><span class="XML-Token">%%</span>: Print <span class="XML-Token">%</span> character.</li>
</ul>
</li>
<li>Flags:<ul>
<li><span class="XML-Token">0</span>: Pad the displayed value with zeros instead of spaces if padding is required by the <span class="XML-Token">width</span> option.</li>
</ul>
</li>
<li>Width: Minimum number of displayed characters. If <span class="XML-Token">width</span> is less than the number of characters of the value, then the value is padded with spaces to the left.</li>
<li>.Precision:<ul>
<li><b>Integer</b>: Minimum number of displayed digits. Padded with zeros to the left if the value has less digits than specified with <span class="XML-Token">.precision</span>.</li>
<li><b>Floating Point</b>: Number of displayed digits after decimal point. Defaults to <span class="XML-Token">6</span> if not specified.</li>
<li><b>Constant String</b>: Maximum number of displayed characters.</li>
</ul>
</li>
</ul>
</li>
<li>... : Additional function parameters to replace format string specifiers. Each parameter can be a constant string, or an expression that resolves to an unsigned 64-bit integer. A parameter type must match the corresponding specifier type.</li>
</ul>
<p><b>Return Value:</b><br/>
Always returns <span class="XML-Token">0</span>.</p>
<dl class="section note"><dt>Note</dt><dd>For 32-bit specifiers the <b>Message</b> command must print the lower 32 Bit of a 64 Bit debug access variable.</dd></dl>
</td></tr>
<tr>
<td style="white-space: nowrap"><pre>LoadDebugInfo("file")</pre> </td><td><p class="starttd">Loads DWARF debug information from an application executable.<br/>
<br/>
<b>Parameters:</b><br/>
</p>
<ul>
<li>file: A constant string with the path to the executable. The path must be relative to the root folder of the pack and use the format <b>path/name.extension</b>. It must not be an expression and it must be enclosed by quotes.</li>
</ul>
<p><b>Return Value:</b><br/>
Returns <span class="XML-Token">0</span> after successful debug information load.<br/>
Returns <span class="XML-Token">1</span> if debug information load failed.</p>
<p class="endtd"></p>
</td></tr>
</table>
<dl class="section note"><dt>Note</dt><dd><ul>
<li>Target memory access functions must perform a debug access of the size indicated by their name. The target system must support debug accesses of this size.</li>
<li>Results of all functions are casted to 64-bit unsigned integer values.</li>
<li>Some target access functions determine the used debug and access port by the current values of the <b>__dp</b> and <b>__ap</b> debug access variables. If a target access requires a different debug or access port than the default ones, it must change these values. This change is held until finishing the sequence the change has occurred in. </li>
</ul>
</dd></dl>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="coresight_setup.html">Simplifying debug setup using debug descriptions</a></li>
<li class="footer">Generated on Wed Feb 8 2017 10:21:01 for CMSIS-Pack by ARM Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
-->
</li>
</ul>
</div>
</body>
</html>