Merge branch 'develop'

Author: flit

docs/configuration.md

@@ -10,7 +10,7 @@ multiple ways to set these options.
 
 - Many of the most commonly used session options have dedicated command line arguments.
 - Options can be placed in a YAML config file.
-- Arbitrary options can be set individually with the `-Ooption=value` command line argument.
+- Arbitrary options can be set individually with the <tt>-O<i>option</i>=<i>value</i></tt> command line argument.
 - If you are using the Python API, you may pass any option values directly
     to the `ConnectHelper` methods or `Session` constructor as keyword arguments. You can also
     pass a dictionary for the `options` parameter of these methods.
@@ -27,14 +27,18 @@ The priorities of the different session option sources, from highest to lowest:
 ## Project directory
 
 To help pyOCD automatically find configuration files and other resources, it has the concept of
-the project directory. By default this is simply the working directory where you ran the `pyocd`
-tool. You can set the project directory explicitly with the `-j` or `--dir` command line
-arguments. This can be helpful if you are running pyOCD from another tool or application.
+the project directory.
 
 When pyOCD looks for files such as the config file or a user script, it first expands '~'
 references to the home directory. Then it checks whether the filename is absolute, and if so, it
 uses the filename as-is. Otherwise, it looks for the file in the project directory.
 
+By default, the project directory is simply the working directory where you ran the `pyocd` tool.
+You can change the project directory to another location with the `-j`, `--project`, or `--dir` command line
+arguments. This can be helpful if you are running pyOCD from another tool or application. The project
+directory can also be set using the `PYOCD_PROJECT_DIR` environment variable. Command line arguments
+have precedence over the environment variable.
+
 ## Config file
 
 pyOCD supports a YAML configuration file that lets you set session options that either apply to
@@ -44,7 +48,8 @@ The easiest way to use a config file is to place a `pyocd.yaml` file in the proj
 An alternate `.yml` extension and
 optional dot prefix on the config file name are allowed. Alternatively, you can use the
 `--config` command line option, for instance `--config=myconfig.yaml`. Finally, you can set the
-`config_file` option.
+`config_file` option. If there is a need to prevent reading a config file, use the `--no-config`
+argument.
 
 The top level of the YAML file is a dictionary. The keys in the top-level dictionary must be names
 of session options, or the key `probes`. Session options are set to the value corresponding to the

docs/options.md

@@ -90,6 +90,13 @@ working directory.
 <td>'halt'</td>
 <td>
 Controls how pyOCD connects to the target. One of 'halt', 'pre-reset', 'under-reset', 'attach'.
+<ul>
+<li>'halt': immediately halt all accessible cores upon connect.</li>
+<li>'pre-reset': perform a hardware reset prior to connect and halt.</li>
+<li>'under-reset': assert hardware reset during the connect sequence, then deassert after the cores are halted.
+    This connect mode is often necessary to gain control of a target that is in a deep low power mode.</li>
+<li>'attach': connect to a running target without halting cores.</li>
+</ul>
 </td></tr>
 
 <tr><td>cpu.step.instruction.timeout</td>

docs/target_support.md

@@ -133,13 +133,13 @@ DFPs. The part number patterns are matched case-insensitively and as a contains
 For instance, if you know the specific part number of the device you are using, say STM32L073, you
 can run this command to install support:
 
-    $ pyocd pack --install stm32l073
+    $ pyocd pack install stm32l073
 
 This will download the index if required, then download the STM32L0xx_DFP pack. The
 
 As another example, to find which pack(s) support the NXP MK26F family, you could run:
 
-    $ pyocd pack --find k26
+    $ pyocd pack find k26
 
 This will print a table similar to:
 

docs/terminology.md

@@ -3,12 +3,14 @@ Terminology
 
 These are the key terms used by pyOCD and its documentation.
 
-- **ADI**: Arm Debug Interface, an Arm architecture standard for how JTAG and SWD interface with CoreSight.
+- **ADI**: Arm Debug Interface, an Arm architecture specification for how JTAG and SWD interface with CoreSight.
     It defines the DAP structure and registers.
 - **AP**: Access Port, part of the DAP, connected to the DP, that allows the debugger to perform operations
     on the chip and cores. There are multiple types of AP that serve different purposes (see MEM-AP). Some MCU
     vendors implement proprietary APs in their chips.
-- **CoreSight**: A standard Arm architecture for debug subsystems. It defines a standardised way
+- **Commander**: Refers to the `pyocd commander` subcommand that presents an interactive interface for exploring
+    the connected target.
+- **CoreSight**: An Arm architecture specification for debug subsystems. It defines a standardised way
     to discover the debug resources provided by a device.
 - **DAP**: Debug Access Port, the debugging module that is accessed via the JTAG or SWD port. Composed of a
     DP and one or more APs.
@@ -30,6 +32,8 @@ These are the key terms used by pyOCD and its documentation.
     writes within the chip. Concrete MEM-APs have names that represent the kind of bus fabric with which they
     interface, such as AHB-AP or AXI-AP.
 - **probe server**: Server that shares a debug probe over TCP/IP.
+- **REPL**: Read-Eval-Print-Loop. An interactive type of command interface used by pyOCD Commander, as well as
+    Python and other similar tools.
 - **session**: Represents a connection to a debug probe and the runtime object graph.
 - **session option**: A named setting that controls some feature of pyOCD. Options are associated with
     a session, and each session can have different values for a given option.. They can be set from the

pyocd/board/board.py

@@ -1,5 +1,6 @@
 # pyOCD debugger
 # Copyright (c) 2006-2013,2018 Arm Limited
+# Copyright (c) 2021 Chris Reed
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,12 +15,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import logging
+
 from ..core import exceptions
 from ..target import TARGET
 from ..target.pack import pack_target
 from ..utility.graph import GraphNode
-import logging
-import six
 
 LOG = logging.getLogger(__name__)
 
@@ -60,11 +61,11 @@ def __init__(self, session, target=None):
         try:
             self.target = TARGET[self._target_type](session)
         except KeyError as exc:
-            six.raise_from(exceptions.TargetSupportError(
-                "Target type '%s' not recognized. Use 'pyocd list --targets' to see currently "
+            raise exceptions.TargetSupportError(
+                f"Target type {self._target_type} not recognized. Use 'pyocd list --targets' to see currently "
                 "available target types. "
                 "See <https://github.com/pyocd/pyOCD/blob/master/docs/target_support.md> "
-                "for how to install additional target support." % self._target_type), exc)
+                "for how to install additional target support.") from exc
 
         # Tell the user what target type is selected.
         LOG.info("Target type is %s", self._target_type)
@@ -97,7 +98,7 @@ def uninit(self):
                 resume = self.session.options.get('resume_on_disconnect')
                 self.target.disconnect(resume)
                 self._inited = False
-            except:
+            except exceptions.Error:
                 LOG.error("link exception during target disconnect:", exc_info=self._session.log_tracebacks)
 
     @property

pyocd/board/board_ids.py

@@ -262,6 +262,8 @@ def __init__(self, name, target, binary):
     "9014": BoardInfo(  "Seeed 96Boards Nitrogen", "nrf52",         "l1_nrf52-dk.bin",      ),
     "9900": BoardInfo(  "micro:bit",            "nrf51",            "l1_microbit.bin",      ),
     "9901": BoardInfo(  "micro:bit",            "nrf51",            "l1_microbit.bin",      ),
+    "9903": BoardInfo(  "micro:bit v2",         "nrf52833",         "microbitv2.bin",       ),
+    "9904": BoardInfo(  "micro:bit v2",         "nrf52833",         "microbitv2.bin",       ),
     "C004": BoardInfo(  "tinyK20",              "k20d50m",          "l1_k20d50m.bin",       ),
     "C006": BoardInfo(  "VBLUno51",             "nrf51",            "l1_nrf51.bin",         ),
 }

pyocd/commands/base.py

@@ -17,7 +17,6 @@
 
 import logging
 import textwrap
-import six
 
 from ..core import exceptions
 from ..utility import conversion
@@ -55,8 +54,7 @@ def __new__(mcs, name, bases, dict):
             ALL_COMMANDS.setdefault(info['group'], set()).add(new_type)
         return new_type
 
-@six.add_metaclass(CommandMeta)
-class CommandBase(object):
+class CommandBase(metaclass=CommandMeta):
     """! @brief Base class for a command.
     
     Each command class must have an `INFO` attribute with the following keys:
@@ -164,7 +162,7 @@ def _convert_value(self, arg):
 
             return value
         except ValueError as err:
-            raise six.raise_from(exceptions.CommandError("invalid argument '{}'".format(arg)), None)
+            raise exceptions.CommandError("invalid argument '{}'".format(arg)) from None
 
     @classmethod
     def format_help(cls, context, max_width=72):

pyocd/commands/commander.py

@@ -1,5 +1,6 @@
 # pyOCD debugger
 # Copyright (c) 2015-2020 Arm Limited
+# Copyright (c) 2021 Chris Reed
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,7 +15,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import logging
 import os
 import traceback

pyocd/commands/execution_context.py

@@ -162,7 +162,7 @@ def write(self, message='', **kwargs):
         if self._output is None:
             return
         end = kwargs.pop('end', "\n")
-        if not isinstance(message, six.string_types):
+        if not isinstance(message, str):
             message = str(message)
         self._output.write(message + end)
 
@@ -175,7 +175,7 @@ def writei(self, fmt, *args, **kwargs):
         @param self This object.
         @param fmt Format string using printf-style "%" formatters.
         """
-        assert isinstance(fmt, six.string_types)
+        assert isinstance(fmt, str)
         message = fmt % args
         self.write(message, **kwargs)
 
@@ -188,7 +188,7 @@ def writef(self, fmt, *args, **kwargs):
         @param self This object.
         @param fmt Format string using the format() mini-language.
         """
-        assert isinstance(fmt, six.string_types)
+        assert isinstance(fmt, str)
         message = fmt.format(*args, **kwargs)
         self.write(message, **kwargs)
 
@@ -394,7 +394,7 @@ def handle_python(self, invocation):
 
             result = eval(invocation.cmd, globals(), self._python_namespace)
             if result is not None:
-                if isinstance(result, six.integer_types):
+                if isinstance(result, str):
                     self.writei("0x%08x (%d)", result, result)
                 else:
                     w, h = get_terminal_size()
@@ -411,4 +411,4 @@ def handle_system(self, invocation):
             output = subprocess.check_output(invocation.cmd, stderr=subprocess.STDOUT, shell=True)
             self.write(six.ensure_str(output), end='')
         except subprocess.CalledProcessError as err:
-            six.raise_from(exceptions.CommandError(str(err)), err)
+            raise exceptions.CommandError(str(err)) from err

pyocd/commands/repl.py

@@ -1,5 +1,6 @@
 # pyOCD debugger
 # Copyright (c) 2015-2020 Arm Limited
+# Copyright (c) 2021 Chris Reed
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,10 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import print_function
 import logging
 import os
-import six
 import traceback
 import atexit
 
@@ -75,7 +74,7 @@ def run(self):
         try:
             while True:
                 try:
-                    line = six.moves.input(self.PROMPT)
+                    line = input(self.PROMPT)
                     self.run_one_command(line)
                 except KeyboardInterrupt:
                     print()