hector-cli 0.1.0__py3-none-any.whl

hector/modules.py

@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+MODULE_KINDS — how a module type is built into a loadable artifact (.so or .dll).
+
+Register a builder `(module_name, module_config, BuildContext) -> artifact_host_path`:
+    @MODULE_KINDS.register("my-kind")
+    def build_my_kind(module_name, cfg, ctx):
+        return path_to_artifact
+"""
+
+import glob
+import os
+import shutil
+from dataclasses import dataclass
+
+from .core import (ARTIFACTS_DIR, LIBOPENLIBM_NAME, Registry,
+                   container_path_for, split_host_container, to_container_path)
+from .docker import run_build
+
+MODULE_KINDS = Registry("module kind")
+
+
+@dataclass
+class BuildContext:
+    renode_dir_container: str
+    integration_dir_host: str
+    image: str
+
+
+def _libopenlibm_flag(integration_dir_host):
+    libm = os.path.join(integration_dir_host, "lib", LIBOPENLIBM_NAME)
+    if os.path.isfile(libm):
+        return f'-DLIBOPENLIBM="{container_path_for(libm)}"'
+    print(f"  [!] {LIBOPENLIBM_NAME} not found at {libm}; skipping -DLIBOPENLIBM "
+          "(add it via cmake_flags if your build needs it).")
+    return ""
+
+
+@MODULE_KINDS.register("renode-verilator")
+def build_renode_verilator(module_name, module_config, ctx):
+    """Build a verilated co-simulation peripheral into a .so, inside the Renode image."""
+    if not module_config.get("type"):
+        raise ValueError(f"Module '{module_name}' is missing required 'type' (its Renode class).")
+    source = module_config.get("source")
+    if not source:
+        raise ValueError(f"Module '{module_name}' is missing required 'source'.")
+
+    source_host, source_container = split_host_container(source)
+    if not os.path.isdir(source_host):
+        raise FileNotFoundError(f"Module '{module_name}': source dir not found: {source} ({source_host})")
+
+    build_host = os.path.join(ARTIFACTS_DIR, "build", "modules", module_name)
+    os.makedirs(build_host, exist_ok=True)
+    build_container = to_container_path(build_host)
+    cmake_flags = module_config.get("cmake_flags", "")
+    auto_flags = _libopenlibm_flag(ctx.integration_dir_host)
+    uid, gid = os.getuid(), os.getgid()
+
+    print(f"\n[MODULE] Building '{module_name}' ({module_config['type']}) in {ctx.image}")
+    print(f"         source: {source}")
+
+    run_build(
+        "set -e\n"
+        "export DEBIAN_FRONTEND=noninteractive\n"
+        "apt-get update\n"
+        "apt-get install -y --no-install-recommends build-essential cmake verilator\n"
+        f'cmake -S "{source_container}" -B "{build_container}" '
+        f'-DUSER_RENODE_DIR="{ctx.renode_dir_container}" {auto_flags} {cmake_flags}\n'
+        f'cmake --build "{build_container}"\n'
+        f'chown -R {uid}:{gid} "{build_container}"\n',
+        ctx.image,
+    )
+
+    so_files = glob.glob(os.path.join(build_host, "**", "*.so"), recursive=True)
+    if not so_files:
+        raise RuntimeError(f"Module '{module_name}' produced no .so in {build_host}.")
+    if len(so_files) > 1:
+        raise RuntimeError(f"Module '{module_name}' produced multiple .so files: {so_files}.")
+    print(f"  -> {so_files[0]}")
+    return so_files[0]
+
+
+# Renode DLLs bundled in its own installation — filter these out when locating
+# the user's output DLL after a dotnet build.
+_RENODE_DLL_PREFIXES = (
+    "Antmicro.", "Mono.", "System.", "Microsoft.", "mscorlib",
+    "netstandard", "IronPython", "FasterReflection",
+)
+
+
+@MODULE_KINDS.register("csharp")
+def build_csharp(module_name, module_config, ctx):
+    """Build or locate a C# Renode peripheral plugin (.dll).
+    `source` can be a pre-built .dll path or a directory containing a .csproj.
+    The DLL is loaded at emulation scope via `i @<path>`; one import covers all instances.
+    """
+    if not module_config.get("type"):
+        raise ValueError(f"Module '{module_name}' is missing required 'type' (the C# class name).")
+    source = module_config.get("source")
+    if not source:
+        raise ValueError(f"Module '{module_name}' is missing required 'source'.")
+
+    source_host, _ = split_host_container(source)
+
+    # ---- pre-built DLL: use as-is ----
+    if source_host.endswith(".dll"):
+        if not os.path.isfile(source_host):
+            raise FileNotFoundError(f"Module '{module_name}': DLL not found: {source} ({source_host})")
+        print(f"\n[MODULE] C# '{module_name}' ({module_config['type']}) using pre-built DLL")
+        print(f"         source: {source}")
+        return source_host
+
+    # ---- build from source ----
+    if not os.path.isdir(source_host):
+        raise FileNotFoundError(
+            f"Module '{module_name}': source not found: {source} ({source_host})\n"
+            "  Provide either a directory containing a .csproj or a path to a pre-built .dll."
+        )
+
+    source_container = to_container_path(source_host)
+    build_host = os.path.join(ARTIFACTS_DIR, "build", "modules", module_name)
+    os.makedirs(build_host, exist_ok=True)
+    build_container = to_container_path(build_host)
+    uid, gid = os.getuid(), os.getgid()
+
+    print(f"\n[MODULE] Building C# '{module_name}' ({module_config['type']}) in {ctx.image}")
+    print(f"         source: {source}")
+
+    run_build(
+        "set -e\n"
+        # Renode's official image ships Mono; dotnet may also be present.
+        # Try dotnet first (produces a self-contained output), fall back to msbuild/xbuild.
+        f'if command -v dotnet >/dev/null 2>&1; then\n'
+        f'  dotnet build "{source_container}" -o "{build_container}" -c Release\n'
+        f'elif command -v msbuild >/dev/null 2>&1; then\n'
+        f'  msbuild "{source_container}" /p:OutputPath="{build_container}" /p:Configuration=Release\n'
+        f'else\n'
+        f'  echo "[ERROR] Neither dotnet nor msbuild found in container {ctx.image}"; exit 1\n'
+        f'fi\n'
+        f'chown -R {uid}:{gid} "{build_container}"\n',
+        ctx.image,
+    )
+
+    # Collect DLLs, excluding Renode/framework assemblies
+    all_dlls = glob.glob(os.path.join(build_host, "**", "*.dll"), recursive=True)
+    user_dlls = [
+        f for f in all_dlls
+        if not any(os.path.basename(f).startswith(p) for p in _RENODE_DLL_PREFIXES)
+    ]
+
+    if not user_dlls:
+        raise RuntimeError(
+            f"Module '{module_name}': no user DLL found in {build_host}.\n"
+            f"  All .dll files found: {[os.path.basename(f) for f in all_dlls]}"
+        )
+    if len(user_dlls) > 1:
+        # Try to pick the one whose name matches the module or the last path component of source
+        stem = os.path.basename(source_host)
+        candidates = [f for f in user_dlls
+                      if module_name.lower() in os.path.basename(f).lower()
+                      or stem.lower() in os.path.basename(f).lower()]
+        if len(candidates) == 1:
+            user_dlls = candidates
+        else:
+            raise RuntimeError(
+                f"Module '{module_name}': multiple user DLLs found — cannot determine which "
+                f"to use: {[os.path.basename(f) for f in user_dlls]}.\n"
+                f"  Rename your project output or point 'source' directly at the .dll."
+            )
+
+    print(f"  -> {user_dlls[0]}")
+    return user_dlls[0]
+
+
+def build_modules(modules_cfg, ctx):
+    """Build every declared module via its registered kind.
+
+    Returns {module_name: {'type': renode_class, 'artifact_host': path, 'artifact_type': 'so'|'dll'}}
+    """
+    registry = {}
+    for name, cfg in (modules_cfg or {}).items():
+        kind = cfg.get("kind", "renode-verilator")
+        builder = MODULE_KINDS.get(kind)
+        artifact_host = builder(name, cfg, ctx)
+        artifact_type = "dll" if artifact_host.endswith(".dll") else "so"
+        registry[name] = {
+            "type": cfg.get("type"),
+            "artifact_host": artifact_host,
+            "artifact_type": artifact_type,
+        }
+    return registry
+
+
+def materialize_instance_so(node_name, instance, module_so_host):
+    """Copy a module's .so to a per-instance file so each instance gets a distinct inode
+    (and therefore independent simulation state when loaded)."""
+    inst_dir = os.path.join(ARTIFACTS_DIR, "build", "instances")
+    os.makedirs(inst_dir, exist_ok=True)
+    dest = os.path.join(inst_dir, f"{node_name}__{instance}.so")
+    shutil.copy2(module_so_host, dest)
+    return dest

hector/peripherals.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Peripheral instantiation: place a native Renode class OR a module type into a machine.
+
+Verilator (.so) modules:  per-instance .so copy + SimulationFilePathLinux command
+                          (stored in NodeDescriptor.so_commands).
+C# (.dll) modules:        emulation-level `i @<dll>` import (stored in
+                          NodeDescriptor.csharp_dlls; pipeline.py emits these before
+                          any machine block in the resc).
+"""
+
+import os
+
+from .core import to_container_path
+from .generator import NodeDescriptor, PeripheralDef
+from .modules import materialize_instance_so
+
+_RESERVED = {"type", "at", "peripherals", "init", "connections"}
+
+
+def _parse_repl_signals(raw):
+    """Parse repl-style signal connection lines into {peripheral_name: [repl_line, ...]}.
+
+    Each line: <periph>[<pin_range>] -> <target>@<pin>
+      nvic -> cpu@0               =>  nvic:        ["-> cpu@0"]
+      nvic.IRQ -> cpu@0           =>  nvic:        ["IRQ -> cpu@0"]
+      gpioPortC[0-15] -> nvic@6  =>  gpioPortC:   ["[0-15] -> nvic@6"]
+
+    The destination (right of '->') is preserved verbatim, so Renode's receiver
+    qualifiers pass through untouched, e.g. a local index '#N' and an input pin '@N':
+      timer1@0 -> gpioPortA#08@01  =>  timer1:     ["0 -> gpioPortA#08@01"]
+    The source (left of '->') is only a named signal, a number, or a range — '#' is a
+    receiver-only qualifier, so a '#' on the source side is flagged, not emitted.
+    """
+    result = {}
+    for line in (raw or "").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if " -> " not in line:
+            print(f"  [WARN] irqs: '{line}' has no '->' — skipped.")
+            continue
+        source, target = line.split(" -> ", 1)
+        source, target = source.strip(), target.strip()
+        if "#" in source:
+            # '#localIndex' is a Renode *receiver* qualifier (it belongs on the
+            # destination, right of '->'). It has no meaning on the source side, so
+            # emitting it would produce a .repl Renode rejects. Flag and skip.
+            print(f"  [WARN] irqs: '{line}' has '#' on the source side; '#index' is a "
+                  "destination (receiver) qualifier and belongs after '->' "
+                  "(e.g. 'timer1@0 -> gpioPortA#08@01'). Skipped.")
+            continue
+        if "[" in source:
+            periph, pin = source.split("[", 1)
+            irq_line = f"[{pin} -> {target}"
+        elif "." in source:
+            periph, signal = source.split(".", 1)
+            irq_line = f"{signal} -> {target}"
+        elif "@" in source:
+            periph, pin = source.split("@", 1)
+            irq_line = f"{pin} -> {target}"
+        else:
+            periph = source
+            irq_line = f"-> {target}"
+        result.setdefault(periph.strip(), []).append(irq_line)
+    return result
+
+
+def _gather_connections(peripherals):
+    """Collect `connections:` blocks declared on peripherals (recursively).
+
+    Lets wiring live next to the peripheral it concerns — e.g. an `mcu` grouping
+    peripheral can carry all the MCU-internal wiring, separate from a board-level
+    `connections:` at the node. Returns the combined raw text, parsed together with
+    the node-level connections. These are always intra-machine signals; cross-machine
+    hub links must still use the node-level `connections:` block.
+    """
+    blocks = []
+    for spec in (peripherals or {}).values():
+        spec = spec or {}
+        if not isinstance(spec, dict):
+            continue
+        conn = spec.get("connections")
+        if conn:
+            blocks.append(conn if isinstance(conn, str) else "\n".join(str(c) for c in conn))
+        child = spec.get("peripherals")
+        if child:
+            sub = _gather_connections(child)
+            if sub:
+                blocks.append(sub)
+    return "\n".join(blocks)
+
+
+def resolve_peripherals(concrete_nodes, modules_registry):
+    """Build a NodeDescriptor for each renode node.
+
+    Returns {node_name: NodeDescriptor} with peripheral_defs, so_commands,
+    csharp_dlls, and init populated. updating_entries is left empty — connections.py
+    fills those in later.
+    """
+    descriptors = {}
+    for node_name, node_config in concrete_nodes.items():
+        if node_config.get("backend", "renode") != "renode":
+            continue
+        # Wiring may be declared at the node level (`connections:`) or inline on a
+        # peripheral (a `connections:` block on the peripheral it concerns). Both are
+        # intra-machine signals and merge into one map.
+        raw_signals = node_config.get("_repl_signals", "")
+        periph_signals = _gather_connections(node_config.get("peripherals") or {})
+        signals_map = _parse_repl_signals(
+            "\n".join(s for s in (raw_signals, periph_signals) if s))
+        init = (node_config.get("init") or "").strip() or None
+        descriptor = NodeDescriptor(name=node_name, init=init)
+
+        for instance, spec in (node_config.get("peripherals") or {}).items():
+            _resolve(instance, spec or {}, node_name, descriptor, modules_registry,
+                     default_at="sysbus", signals_map=signals_map)
+
+        # Signals targeting peripherals not declared in this YAML (from a platform .repl file)
+        # can't be inlined; emit them as updating entries instead.
+        declared = {p.name for p in descriptor.peripheral_defs}
+        for periph_name, wires in signals_map.items():
+            if periph_name not in declared:
+                for wire in wires:
+                    descriptor.updating_entries.append((periph_name, wire))
+
+        descriptors[node_name] = descriptor
+    return descriptors
+
+
+def _resolve(instance, spec, node_name, descriptor, modules_registry, default_at, signals_map=None):
+    type_name = spec.get("type")
+    if not type_name:
+        raise ValueError(f"peripherals.{instance} on '{node_name}' is missing 'type'.")
+
+    at = spec["at"] if "at" in spec else default_at
+    at = at or None
+    signals = list((signals_map or {}).get(instance, []))
+    init = spec.get("init") or None
+    args = {k: v for k, v in spec.items() if k not in _RESERVED}
+
+    if type_name in modules_registry:
+        mod = modules_registry[type_name]
+        descriptor.peripheral_defs.append(
+            PeripheralDef(name=instance, ptype=mod["type"], at=at,
+                          args=args, signals=signals, init=init))
+
+        if mod["artifact_type"] == "so":
+            inst_so = materialize_instance_so(node_name, instance, mod["artifact_host"])
+            descriptor.so_commands.append(
+                f"{instance} SimulationFilePathLinux @{to_container_path(inst_so)}")
+            print(f"[INST] {node_name}.{instance} = module '{type_name}' ({mod['type']})"
+                  + (f" @ {at}" if at else "")
+                  + f"  [.so: {os.path.basename(inst_so)}]")
+        else:
+            descriptor.csharp_dlls.add(mod["artifact_host"])
+            print(f"[INST] {node_name}.{instance} = C# module '{type_name}' ({mod['type']})"
+                  + (f" @ {at}" if at else "")
+                  + f"  [.dll: {os.path.basename(mod['artifact_host'])}]")
+    else:
+        descriptor.peripheral_defs.append(
+            PeripheralDef(name=instance, ptype=type_name, at=at,
+                          args=args, signals=signals, init=init))
+        print(f"[INST] {node_name}.{instance} = native {type_name} "
+              + (f"@ {at}" if at else "(no registration)"))
+
+    for child_instance, child_spec in (spec.get("peripherals") or {}).items():
+        _resolve(child_instance, child_spec or {}, node_name, descriptor, modules_registry,
+                 default_at=instance, signals_map=signals_map)