hector-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{hector_cli-0.2.0 → hector_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hector-cli
-Version: 0.2.0
+Version: 0.3.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,6 +199,7 @@ 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 |
@@ -166,6 +244,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 +264,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
@@ -606,11 +705,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))
+
+`source` can take three forms:
 
-Two usage modes:
+**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 the `.dll`:
+**Pre-built DLL** — point `source` directly at a `.dll` (used as-is):
 
 ```yaml
 modules:
@@ -620,7 +729,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 +742,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 `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
 
-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.
+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 +887,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 +904,69 @@ 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, so it can extend or override
+  them — list a released board under `platform:` and patch it with `repl:`.
+- **`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.
+
 #### 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`.