libjava/java/util/HashMap.h


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


// DO NOT EDIT THIS FILE - it is machine generated -*- c++ -*-

#ifndef __java_util_HashMap__
#define __java_util_HashMap__

#pragma interface

#include <java/util/AbstractMap.h>
#include <gcj/array.h>


class java::util::HashMap : public ::java::util::AbstractMap
{

public:
  HashMap();
  HashMap(::java::util::Map *);
  HashMap(jint);
  HashMap(jint, jfloat);
  virtual jint size();
  virtual jboolean isEmpty();
  virtual ::java::lang::Object * get(::java::lang::Object *);
  virtual jboolean containsKey(::java::lang::Object *);
  virtual ::java::lang::Object * put(::java::lang::Object *, ::java::lang::Object *);
  virtual void putAll(::java::util::Map *);
  virtual ::java::lang::Object * remove(::java::lang::Object *);
  virtual void clear();
  virtual jboolean containsValue(::java::lang::Object *);
  virtual ::java::lang::Object * clone();
  virtual ::java::util::Set * keySet();
  virtual ::java::util::Collection * values();
  virtual ::java::util::Set * entrySet();
public: // actually package-private
  virtual void addEntry(::java::lang::Object *, ::java::lang::Object *, jint, jboolean);
  virtual ::java::util::HashMap$HashEntry * getEntry(::java::lang::Object *);
  virtual jint hash(::java::lang::Object *);
  virtual ::java::util::Iterator * iterator(jint);
  virtual void putAllInternal(::java::util::Map *);
private:
  void rehash();
  void writeObject(::java::io::ObjectOutputStream *);
  void readObject(::java::io::ObjectInputStream *);
public: // actually package-private
  static const jint DEFAULT_CAPACITY = 16;
  static jfloat DEFAULT_LOAD_FACTOR;
private:
  static const jlong serialVersionUID = 362498820763181265LL;
  jint __attribute__((aligned(__alignof__( ::java::util::AbstractMap)))) threshold;
public: // actually package-private
  jfloat loadFactor;
  JArray< ::java::util::HashMap$HashEntry * > * buckets;
  jint modCount;
  jint size__;
private:
  ::java::util::Set * entries;
public:
  static ::java::lang::Class class$;
};

#endif // __java_util_HashMap__
import collections
import os
import os.path
import random
import re
import shlex
import subprocess
import sys
import tempfile
import time
import traceback

from datetime import datetime

import tty
import pexpect
import yaml

print_log_names = False
real_stdout = sys.stdout

# Note that gdb comes with its own testsuite. I was unable to figure out how to
# run that testsuite against the spike simulator.

class TestLibError(Exception):
    pass

def find_file(path):
    for directory in (os.getcwd(), os.path.dirname(__file__)):
        fullpath = os.path.join(directory, path)
        relpath = os.path.relpath(fullpath)
        if len(relpath) >= len(fullpath):
            relpath = fullpath
        if os.path.exists(relpath):
            return relpath
    return None

class CompileError(Exception):
    def __init__(self, stdout, stderr):
        super().__init__()
        self.stdout = stdout
        self.stderr = stderr

gcc_cmd = None
def compile(args): # pylint: disable=redefined-builtin
    cmd = [gcc_cmd]
    cmd.append("-g")
    for arg in args:
        found = find_file(arg)
        if found:
            cmd.append(found)
        else:
            cmd.append(arg)
    header("Compile")
    print("+", " ".join(cmd))
    with subprocess.Popen(cmd, stdout=subprocess.PIPE,
                          stderr=subprocess.PIPE) as process:
        stdout, stderr = process.communicate()
        if process.returncode:
            print(stdout.decode('ascii'), end=" ")
            print(stderr.decode('ascii'), end=" ")
            header("")
            raise CompileError(stdout, stderr)

class Spike:
    # pylint: disable=too-many-instance-attributes
    # pylint: disable=too-many-locals
    # pylint: disable=too-many-positional-arguments
    def __init__(self, target, halted=False, timeout=None, with_jtag_gdb=True,
            isa=None, progbufsize=None, dmi_rti=None, abstract_rti=None,
            support_hasel=True, support_abstract_csr=True,
            support_abstract_fpr=False,
            support_haltgroups=True, vlen=128, elen=64, harts=None):
        """Launch spike. Return tuple of its process and the port it's running
        on."""
        self.process = None
        self.isa = isa
        self.progbufsize = progbufsize
        self.dmi_rti = dmi_rti
        self.abstract_rti = abstract_rti
        self.support_abstract_csr = support_abstract_csr
        self.support_abstract_fpr = support_abstract_fpr
        self.support_hasel = support_hasel
        self.support_haltgroups = support_haltgroups
        self.vlen = vlen
        self.elen = elen

        self.harts = harts or target.harts or [target]

        cmd = self.command(target, halted, timeout, with_jtag_gdb)
        self.infinite_loop = target.compile(self.harts[0],
                "programs/checksum.c", "programs/tiny-malloc.c",
                "programs/infinite_loop.S", "-DDEFINE_MALLOC", "-DDEFINE_FREE")
        cmd.append(self.infinite_loop)
        # pylint: disable-next=consider-using-with
        self.logfile = tempfile.NamedTemporaryFile(prefix="spike-",
                suffix=".log")
        logname = self.logfile.name
        self.lognames = [logname]
        if print_log_names:
            real_stdout.write("Temporary spike log: {logname}\n")
        self.logfile.write(("+ " + " ".join(cmd) + "\n").encode())
        self.logfile.flush()
        # pylint: disable-next=consider-using-with
        self.process = subprocess.Popen(cmd, stdin=subprocess.PIPE,
                stdout=self.logfile, stderr=self.logfile)

        if with_jtag_gdb:
            self.port = None
            for _ in range(30):
                with open(logname, encoding='utf-8') as fd:
                    m = re.search(r"Listening for remote bitbang connection on "
                            r"port (\d+).", fd.read())
                if m:
                    self.port = int(m.group(1))
                    os.environ['REMOTE_BITBANG_PORT'] = m.group(1)
                    break
                time.sleep(0.11)
            if not self.port:
                print_log(logname)
                raise TestLibError("Didn't get spike message about bitbang "
                        "connection")

    # pylint: disable=too-many-branches
    def command(self, target, halted, timeout, with_jtag_gdb):
        if target.sim_cmd:
            cmd = shlex.split(target.sim_cmd)
        else:
            cmd = ["spike"]

        cmd += [f"-p{len(self.harts)}"]

        assert len(set(t.xlen for t in self.harts)) == 1, \
                "All spike harts must have the same XLEN"

        if self.isa:
            isa = self.isa
        else:
            isa = f"RV{self.harts[0].xlen}G"

        if 'V' in isa[2:]:
            isa += f"_Zvl{self.vlen}b_Zve{self.elen}d"

        cmd += ["--isa", isa]
        cmd += ["--dm-auth"]

        if not self.progbufsize is None:
            cmd += ["--dm-progsize", str(self.progbufsize)]
            cmd += ["--dm-sba", "64"]

        if not self.dmi_rti is None:
            cmd += ["--dmi-rti", str(self.dmi_rti)]

        if not self.abstract_rti is None:
            cmd += ["--dm-abstract-rti", str(self.abstract_rti)]

        if not self.support_abstract_csr:
            cmd.append("--dm-no-abstract-csr")

        if not self.support_abstract_fpr:
            cmd.append("--dm-no-abstract-fpr")

        if not self.support_hasel:
            cmd.append("--dm-no-hasel")

        if not self.support_haltgroups:
            cmd.append("--dm-no-halt-groups")


        assert len(set(t.ram for t in self.harts)) == 1, \
                "All spike harts must have the same RAM layout"
        assert len(set(t.ram_size for t in self.harts)) == 1, \
                "All spike harts must have the same RAM layout"
        os.environ['WORK_AREA'] = f'0x{self.harts[0].ram:x}'
        cmd += [f"-m0x{self.harts[0].ram:x}:0x{self.harts[0].ram_size:x}"]

        if timeout:
            cmd = ["timeout", str(timeout)] + cmd

        if halted:
            cmd.append('-H')
        if with_jtag_gdb:
            cmd += ['--rbb-port', '0']
            os.environ['REMOTE_BITBANG_HOST'] = 'localhost'

        return cmd

    def __del__(self):
        if self.process:
            try:
                self.process.kill()
                self.process.wait()
            except OSError:
                pass

    def wait(self, *args, **kwargs):
        return self.process.wait(*args, **kwargs)

class MultiSpike:
    def __init__(self, spikes):
        self.process = None

        self.spikes = spikes
        self.lognames = sum((spike.lognames for spike in spikes), [])
        # pylint: disable-next=consider-using-with
        self.logfile = tempfile.NamedTemporaryFile(prefix="daisychain-",
                suffix=".log")
        self.lognames.append(self.logfile.name)

        # Now create the daisy-chain process.
        cmd = ["./rbb_daisychain.py", "0"] + \
            [str(spike.port) for spike in spikes]
        self.logfile.write(f"+ {cmd}\n".encode())
        self.logfile.flush()
        # pylint: disable-next=consider-using-with
        self.process = subprocess.Popen(cmd, stdin=subprocess.PIPE,
                stdout=self.logfile, stderr=self.logfile)

        self.port = None
        for _ in range(30):
            with open(self.lognames[-1], encoding='utf=8') as fd:
                m = re.search(r"Listening on port (\d+).", fd.read())
            if m:
                self.port = int(m.group(1))
                break
            time.sleep(0.11)
        if not self.port:
            print_log(self.lognames[-1])
            raise TestLibError(
                    "Didn't get daisy chain message about which port "
                    "it's listening on.")

        os.environ['REMOTE_BITBANG_HOST'] = 'localhost'
        os.environ['REMOTE_BITBANG_PORT'] = str(self.port)

    def __del__(self):
        if self.process:
            try:
                self.process.kill()
                self.process.wait()
            except OSError:
                pass

class VcsSim:
    # pylint: disable-next=consider-using-with
    logfile = tempfile.NamedTemporaryFile(prefix='simv', suffix='.log')
    logname = logfile.name
    lognames = [logname]

    def __init__(self, sim_cmd=None, debug=False, timeout=300):
        if sim_cmd:
            cmd = shlex.split(sim_cmd)
        else:
            cmd = ["simv"]
        cmd += ["+jtag_vpi_enable"]
        if debug:
            cmd[0] = cmd[0] + "-debug"
            cmd += ["+vcdplusfile=output/gdbserver.vpd"]

        # pylint: disable-next=consider-using-with
        logfile = open(self.logname, "w", encoding='utf-8')
        if print_log_names:
            real_stdout.write(f"Temporary VCS log: {self.logname}\n")
        logfile.write("+ " + " ".join(cmd) + "\n")
        logfile.flush()

        with open(self.logname, "r", encoding='utf-8') as listenfile:
            listenfile.seek(0, 2)
            # pylint: disable-next=consider-using-with
            self.process = subprocess.Popen(cmd, stdin=subprocess.PIPE,
                    stdout=logfile, stderr=logfile)
            done = False
            start = time.time()
            while not done:
                # Fail if VCS exits early
                exit_code = self.process.poll()
                if exit_code is not None:
                    raise RuntimeError(
                        f'VCS simulator exited early with status {exit_code}')

                line = listenfile.readline()
                if not line:
                    time.sleep(1)
                match = re.match(r"^Listening on port (\d+)$", line)
                if match:
                    done = True
                    self.port = int(match.group(1))
                    os.environ['JTAG_VPI_PORT'] = str(self.port)

                if (time.time() - start) > timeout:
                    raise TestLibError(
                        "Timed out waiting for VCS to listen for JTAG vpi")

    def __del__(self):
        try:
            self.process.kill()
            self.process.wait()
        except OSError:
            pass

class Openocd:
    # pylint: disable=too-many-instance-attributes
    # pylint: disable-next=consider-using-with
    # pylint: disable=too-many-positional-arguments
    # pylint: disable=consider-using-with
    logfile = tempfile.NamedTemporaryFile(prefix='openocd', suffix='.log')
    logname = logfile.name

    def __init__(self, server_cmd=None, config=None, debug=False, timeout=60,
                 freertos=False, debug_openocd=False):
        self.timeout = timeout
        self.debug_openocd = debug_openocd
        self.command_count = 0

        if server_cmd:
            cmd = shlex.split(server_cmd)
        else:
            cmd = ["openocd"]

        # This command needs to come before any config scripts on the command
        # line, since they are executed in order.
        cmd += [
            # Tell OpenOCD to bind gdb to an unused, ephemeral port.
            "--command", "gdb_port 0",
            # We create a socket for OpenOCD command line (TCL-RPC)
            "--command", "tcl_port 0",
            # don't use telnet
            "--command", "telnet_port disabled",
        ]

        if config:
            self.config_file = find_file(config)
            if self.config_file is None:
                print("Unable to read file", config)
                sys.exit(1)

            cmd += ["-f", self.config_file]

        if debug:
            cmd.append("-d")

        extra_env = {}
        if freertos:
            extra_env['USE_FREERTOS'] = "1"
        else:
            extra_env['USE_FREERTOS'] = "0"

        # pylint: disable-next=consider-using-with
        raw_logfile = open(Openocd.logname, "wb")
        # pylint: disable-next=consider-using-with
        self.read_log_fd = open(Openocd.logname, "rb")
        self.log_buf = b""
        try:
            # pylint: disable-next=consider-using-with
            spike_dasm = subprocess.Popen("spike-dasm", stdin=subprocess.PIPE,
                    stdout=raw_logfile, stderr=raw_logfile)
            logfile = spike_dasm.stdin
        except FileNotFoundError:
            logfile = raw_logfile
        if print_log_names:
            real_stdout.write(f"Temporary OpenOCD log: {Openocd.logname}\n")
        env_entries = ("REMOTE_BITBANG_HOST", "REMOTE_BITBANG_PORT",
                "WORK_AREA")
        env_entries = [key for key in env_entries if key in os.environ]
        parts = [
            " ".join(f"{key}={os.environ[key]}" for key in env_entries),
            " ".join(f"{k}={v}" for k, v in extra_env.items()),
            " ".join(map(shlex.quote, cmd))
        ]
        logfile.write(("+ " + " ".join(parts) + "\n").encode())
        logfile.flush()

        self.gdb_ports = []
        self.tclrpc_port = None
        self.start(cmd, logfile, extra_env)

        self.openocd_cli = pexpect.spawn(f"nc localhost {self.tclrpc_port}",
            echo=False)
        # TCL-RPC uses \x1a as a watermark for end of message. We set raw
        # pty mode to disable translation of \x1a to EOF
        tty.setraw(self.openocd_cli.child_fd)
        hello_string = self.command(
            "capture { echo \"Hello TCL-RPC!\" }").decode()
        if not "Hello TCL-RPC!" in hello_string:
            raise RuntimeError(f"TCL-RPC - unexpected reply:\n{hello_string}")

    def start(self, cmd, logfile, extra_env):
        combined_env = {**os.environ, **extra_env}
        # pylint: disable-next=consider-using-with
        self.process = subprocess.Popen(cmd, stdin=None,
                stdout=logfile, stderr=logfile, env=combined_env)

        try:
            # Wait for OpenOCD to have made it through riscv_examine(). When
            # using OpenOCD to communicate with a simulator this may take a
            # long time, and gdb will time out when trying to connect if we
            # attempt too early.
            while True:
                m = self.expect(
                        rb"Listening on port (?P<port>\d+) for "
                        rb"(?P<server>(?:gdb)|(?:tcl)) connections",
                        message="Waiting for OpenOCD to start up...")
                if m["server"] == b"gdb":
                    self.gdb_ports.append(int(m["port"]))
                elif m["server"] == b"tcl":
                    if self.tclrpc_port:
                        raise TestLibError(
                            "unexpected re-definition of TCL-RPC port")
                    self.tclrpc_port = int(m["port"])
                # WARNING! WARNING! WARNING!
                # The condition below works properly only if OpenOCD reports
                # gdb/tcl ports in a specific order. Namely, it requires the
                # gdb ports to be reported before the tcl one. At the moment
                # this comment was written OpenOCD reports these ports in the
                # required order if we have a call to `init` statement in
                # either target configuration file or command-line parameter.
                # All configuration files used in testing include a call to
                # `init`
                if self.tclrpc_port and (len(self.gdb_ports) > 0):
                    break

            if self.debug_openocd:
                # pylint: disable=consider-using-with
                self.debugger = subprocess.Popen(["gnome-terminal", "-e",
                                            f"gdb --pid={self.process.pid}"])
        except Exception:
            print_log(Openocd.logname)
            raise

    def __del__(self):
        try:
            self.process.terminate()
            start = time.time()
            while time.time() < start + 10:
                if self.process.poll():
                    break
            else:
                self.process.kill()
        except (OSError, AttributeError):
            pass

    def smp(self):
        """Return true iff OpenOCD internally sees the harts as part of an SMP
        group."""
        with open(self.config_file, "r", encoding='utf-8') as handle:
            for line in handle:
                if "target smp" in line:
                    return True
        return False

    def command(self, cmd):
        """Send the command to OpenOCD's TCL-RPC server. Return the output of
        the command, minus the prompt."""
        self.openocd_cli.write(f"{cmd}\n\x1a")
        self.openocd_cli.expect(rb"(.*)\x1a")
        m = self.openocd_cli.match.group(1)
        return m

    def expect(self, regex, message=None):
        """Wait for the regex to match the log, and return the match object. If
        message is given, print it while waiting.
        We read the logfile to tell us what OpenOCD has done."""
        messaged = False
        start = time.time()

        while True:
            for line in self.read_log_fd.readlines():
                line = line.rstrip()
                # Remove nulls, carriage returns, and newlines.
                line = re.sub(rb"[\x00\r\n]+", b"", line)
                # Remove debug messages.
                debug_match = re.search(rb"Debug: \d+ \d+ .*", line)
                if debug_match:
                    line = line[:debug_match.start()] + line[debug_match.end():]
                    self.log_buf += line
                else:
                    self.log_buf += line + b"\n"

            m = re.search(regex, self.log_buf, re.MULTILINE | re.DOTALL)
            if m:
                self.log_buf = self.log_buf[m.end():]
                return m

            if not self.process.poll() is None:
                raise TestLibError("OpenOCD exited early.")

            if message and not messaged and time.time() - start > 1:
                messaged = True
                print(message)

            if (time.time() - start) > self.timeout:
                raise TestLibError(f"Timed out waiting for {regex} in "
                                   f"{Openocd.logname}")

            time.sleep(0.1)

    def targets(self):
        """Run `targets` command."""
        result = self.command("targets").decode()
        #     TargetName         Type       Endian TapName            State
        # --  ------------------ ---------- ------ ------------------ --------
        #  0* riscv.cpu          riscv      little riscv.cpu          halted
        lines = result.splitlines()
        headers = lines[0].split()
        data = []
        for line in lines[2:]:
            if line.strip():
                data.append(dict(zip(headers, line.split()[1:])))
        return data

    def wait_until_running(self, harts):
        """Wait until the given harts are running."""
        start = time.time()
        while True:
            targets = self.targets()
            if all(targets[hart.id]["State"] == "running" for hart in harts):
                return
            if time.time() - start > self.timeout:
                raise TestLibError("Timed out waiting for targets to run.")

    def set_available(self, harts):
        """Set the given harts to available, and any others to be unavailable.
        This uses a custom DMI register (0x1f) that is only implemented in
        spike."""
        available_mask = 0
        for hart in harts:
            available_mask |= 1 << hart.id
        self.command(f"riscv dmi_write 0x1f 0x{available_mask:x}")

        # Wait until it happened.
        start = time.time()
        while True:
            currently_available = set()
            currently_unavailable = set()
            for i, target in enumerate(self.targets()):
                if target["State"] == "unavailable":
                    currently_unavailable.add(i)
                else:
                    currently_available.add(i)
            if currently_available == set(hart.id for hart in harts):
                return
            if time.time() - start > self.timeout:
                raise TestLibError("Timed out waiting for hart availability.")

class OpenocdCli:
    def __init__(self, port=4444):
        self.child = pexpect.spawn(
                f"sh -c 'telnet localhost {port} | tee openocd-cli.log'")
        self.child.expect("> ")

    def command(self, cmd):
        self.child.sendline(cmd)
        self.child.expect(cmd)
        self.child.expect("\n")
        self.child.expect("> ")
        return self.child.before.strip("\t\r\n \0").decode("utf-8")

    def reg(self, reg=''):
        output = self.command(f"reg {reg}")
        matches = re.findall(r"(\w+) \(/\d+\): (0x[0-9A-F]+)", output)
        values = {r: int(v, 0) for r, v in matches}
        if reg:
            return values[reg]
        return values

    def load_image(self, image):
        output = self.command(f"load_image {image}")
        if 'invalid ELF file, only 32bits files are supported' in output:
            raise TestNotApplicable(output)

class CannotAccess(Exception):
    def __init__(self, address):
        Exception.__init__(self)
        self.address = address

class CannotInsertBreakpoint(Exception):
    def __init__(self, number):
        Exception.__init__(self)
        self.number = number

class CouldNotFetch(Exception):
    def __init__(self, regname, explanation):
        Exception.__init__(self)
        self.regname = regname
        self.explanation = explanation

class CouldNotReadRegisters(Exception):
    def __init__(self, explanation):
        Exception.__init__(self)
        self.explanation = explanation

class NoSymbol(Exception):
    def __init__(self, symbol):
        Exception.__init__(self)
        self.symbol = symbol

    def __repr__(self):
        return f"NoSymbol({self.symbol!r})"

class UnknownThread(Exception):
    def __init__(self, explanation):
        Exception.__init__(self, explanation)

class ThreadTerminated(Exception):
    pass

Thread = collections.namedtuple('Thread', ('id', 'description', 'target_id',
    'name', 'frame'))

class Repeat:
    def __init__(self, count):
        self.count = count

def tokenize(text):
    index = 0
    while index < len(text):
        for regex, fn in (
                (r"[\s]+", lambda m: None),
                (r"[,{}=]", lambda m: m.group(0)),
                (r"0x[\da-fA-F]+", lambda m: int(m.group(0)[2:], 16)),
                (r"-?\d*\.\d+(e[-+]\d+)?", lambda m: float(m.group(0))),
                (r"-?\d+", lambda m: int(m.group(0))),
                # We want something that can compare equal, and float(nan) does
                # not do that. So use something else that isn't good for math,
                # but we don't actually do math with NaN.
                (r"-?nan\(0x[a-f0-9]+\)", lambda m: "nan"),
                (r"<repeats (\d+) times>", lambda m: Repeat(int(m.group(1)))),
                (r"Could not fetch register \"(\w+)\"; (.*)$",
                    lambda m: CouldNotFetch(m.group(1), m.group(2))),
                (r"Could not read registers; (.*)$",
                    lambda m: CouldNotReadRegisters(m.group(1))),
                (r"Cannot access memory at address (0x[0-9a-f]+)",
                    lambda m: CannotAccess(int(m.group(1), 0))),
                (r"Cannot insert breakpoint (\d+).",
                    lambda m: CannotInsertBreakpoint(int(m.group(1)))),
                (r'No symbol "(\w+)" in current context.',
                    lambda m: NoSymbol(m.group(1))),
                (r'"([^"]*)"', lambda m: m.group(1)),
                (r"[a-zA-Z][a-zA-Z\d]*", lambda m: m.group(0)),
                ):
            m = re.match(regex, text[index:])
            if m:
                index += len(m.group(0))
                token = fn(m)
                if not token is None:
                    yield token
                break
        else:
            raise TestLibError(repr(text[index:]))

def parse_dict(tokens):
    assert tokens[0] == "{"
    tokens.pop(0)
    result = {}
    while True:
        key = tokens.pop(0)
        assert tokens.pop(0) == "="
        value = parse_tokens(tokens)
        result[key] = value
        token = tokens.pop(0)
        if token == "}":
            return result
        assert token == ","

def parse_list(tokens):
    assert tokens[0] == "{"
    tokens.pop(0)
    result = []
    while True:
        result.append(tokens.pop(0))
        token = tokens.pop(0)
        if isinstance(token, Repeat):
            result += [result[-1]] * (token.count - 1)
            token = tokens.pop(0)
        if token == "}":
            return result
        assert token == ","

def parse_dict_or_list(tokens):
    assert tokens[0] == "{"
    if tokens[2] == "=":
        return parse_dict(tokens)
    else:
        return parse_list(tokens)

def parse_tokens(tokens):
    if isinstance(tokens[0], Exception):
        raise tokens[0]
    if isinstance(tokens[0], (float, int)):
        return tokens.pop(0)
    if tokens[0] == "{":
        return parse_dict_or_list(tokens)
    if isinstance(tokens[0], str):
        return tokens.pop(0)
    raise TestLibError(f"Unsupported tokens: {tokens!r}")

def parse_rhs(text):
    tokens = list(tokenize(text))
    result = parse_tokens(tokens)
    if tokens:
        raise TestLibError(f"Unexpected input: {tokens!r}")
    return result

class CommandException(Exception):
    pass

class CommandSendTimeout(CommandException):
    pass

class CommandCompleteTimeout(CommandException):
    pass

class Gdb:
    """A single gdb class which can interact with one or more gdb instances."""

    # pylint: disable=too-many-public-methods
    # pylint: disable=too-many-instance-attributes

    reset_delays = (127, 181, 17, 13, 83, 151, 31, 67, 131, 167, 23, 41, 61,
            11, 149, 107, 163, 73, 47, 43, 173, 7, 109, 101, 103, 191, 2, 139,
            97, 193, 157, 3, 29, 79, 113, 5, 89, 19, 37, 71, 179, 59, 137, 53)

    # pylint: disable=too-many-positional-arguments
    def __init__(self, target, ports, cmd=None, timeout=60, binaries=None,
                 logremote=False):
        assert ports

        self.target = target
        self.ports = ports
        self.cmd = cmd
        self.timeout = timeout
        self.binaries = binaries or [None] * len(ports)

        self.reset_delay_index = 0
        self.stack = []
        self.harts = {}

        self.logfiles = []
        self.children = []
        for port in ports:
            # pylint: disable-next=consider-using-with
            logfile = tempfile.NamedTemporaryFile(prefix=f"gdb@{port}-",
                                                  suffix=".log")
            self.logfiles.append(logfile)
            if print_log_names:
                real_stdout.write(f"Temporary gdb log: {logfile.name}\n")
            child = pexpect.spawn(self.cmd)
            child.logfile = logfile
            child.logfile.write(f"+ {self.cmd}\n".encode())
            self.children.append(child)
            self.select_child(child)
            self.wait()
            self.command("set style enabled off", reset_delays=None)
            self.command("set confirm off", reset_delays=None)
            self.command("set width 0", reset_delays=None)
            self.command("set height 0", reset_delays=None)
            # Force consistency.
            self.command("set print entry-values no", reset_delays=None)
            self.command(f"set remotetimeout {self.timeout}", reset_delays=None)
            if logremote:
                # pylint: disable-next=consider-using-with
                remotelog = tempfile.NamedTemporaryFile(
                    prefix=f"remote.gdb@{port}-", suffix=".log")
                if print_log_names:
                    real_stdout.write(
                        f"Temporary remotelog: {remotelog.name}\n")
                self.logfiles.append(remotelog)
                self.command(f"set remotelogfile {remotelog.name}",
                             reset_delays=None)
        self.active_child = self.children[0]

    def connect(self):
        with PrivateState(self):
            for port, child, binary in zip(self.ports, self.children,
                                        self.binaries):
                self.select_child(child)
                self.command(f"target extended-remote localhost:{port}",
                        ops=10, reset_delays=None)
                if binary:
                    output = self.command(f"file {binary}")
                    assertIn("Reading symbols", output)
                threads = self.threads()
                for t in threads:
                    hartid = None
                    if t.name:
                        m = re.search(r"Hart (\d+)", t.name)
                        if m:
                            hartid = int(m.group(1))
                    if hartid is None:
                        if self.harts:
                            hartid = max(self.harts) + 1
                        else:
                            hartid = 0
                    # solo: True iff this is the only thread on this child
                    self.harts[hartid] = {'child': child,
                            'thread': t,
                            'solo': len(threads) == 1}

    def disconnect(self):
        with PrivateState(self):
            for child in self.children:
                self.select_child(child)
                self.command("disconnect")

    def __del__(self):
        for i, _ in enumerate(self.children):
            del self.children[i]

    def one_hart_per_gdb(self):
        return all(h['solo'] for h in self.harts.values())

    def lognames(self):
        return [logfile.name for logfile in self.logfiles]

    def select_child(self, child):
        self.active_child = child

    def select_hart(self, hart):
        h = self.harts[hart.id]
        self.select_child(h['child'])
        if not h['solo']:
            output = self.command(f"thread {h['thread'].id}", ops=5)
            if "Unknown" in output:
                raise UnknownThread(output)
            if f"Thread ID {h['thread'].id} has terminated" in output:
                raise ThreadTerminated(output)

    def push_state(self):
        self.stack.append({
            'active_child': self.active_child
            })

    def pop_state(self):
        state = self.stack.pop()
        self.active_child = state['active_child']

    def wait(self):
        """Wait for prompt."""
        self.active_child.expect(r"\(gdb\)")

    def command(self, command, ops=1, reset_delays=0):
        """ops is the estimated number of operations gdb will have to perform
        to perform this command. It is used to compute a timeout based on
        self.timeout."""
        if not reset_delays is None:
            if reset_delays == 0:
                reset_delays = self.reset_delays[self.reset_delay_index]
                self.reset_delay_index = (self.reset_delay_index + 1) % \
                        len(self.reset_delays)
            self.command(f"monitor riscv reset_delays {reset_delays}",
                    reset_delays=None)
        timeout = max(1, ops) * self.timeout
        self.active_child.sendline(command)
        try:
            self.active_child.expect(re.escape(command), timeout=timeout)
            self.active_child.expect("\n", timeout=timeout)
        except pexpect.exceptions.TIMEOUT as exc:
            raise CommandSendTimeout(command) from exc
        try:
            self.active_child.expect(r"\(gdb\)", timeout=timeout)
        except pexpect.exceptions.TIMEOUT as exc:
            raise CommandCompleteTimeout(command) from exc
        output = self.active_child.before.decode("utf-8", errors="ignore")
        ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
        return ansi_escape.sub('', output).strip()

    def interact(self):
        """Call this from a test at a point where you just want to interact with
        gdb directly. This is useful when you're debugging a problem and just
        want to take over at a certain point in the test."""
        saved_stdout = sys.stdout
        sys.stdout = real_stdout
        try:
            print()
            print("Interact with the gdb instance created by the test.")
            print("This is not a true gdb prompt, so things like tab ")
            print("completion won't work.")
            while True:
                command = input("(gdb) ")
                print(self.command(command))
        finally:
            sys.stdout = saved_stdout


    def global_command(self, command):
        """Execute this command on every gdb that we control."""
        with PrivateState(self):
            for child in self.children:
                self.select_child(child)
                self.command(command)

    def system_command(self, command, ops=20):
        """Execute this command on every unique system that we control."""
        done = set()
        output = ""
        with PrivateState(self):
            for i, child in enumerate(self.children):
                self.select_child(child)
                if self.target.harts[i].system in done:
                    self.command("set $pc=_start")
                else:
                    output += self.command(command, ops=ops)
                    done.add(self.target.harts[i].system)
        return output

    def c(self, wait=True, sync=True, checkOutput=True, ops=20):
        """
        Dumb c command.
        In RTOS mode, gdb will resume all harts.
        In multi-gdb mode, this command will just go to the current gdb, so
        will only resume one hart.
        """
        if sync:
            sync = ""
        else:
            sync = "&"
        if wait:
            output = self.command(f"c{sync}", ops=ops)
            if checkOutput:
                assert "Continuing" in output
                assert "Could not insert hardware" not in output
            return output
        else:
            self.active_child.sendline(f"c{sync}")