1# Copyright (c) 2017 Linaro Limited.
2#
3# SPDX-License-Identifier: Apache-2.0
4
5'''Runner for pyOCD .'''
6
7import os
8from os import path
9
10from runners.core import BuildConfiguration, RunnerCaps, ZephyrBinaryRunner
11
12DEFAULT_PYOCD_GDB_PORT = 3333
13DEFAULT_PYOCD_TELNET_PORT = 4444
14
15
16class PyOcdBinaryRunner(ZephyrBinaryRunner):
17    '''Runner front-end for pyOCD.'''
18
19    def __init__(self, cfg, target,
20                 pyocd='pyocd',
21                 dev_id=None, flash_addr=0x0, erase=False, flash_opts=None,
22                 gdb_port=DEFAULT_PYOCD_GDB_PORT,
23                 telnet_port=DEFAULT_PYOCD_TELNET_PORT, tui=False,
24                 pyocd_config=None,
25                 daparg=None, frequency=None, tool_opt=None):
26        super().__init__(cfg)
27
28        default = path.join(cfg.board_dir, 'support', 'pyocd.yaml')
29        if path.exists(default):
30            self.pyocd_config = default
31        else:
32            self.pyocd_config = None
33
34
35        self.target_args = ['-t', target]
36        self.pyocd = pyocd
37        self.flash_addr_args = ['-a', hex(flash_addr)] if flash_addr else []
38        self.erase = erase
39        self.gdb_cmd = [cfg.gdb] if cfg.gdb is not None else None
40        self.gdb_port = gdb_port
41        self.telnet_port = telnet_port
42        self.tui_args = ['-tui'] if tui else []
43        self.hex_name = cfg.hex_file
44        self.bin_name = cfg.bin_file
45        self.elf_name = cfg.elf_file
46
47        pyocd_config_args = []
48
49        if self.pyocd_config is not None:
50            pyocd_config_args = ['--config', self.pyocd_config]
51
52        self.pyocd_config_args = pyocd_config_args
53
54        board_args = []
55        if dev_id is not None:
56            board_args = ['-u', dev_id]
57        self.board_args = board_args
58
59        daparg_args = []
60        if daparg is not None:
61            daparg_args = ['-da', daparg]
62        self.daparg_args = daparg_args
63
64        frequency_args = []
65        if frequency is not None:
66            frequency_args = ['-f', frequency]
67        self.frequency_args = frequency_args
68
69        self.tool_opt_args = tool_opt or []
70
71        self.flash_extra = flash_opts if flash_opts else []
72
73    @classmethod
74    def name(cls):
75        return 'pyocd'
76
77    @classmethod
78    def capabilities(cls):
79        return RunnerCaps(commands={'flash', 'debug', 'debugserver', 'attach', 'rtt'},
80                          dev_id=True, flash_addr=True, erase=True,
81                          tool_opt=True, rtt=True)
82
83    @classmethod
84    def dev_id_help(cls) -> str:
85        return '''Device identifier. Use it to select the probe's unique ID
86                  or substring thereof.'''
87
88    @classmethod
89    def do_add_parser(cls, parser):
90        parser.add_argument('--target', required=True,
91                            help='target override')
92
93        parser.add_argument('--daparg',
94                            help='Additional -da arguments to pyocd tool')
95        parser.add_argument('--pyocd', default='pyocd',
96                            help='path to pyocd tool, default is pyocd')
97        parser.add_argument('--flash-opt', default=[], action='append',
98                            help='''Additional options for pyocd flash,
99                            e.g. --flash-opt="-e=chip" to chip erase''')
100        parser.add_argument('--frequency',
101                            help='SWD clock frequency in Hz')
102        parser.add_argument('--gdb-port', default=DEFAULT_PYOCD_GDB_PORT,
103                            help=f'pyocd gdb port, defaults to {DEFAULT_PYOCD_GDB_PORT}')
104        parser.add_argument('--telnet-port', default=DEFAULT_PYOCD_TELNET_PORT,
105                            help=f'pyocd telnet port, defaults to {DEFAULT_PYOCD_TELNET_PORT}')
106        parser.add_argument('--tui', default=False, action='store_true',
107                            help='if given, GDB uses -tui')
108        parser.add_argument('--board-id', dest='dev_id',
109                            help='obsolete synonym for -i/--dev-id')
110
111    @classmethod
112    def tool_opt_help(cls) -> str:
113        return """Additional options for pyocd commander,
114        e.g. '--script=user.py'"""
115
116    @classmethod
117    def do_create(cls, cfg, args):
118        build_conf = BuildConfiguration(cfg.build_dir)
119        flash_addr = cls.get_flash_address(args, build_conf)
120
121        ret = PyOcdBinaryRunner(
122            cfg, args.target,
123            pyocd=args.pyocd,
124            flash_addr=flash_addr, erase=args.erase, flash_opts=args.flash_opt,
125            gdb_port=args.gdb_port, telnet_port=args.telnet_port, tui=args.tui,
126            dev_id=args.dev_id, daparg=args.daparg,
127            frequency=args.frequency,
128            tool_opt=args.tool_opt)
129
130        daparg = os.environ.get('PYOCD_DAPARG')
131        if not ret.daparg_args and daparg:
132            ret.logger.warning('PYOCD_DAPARG is deprecated; use --daparg')
133            ret.logger.debug(f'--daparg={daparg} via PYOCD_DAPARG')
134            ret.daparg_args = ['-da', daparg]
135
136        return ret
137
138    def port_args(self):
139        return ['-p', str(self.gdb_port), '-T', str(self.telnet_port)]
140
141    def do_run(self, command, **kwargs):
142        self.require(self.pyocd)
143        if command == 'rtt':
144            self.rtt(**kwargs)
145        elif command == 'flash':
146            self.flash(**kwargs)
147        else:
148            self.debug_debugserver(command, **kwargs)
149
150    def flash(self, **kwargs):
151        # Use hex, bin or elf file provided by the buildsystem.
152        # Preferring .hex over .bin and .elf
153        if self.hex_name is not None and os.path.isfile(self.hex_name):
154            fname = self.hex_name
155        # Preferring .bin over .elf
156        elif self.bin_name is not None and os.path.isfile(self.bin_name):
157            fname = self.bin_name
158        elif self.elf_name is not None and os.path.isfile(self.elf_name):
159            fname = self.elf_name
160        else:
161            raise ValueError(
162                f'Cannot flash; no hex ({self.hex_name}), bin ({self.bin_name}) '
163                f'or elf ({self.elf_name}) files found. ')
164
165        erase_method = 'chip' if self.erase else 'sector'
166
167        cmd = ([self.pyocd] +
168               ['flash'] +
169               self.pyocd_config_args +
170               ['-e', erase_method] +
171               self.flash_addr_args +
172               self.daparg_args +
173               self.target_args +
174               self.board_args +
175               self.frequency_args +
176               self.tool_opt_args +
177               self.flash_extra +
178               [fname])
179
180        self.logger.info(f'Flashing file: {fname}')
181        self.check_call(cmd)
182
183    def log_gdbserver_message(self):
184        self.logger.info(f'pyOCD GDB server running on port {self.gdb_port}')
185
186    def debug_debugserver(self, command, **kwargs):
187        server_cmd = ([self.pyocd] +
188                      ['gdbserver'] +
189                      self.daparg_args +
190                      self.port_args() +
191                      self.target_args +
192                      self.board_args +
193                      self.frequency_args +
194                      self.tool_opt_args)
195
196        if command == 'debugserver':
197            self.log_gdbserver_message()
198            self.check_call(server_cmd)
199        else:
200            if self.gdb_cmd is None:
201                raise ValueError('Cannot debug; gdb is missing')
202            if self.elf_name is None:
203                raise ValueError('Cannot debug; elf is missing')
204            client_cmd = (self.gdb_cmd +
205                          self.tui_args +
206                          [self.elf_name] +
207                          ['-ex', f'target remote :{self.gdb_port}'])
208            if command == 'debug':
209                client_cmd += ['-ex', 'monitor halt',
210                               '-ex', 'monitor reset',
211                               '-ex', 'load']
212
213            self.require(client_cmd[0])
214            self.log_gdbserver_message()
215            self.run_server_and_client(server_cmd, client_cmd)
216
217
218    def rtt(self):
219        rtt_addr = self.get_rtt_address()
220        if rtt_addr is None:
221            raise ValueError('RTT control block not found')
222
223        self.logger.debug(f'rtt address: 0x{rtt_addr:x}')
224
225        cmd = ([self.pyocd] +
226               ['rtt'] +
227               self.pyocd_config_args +
228               self.daparg_args +
229               self.target_args +
230               self.board_args +
231               self.frequency_args +
232               self.tool_opt_args +
233               ['-a', f'0x{rtt_addr:x}'])
234
235        self.check_call(cmd)
236