Deploying to main from @ pyocd/pyocd-website-source@39b32dc 🚀

Author: pyocd-bot

docs/README.md

@@ -0,0 +1,48 @@
+
+## Table of Contents
+
+### Getting started
+
+- [Installing](installing.md)
+- [Installing on non-x86](installing_on_non_x86.md)
+- [GDB setup](gdb_setup.md)
+
+### User documentation
+
+- [Terminology](terminology.md)
+- [Target support](target_support.md)
+- [Debug probes](debug_probes.md)
+- [Configuration](configuration.md)
+- [User scripts](user_scripts.md)
+- [Remote probe access](remote_probe_access.md)
+- [Configuring logging](configuring_logging.md)
+- [Target security features](security.md)
+- [Debugging multicore devices](multicore_debug.md)
+- [Semihosting](semihosting.md)
+- [SWO/SWV](swo_swv.md)
+- [Target family usage notes](target_notes.md)
+
+### Reference
+
+- [Built-in targets](builtin-targets.md)
+- [Session options reference](options.md)
+- [Command reference](command_reference.md)
+- [Environment variables](env_vars.md)
+
+### Python API
+
+- [Introduction to the pyOCD Python API](python_api.md)
+- [Python API examples](api_examples.md)
+
+### Developer documentation
+
+- [Developers’ guide](developers_guide.md)
+- [How to add new targets](adding_new_targets.md)
+- [Running the automated tests](automated_tests.md)
+- Internal design
+  - [Architecture overview](architecture.md)
+  - [Remote probe protocol](remote_probe_protocol.md)
+
+
+
+

docs/automated_tests.html

@@ -205,6 +205,7 @@ <h5 class="sidebar-header">On this page</h5>
                         <ul id="toc" class="section-nav">
 <li class="toc-entry toc-h2"><a href="#unit-tests">Unit tests</a></li>
 <li class="toc-entry toc-h2"><a href="#functional-tests">Functional tests</a></li>
+<li class="toc-entry toc-h2"><a href="#azure-pipelines">Azure Pipelines</a></li>
 <li class="toc-entry toc-h2"><a href="#testing-with-tox">Testing with tox</a></li>
 </ul>
                     </div>
@@ -244,19 +245,38 @@ <h2 id="functional-tests">Functional tests</h2>
 <ul>
   <li><code class="highlighter-rouge">basic_test.py</code>: a simple test that checks a range of basic functionality, from flash programming to accessing memory and core registers.</li>
   <li><code class="highlighter-rouge">blank_test.py</code>: tests ability to connect to devices with with blank flash. (Not run by <code class="highlighter-rouge">automated_test.py</code>.)</li>
+  <li><code class="highlighter-rouge">commander_test.py</code>: tests the <code class="highlighter-rouge">pyocd commander</code> functionality.</li>
+  <li><code class="highlighter-rouge">commands_test.py</code>: tests commands supported by commander and gdb monitor commands.</li>
+  <li><code class="highlighter-rouge">concurrency_test.py</code>: verify multiple threads can simultaneously access a debug probe, specifically for memory
+  transfers.</li>
   <li><code class="highlighter-rouge">connect_test.py</code>: tests all combinations of the halt on connect and disconnect resume options.</li>
   <li><code class="highlighter-rouge">cortex_test.py</code>: validates CPU control operations and memory accesses.</li>
   <li><code class="highlighter-rouge">debug_context_test.py</code>: tests some <code class="highlighter-rouge">DebugContext</code> classes.</li>
-  <li><code class="highlighter-rouge">flash_test.py</code>: comprehensive test of flash programming.</li>
   <li><code class="highlighter-rouge">flash_loader_test.py</code>: test the classes in the <code class="highlighter-rouge">pyocd.flash.loader</code> module.</li>
-  <li><code class="highlighter-rouge">gdb_server_json_test.py</code>: validates the JSON output from pyocd-gdbserver used by tools like the GNU MCU Eclipse pyOCD plugin.</li>
+  <li><code class="highlighter-rouge">flash_test.py</code>: comprehensive test of flash programming.</li>
+  <li><code class="highlighter-rouge">import_all.py</code>: imports all pyocd modules. (Not run by <code class="highlighter-rouge">automated_test.py</code>.)</li>
   <li><code class="highlighter-rouge">gdb_test.py</code>: tests the gdbserver by running a script in a gdb process. Note that on Windows,
   the 32-bit Python 2.7 must be installed for the Python-enabled gdb to work properly and for
   this test to pass.</li>
+  <li><code class="highlighter-rouge">json_lists_test.py</code>: validates the JSON output from <code class="highlighter-rouge">pyocd json</code>.</li>
   <li><code class="highlighter-rouge">parallel_test.py</code>: checks for issues with accessing debug probes from multiple processes and threads simultaneously. (Not run by <code class="highlighter-rouge">automated_test.py</code>.)</li>
+  <li><code class="highlighter-rouge">probeserver_test.py</code>: verify remote probe server and client.</li>
   <li><code class="highlighter-rouge">speed_test.py</code>: performance test for memory reads and writes.</li>
+  <li><code class="highlighter-rouge">user_script_test.py</code>: verify loading of user scripts.</li>
 </ul>
 
+<h2 id="azure-pipelines">Azure Pipelines</h2>
+
+<p>PyOCD uses Azure Pipelines to run the CI tests for commits and pull requests. The pipeline runs the functional tests on
+a set of test machines, called self-hosted test agents in Azure Pipelines parlance. There is one each of Mac, Linux, and
+Windows test agents.</p>
+
+<p>The complete results from pipeline runs are <a href="https://dev.azure.com/pyocd/pyocd/_build?definitionId=1&amp;_a=summary">publicly
+accessible</a>.</p>
+
+<p>For pull requests, a pyOCD team member or collaborator must manually initiate the pipeline run by entering a special
+comment of the form “/azp run” or “/AzurePipelines run”.</p>
+
 <h2 id="testing-with-tox">Testing with tox</h2>
 
 <p>pyOCD includes a configuration file for tox that enables easy testing of multiple Python versions.

docs/command_reference.html

@@ -282,6 +282,11 @@ <h5 class="sidebar-header">On this page</h5>
 <li class="toc-entry toc-h5"><a href="#init">init</a></li>
 </ul>
 </li>
+<li class="toc-entry toc-h3"><a href="#probe">Probe</a>
+<ul>
+<li class="toc-entry toc-h5"><a href="#flushprobe">flushprobe</a></li>
+</ul>
+</li>
 <li class="toc-entry toc-h3"><a href="#registers">Registers</a>
 <ul>
 <li class="toc-entry toc-h5"><a href="#reg">reg</a></li>
@@ -690,20 +695,31 @@ <h2 id="all-commands">All commands</h2>
 Ignored; for OpenOCD compatibility.
 </td></tr>
 
+<tr><td colspan="3"><b>Probe</b></td></tr>
+
+<tr><td>
+<a href="#flushprobe"><tt>flushprobe</tt></a>
+</td><td>
+</td><td>
+Ensure all debug probe requests have been completed.
+</td></tr>
+
 <tr><td colspan="3"><b>Registers</b></td></tr>
 
 <tr><td>
-<a href="#reg"><tt>reg</tt></a>
+<a href="#reg"><tt>reg</tt></a>,
+<a href="#reg"><tt>rr</tt></a>
 </td><td>
-[-f] [REG]
+[-p] [-f] [REG...]
 </td><td>
 Print core or peripheral register(s).
 </td></tr>
 
 <tr><td>
-<a href="#wreg"><tt>wreg</tt></a>
+<a href="#wreg"><tt>wreg</tt></a>,
+<a href="#wreg"><tt>wr</tt></a>
 </td><td>
-[-r] REG VALUE
+[-r] [-p] [-f] REG VALUE
 </td><td>
 Set the value of a core or peripheral register.
 </td></tr>
@@ -1198,17 +1214,26 @@ <h5 id="init"><code class="highlighter-rouge">init</code></h5>
 <p><strong>Usage</strong>: init <br />
 Ignored; for OpenOCD compatibility.</p>
 
+<h3 id="probe">Probe</h3>
+
+<h5 id="flushprobe"><code class="highlighter-rouge">flushprobe</code></h5>
+
+<p><strong>Usage</strong>:  <br />
+Ensure all debug probe requests have been completed.</p>
+
 <h3 id="registers">Registers</h3>
 
 <h5 id="reg"><code class="highlighter-rouge">reg</code></h5>
 
-<p><strong>Usage</strong>: [-f] [REG] <br />
-Print core or peripheral register(s). If no arguments are provided, all core registers will be printed. Either a core register name, the name of a peripheral, or a peripheral.register can be provided. When a peripheral name is provided without a register, all registers in the peripheral will be printed. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.</p>
+<p><strong>Aliases</strong>: <code class="highlighter-rouge">rr</code> <br />
+<strong>Usage</strong>: [-p] [-f] [REG…] <br />
+Print core or peripheral register(s). If no arguments are provided, the ‘general’ core register group will be printed. Either a core register name, the name of a peripheral, or a peripheral.register can be provided. When a peripheral name is provided without a register, all registers in the peripheral will be printed. The -p option forces evaluating the register name as a peripheral register name. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.</p>
 
 <h5 id="wreg"><code class="highlighter-rouge">wreg</code></h5>
 
-<p><strong>Usage</strong>: [-r] REG VALUE <br />
-Set the value of a core or peripheral register. The REG parameter must be a core register name or a peripheral.register. When a peripheral register is written, if the -r option is passed then it is read back and the updated value printed.</p>
+<p><strong>Aliases</strong>: <code class="highlighter-rouge">wr</code> <br />
+<strong>Usage</strong>: [-r] [-p] [-f] REG VALUE <br />
+Set the value of a core or peripheral register. The REG parameter must be a core register name or a peripheral.register. When a peripheral register is written, if the -r option is passed then it is read back and the updated value printed. The -p option forces evaluating the register name as a peripheral register name. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.</p>
 
 <h3 id="semihosting">Semihosting</h3>
 

docs/configuring_logging.html

@@ -206,6 +206,7 @@ <h5 class="sidebar-header">On this page</h5>
 <li class="toc-entry toc-h2"><a href="#overview">Overview</a></li>
 <li class="toc-entry toc-h2"><a href="#log-levels">Log levels</a></li>
 <li class="toc-entry toc-h2"><a href="#basic-control">Basic control</a></li>
+<li class="toc-entry toc-h2"><a href="#color-logging">Color logging</a></li>
 <li class="toc-entry toc-h2"><a href="#loggers">Loggers</a>
 <ul>
 <li class="toc-entry toc-h3"><a href="#trace-loggers">Trace loggers</a></li>
@@ -289,6 +290,10 @@ <h2 id="log-levels">Log levels</h2>
       <td><code class="highlighter-rouge">reset</code></td>
       <td>WARNING</td>
     </tr>
+    <tr>
+      <td><code class="highlighter-rouge">rtt</code></td>
+      <td>INFO</td>
+    </tr>
     <tr>
       <td><code class="highlighter-rouge">server</code></td>
       <td>INFO</td>
@@ -303,6 +308,17 @@ <h2 id="basic-control">Basic control</h2>
 logging verbosity level. For example, a single <code class="highlighter-rouge">--verbose</code> moves <code class="highlighter-rouge">pyocd flash</code> from the default
 level of WARNING to INFO.</p>
 
+<h2 id="color-logging">Color logging</h2>
+
+<p>By default, log output to a tty is colorised. Control over colorised log output is possible two ways.</p>
+
+<p>The command-line <code class="highlighter-rouge">--color</code> argument accepts an optional parameter that must be one of <code class="highlighter-rouge">auto</code>, <code class="highlighter-rouge">always</code>, or <code class="highlighter-rouge">never</code>.
+The default is <code class="highlighter-rouge">auto</code>, which will enable color only when outputting to a tty.</p>
+
+<p>Another option for controlling color output is the <code class="highlighter-rouge">PYOCD_COLOR</code> environment variable. It should be set to one of the
+same values supported by <code class="highlighter-rouge">--color</code>. This environment variable changes the default color output setting, and is
+overridden by <code class="highlighter-rouge">--color</code> on the command line.</p>
+
 <h2 id="loggers">Loggers</h2>
 
 <p>Each module in pyOCD uses its own module-specific logger with a name matching the dotted module
@@ -316,7 +332,7 @@ <h2 id="loggers">Loggers</h2>
 <h3 id="trace-loggers">Trace loggers</h3>
 
 <p>Certain modules define additional sub-module loggers that output debug trace logs. These loggers always have the
-suffix “.trace” and are set to critical log level by default.</p>
+suffix “.trace” and are disabled by default. This ensures the trace messages won’t be seen unless explicitly enabled by the <code class="highlighter-rouge">--log-level</code> / <code class="highlighter-rouge">-L</code> argument described in the following section.</p>
 
 <p>Currently defined trace loggers:</p>
 
@@ -356,6 +372,22 @@ <h3 id="trace-loggers">Trace loggers</h3>
       <td><code class="highlighter-rouge">pyocd.probe.pydapaccess.dap_access_cmsis_dap.trace</code></td>
       <td>CMSIS-DAP packet building</td>
     </tr>
+    <tr>
+      <td><code class="highlighter-rouge">pyocd.probe.pydapaccess.interface.hidapi_backend.trace</code></td>
+      <td>CMSIS-DAP v1 hidapi backend USB transfers</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">pyocd.probe.pydapaccess.interface.pyusb_backend.trace</code></td>
+      <td>CMSIS-DAP v1 pyusb backend USB transfers</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">pyocd.probe.pydapaccess.interface.pyusb_v2_backend.trace</code></td>
+      <td>CMSIS-DAP v2 pyusb backend USB transfers</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">pyocd.probe.pydapaccess.interface.pywinusb_backend.trace</code></td>
+      <td>CMSIS-DAP v1 pywinusb backend USB transfers</td>
+    </tr>
     <tr>
       <td><code class="highlighter-rouge">pyocd.probe.stlink.usb.trace</code></td>
       <td>STLink USB transfers</td>