runner: Introduce attach command

Introduces a new west command to start a debugging session without
programming the flash. This can be used when you want to debug a Zephyr
application that is already running.

Signed-off-by: Maureen Helm <maureen.helm@nxp.com>

src/west/cmd/debug.py

@@ -15,7 +15,9 @@ class Debug(WestCommand):
     def __init__(self):
         super(Debug, self).__init__(
             'debug',
-            'Connect to the board and start a debugging session.\n\n' +
+            dedent('''
+            Connect to the board, program the flash, and start a
+            debugging session.\n\n''') +
             desc_common('debug'),
             accepts_unknown_args=True)
 
@@ -47,3 +49,21 @@ class DebugServer(WestCommand):
     def do_run(self, my_args, runner_args):
         do_run_common(self, my_args, runner_args,
                       'ZEPHYR_BOARD_DEBUG_RUNNER')
+
+class Attach(WestCommand):
+
+    def __init__(self):
+        super(Attach, self).__init__(
+            'attach',
+            dedent('''
+            Connect to the board without programming the flash, and
+            start a debugging session.\n\n''') +
+            desc_common('attach'),
+            accepts_unknown_args=True)
+
+    def do_add_parser(self, parser_adder):
+        return add_parser_common(parser_adder, self)
+
+    def do_run(self, my_args, runner_args):
+        do_run_common(self, my_args, runner_args,
+                      'ZEPHYR_BOARD_DEBUG_RUNNER')

src/west/main.py

@@ -16,7 +16,7 @@ from . import log
 from .cmd import CommandContextError
 from .cmd.build import Build
 from .cmd.flash import Flash
-from .cmd.debug import Debug, DebugServer
+from .cmd.debug import Debug, DebugServer, Attach
 from .cmd.project import ListProjects, Fetch, Pull, Rebase, Branch, Checkout, \
                          Diff, Status, ForAll
 from .util import quote_sh_list
@@ -27,6 +27,7 @@ COMMANDS = (
     Flash(),
     Debug(),
     DebugServer(),
+    Attach(),
 
     # Project-related commands
     ListProjects(),

src/west/runner/core.py

@@ -163,7 +163,7 @@ class RunnerCaps:
     Available capabilities:
 
     - commands: set of supported commands; default is {'flash',
-      'debug', 'debugserver'}.
+      'debug', 'debugserver', 'attach'}.
 
     - flash_addr: whether the runner supports flashing to an
       arbitrary address. Default is False. If true, the runner
@@ -171,7 +171,7 @@ class RunnerCaps:
     '''
 
     def __init__(self,
-                 commands={'flash', 'debug', 'debugserver'},
+                 commands={'flash', 'debug', 'debugserver', 'attach'},
                  flash_addr=False):
         self.commands = commands
         self.flash_addr = bool(flash_addr)
@@ -256,15 +256,21 @@ class ZephyrBinaryRunner(abc.ABC):
     - 'flash': flash a previously configured binary to the board,
       start execution on the target, then return.
 
-    - 'debug': connect to the board via a debugging protocol, then
+    - 'debug': connect to the board via a debugging protocol, program
-      drop the user into a debugger interface with symbol tables
+      the flash, then drop the user into a debugger interface with
-      loaded from the current binary, and block until it exits.
+      symbol tables loaded from the current binary, and block until it
+      exits.
 
     - 'debugserver': connect via a board-specific debugging protocol,
       then reset and halt the target. Ensure the user is now able to
       connect to a debug server with symbol tables loaded from the
       binary.
 
+    - 'attach': connect to the board via a debugging protocol, then drop
+      the user into a debugger interface with symbol tables loaded from
+      the current binary, and block until it exits. Unlike 'debug', this
+      command does not program the flash.
+
     This class provides an API for these commands. Every runner has a
     name (like 'pyocd'), and declares commands it can handle (like
     'flash'). Zephyr boards (like 'nrf52_pca10040') declare compatible
@@ -391,7 +397,7 @@ class ZephyrBinaryRunner(abc.ABC):
             return default
 
     def run(self, command, **kwargs):
-        '''Runs command ('flash', 'debug', 'debugserver').
+        '''Runs command ('flash', 'debug', 'debugserver', 'attach').
 
         This is the main entry point to this runner.'''
         caps = self.capabilities()

src/west/runner/jlink.py

@@ -42,7 +42,8 @@ class JLinkBinaryRunner(ZephyrBinaryRunner):
 
     @classmethod
     def capabilities(cls):
-        return RunnerCaps(flash_addr=True)
+        return RunnerCaps(commands={'flash', 'debug', 'debugserver'},
+                          flash_addr=True)
 
     @classmethod
     def do_add_parser(cls, parser):

src/west/runner/pyocd.py

@@ -51,7 +51,8 @@ class PyOcdBinaryRunner(ZephyrBinaryRunner):
 
     @classmethod
     def capabilities(cls):
-        return RunnerCaps(flash_addr=True)
+        return RunnerCaps(commands={'flash', 'debug', 'debugserver'},
+                          flash_addr=True)
 
     @classmethod
     def do_add_parser(cls, parser):