hector-cli 0.1.0__py3-none-any.whl

hector/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+from .core import TOOL_VERSION
+
+__version__ = TOOL_VERSION

hector/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Enable `python -m hector`, equivalent to the `hector` console script."""
+
+from hector.pipeline import main
+
+if __name__ == "__main__":
+    main()

hector/commands/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""hector's command surface: one `hector <name>` subcommand per module here.
+
+Importing this package registers every command into COMMANDS; build_parser() then
+wires them all into a single argparse parser. To add a command, create a module
+(see run.py for the template) and add it to the import list below.
+"""
+
+import argparse
+
+from ..core import TOOL_VERSION
+from .base import COMMANDS, Command, add_common_arguments, add_simulation_arguments
+
+# Importing each module runs its @COMMANDS.register(...) decorator.
+from . import run, test, export, init, validate  # noqa: E402,F401
+
+__all__ = ["COMMANDS", "Command", "build_parser",
+           "add_common_arguments", "add_simulation_arguments"]
+
+
+def build_parser():
+    """Assemble the top-level `hector` parser with one subparser per registered command."""
+    parser = argparse.ArgumentParser(
+        prog="hector",
+        description="YAML-driven Renode + Verilator simulation orchestrator",
+    )
+    parser.add_argument("--version", action="version", version=f"hector {TOOL_VERSION}")
+
+    sub = parser.add_subparsers(dest="command", required=True, metavar="<command>")
+    for name in sorted(COMMANDS.keys()):
+        cmd = COMMANDS.get(name)()      # the registry holds classes; instantiate
+        sp = sub.add_parser(cmd.name, help=cmd.help, description=cmd.help)
+        cmd.add_arguments(sp)
+        sp.set_defaults(_command=cmd)
+    return parser

hector/commands/base.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Command framework: a tiny registry + base class so each subcommand is a
+self-contained module.
+
+To add a command, drop a module in this package that subclasses Command, fills in
+name/help, declares its flags in add_arguments(), does its work in execute(), and
+registers itself with @COMMANDS.register("<name>"). Import it from __init__.py and
+`hector <name>` exists — no central switch to edit.
+"""
+
+from ..core import Registry
+
+COMMANDS = Registry("command")
+
+
+class Command:
+    """One `hector <name>` subcommand."""
+    name = ""          # the subcommand word, e.g. "run"
+    help = ""          # one-line description shown in `hector --help`
+
+    def add_arguments(self, parser):
+        """Declare this command's flags on its argparse subparser."""
+
+    def execute(self, args):
+        """Do the work. Return a process exit code (0 = success, falsy == 0)."""
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# Reusable flag groups (shared so each command's surface stays consistent)
+# ---------------------------------------------------------------------------
+
+def add_common_arguments(parser):
+    """Flags shared by the config-driven commands (run / test / export): they all
+    read .hector.yaml, pin a Renode version, expand the matrix, and collect output."""
+    parser.add_argument(
+        "--set", action="append", metavar="KEY=VALUE", dest="set_args",
+        help="Override a config argument. Repeatable. Takes precedence over env vars "
+             "and config defaults. Example: --set BIN=fw.elf --set BOARD=nucleo.",
+    )
+    parser.add_argument(
+        "--renode-version", metavar="VERSION", dest="renode_version",
+        help="Renode version to use (e.g. 1.16.1). Overrides renode_version from "
+             ".hector.yaml.",
+    )
+    parser.add_argument(
+        "--renode-dir", metavar="PATH", dest="renode_dir", default=None,
+        help="Location of the Renode source checkout (only fetched when a config builds "
+             "'modules:' or uses ${RENODE_DIR}). Reused if it exists, cloned there if "
+             "not. Default: .hector/renode. Point it at a cache to avoid re-cloning.",
+    )
+    parser.add_argument(
+        "--renode-integration-dir", metavar="PATH", dest="renode_integration_dir",
+        default=None,
+        help="Location of the renode-verilator-integration checkout (see --renode-dir). "
+             "Default: .hector/renode-verilator-integration.",
+    )
+    parser.add_argument(
+        "--output", metavar="DIR", default="results",
+        help="Directory for test results, artifacts, and simulation output files "
+             "(default: results).",
+    )
+    parser.add_argument(
+        "--artifacts", action="append", metavar="GLOB", dest="artifacts",
+        help="Glob pattern(s) for output files to collect into <output>/artifacts/ "
+             "after each job. Repeatable. Overrides the top-level 'artifacts:' in "
+             ".hector.yaml when given.",
+    )
+    parser.add_argument(
+        "--gather-execution-metrics", action="append", nargs="?", const=None,
+        metavar="NODE", dest="gather_execution_metrics",
+        help="Enable Renode's CPU execution profiler. With no argument, enables it for "
+             "all machines. Pass a node name to target one machine. Repeatable. Writes "
+             "one binary file per node to the output directory.",
+    )
+    parser.add_argument(
+        "--job", metavar="KEY=VALUE",
+        help="Select the matrix combination to run, e.g. --job BOARD=stm32f7 "
+             "(repeat keys with commas: --job BOARD=stm32f7,FW=release.elf). Required "
+             "when a matrix is defined — hector runs one combination per invocation and "
+             "does not expand the matrix itself (that's the CI's job).",
+    )
+    docker_mode = parser.add_mutually_exclusive_group()
+    docker_mode.add_argument(
+        "--no-docker", action="store_true", dest="no_docker",
+        help="Call the locally installed renode / renode-test binaries directly "
+             "instead of launching a Docker container.",
+    )
+    docker_mode.add_argument(
+        "--workspace-mount", metavar="PATH", dest="workspace_mount", default=None,
+        help="Container path where the project root is bind-mounted "
+             "(default: same absolute path as on the host).",
+    )
+
+
+def add_simulation_arguments(parser):
+    """Flags shared by commands that assemble/boot a single emulation (run / export)."""
+    parser.add_argument(
+        "--debug", action="append", metavar="NODE:PORT",
+        help="Halt the CPU and open a GDB server for each named node. Repeatable: "
+             "--debug boardA:3333 --debug boardB:3334.",
+    )
+    parser.add_argument(
+        "--snapshot", metavar="PATH", dest="snapshot",
+        help="Load a Renode snapshot instead of booting from the generated resc.",
+    )
+    parser.add_argument(
+        "--renode-args", metavar="ARGS", dest="renode_args", default="",
+        help="Extra arguments passed verbatim to Renode "
+             "(e.g. --renode-args '--console --hide-log').",
+    )

hector/commands/export.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector export` — generate the emulation files but, instead of running, print
+the command that would run them.
+
+Emits the `docker run ... renode ...` invocation (or the bare `renode ...` command
+under --no-docker) for each matrix job, so you can inspect, copy, or wrap it.
+"""
+
+from .. import pipeline
+from .base import COMMANDS, Command, add_common_arguments, add_simulation_arguments
+
+
+@COMMANDS.register("export")
+class ExportCommand(Command):
+    name = "export"
+    help = "Generate the files and print the run command instead of executing it."
+
+    def add_arguments(self, parser):
+        add_common_arguments(parser)
+        add_simulation_arguments(parser)
+
+    def execute(self, args):
+        pipeline.apply_global_flags(args)
+        config = pipeline.load_config_or_exit()
+        cfg = pipeline.build_job_config(pipeline.action_export, config, args)
+        return pipeline.execute_jobs(cfg, args)

hector/commands/init.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector init` — scaffold a new .hector.yaml in the current directory."""
+
+from ..scaffold import scaffold_init
+from .base import COMMANDS, Command
+
+
+@COMMANDS.register("init")
+class InitCommand(Command):
+    name = "init"
+    help = "Scaffold a new .hector.yaml in the current directory."
+
+    def execute(self, args):
+        scaffold_init()
+        return 0

hector/commands/run.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector run` — boot the emulation interactively in the Renode monitor."""
+
+from .. import pipeline
+from .base import COMMANDS, Command, add_common_arguments, add_simulation_arguments
+
+
+@COMMANDS.register("run")
+class RunCommand(Command):
+    name = "run"
+    help = "Build the emulation and run it interactively in Renode."
+
+    def add_arguments(self, parser):
+        add_common_arguments(parser)
+        add_simulation_arguments(parser)
+
+    def execute(self, args):
+        pipeline.apply_global_flags(args)
+
+        # Convenience fast path: a snapshot + pinned version needs no .hector.yaml.
+        if args.snapshot and args.renode_version:
+            pipeline.snapshot_fastpath(args)
+            return 0
+
+        config = pipeline.load_config_or_exit()
+        cfg = pipeline.build_job_config(pipeline.action_simulate, config, args)
+        return pipeline.execute_jobs(cfg, args)

hector/commands/test.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector test` — run the `tests:` section; exit 1 on any failure."""
+
+from .. import pipeline
+from .base import COMMANDS, Command, add_common_arguments
+
+
+@COMMANDS.register("test")
+class TestCommand(Command):
+    name = "test"
+    help = "Run the 'tests:' section against the generated emulation; exit 1 on failure."
+
+    def add_arguments(self, parser):
+        add_common_arguments(parser)
+        parser.add_argument(
+            "--test-file", metavar="FILE", dest="test_file",
+            help="Run a specific .robot file against the generated resc instead of the "
+                 "YAML-defined tests. ${RESC} expands to the resc path.",
+        )
+        parser.add_argument(
+            "--test-name", metavar="NAME", dest="test_name", action="append",
+            help="Run only tests whose name contains NAME. Repeatable.",
+        )
+        parser.add_argument(
+            "--reporters", action="append", metavar="REPORTER", dest="reporters",
+            help="Reporter to call after tests. Repeatable (default: junit). "
+                 "Example: --reporters junit --reporters json.",
+        )
+        parser.add_argument(
+            "--live", action="store_true",
+            help="Stream bash test output line-by-line and run robot tests verbosely.",
+        )
+        parser.add_argument(
+            "--snapshot", metavar="PATH", dest="snapshot",
+            help="Load a Renode snapshot at the start of every test instead of booting "
+                 "from the resc. Overrides per-test 'snapshot:' fields.",
+        )
+        parser.add_argument(
+            "--renode-test-args", metavar="ARGS", dest="renode_test_args", default="",
+            help="Extra arguments passed verbatim to renode-test "
+                 "(e.g. --renode-test-args '--loglevel DEBUG').",
+        )
+        parser.add_argument(
+            "--fail-fast", action="store_true", dest="fail_fast",
+            help="Stop after the first failing test instead of running them all.",
+        )
+
+    def execute(self, args):
+        pipeline.apply_global_flags(args)
+        config = pipeline.load_config_or_exit()
+        cfg = pipeline.build_job_config(pipeline.action_test, config, args, test_mode=True)
+        return pipeline.execute_jobs(cfg, args)

hector/commands/validate.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector validate` — check .hector.yaml without running anything; exit 1 on errors."""
+
+from .. import pipeline
+from .base import COMMANDS, Command
+
+
+@COMMANDS.register("validate")
+class ValidateCommand(Command):
+    name = "validate"
+    help = "Validate .hector.yaml without running anything; exit 1 on errors."
+
+    def execute(self, args):
+        # _run_validate prints a report and exits with the right code itself.
+        pipeline._run_validate()

hector/connections.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+Connection resolution. Generic over the HUBS registry, so adding a hub type needs no
+change here.
+
+  intra-machine (same node, '->')   -> repl updating entry (GPIO/IRQ wire)
+  periph <-> hub  /  port@pin -> hub -> cross-machine link via a declared hub
+"""
+
+import re
+
+from .core import parse_endpoint
+from .hubs import HUBS
+
+
+def is_hub_line(line, hubs_registry):
+    """Return True if any token in the line is a declared hub name."""
+    for tok in re.split(r"<->|->", line):
+        base = re.split(r"[@\[]", tok.strip())[0]
+        if "." not in base and base in hubs_registry:
+            return True
+    return False
+
+
+def _expand_chains(connections):
+    """Expand inline hub-chain syntax into two separate endpoint↔hub lines.
+
+    Symmetric:    A <-> hub <-> B   →   A <-> hub  +  B <-> hub
+    Directional:  A -> hub -> B    →   A -> hub   +  hub -> B
+    """
+    result = []
+    for line in connections:
+        parts = line.split("<->")
+        if len(parts) == 3:
+            a, hub, b = (p.strip() for p in parts)
+            result += [f"{a} <-> {hub}", f"{b} <-> {hub}"]
+            continue
+        if "<->" not in line:
+            parts = line.split("->")
+            if len(parts) == 3:
+                a, hub, b = (p.strip() for p in parts)
+                result += [f"{a} -> {hub}", f"{hub} -> {b}"]
+                continue
+        result.append(line)
+    return result
+
+
+def qualify_node_connection(line, node_name, hubs_registry, known_nodes=None):
+    """Qualify bare peripheral names in a per-node connections block with the node name.
+    Hub names and already-qualified 'node.x' tokens are left unchanged.
+    'periph.Signal' tokens (where periph is not a node) are qualified as 'node.periph.Signal'."""
+    known_nodes = known_nodes or set()
+    def q(tok):
+        tok = tok.strip()
+        base = tok.split("@", 1)[0]
+        if "." in base:
+            prefix = base.split(".", 1)[0]
+            if prefix in known_nodes or prefix in hubs_registry:
+                return tok
+            return f"{node_name}.{tok}"
+        return tok if base in hubs_registry else f"{node_name}.{tok}"
+    parts = line.split("<->")
+    if len(parts) == 3:
+        a, hub, b = (p.strip() for p in parts)
+        return f"{q(a)} <-> {hub} <-> {q(b)}"
+    if "<->" not in line:
+        parts = line.split("->")
+        if len(parts) == 3:
+            a, hub, b = (p.strip() for p in parts)
+            return f"{q(a)} -> {hub} -> {q(b)}"
+    if "<->" in line:
+        a, b = line.split("<->", 1); return f"{q(a)} <-> {q(b)}"
+    if "->" in line:
+        a, b = line.split("->", 1); return f"{q(a)} -> {q(b)}"
+    raise ValueError(f"Connection '{line}' (node '{node_name}') has no '->' or '<->'")
+
+
+def resolve_connections(connections, concrete_nodes, hubs_registry):
+    """Return cross_connection_specs for hub-connected endpoints.
+    All intra-machine wires must have been injected into _repl_signals before calling this.
+    `hubs_registry` maps a hub NAME to its declared type string."""
+    def check_node(node, line):
+        if node not in concrete_nodes:
+            raise ValueError(f"Connection '{line}': unknown node '{node}'.")
+        if concrete_nodes[node].get("backend", "renode") != "renode":
+            raise ValueError(f"Connection '{line}': '{node}' is not a renode node.")
+
+    specs = []
+    hub_specs = {}
+    for line in _expand_chains(connections):
+        if "<->" in line:  a, b = line.split("<->", 1); op = "<->"
+        elif "->" in line: a, b = line.split("->", 1); op = "->"
+        else: raise ValueError(f"Connection '{line}' has no '->' or '<->'")
+        a, b = a.strip(), b.strip()
+        a_hub = is_hub_line(a, hubs_registry)
+        b_hub = is_hub_line(b, hubs_registry)
+
+        if not a_hub and not b_hub:
+            raise ValueError(
+                f"Connection '{line}': non-hub connection reached resolve_connections. "
+                "Cross-machine links require a hub declared under 'hubs:'. "
+                "Intra-machine wires belong in the per-node 'connections:' block.")
+
+        if a_hub and b_hub:
+            raise ValueError(f"Connection '{line}': both sides are hubs.")
+
+        hub_name = (a if a_hub else b).split("@", 1)[0]
+        ep = parse_endpoint(b if a_hub else a)
+        check_node(ep["node"], line)
+        hub_cls = HUBS.get(hubs_registry[hub_name])
+
+        if hub_cls.symmetric and op != "<->":
+            raise ValueError(f"Connection '{line}': '{hub_name}' is symmetric; use '<->'.")
+        if not hub_cls.symmetric and op != "->":
+            raise ValueError(f"Connection '{line}': '{hub_name}' is directional; use '->'.")
+
+        spec = hub_cls.build_spec(ep["node"], ep["name"], hub_name, ep,
+                                  hub_on_left=a_hub, line=line)
+        specs.append(spec)
+        hub_specs.setdefault(hub_name, (hub_cls, []))[1].append(spec)
+
+    for hub_name, (hub_cls, hspecs) in hub_specs.items():
+        if hub_cls.symmetric and len(hspecs) == 2:
+            a = f'{hspecs[0]["node"]}.{hspecs[0]["periph"]}'
+            b = f'{hspecs[1]["node"]}.{hspecs[1]["periph"]}'
+            print(f"[XCONN] {a} <-> {hub_name} <-> {b}")
+        else:
+            for spec in hspecs:
+                print(f"[XCONN] {hub_cls.describe(spec)}")
+    return specs