<p>Using pyOCD’s Python API, you have extreme flexibility and precise control, and can do anything
SWD allows, at the expense of more complexity compared to <codeclass="highlighter-rouge">pyocd commander</code>. Using pyOCD like this is
particularly useful for situations where other debuggers become ineffective, such as device and
board bringup, or automated testing.</p>
<p>This document assumes familiarity with the Arm CoreSight debug architecture.</p>
<p>See the <ahref="/docs/api/architecture.html">architecture</a> documentation for an overview of the classes and how
they are connected.</p>
<h2id="connecting">Connecting</h2>
<p>pyOCD provides a handful of helper routines that make it very easy to enumerate and connect to
available debug probes. These routines are all available as static methods on the <codeclass="highlighter-rouge">ConnectHelper</code>
class in <codeclass="highlighter-rouge">pyocd.core.helpers</code>.</p>
<p><codeclass="highlighter-rouge">ConnectHelper.session_with_chosen_probe()</code> is the primary connection helper. This method returns
a single <codeclass="highlighter-rouge">Session</code> object, or None. If only a single probe is available, a new session for that
probe is returned immediately. But if there are multiple probes available, then by default, it will
present a simple console UI that lets the user select which probe they want to use. Other options
allow automatically picking the first available probe.</p>
<p>One of the most useful parameters for <codeclass="highlighter-rouge">session_with_chosen_probe()</code> is <codeclass="highlighter-rouge">unique_id</code>. Pass whole or
part of a probe’s unique ID (aka serial number) to programmatically select a specific probe.</p>
<p>Session options may be passed to <codeclass="highlighter-rouge">session_with_chosen_probe()</code> in two ways. The <codeclass="highlighter-rouge">options</code>
parameter accepts a dictionary of session options. Or, you may pass options as keyword parameters.
The two methods may be combined.</p>
<h2id="dp-access">DP access</h2>
<p>The DP is controlled through an instance of the <codeclass="highlighter-rouge">DebugPort</code> class (in <codeclass="highlighter-rouge">pyocd.coresight.dap</code>). You
get the <codeclass="highlighter-rouge">DebugPort</code> object via the ‘dp’ attribute of the target instance, i.e., <codeclass="highlighter-rouge">session.board.target.dp</code>.</p>
<p>The <codeclass="highlighter-rouge">DebugPort</code> class has <codeclass="highlighter-rouge">read_reg(addr)</code> and <codeclass="highlighter-rouge">write_reg(addr, data)</code> methods. ‘addr’ must be an
<p>For completeness, the DebugPort class also has <codeclass="highlighter-rouge">readDP(addr)</code>, <codeclass="highlighter-rouge">writeDP(addr, data)</code>, <codeclass="highlighter-rouge">readAP(addr)</code>, and
<codeclass="highlighter-rouge">writeAP(addr, data)</code> methods. They work as described below, except that the <codeclass="highlighter-rouge">readAP()</code> and <codeclass="highlighter-rouge">writeAP()</code> methods
require the APSEL in the address (i.e., 0x010000fc to read ID of APSEL=1). The AP will automatically be
selected.</p>
<h2id="ap-access">AP access</h2>
<p>CoreSight APs are represented with <codeclass="highlighter-rouge">AccessPort</code> classes defined in <codeclass="highlighter-rouge">pyocd.coresight.ap</code>. These include
the <codeclass="highlighter-rouge">MEM_AP</code> subclass and <codeclass="highlighter-rouge">AHB_AP</code> subclass of that.</p>
<p>To get the AP objects you can use the ‘aps’ attribute of the <codeclass="highlighter-rouge">DebugPort</code>. This attribute is a dict
with the keys being the APSEL number and values being AccessPort instances. For instance, use
<codeclass="highlighter-rouge">session.board.target.aps[1]</code> to get the AP with APSEL=1, assuming it exists (if not, you’ll get an
<p><codeclass="highlighter-rouge">AccessPort</code> also has <codeclass="highlighter-rouge">read_reg(addr)</code> and <codeclass="highlighter-rouge">write_reg(addr, data)</code> methods. For these methods, <codeclass="highlighter-rouge">addr</code> is
an integer of the register offset. Note that you do not need to include the APSEL in the address, and
you do not need to modify the DP’s SELECT register prior to accessing AP registers. The AP will
automatically be selected in the DP as required.</p>
<p>The <codeclass="highlighter-rouge">MEM_AP</code>/<codeclass="highlighter-rouge">AHB_AP</code> class has the memory access methods that are available on
the target, but the access is, of course, performed through that specific AP. This is particularly
useful for multicore devices or Cortex-A class devices.</p>
<p>Example showing access of the proprietary MDM-AP of NXP Kinetis MCUs:</p>
<p>To control reset, there are several options.</p>
<p><codeclass="highlighter-rouge">DebugPort</code> has methods for driving the hardware reset signal:</p>
<ul>
<li><codeclass="highlighter-rouge">DebugPort.reset()</code>, asks the debug probe to perform a hardware reset of the target.</li>
<li><codeclass="highlighter-rouge">DebugPort.assert_reset(asserted)</code> to directly control the nRESET signal. Pass True to drive
nRESET low, False to drive high.</li>
</ul>
<p>A wider range of reset options is provided by these <codeclass="highlighter-rouge">Target</code> methods:</p>
<ul>
<li><codeclass="highlighter-rouge">Target.reset(reset_type=None)</code>. Normally performs a software reset unless the optional parameter
is set to False.</li>
<li><codeclass="highlighter-rouge">Target.reset_and_halt(reset_type=None)</code> to perform a halting reset. Again, the reset defaults
to software but may be set to hardware.</li>
</ul>
<p>The <codeclass="highlighter-rouge">reset_type</code> parameter on the <codeclass="highlighter-rouge">Target</code> reset methods can be set to one of the <codeclass="highlighter-rouge">Target.ResetType</code>
enums:</p>
<ul>
<li><codeclass="highlighter-rouge">ResetType.DEFAULT</code>: Uses the core’s default reset method. For pack targets <codeclass="highlighter-rouge">defaultResetSequence</code> is used.
For internal targets, the default is mapped to <codeclass="highlighter-rouge">ResetType.SYSTEM</code>, unless <codeclass="highlighter-rouge">default_reset_type</code>
property is explicitly set.</li>
<li><codeclass="highlighter-rouge">ResetType.HARDWARE</code>: Execute <codeclass="highlighter-rouge">ResetHardware</code> debug sequence for pack targets, if the sequence doesn’t exist,
hardware reset using the nSRST signal is used. The same mapping applies for internal targets.</li>
<li><codeclass="highlighter-rouge">ResetType.SYSTEM</code>: Execute <codeclass="highlighter-rouge">ResetSystem</code> debug sequence for pack targets, if the sequence doesn’t exist,
software reset using SYSRESETREQ is used. The same mapping applies for internal targets.</li>
<li><codeclass="highlighter-rouge">ResetType.CORE</code>: Execute <codeclass="highlighter-rouge">ResetProcessor</code> debug sequence for pack targets, if the sequence doesn’t exist,
software reset using VECTRESET is used. The same mapping applies for internal targets.</li>
<li><codeclass="highlighter-rouge">ResetType.NSRST</code>: Hardware reset using the nSRST signal.</li>
<li><codeclass="highlighter-rouge">ResetType.SYSRESETREQ</code>: Software reset using SYSRESETREQ, which usually resets the entire system
on most MCUs.</li>
<li><codeclass="highlighter-rouge">ResetType.VECTRESET</code>: Software reset using VECTRESET, only available on v7-M targets. This
resets only the core itself. If requested on non-v7-M targets, it will fall back to <codeclass="highlighter-rouge">ResetType.EMULATED</code>.</li>
<li><codeclass="highlighter-rouge">ResetType.EMULATED</code>: Restores the core to reset conditions by writing registers. However, this
will not trigger a reset vector catch.</li>
</ul>
<p>The <codeclass="highlighter-rouge">CortexM</code> objects have a <codeclass="highlighter-rouge">default_reset_type</code> property that lets you control the overall default reset type.
Property value can be any one of the <codeclass="highlighter-rouge">ResetType</code> enums.</p>
<p>Another option for performing a halting reset is by setting vector catch with the target’s <codeclass="highlighter-rouge">set_vector_catch()</code>
method, then using a normal reset. This has the benefit of always halting at reset, if you leave the
vector catch enabled.</p>
<p>Example timed reset using the DP:</p>
<divclass="highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>import time
dp = session.board.target.dp
# Timed reset.
dp.assert_reset(True)
time.sleep(1.0)
dp.assert_reset(False)
</code></pre></div></div>
<h2id="notes">Notes</h2>
<p>You are encouraged to look through the code to see what additional functionality is available. The
most interesting places to look at are:</p>
<ul>
<li>pyocd.core.target: defines Target class, which is the main API.</li>
<li>pyocd.core.coresight_target: Represents the chip as a whole,
provides access to DP and APs, as well as each of the cores.</li>
<li>pyocd.coresight.cortex_m: CortexM class to control a core,
implements Target API and adds some stuff.</li>
<li>pyocd.flash.loader: high level flash programming of raw binary data.</li>
<li>pyocd.flash.eraser: high level flash erasing.</li>
<li>pyocd.flash.file_programmer: high level file programming.</li>
<li>pyocd.flash.flash: low level flash programming API in the @ref pyocd.flash.flash.Flash “Flash”
class. Each flash memory region has a @ref pyocd.flash.flash.Flash “Flash” class instance
associated with it, accessible from the <codeclass="highlighter-rouge">flash</code> property on the region. To get the boot flash
memory region, call <codeclass="highlighter-rouge">target.memory_map.get_boot_memory()</code>. The <codeclass="highlighter-rouge">flash</code> attribute of this region
then returns the boot flash memory’s @ref pyocd.flash.flash.Flash “Flash” instance.</li>