hector-cli 0.1.0__py3-none-any.whl

hector/generator.py

@@ -0,0 +1,292 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Node descriptor, .repl generation, and .resc generation.
+
+Each upstream step (peripherals, connections) is a pure data producer that populates
+a NodeDescriptor. This module is the single place that turns those descriptors into
+files on disk.
+"""
+
+import fnmatch
+import glob
+import os
+import re
+import shutil
+from dataclasses import dataclass, field
+
+from .core import ARTIFACTS_DIR
+from .hubs import HUBS
+
+
+# ==========================================================================
+# DATA STRUCTURES
+# ==========================================================================
+
+@dataclass
+class PeripheralDef:
+    name: str
+    ptype: str
+    at: str | None
+    args: dict
+    signals: list       # IRQ/GPIO connection lines inlined on this peripheral
+    init: str | None
+
+
+@dataclass
+class NodeDescriptor:
+    name: str
+    peripheral_defs: list = field(default_factory=list)   # PeripheralDef items, declaration order
+    updating_entries: list = field(default_factory=list)  # (periph_name, wire_line) from connections
+    so_commands: list = field(default_factory=list)       # Verilator SimulationFilePathLinux commands
+    csharp_dlls: set = field(default_factory=set)
+    init: str | None = None                               # sysbus init block (node-level init:)
+
+
+# ==========================================================================
+# REPL VALUE FORMATTING
+# ==========================================================================
+
+_IDENT_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_.]*$')
+_HEX_RE   = re.compile(r'^0[xX][0-9a-fA-F]+$')
+
+
+def repl_value(v):
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, list):
+        return "[" + ", ".join(repl_value(i) for i in v) + "]"
+    if isinstance(v, str):
+        # Identifiers (peripheral refs) and hex literals are emitted unquoted.
+        if _IDENT_RE.match(v) or _HEX_RE.match(v):
+            return v
+        return f'"{v}"'
+    return str(v)
+
+
+def build_repl_fragment(name, ptype, args=None, at=None, irqs=None, init=None):
+    """One repl entry: `name: Type [@ registration]` plus args, IRQ connections, and init commands."""
+    head = f"{name}: {ptype}" + (f" @ {at}" if at else "")
+    lines = [head]
+    lines += [f"    {k}: {repl_value(v)}" for k, v in (args or {}).items()]
+    lines += [f"    {irq}" for irq in (irqs or [])]
+    if init:
+        lines.append("    init:")
+        for cmd in init.splitlines():
+            if cmd.strip():
+                lines.append(f"        {cmd.strip()}")
+    return "\n".join(lines)
+
+
+def queue_command(node_config, command):
+    node_config.setdefault("_gen_commands", []).append(command)
+
+
+# ==========================================================================
+# .REPL GENERATION
+# ==========================================================================
+
+def generate_node_repl(descriptor, job_index):
+    """Write a .repl for one node from its NodeDescriptor.
+
+    Layout:
+      1. Peripheral declarations (with inline signals and per-peripheral init blocks)
+      2. Updating entries from connections (one per intra-machine wire)
+      3. sysbus: init: block (node-level init commands)
+
+    Returns the host path written, or None if there was nothing to emit.
+    """
+    parts = []
+
+    for p in descriptor.peripheral_defs:
+        parts.append(build_repl_fragment(p.name, p.ptype, p.args, p.at,
+                                         irqs=p.signals, init=p.init))
+
+    for periph_name, wire in descriptor.updating_entries:
+        parts.append(f"{periph_name}:\n    {wire}")
+
+    if not parts and not descriptor.init:
+        return None
+
+    repl_root = os.path.join(ARTIFACTS_DIR, "repl")
+    os.makedirs(repl_root, exist_ok=True)
+    repl_host = os.path.join(repl_root, f"job_{job_index}_{descriptor.name}.gen.repl")
+
+    with open(repl_host, "w") as f:
+        if parts:
+            f.write("\n\n".join(parts) + "\n")
+        if descriptor.init:
+            indented = "\n".join(f"        {l}" for l in descriptor.init.splitlines())
+            f.write(f"\nsysbus:\n    init:\n{indented}\n")
+
+    return repl_host
+
+
+# ==========================================================================
+# NODE COMMAND FINALIZATION
+# ==========================================================================
+
+def finalize_commands(concrete_nodes):
+    """Prepend generated commands (instance attaches, then host mappings) before the
+    user's own commands: order is [attach] [map] [user]."""
+    for node_config in concrete_nodes.values():
+        gen = node_config.get("_gen_commands")
+        if not gen:
+            continue
+        block = "\n".join(gen)
+        existing = node_config.get("commands")
+        if not existing:
+            node_config["commands"] = block
+        elif isinstance(existing, list):
+            node_config["commands"] = [block] + existing
+        else:
+            node_config["commands"] = block + "\n" + existing.rstrip()
+
+
+# ==========================================================================
+# .RESC GENERATION
+# ==========================================================================
+
+def generate_emulation_resc(renode_nodes, hubs_registry, cross_connections,
+                            quantum, debug_config, output_filename, emulation_setup=None):
+    """One resc per job: every node becomes a named machine in one emulation; hubs and
+    cross-machine connectors wire them; one shared `start`.
+
+    renode_nodes    : list of (node_name, node_config)
+    hubs_registry   : {hub_name: hub_type}
+    debug_config    : {node_name: gdb_port}
+    emulation_setup : list of emulation-level lines to emit before machine blocks
+                      (e.g. CreateServerSocketTerminal, CreateUartPtyTerminal)
+    """
+    lines = []
+
+    # --- emulation-level setup (terminals, etc.) – must exist before machines connect ---
+    if emulation_setup:
+        lines.append("# === emulation-level setup ===")
+        lines.extend(emulation_setup)
+
+    # --- machines ---
+    for node_name, node_config in renode_nodes:
+        lines.append(f"\n# === machine: {node_name} ===")
+        lines.append(f'mach create "{node_name}"')
+        for repl in node_config.get("platform", []):
+            lines.append(f"machine LoadPlatformDescription @{repl}")
+        fw = node_config.get("firmware")
+        if fw and fw != "none":
+            lines.append(f"sysbus LoadELF @{fw}")
+        cmds = node_config.get("commands", "")
+        if cmds:
+            lines.extend(cmds if isinstance(cmds, list) else [cmds.strip()])
+        if node_name in debug_config:
+            port = debug_config[node_name]
+            lines.append(f"machine StartGdbServer {port}")
+            lines.append("cpu IsHalted true")
+            lines.append(f'echo "GDB server ready for {node_name} on port {port}"')
+
+    # --- emulation-global quantum ---
+    if quantum:
+        lines.append(f'\nemulation SetGlobalQuantum "{quantum}"')
+
+    # --- hubs (each hub class emits its own create command) ---
+    if hubs_registry:
+        lines.append("\n# === hubs ===")
+        for hub_name, hub_type in hubs_registry.items():
+            lines.extend(HUBS.get(hub_type).emit_create(hub_name))
+
+    # --- cross-machine connections (each hub class emits its own connect lines) ---
+    if cross_connections:
+        lines.append("\n# === cross-machine connections ===")
+        for spec in cross_connections:
+            lines.extend(HUBS.get(hubs_registry[spec["hub"]]).emit_connect(spec))
+
+    lines.append("\nstart")
+    content = "\n".join(lines)
+    with open(output_filename, "w") as f:
+        f.write(content)
+    return content
+
+
+def snapshot_resc(snapshot_container_path, debug_config=None):
+    """Build resc text that loads a snapshot and resumes.
+
+    When debug_config ({machine_name: gdb_port}) is given, each named machine gets a
+    GDB server opened and its CPU halted before the resume — so a loaded snapshot is
+    debuggable just like a fresh boot. (A GDB server is a live connection, never part
+    of saved snapshot state, so it must be (re)started after every Load.)
+    """
+    lines = [f"Load @{snapshot_container_path}"]
+    for node_name, port in (debug_config or {}).items():
+        lines += [f'mach set "{node_name}"',
+                  f"machine StartGdbServer {port}",
+                  "cpu IsHalted true",
+                  f'echo "GDB server ready for {node_name} on port {port}"']
+    lines.append("start")
+    return "\n".join(lines) + "\n"
+
+
+# ==========================================================================
+# ARTIFACT COLLECTION
+# ==========================================================================
+
+def collect_artifacts(patterns, output_dir, job_index=None):
+    """Sweep the global artifact glob patterns and copy matches into
+    <output_dir>/artifacts/ so a single directory can be uploaded by CI / read by a
+    dashboard.
+
+    patterns   : list of glob strings (top-level 'artifacts:' or --artifacts override)
+    output_dir : the run output directory (--output)
+    job_index  : 1-based job number; prefixes copied filenames to avoid cross-job clashes
+
+    Returns the list of collected destination paths (relative to cwd).
+    """
+    if not patterns:
+        return []
+    dest_root = os.path.realpath(os.path.join(output_dir, "artifacts"))
+    # Never collect from the framework's own tree (the Renode/integration clones and
+    # generated files live here) or from our own previous copies.
+    prune = (dest_root, os.path.realpath(ARTIFACTS_DIR))
+    job_sub = f"job_{job_index}" if job_index else ""
+    collected, seen = [], set()
+    header_shown = False
+    for pattern in patterns:
+        for src in sorted(_match_artifacts(pattern, dest_root)):
+            real = os.path.realpath(src)
+            if real in seen or not os.path.isfile(real):
+                continue
+            if any(real == p or real.startswith(p + os.sep) for p in prune):
+                continue
+            seen.add(real)
+            # Mirror the source path under artifacts/job_N/ so files with the same
+            # basename in different directories don't clobber each other.
+            rel_src = os.path.relpath(real)
+            if rel_src.startswith(".."):       # outside cwd → flatten to basename
+                rel_src = os.path.basename(real)
+            dest = os.path.join(dest_root, job_sub, rel_src)
+            os.makedirs(os.path.dirname(dest), exist_ok=True)
+            shutil.copy2(real, dest)
+            rel = os.path.relpath(dest)
+            collected.append(rel)
+            if not header_shown:
+                label = f" (job {job_index})" if job_index else ""
+                print(f"\n[ARTIFACTS]{label}:")
+                header_shown = True
+            print(f"  -> {os.path.relpath(real)}  →  {rel}")
+    return collected
+
+
+def _match_artifacts(pattern, dest_root):
+    """Resolve one artifact glob pattern to a list of host paths.
+
+    A bare filename pattern (no '/', e.g. '*.xml') searches the whole project tree
+    recursively, pruning hidden dirs (.hector, .git, …) and the artifacts output dir —
+    so 'results/junit.xml' is found without sweeping the bundled Renode clone.
+    A pattern with a path component ('results/*.bin', 'logs/**/*.log') is passed to
+    glob as-is, so explicit directories and '**' behave normally.
+    """
+    if "/" in pattern or os.sep in pattern:
+        return glob.glob(pattern, recursive=True)
+    matches = []
+    for root, dirs, files in os.walk("."):
+        dirs[:] = [d for d in dirs
+                   if not d.startswith(".")
+                   and os.path.realpath(os.path.join(root, d)) != dest_root]
+        matches.extend(os.path.join(root, name) for name in fnmatch.filter(files, pattern))
+    return matches

hector/hubs.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+HUBS  -  cross-machine connection media (emulation-level objects).
+
+==========================================================================
+HOW TO ADD A NEW HUB TYPE
+==========================================================================
+1. Subclass `Hub`.
+2. Decorate it with `@HUBS.register("<yaml-type-name>")`.
+3. Set `create_command` (the `emulation <X> "name"` verb) and `symmetric`.
+4. If it is asymmetric (needs source/dest roles + pins), override `build_spec`
+   and `emit_connect` (see GpioConnector below for the template).
+
+That is the whole change. `connections.py` and `engine.py` are generic over this
+registry, so nothing else needs editing. Example — adding a SPI connector:
+
+    @HUBS.register("spi")
+    class SpiConnector(Hub):
+        create_command = "CreateSPIConnector"   # whatever Renode calls it
+        symmetric = False
+        # ... override build_spec/emit_connect if it needs pins/roles ...
+
+The YAML then immediately accepts:   hubs:\n  mylink: { type: spi }
+==========================================================================
+"""
+
+from .core import Registry, RuntimeOptions
+
+HUBS = Registry("hub type")
+
+
+class Hub:
+    """Base class for a cross-machine connection medium.
+
+    A symmetric hub (uart/can/ethernet) is wired with '<->' and every endpoint is
+    equal. An asymmetric connector (gpio) is wired with '->' and each endpoint has a
+    role (source/destination) plus a pin.
+    """
+    create_command = None     # the `emulation <create_command> "name"` verb
+    symmetric = True          # True -> '<->'; False -> directional '->'
+
+    @classmethod
+    def emit_create(cls, name):
+        """resc line(s) that instantiate the hub."""
+        return [f'emulation {cls.create_command} "{name}"']
+
+    @classmethod
+    def build_spec(cls, node, periph, hub_name, ep, hub_on_left, line):
+        """Validate one connection endpoint and return a spec dict for the resc.
+        Default: symmetric medium, no role/pin."""
+        return {"node": node, "periph": periph, "hub": hub_name}
+
+    @classmethod
+    def emit_connect(cls, spec):
+        """resc lines connecting one endpoint (one spec) to this hub."""
+        return [f'mach set "{spec["node"]}"',
+                f'connector Connect sysbus.{spec["periph"]} {spec["hub"]}']
+
+    @classmethod
+    def runtime_options(cls, spec):
+        """Execution-environment needs this connection imposes on the Renode run
+        (docker caps/devices/root). Default: none. Override for a medium that needs,
+        e.g., a host device or NET_ADMIN."""
+        return RuntimeOptions()
+
+    @classmethod
+    def describe(cls, spec):
+        return f'{spec["node"]}.{spec["periph"]} <-> {spec["hub"]}'
+
+
+# -------------------- symmetric media --------------------
+@HUBS.register("uart")
+class UartHub(Hub):
+    create_command = "CreateUARTHub"
+    symmetric = True
+
+
+@HUBS.register("can")
+class CanHub(Hub):
+    create_command = "CreateCANHub"
+    symmetric = True
+
+
+@HUBS.register("ethernet")
+class EthernetSwitch(Hub):
+    create_command = "CreateSwitch"
+    symmetric = True
+
+
+# -------------------- asymmetric connectors --------------------
+@HUBS.register("gpio")
+class GpioConnector(Hub):
+    create_command = "CreateGPIOConnector"
+    symmetric = False
+
+    @classmethod
+    def build_spec(cls, node, periph, hub_name, ep, hub_on_left, line):
+        if ep["kind"] != "pin":
+            raise ValueError(
+                f"Connection '{line}': gpio connections need a pin, e.g. "
+                f"{node}.{periph}@<n>."
+            )
+        # arrow direction relative to the hub picks the role:
+        #   periph -> hub   => this port is the SOURCE
+        #   hub -> periph   => this port is the DESTINATION
+        role = "dest" if hub_on_left else "source"
+        return {"node": node, "periph": periph, "hub": hub_name,
+                "role": role, "pin": ep["pin"]}
+
+    @classmethod
+    def emit_connect(cls, spec):
+        sel = "SelectSourcePin" if spec["role"] == "source" else "SelectDestinationPin"
+        return [f'mach set "{spec["node"]}"',
+                f'connector Connect sysbus.{spec["periph"]} {spec["hub"]}',
+                f'{spec["hub"]} {sel} sysbus.{spec["periph"]} {spec["pin"]}']
+
+    @classmethod
+    def describe(cls, spec):
+        return f'{spec["node"]}.{spec["periph"]}@{spec["pin"]} ({spec["role"]}) -> {spec["hub"]}'
+
+
+# -------------------- USB connector --------------------
+@HUBS.register("usb")
+class UsbConnector(Hub):
+    """Asymmetric USB connector. The device side uses `connector Connect`;
+    the controller side uses `RegisterInController`.
+
+    In connections:
+      mcu.usb   -> usblink      # mcu is the USB DEVICE  (periph->hub)
+      usblink   -> host.usb     # host is the USB CONTROLLER  (hub->periph)
+
+    Docs: https://renode.readthedocs.io/en/latest/tutorials/usbip.html
+    """
+    create_command = "CreateUSBConnector"
+    symmetric = False
+
+    @classmethod
+    def build_spec(cls, node, periph, hub_name, ep, hub_on_left, line):
+        # periph -> hub  =>  device;   hub -> periph  =>  controller
+        role = "controller" if hub_on_left else "device"
+        return {"node": node, "periph": periph, "hub": hub_name, "role": role}
+
+    @classmethod
+    def emit_connect(cls, spec):
+        if spec["role"] == "device":
+            return [f'mach set "{spec["node"]}"',
+                    f'connector Connect sysbus.{spec["periph"]} {spec["hub"]}']
+        else:  # controller
+            return [f'mach set "{spec["node"]}"',
+                    f'{spec["hub"]} RegisterInController sysbus.{spec["periph"]}']
+
+    @classmethod
+    def describe(cls, spec):
+        return f'{spec["node"]}.{spec["periph"]} ({spec["role"]}) <-> {spec["hub"]}'
+
+
+@HUBS.register("wireless")
+class WirelessMedium(Hub):
+    """IEEE 802.15.4 wireless medium (ZigBee / Thread / 6LoWPAN / Matter).
+
+    Connects radio interfaces across machines. All connected interfaces receive all
+    packets by default; use SetMediumFunction to model range / packet loss.
+
+    Docs: https://renode.readthedocs.io/en/latest/networking/wireless.html
+    """
+    create_command = "CreateIEEE802_15_4Medium"
+    symmetric = True
+
+
+@HUBS.register("ble")
+class BLEMedium(Hub):
+    """Bluetooth Low Energy medium.
+
+    Connects BLE radio interfaces across machines. Same positioning and range/loss
+    model as the IEEE 802.15.4 medium — see the wireless hub for details.
+
+    Docs: https://renode.readthedocs.io/en/latest/networking/wireless.html
+         https://renode.readthedocs.io/en/latest/tutorials/ble-simulation.html
+    """
+    create_command = "CreateBLEMedium"
+    symmetric = True
+
+
+@HUBS.register("wisun")
+class WiSUNMedium(Hub):
+    """Wi-SUN (Wireless Smart Utility Network) medium — IEEE 802.11ah-based mesh.
+
+    Used for large-scale IoT mesh networks (smart meters, grid infrastructure).
+    All connected radio interfaces receive all packets by default.
+    Supports the same SetPosition / SetMediumFunction range-loss model as the
+    IEEE 802.15.4 and BLE mediums.
+
+    Docs: https://renode.readthedocs.io/en/latest/networking/wireless.html
+    """
+    create_command = "CreateWiSUNMedium"
+    symmetric = True

hector/mappings.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+MAPPING_BACKENDS  -  bind an emulated peripheral to a host resource.
+
+PTY and TCP backends follow a two-step emulation model (identical to hubs):
+  1. An emulation-level object is created before any machine blocks in the resc.
+  2. The machine connects its peripheral to that object via `connector Connect`.
+
+The `file` backend is peripheral-level only (no emulation object needed).
+
+==========================================================================
+HOW TO ADD A NEW MAPPING BACKEND
+==========================================================================
+Register a function:  (node_name, peripheral, param, node_config) -> MappingResult
+
+    @MAPPING_BACKENDS.register("tap")
+    def tap_backend(node_name, peripheral, param, node_config):
+        iface = param or "tap0"
+        term  = f"ss_{node_name}_{peripheral}"
+        return MappingResult(
+            machine_cmd     = f"connector Connect sysbus.{peripheral} {term}",
+            emulation_lines = [f'emulation CreateTap "{term}" "{iface}"'],
+        )
+
+`emulation_lines` are emitted at the top of the resc before any `mach create` blocks
+so the object already exists when the machine tries to connect to it. `machine_cmd` is
+queued on the node as an ordinary monitor command.
+
+YAML then accepts:   mappings: |\n  boardA.eth0 -> tap:tap0
+==========================================================================
+"""
+
+from dataclasses import dataclass, field
+from typing import List
+
+from .core import Registry, RuntimeOptions, parse_endpoint, to_container_path
+from .generator import queue_command
+
+MAPPING_BACKENDS = Registry("mapping backend")
+
+
+@dataclass
+class MappingResult:
+    """What a mapping backend produces for one mapping line."""
+    machine_cmd: str                          # monitor command queued on the node
+    emulation_lines: List[str] = field(default_factory=list)   # emulation-level setup
+    runtime: RuntimeOptions = field(default_factory=RuntimeOptions)  # execution-env needs
+
+
+# -------------------- backends --------------------
+@MAPPING_BACKENDS.register("file")
+def file_backend(_node_name, peripheral, param, _node_config):
+    """Redirect UART output to a file.  uart4 -> file:results/uart.log
+    Subsequent calls append with a numeric suffix rather than overwriting."""
+    if not param:
+        raise ValueError("'file' backend requires a path (file:<path>).")
+    return MappingResult(
+        machine_cmd=f"{peripheral} CreateFileBackend @{to_container_path(param)} true",
+    )
+
+
+@MAPPING_BACKENDS.register("tcp")
+def tcp_backend(node_name, peripheral, param, _node_config):
+    """Expose a UART as a TCP socket terminal.  uart4 -> tcp:4567
+    Append ':raw' to suppress IAC telnet bytes:  uart4 -> tcp:4567:raw
+    """
+    if not param:
+        raise ValueError("'tcp' backend requires a port number (tcp:<port>).")
+
+    # Optional ':raw' suffix suppresses IAC bytes
+    raw = False
+    if ":" in param:
+        port_str, _, flag = param.partition(":")
+        raw = flag.strip().lower() == "raw"
+    else:
+        port_str = param
+
+    try:
+        port = int(port_str)
+    except ValueError:
+        raise ValueError(f"'tcp' backend: '{port_str}' is not a valid port number.")
+    if not 1 <= port <= 65535:
+        raise ValueError(f"'tcp' backend: port {port} is out of range (1-65535).")
+
+    term_name = f"ss_{node_name}_{peripheral}"
+    create_cmd = (f'emulation CreateServerSocketTerminal {port} "{term_name}" false'
+                  if raw else
+                  f'emulation CreateServerSocketTerminal {port} "{term_name}"')
+    return MappingResult(
+        machine_cmd=f"connector Connect sysbus.{peripheral} {term_name}",
+        emulation_lines=[create_cmd],
+    )
+
+
+@MAPPING_BACKENDS.register("pty")
+def pty_backend(node_name, peripheral, param, _node_config):
+    """Expose a UART as a PTY symlink inside the container.  uart4 -> pty:/tmp/uart4
+    Note: PTY is not accessible from the host when running in Docker; use tcp: instead.
+    """
+    if not param:
+        raise ValueError("'pty' backend requires a path (pty:/tmp/uart0).")
+
+    term_name = f"ss_{node_name}_{peripheral}"
+    return MappingResult(
+        machine_cmd=f"connector Connect sysbus.{peripheral} {term_name}",
+        emulation_lines=[f'emulation CreateUartPtyTerminal "{term_name}" "{param}"'],
+    )
+
+
+@MAPPING_BACKENDS.register("tap")
+def tap_backend(node_name, peripheral, param, _node_config):
+    """Bridge an Ethernet peripheral to a host TAP device.  eth0 -> tap:tap0
+
+    Host interface name defaults to 'tap0'. Renode wires the emulated NIC and the host
+    TAP through a switch (the NIC can't connect to the TAP directly), so this creates a
+    per-mapping switch, a TAP (exposed as `host.<name>`), and joins both to the switch.
+    Creating a TAP needs NET_ADMIN and /dev/net/tun on the container (host networking
+    alone does NOT grant these).
+    """
+    iface = param or "tap0"
+    sw = f"sw_{node_name}_{peripheral}"        # emulation switch
+    tap = f"tap_{node_name}_{peripheral}"      # Renode TAP element -> host.<tap>
+    return MappingResult(
+        machine_cmd=f"connector Connect sysbus.{peripheral} {sw}",
+        emulation_lines=[
+            f'emulation CreateSwitch "{sw}"',
+            # CreateTap(hostInterfaceName, name): host device first, Renode name second.
+            f'emulation CreateTap "{iface}" "{tap}"',
+            f'connector Connect host.{tap} {sw}',
+        ],
+        # Opening a real host TAP needs the TUN device, NET_ADMIN, and root.
+        runtime=RuntimeOptions(capabilities={"NET_ADMIN"},
+                               devices={"/dev/net/tun"}, root=True),
+    )
+
+
+# -------------------- resolver --------------------
+def resolve_mappings(mappings, concrete_nodes):
+    """Process each mapping line; queue machine commands on nodes.
+
+    Returns (emulation_lines, runtime): the emulation-level setup lines to emit before
+    machine blocks, and the merged RuntimeOptions any backend declared (e.g. a tap needs
+    TUN/TAP access) so the caller can grant them without re-scanning the generated resc."""
+    emulation_lines = []
+    runtime = RuntimeOptions()
+    for line in mappings:
+        if "->" not in line:
+            raise ValueError(f"Mapping '{line}' has no '->' operator")
+        lhs, rhs = line.split("->", 1)
+        ep = parse_endpoint(lhs)
+        backend, _, param = rhs.strip().partition(":")
+        backend, param = backend.strip(), (param.strip() or None)
+
+        node = ep["node"]
+        if node not in concrete_nodes:
+            raise ValueError(f"Mapping '{line}': unknown node '{node}'.")
+        if concrete_nodes[node].get("backend", "renode") != "renode":
+            raise ValueError(f"Mapping '{line}': left side must be on a renode node.")
+
+        handler = MAPPING_BACKENDS.get(backend)
+        result = handler(node, ep["name"], param, concrete_nodes[node])
+        queue_command(concrete_nodes[node], result.machine_cmd)
+        emulation_lines.extend(result.emulation_lines)
+        runtime.merge(result.runtime)
+        print(f"[MAP]  {node}.{ep['name']} -> {backend}:{param or ''}")
+
+    return emulation_lines, runtime