hector-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{hector_cli-0.2.1/hector_cli.egg-info → hector_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hector-cli
-Version: 0.2.1
+Version: 0.4.0
 Summary: YAML-driven Renode + Verilator simulation orchestrator for embedded hardware CI
 Home-page: https://hector-ci.com
 Author: Nemesis
@@ -50,15 +50,19 @@ Licensed under **AGPL-3.0-or-later** — see [LICENSE](LICENSE) and
 ## Contents
 
 - [Requirements](#requirements)
+- [Installation](#installation)
 - [Quick start](#quick-start)
+- [Run via Docker (no install)](#run-via-docker-no-install)
 - [Invocation modes](#invocation-modes)
 - [Configuration reference](#configuration-reference)
   - [Top-level fields](#top-level-fields)
   - [arguments](#arguments)
   - [matrix](#matrix)
   - [modules](#modules)
+    - [developing your own peripherals](#developing-your-own-peripherals)
   - [hubs](#hubs)
   - [machines](#machines)
+    - [inline repl and resc](#inline-repl-and-resc)
     - [peripherals](#peripherals)
     - [connections (per-machine)](#connections-per-machine)
     - [mappings](#mappings)
@@ -84,6 +88,34 @@ Licensed under **AGPL-3.0-or-later** — see [LICENSE](LICENSE) and
 
 ---
 
+## Installation
+
+Install the package to get the `hector` command on your `PATH`:
+
+```bash
+cd cli
+pip install .          # or: pip install -e .   (editable — picks up local edits)
+hector --version
+```
+
+`pip install` creates a `hector` launcher in your environment's scripts directory
+(the venv's `bin/`, or `~/.local/bin` for `pip install --user`). If `hector` isn't
+found afterwards, that scripts directory isn't on your `PATH` — add it, e.g.
+`export PATH="$HOME/.local/bin:$PATH"`.
+
+**No install?** Run the module directly from the `cli/` directory — it's equivalent:
+
+```bash
+python -m hector --version
+```
+
+> **Do not add the `cli/` source directory to your `PATH`.** The Python package is
+> named `hector/`, so a bare `hector` would resolve to that **directory** instead of
+> the command, and your shell fails with `permission denied: hector` (or
+> `command not found`). Install with `pip` (above) or use `python -m hector`.
+
+---
+
 ## Quick start
 
 ```
@@ -112,6 +144,51 @@ Generated files go in `.hector/` — add it to your `.gitignore`. The Renode **b
 
 ---
 
+## Run via Docker (no install)
+
+If you'd rather not install hector (or even Python) on the host, build the bundled
+image — it sits on top of the official Renode image, so `renode`, `renode-test`
+and `hector` are all inside one container:
+
+```bash
+cd cli
+docker build -t hector-renode .
+# match your project's renode_version:
+docker build --build-arg RENODE_VERSION=1.16.1 -t hector-renode:1.16.1 .
+```
+
+Because Renode is already in the image, hector runs **in-process**
+(`HECTOR_NO_DOCKER=1` is baked in) — no Docker socket, no sibling containers, no
+host-path matching. Use the bundled `hector-docker` wrapper, which mounts your
+project and runs as your UID so output stays yours:
+
+```bash
+./hector-docker test                       # run from your project directory
+./hector-docker validate -f ci.hector.yaml
+./hector-docker run --renode-args '--console'   # headless monitor (no GUI window)
+
+# use it like the real thing by symlinking onto your PATH:
+ln -s "$(pwd)/cli/hector-docker" ~/.local/bin/hector
+```
+
+Or the raw form (what the wrapper runs):
+
+```bash
+docker run --rm -it -u "$(id -u):$(id -g)" -e HOME=/tmp \
+  -v "$PWD":"$PWD" -w "$PWD" hector-renode test
+```
+
+Override the image tag with `HECTOR_IMAGE` (default `hector-renode:latest`).
+
+**Caveats of the in-image mode:** a `build:`/`shell` step's `image:` is ignored —
+the script runs in *this* image instead (a warning is printed), and module builds
+rely on this image's toolchain rather than a per-module one. Interactive `hector
+run` opens Renode's GUI, which needs X forwarding; pass `--renode-args '--console'`
+for a headless monitor. For full per-step image isolation (matching CI), install
+the CLI natively with `pip` and let hector launch real per-step containers.
+
+---
+
 ## Invocation modes
 
 | Command | Behaviour |
@@ -122,11 +199,13 @@ Generated files go in `.hector/` — add it to your `.gitignore`. The Renode **b
 | `hector run --set BIN=fw.elf --set BOARD=nucleo` | Override multiple arguments |
 | `hector run --debug boardA:3333` | Halt a CPU and open a GDB server |
 | `hector run --debug boardA:3333 --debug boardB:3334` | Halt multiple CPUs on different ports |
+| `hector run --no-start` | Load the platform and drop into the monitor **paused** — type `start` yourself |
 | `hector run --renode-args '--console'` | Pass extra flags verbatim to Renode |
 | `hector run --gather-execution-metrics` | Enable Renode's CPU execution profiler for all machines |
 | `hector run --gather-execution-metrics boardA` | Enable profiler for one specific machine |
 | `hector run --gather-execution-metrics boardA --gather-execution-metrics boardB` | Enable profiler for selected machines |
 | `hector run --renode-version 1.16.1` | Override the Renode version from `.hector.yaml` |
+| `hector run --renode-image my-renode:dev` | Use a specific (e.g. self-built) Renode Docker image |
 | `hector run --renode-dir /cache/renode` | Use/cache the Renode source checkout at this path (only fetched when needed) |
 | `hector run --renode-integration-dir /cache/integration` | Likewise for the verilator-integration checkout |
 | `hector run --no-docker` | Use locally installed `renode` / `renode-test` instead of Docker |
@@ -151,11 +230,15 @@ Generated files go in `.hector/` — add it to your `.gitignore`. The Renode **b
 | `hector validate -f board.yaml` | Validate a config file by another name |
 | `hector init` | Scaffold a starter `.hector.yaml` |
 | `hector init -f board.yaml` | Scaffold the starter config under a custom name |
+| `hector clean` | Remove generated build artifacts (`.hector/resc,repl,tests`) and `results/`; keeps the Renode cache |
+| `hector clean --all` | Also remove the cached Renode source checkouts under `.hector/` (forces a re-clone next build) |
+| `hector clean --output my-results` | Clean a custom results directory instead of `results/` |
+| `hector clean --dry-run` | Show what would be removed without deleting anything |
 | `hector --version` | Print the tool version |
 
 `hector` is structured as subcommands: `run` (simulate), `test` (run the `tests:`
-section), `export` (emit the command without running it), plus `init` and
-`validate`. Run `hector <command> --help` for the flags each one accepts.
+section), `export` (emit the command without running it), plus `init`, `validate`,
+and `clean`. Run `hector <command> --help` for the flags each one accepts.
 
 Every command reads (or, for `init`, writes) `.hector.yaml` by default. Point it
 at a different file with **`-f` / `--file`** — useful when one project keeps
@@ -166,6 +249,11 @@ hector test -f ci.hector.yaml
 hector run  --file boards/nucleo.yaml
 ```
 
+**`.yaml` and `.yml` are interchangeable.** If the requested file isn't there but its
+counterpart is, hector uses that instead — so a project may keep `.hector.yml` and
+every command still finds it with no flag, and `-f board.yaml` will pick up
+`board.yml`.
+
 ### Debug mode (`--debug NODE:PORT`)
 
 Repeat the flag for each machine you want to debug. ([Renode docs: GDB debugging](https://renode.readthedocs.io/en/latest/debugging/gdb.html))
@@ -181,6 +269,22 @@ server(s) and halts the debugged CPU(s) before resuming, so you can attach to a
 restored state. (A GDB server is a live connection, never part of saved snapshot
 state, so it is always (re)started on load.)
 
+### Manual start (`--no-start`)
+
+Every generated resc ends with a `start`, so `hector run` boots the platform
+immediately. Pass `--no-start` to omit it: hector builds/loads the platform, wires
+everything up, and drops you at the Renode monitor **paused**, so you can inspect
+state, set watchpoints, or step the setup by hand and issue `start` yourself.
+
+```bash
+hector run --no-start        # land in the monitor; type `start` when ready
+```
+
+- Applies to a fresh boot and to `--snapshot` (the restored state loads paused).
+- Composes with `--debug`: the GDB server(s) open at load, but nothing runs until
+  you `start`, so you can attach a debugger *before* the very first instruction.
+- `hector test` ignores this (tests must run); it only affects `run`/`export`.
+
 Connect with:
 ```bash
 arm-none-eabi-gdb firmware.elf
@@ -239,7 +343,7 @@ hector run --snapshot results/step_1_Linux_boots/snapshot.save
 hector test --snapshot results/step_1_Linux_boots/snapshot.save
 ```
 
-When used with `--renode-version`, no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
+When used with `--renode-version` (or `--renode-image`), no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
 
 ```bash
 hector run --snapshot /path/to/snapshot.save --renode-version 1.16.1
@@ -404,6 +508,20 @@ When combined with `--snapshot` in simulation mode, `.hector.yaml` is not requir
 hector run --snapshot path/to/snapshot.save --renode-version 1.16.1
 ```
 
+#### Using a custom Renode image (`--renode-image`)
+
+By default the image is `antmicro/renode:<renode_version>`. To use any other image — a nightly, a mirror in your registry, or one you built yourself — set `renode_image:` in `.hector.yaml` or pass `--renode-image`:
+
+```yaml
+renode_image: my-renode:dev
+```
+
+```bash
+hector test --renode-image ghcr.io/acme/renode:1.16.1-patched
+```
+
+Precedence: CLI flags beat the config, and either flag replaces *both* config fields (so `--renode-version 1.15.0` wins over a `renode_image:` in the file). If both fields are set in the config, `renode_image` is the image that runs and `renode_version` only picks the Renode source tag to clone. That tag is otherwise inferred from the image tag when it looks like a version (`…:1.16.1` / `…:v1.16.1`); if the config needs the source (see below) and it can't be inferred, also set `renode_version`.
+
 #### Renode source checkout
 
 Running a simulation does **not** need the Renode source — the binary and its bundled platforms come from the `antmicro/renode` Docker image. Hector clones the Renode source (and the verilator-integration repo) into `.hector/` **only when a config actually needs it**:
@@ -501,7 +619,8 @@ The configuration lives in `.hector.yaml`.
 | Field | Required | Description |
 |---|---|---|
 | `version` | No | Schema version (currently `"0.1"`). Warns if unrecognised. |
-| `renode_version` | Yes | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_version` | Yes¹ | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_image` | Yes¹ | Full Renode Docker image to use instead of `antmicro/renode:<renode_version>` (e.g. a self-built `my-renode:dev`). See [custom Renode image](#using-a-custom-renode-image---renode-image). |
 | `arguments` | No | Scalar defaults, overridable by env var or `--set`. |
 | `build` | No | Pre-sim shell steps run once per job in containers (compile firmware, fetch/generate files, …). Interpolated with the job's arguments/matrix variables. |
 | `matrix` | No | Cross-product job expansion. |
@@ -514,6 +633,8 @@ The configuration lives in `.hector.yaml`.
 | `quantum` | No | Override the global time quantum (seconds). |
 | `ci` | No | CI pipeline definitions: when and how a CI server runs this config. |
 
+¹ At least one of `renode_version` / `renode_image` is required (or the matching CLI flag).
+
 ---
 
 ### arguments
@@ -606,11 +727,21 @@ modules:
 
 #### kind: csharp
 
-Builds (or locates) a C# Renode peripheral plugin. The resulting `.dll` is loaded at emulation scope via `i @<path>` before any machine block, making the type available to all machines in the job. ([Renode docs: writing peripherals](https://renode.readthedocs.io/en/latest/advanced/writing-peripherals.html))
+A native C# Renode peripheral, loaded at emulation scope via `i @<path>` before any machine block so the type is available to every machine in the job. ([Renode docs: writing peripherals](https://renode.readthedocs.io/en/latest/advanced/writing-peripherals.html))
 
-Two usage modes:
+`source` can take three forms:
 
-**Pre-built DLL** — point `source` directly at the `.dll`:
+**Single `.cs` file (recommended)** — Renode compiles it **at load time** using its bundled C# compiler. No .NET SDK, no build step, nothing to install; the source is compiled against the running Renode's own assemblies, so it always matches the version in use. See the runnable [`csharp-peripheral`](examples/csharp-peripheral) example.
+
+```yaml
+modules:
+  my_periph:
+    kind: csharp
+    type: Antmicro.Renode.Peripherals.Miscellaneous.MyPeripheral
+    source: MyPeripheral.cs
+```
+
+**Pre-built DLL** — point `source` directly at a `.dll` (used as-is):
 
 ```yaml
 modules:
@@ -620,7 +751,7 @@ modules:
     source: prebuilt/my_periph.dll
 ```
 
-**Build from source** — point `source` at a directory containing a `.csproj`. `dotnet build` runs inside the Renode container (which ships with Mono/dotnet):
+**Build from a `.csproj`** — point `source` at a directory containing a `.csproj`; `dotnet build` (or `msbuild`) runs in the container. This needs an image that ships the **.NET SDK** *and* Renode's reference assemblies — the stock Renode image has only the runtime, so a `.cs` source is simpler unless you specifically need a pre-built binary:
 
 ```yaml
 modules:
@@ -633,10 +764,63 @@ modules:
 | Field | Required | Description |
 |---|---|---|
 | `kind` | Yes | Must be `csharp`. |
-| `type` | Yes | Fully qualified C# class name as it will appear in the generated `.repl`. |
-| `source` | Yes | Path to a `.csproj` directory **or** a pre-built `.dll` file. |
+| `type` | Yes | Fully qualified C# class name as it appears in the generated `.repl`. |
+| `source` | Yes | A `.cs` file (compiled at load), a `.csproj` directory (built in the container), **or** a pre-built `.dll`. |
+
+The `type` must match the class your source exposes. Multiple peripherals in the same job can share one source (different `type` values, same `source`); Hector emits a single `i @<path>` import even when multiple instances reference it.
+
+#### Developing your own peripherals
 
-The `type` field is what you would write in a `.repl` entry — it must match the class exposed by the compiled DLL. Multiple peripherals in the same job can share one DLL (different `type` values, same `source`); Hector emits a single `i @<path>` import even when multiple instances reference the same DLL.
+The `modules:` block above only *wires in* a peripheral you've built — the actual
+modelling (the Verilog/C++ of a Verilated block, or the C# of a native peripheral)
+is Renode's domain, not Hector's. Hector compiles your `source:` and loads the
+result; **how** you write that source is documented by Renode and Verilator. The
+references below are where to go to design your own hardware in depth.
+
+##### Verilated (HDL) peripherals
+
+A Verilated peripheral is your RTL (Verilog / SystemVerilog) compiled by Verilator
+and bridged to Renode over a bus interface (APB / AXI-Lite / Wishbone). Hector
+builds it from the CMake project you point `source:` at, linking against the
+**renode-verilator-integration** library (`${INTEGRATION_DIR}`).
+
+- **How Renode co-simulates HDL** (the model, the bus connectors, the lifecycle) — [Renode docs: Co-simulating with an HDL simulator](https://renode.readthedocs.io/en/latest/advanced/co-simulating-with-an-hdl-simulator.html)
+- **The integration library + copy-ready CMake samples** (start from `samples/uartlite`, which the `docker-runner`/module examples mirror) — [antmicro/renode-verilator-integration](https://github.com/antmicro/renode-verilator-integration)
+- **Verilating your RTL** (the Verilator C++ API, `--cc`, the `V<top>` model) — [Verilator manual](https://verilator.org/guide/latest/)
+- **Declaring the peripheral in a platform** (the `CoSimulated*` type, its bus window) — [Renode docs: platform description format](https://renode.readthedocs.io/en/latest/advanced/platform_description_format.html)
+
+Workflow: verilate your RTL → wrap it with the integration library's bus connector
+in a CMake project → point a `renode-verilator` module's `source:` at that project
+→ reference the module from a machine's `peripherals:`.
+
+##### C# peripherals
+
+A C# peripheral is a native Renode model — full speed, with direct access to
+Renode's register / IRQ / GPIO infrastructure. Use this when you don't have (or
+don't need) RTL, e.g. a register-level model of a sensor or controller.
+
+- **Writing a peripheral from scratch** (interfaces, read/write, reset — the canonical guide) — [Renode docs: Writing your own peripheral](https://renode.readthedocs.io/en/latest/advanced/writing-peripherals.html)
+- **Register modelling helpers** (`DoubleWordRegisterCollection`, fields, value/read/write callbacks) — [Renode docs: Registers](https://renode.readthedocs.io/en/latest/advanced/registers.html)
+- **Hundreds of real models to read and adapt** — the Renode source tree under [`src/.../Emulator/Peripherals`](https://github.com/renode/renode/tree/master/src/Infrastructure/src/Emulator/Peripherals/Peripherals)
+- **Wiring the finished class into a machine** (the `.repl` entry, IRQ/GPIO connections) — [Renode docs: platform description format](https://renode.readthedocs.io/en/latest/advanced/platform_description_format.html)
+
+Workflow: implement the class (e.g. an `IDoubleWordPeripheral` with a register
+collection, plus `GPIO`/`IKnownSize`/`IGPIOReceiver` as needed) in a **single
+`.cs` file** → point a `csharp` module's `source:` at it → reference its
+fully-qualified `type` from `peripherals:`. Renode compiles the `.cs` at load
+(bundled C# compiler — no .NET SDK), so this is the simplest, version-matched
+path; the [`csharp-peripheral`](examples/csharp-peripheral) example is a complete,
+runnable starting point. Reach for a `.csproj`/`.dll` only to pre-compile a larger
+project — and note that needs a build image carrying both the .NET SDK and
+Renode's reference assemblies.
+
+Either kind, once built, is a first-class Renode peripheral: connect it with
+[connections](#connection-syntax), bind it to host resources with [mappings](#mappings-global),
+and drive it from your [tests](#tests).
+
+> **Version note:** Renode's online docs track its latest release. If you pin an
+> older `renode_version:`, cross-check against that release's docs/tag — the
+> co-simulation bus interface and some C# APIs evolve between versions.
 
 ---
 
@@ -725,12 +909,16 @@ machines:
     backend: renode        # optional; 'renode' is the only supported backend
     platform:
       - platforms/boards/${BOARD}.repl
+    repl: |
+      ...
     firmware: ${FW}
     peripherals: { ... }
     connections: |
       ...
     mappings: |
       ...
+    resc: |
+      ...
     commands: |
       ...
 ```
@@ -738,15 +926,89 @@ machines:
 | Field | Description |
 |---|---|
 | `backend` | Must be `renode` (default). |
-| `platform` | List of [`.repl` platform description](https://renode.readthedocs.io/en/latest/advanced/platform_description_format.html) files loaded in order. |
+| `platform` | List of [`.repl` platform description](https://renode.readthedocs.io/en/latest/advanced/platform_description_format.html) **file paths**, loaded in order. |
+| `repl` | Inline `.repl` platform description **text** (see [below](#inline-repl-and-resc)). |
 | `firmware` | ELF file loaded with [`sysbus LoadELF`](https://renode.readthedocs.io/en/latest/basic/machines.html). Omit or set to `none` to skip. |
 | `peripherals` | Peripheral instances composed onto this machine. See below. |
 | `connections` | Signal wiring scoped to this machine. Covers GPIO, IRQ, and bracket-range connections. Bare peripheral names are accepted. |
 | `mappings` | Per-machine host resource bindings. Same syntax as global `mappings:`. |
+| `resc` | Inline `.resc` monitor-script **text** (see [below](#inline-repl-and-resc)). |
 | `commands` | Raw [Renode monitor](https://renode.readthedocs.io/en/latest/basic/monitor-syntax.html) commands inserted into the resc after hardware loads. |
 
 > **Note:** `artifacts` is now a **top-level** key, not a per-machine one. See [artifacts](#artifacts).
 
+#### Inline `repl` and `resc`
+
+`platform:` takes *paths*, which only works for boards the released Renode image
+already ships. When the board you need exists only on Renode's **master** branch (or
+in your own fork), there is no path to point at — so `repl:` and `resc:` take the
+file **contents** verbatim instead:
+
+```yaml
+machines:
+  mcu:
+    repl: |                                   # a .repl pasted straight in
+      sram: Memory.MappedMemory @ sysbus 0x20000000
+          size: 0x10000000
+      cpu: CPU.CortexM @ sysbus
+          cpuType: "cortex-m3"
+          nvic: nvic
+    resc: |                                   # a .resc's setup lines
+      sysbus ApplySVD @https://.../STM32F103.svd.gz
+      sysbus Tag <0x40021000, 0x40021003> "RCC_CR" 0x0A020083
+```
+
+- **`repl:`** is written to `.hector/repl/job_<n>_<node>.inline.repl` and loaded with
+  `machine LoadPlatformDescription` (Renode only reads platform descriptions from
+  disk). It is loaded **after** any `platform:` files.
+
+> **Patching a bundled platform: use `using`, not `platform:`.** Every
+> `LoadPlatformDescription` is its **own description scope**, so an entry that another
+> file created is only partly reachable from `repl:` — setting a *constructor*
+> attribute on it fails with
+> `E35: Constructor attribute within entry for variable that is not created`.
+> To override one, pull the base platform into the *same* scope from inside `repl:`:
+>
+> ```yaml
+> repl: |
+>   using "platforms/boards/nucleo_h753zi.repl"
+>
+>   nvic:
+>       priorityMask: 0xFF        # works: same scope that creates `nvic`
+> ```
+>
+> This is what Renode's own scripts do with `LoadPlatformDescriptionFromString`.
+> Use `platform:` alone when you're loading a board as-is, and `using` inside `repl:`
+> when you need to patch it. See [`examples/nucleo-h753zi`](examples/nucleo-h753zi).
+- **`resc:`** is emitted verbatim into that machine's block, **after** the platform
+  and firmware load and **before** `commands:`.
+
+Resulting order inside one machine:
+
+```
+mach create "<node>"
+machine LoadPlatformDescription @<platform: files>
+machine LoadPlatformDescription @<inline repl:>
+sysbus LoadELF @<firmware:>
+<resc:>
+<commands:>
+```
+
+> **Do not put `mach create` in `resc:`** — hector already creates the machine. Use
+> `resc:` for the lines that follow it (`sysbus ApplySVD`, `sysbus Tag`, macros,
+> additional `LoadPlatformDescription`, …).
+
+Both accept a block scalar or a list of lines, and both are interpolated like every
+other field. Worked examples:
+
+- [`examples/inline-repl-resc`](examples/inline-repl-resc) — the mechanics, on an
+  STM32F103 that boots real firmware.
+- [`examples/nucleo-f767zi`](examples/nucleo-f767zi) — the real motivation: a
+  **NUCLEO-F767ZI**, which Renode 1.16.1 ships no `.repl` for at all, defined inline
+  and running against the pinned release image.
+- [`examples/nucleo-h753zi`](examples/nucleo-h753zi) — the other side: a board that
+  **is** shipped, loaded via `using` and *patched* inline, booting Hubris.
+
 #### peripherals
 
 Each entry declares one peripheral instance on this machine. The `type` field is either a built-in Renode class name, a `renode-verilator` module name, or a `csharp` module name. Properties are written directly as flat keys alongside `type` and `at`.