1# Copyright (c) 2017 Linaro Limited.
2#
3# SPDX-License-Identifier: Apache-2.0
4
5'''Runner for openocd.'''
6
7import subprocess
8import re
9
10from os import path
11from pathlib import Path
12
13try:
14    from elftools.elf.elffile import ELFFile
15except ImportError:
16    ELFFile = None
17
18from runners.core import ZephyrBinaryRunner
19
20DEFAULT_OPENOCD_TCL_PORT = 6333
21DEFAULT_OPENOCD_TELNET_PORT = 4444
22DEFAULT_OPENOCD_GDB_PORT = 3333
23DEFAULT_OPENOCD_RESET_HALT_CMD = 'reset halt'
24
25class OpenOcdBinaryRunner(ZephyrBinaryRunner):
26    '''Runner front-end for openocd.'''
27
28    def __init__(self, cfg, pre_init=None, reset_halt_cmd=DEFAULT_OPENOCD_RESET_HALT_CMD,
29                 pre_load=None, load_cmd=None, verify_cmd=None, post_verify=None,
30                 tui=None, config=None, serial=None, use_elf=None,
31                 no_halt=False,
32                 tcl_port=DEFAULT_OPENOCD_TCL_PORT,
33                 telnet_port=DEFAULT_OPENOCD_TELNET_PORT,
34                 gdb_port=DEFAULT_OPENOCD_GDB_PORT):
35        super().__init__(cfg)
36
37        if not config:
38            default = path.join(cfg.board_dir, 'support', 'openocd.cfg')
39            if path.exists(default):
40                config = [default]
41        self.openocd_config = config
42
43        search_args = []
44        if self.openocd_config is not None:
45            for i in self.openocd_config:
46                if path.exists(i):
47                    search_args.append('-s')
48                    search_args.append(path.dirname(i))
49
50        if cfg.openocd_search is not None:
51            for p in cfg.openocd_search:
52                search_args.extend(['-s', p])
53        self.openocd_cmd = [cfg.openocd] + search_args
54        # openocd doesn't cope with Windows path names, so convert
55        # them to POSIX style just to be sure.
56        self.elf_name = Path(cfg.elf_file).as_posix()
57        self.pre_init = pre_init or []
58        self.reset_halt_cmd = reset_halt_cmd
59        self.pre_load = pre_load or []
60        self.load_cmd = load_cmd
61        self.verify_cmd = verify_cmd
62        self.post_verify = post_verify or []
63        self.tcl_port = tcl_port
64        self.telnet_port = telnet_port
65        self.gdb_port = gdb_port
66        self.gdb_cmd = [cfg.gdb] if cfg.gdb else None
67        self.tui_arg = ['-tui'] if tui else []
68        self.halt_arg = [] if no_halt else ['-c halt']
69        self.serial = ['-c set _ZEPHYR_BOARD_SERIAL ' + serial] if serial else []
70        self.use_elf = use_elf
71
72    @classmethod
73    def name(cls):
74        return 'openocd'
75
76    @classmethod
77    def do_add_parser(cls, parser):
78        parser.add_argument('--config', action='append',
79                            help='''if given, override default config file;
80                            may be given multiple times''')
81        parser.add_argument('--serial', default="",
82                            help='if given, selects FTDI instance by its serial number, defaults to empty')
83        parser.add_argument('--use-elf', default=False, action='store_true',
84                            help='if given, Elf file will be used for loading instead of HEX image')
85        # Options for flashing:
86        parser.add_argument('--cmd-pre-init', action='append',
87                            help='''Command to run before calling init;
88                            may be given multiple times''')
89        parser.add_argument('--cmd-reset-halt', default=DEFAULT_OPENOCD_RESET_HALT_CMD,
90                            help=f'''Command to run for resetting and halting the target,
91                            defaults to "{DEFAULT_OPENOCD_RESET_HALT_CMD}"''')
92        parser.add_argument('--cmd-pre-load', action='append',
93                            help='''Command to run before flashing;
94                            may be given multiple times''')
95        parser.add_argument('--cmd-load',
96                            help='''Command to load/flash binary
97                            (required when flashing)''')
98        parser.add_argument('--cmd-verify',
99                            help='''Command to verify flashed binary''')
100        parser.add_argument('--cmd-post-verify', action='append',
101                            help='''Command to run after verification;
102                            may be given multiple times''')
103
104        # Options for debugging:
105        parser.add_argument('--tui', default=False, action='store_true',
106                            help='if given, GDB uses -tui')
107        parser.add_argument('--tcl-port', default=DEFAULT_OPENOCD_TCL_PORT,
108                            help='openocd TCL port, defaults to 6333')
109        parser.add_argument('--telnet-port',
110                            default=DEFAULT_OPENOCD_TELNET_PORT,
111                            help='openocd telnet port, defaults to 4444')
112        parser.add_argument('--gdb-port', default=DEFAULT_OPENOCD_GDB_PORT,
113                            help='openocd gdb port, defaults to 3333')
114        parser.add_argument('--no-halt', action='store_true',
115                            help='if given, no halt issued in gdb server cmd')
116
117    @classmethod
118    def do_create(cls, cfg, args):
119        return OpenOcdBinaryRunner(
120            cfg,
121            pre_init=args.cmd_pre_init, reset_halt_cmd=args.cmd_reset_halt,
122            pre_load=args.cmd_pre_load, load_cmd=args.cmd_load,
123            verify_cmd=args.cmd_verify, post_verify=args.cmd_post_verify,
124            tui=args.tui, config=args.config, serial=args.serial,
125            use_elf=args.use_elf, no_halt=args.no_halt,
126            tcl_port=args.tcl_port, telnet_port=args.telnet_port,
127            gdb_port=args.gdb_port)
128
129    def print_gdbserver_message(self):
130        if not self.thread_info_enabled:
131            thread_msg = '; no thread info available'
132        elif self.supports_thread_info():
133            thread_msg = '; thread info enabled'
134        else:
135            thread_msg = '; update OpenOCD software for thread info'
136        self.logger.info('OpenOCD GDB server running on port '
137                         f'{self.gdb_port}{thread_msg}')
138
139    # pylint: disable=R0201
140    def to_num(self, number):
141        dev_match = re.search(r"^\d*\+dev", number)
142        dev_version = not dev_match is None
143
144        num_match = re.search(r"^\d*", number)
145        num = int(num_match.group(0))
146
147        if dev_version:
148            num += 1
149
150        return num
151
152    def read_version(self):
153        self.require(self.openocd_cmd[0])
154
155	# OpenOCD prints in stderr, need redirect to get output
156        out = self.check_output([self.openocd_cmd[0], '--version'],
157                                stderr=subprocess.STDOUT).decode()
158
159        return out.split('\n')[0]
160
161    def supports_thread_info(self):
162        # Zephyr rtos was introduced after 0.11.0
163        version_str = self.read_version().split(' ')[3]
164        version = version_str.split('.')
165        (major, minor, rev) = [self.to_num(i) for i in version]
166        return (major, minor, rev) > (0, 11, 0)
167
168    def do_run(self, command, **kwargs):
169        self.require(self.openocd_cmd[0])
170        if ELFFile is None:
171            raise RuntimeError(
172                'elftools missing; please "pip3 install elftools"')
173
174        self.cfg_cmd = []
175        if self.openocd_config is not None:
176            for i in self.openocd_config:
177                self.cfg_cmd.append('-f')
178                self.cfg_cmd.append(i)
179
180        if command == 'flash' and self.use_elf:
181            self.do_flash_elf(**kwargs)
182        elif command == 'flash':
183            self.do_flash(**kwargs)
184        elif command in ('attach', 'debug'):
185            self.do_attach_debug(command, **kwargs)
186        elif command == 'load':
187            self.do_load(**kwargs)
188        else:
189            self.do_debugserver(**kwargs)
190
191    def do_flash(self, **kwargs):
192        self.ensure_output('hex')
193        if self.load_cmd is None:
194            raise ValueError('Cannot flash; load command is missing')
195        if self.verify_cmd is None:
196            raise ValueError('Cannot flash; verify command is missing')
197
198        # openocd doesn't cope with Windows path names, so convert
199        # them to POSIX style just to be sure.
200        hex_name = Path(self.cfg.hex_file).as_posix()
201
202        self.logger.info('Flashing file: {}'.format(hex_name))
203
204        pre_init_cmd = []
205        pre_load_cmd = []
206        post_verify_cmd = []
207        for i in self.pre_init:
208            pre_init_cmd.append("-c")
209            pre_init_cmd.append(i)
210
211        for i in self.pre_load:
212            pre_load_cmd.append("-c")
213            pre_load_cmd.append(i)
214
215        for i in self.post_verify:
216            post_verify_cmd.append("-c")
217            post_verify_cmd.append(i)
218
219        cmd = (self.openocd_cmd + self.serial + self.cfg_cmd +
220               pre_init_cmd + ['-c', 'init',
221                                '-c', 'targets'] +
222               pre_load_cmd + ['-c', self.reset_halt_cmd,
223                                '-c', self.load_cmd + ' ' + hex_name,
224                                '-c', self.reset_halt_cmd] +
225               ['-c', self.verify_cmd + ' ' + hex_name] +
226               post_verify_cmd +
227               ['-c', 'reset run',
228                '-c', 'shutdown'])
229        self.check_call(cmd)
230
231    def do_flash_elf(self, **kwargs):
232        if self.elf_name is None:
233            raise ValueError('Cannot debug; no .elf specified')
234
235        # Extract entry point address from Elf to use it later with
236        # "resume" command of OpenOCD.
237        with open(self.elf_name, 'rb') as f:
238            ep_addr = f"0x{ELFFile(f).header['e_entry']:016x}"
239
240        pre_init_cmd = []
241        for i in self.pre_init:
242            pre_init_cmd.append("-c")
243            pre_init_cmd.append(i)
244
245        cmd = (self.openocd_cmd + self.serial + self.cfg_cmd +
246                      pre_init_cmd + ['-c', 'init',
247                                       '-c', 'targets',
248                                       '-c', self.reset_halt_cmd,
249                                       '-c', 'load_image ' + self.elf_name,
250                                       '-c', 'resume ' + ep_addr,
251                                       '-c', 'shutdown'])
252        self.check_call(cmd)
253
254    def do_attach_debug(self, command, **kwargs):
255        if self.gdb_cmd is None:
256            raise ValueError('Cannot debug; no gdb specified')
257        if self.elf_name is None:
258            raise ValueError('Cannot debug; no .elf specified')
259
260        pre_init_cmd = []
261        for i in self.pre_init:
262            pre_init_cmd.append("-c")
263            pre_init_cmd.append(i)
264
265        if self.thread_info_enabled and self.supports_thread_info():
266            pre_init_cmd.append("-c")
267            pre_init_cmd.append("$_TARGETNAME configure -rtos Zephyr")
268
269        server_cmd = (self.openocd_cmd + self.serial + self.cfg_cmd +
270                      ['-c', 'tcl_port {}'.format(self.tcl_port),
271                       '-c', 'telnet_port {}'.format(self.telnet_port),
272                       '-c', 'gdb_port {}'.format(self.gdb_port)] +
273                      pre_init_cmd + ['-c', 'init', '-c', 'targets'] +
274                      self.halt_arg)
275        gdb_cmd = (self.gdb_cmd + self.tui_arg +
276                   ['-ex', 'target remote :{}'.format(self.gdb_port),
277                    self.elf_name])
278        if command == 'debug':
279            gdb_cmd.extend(['-ex', 'load'])
280        self.require(gdb_cmd[0])
281        self.print_gdbserver_message()
282        self.run_server_and_client(server_cmd, gdb_cmd)
283
284    def do_debugserver(self, **kwargs):
285        pre_init_cmd = []
286        for i in self.pre_init:
287            pre_init_cmd.append("-c")
288            pre_init_cmd.append(i)
289
290        cmd = (self.openocd_cmd + self.cfg_cmd +
291               ['-c', 'tcl_port {}'.format(self.tcl_port),
292                '-c', 'telnet_port {}'.format(self.telnet_port),
293                '-c', 'gdb_port {}'.format(self.gdb_port)] +
294               pre_init_cmd + ['-c', 'init',
295                                '-c', 'targets',
296                                '-c', self.reset_halt_cmd])
297        self.print_gdbserver_message()
298        self.check_call(cmd)
299