François
043fef0a31
- `essim --commands-md [file]` instantiates the Tui, calls
`Tui::DumpCommandsMd(ostream&)` which iterates the live registry and
emits Markdown grouped by interactive/other, then exits. Single
source of truth: a new `CommandSpec` field surfaces automatically.
- CMake `doc` target now `DEPENDS essim` and chains:
doxygen → gen_api_md.py → doc/api/
essim --commands-md → doc/user/commands.md
- `doc/user/` adds:
- index.md (hand-written) — first session, interactive-screen
conventions, save/restore/replay overview.
- scripting.md (hand-written) — `set`/`$var` expansion semantics,
`source` event-paced execution, script-save denylist, worked
example pointing at test/system.essim.
- commands.md (auto-generated, regenerated by the `doc` target).
- Top-level README refocused on quick start; pointers to the new
doc tree (user/, api/, DESIGN.md) instead of an inline command table.
- doc/README.md and DESIGN.md document the two-pipeline doc workflow.
- `test/system.essim` and user docs anonymised: bkp → backplane,
vdn1/2/3 → payload1/2/3, cb3p → payload4, bpb/cob/ssu →
peripheral1/2/3; netlist file names + variable names + paths all
replaced with generic equivalents.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
# essim — user guide
|
||
|
||
A short, task-oriented introduction to using essim. For an exhaustive
|
||
reference of every command, see [`commands.md`](commands.md) (auto-
|
||
generated from the binary). For scripting and `$variable` expansion,
|
||
see [`scripting.md`](scripting.md).
|
||
|
||
## What essim is
|
||
|
||
A digital twin for the inter-card connections inside a system. You
|
||
**load** modules (cards/boards) from netlist or pinout files, **tag**
|
||
their connectors with a `connector_type`, **connect** them across
|
||
modules, and **verify** that the signal types match the connector role
|
||
expectations. You can save a snapshot, restore it later, or replay a
|
||
session as a script.
|
||
|
||
```
|
||
┌──────────┐ ┌──────────┐
|
||
│ Module A │ │ Module B │
|
||
│ Part J1 │◀──▶│ Part P1 │ <— a Connection (built by `connect`)
|
||
│ pins │ │ pins │
|
||
└──────────┘ └──────────┘
|
||
```
|
||
|
||
## First session
|
||
|
||
After launching `./build/essim`, the prompt accepts a sequence of
|
||
commands. The most common bring-up looks like this:
|
||
|
||
```text
|
||
> new
|
||
> load backplane /path/to/netlists/backplane.NET altium
|
||
> load payload1 /path/to/netlists/payload.qcv mentor
|
||
> set-type backplane J20 vpx-3u-bkp-p0
|
||
> set-type payload1 P0 vpx-3u-payload-p0
|
||
> connect backplane J20 payload1 P0
|
||
> verify
|
||
> save my-system.essim
|
||
```
|
||
|
||
Things to try at any time:
|
||
|
||
| Action | How |
|
||
|---|---|
|
||
| List every command | `help` |
|
||
| Help on one command | `help <name>` |
|
||
| Scroll back through output | `PageUp` / `PageDown`, `Home`, `End` |
|
||
| Re-run a previous command | ↑ / ↓ (also `history` is on disk) |
|
||
| Tab-complete a command name | `set‹Tab›` → `set-type` etc. |
|
||
| Cancel a multi-step prompt | `Esc` |
|
||
| Leave essim | `quit` (or `exit`) |
|
||
|
||
## Interactive screens
|
||
|
||
Some commands open a dedicated full-screen layout when invoked with no
|
||
arguments (the help listing tags these `[interactive]`). They all
|
||
share the same conventions:
|
||
|
||
- A title bar `essim → <name> — <short description>` is shown at the
|
||
top.
|
||
- `Tab` cycles focus between fields; the active field's label flips to
|
||
reverse video so it's obvious where the next keystroke goes.
|
||
- `Esc` leaves the screen and returns to the main prompt.
|
||
- The screens are user-facing only — they are **never** allowed inside
|
||
a sourced script. A sourced script must use the inline form of these
|
||
commands instead.
|
||
|
||
Today's interactive screens: `connect`, `search`, `set-type`,
|
||
`explore`, `net`. See [`commands.md`](commands.md) for each.
|
||
|
||
## Saving, restoring, replaying
|
||
|
||
Three orthogonal mechanisms persist your work:
|
||
|
||
- `save <file>` writes a **binary-tab-delimited snapshot** of the whole
|
||
system (modules, parts, signals, connector types, signal-type
|
||
overrides, connections, pin maps). `restore <file>` replaces the
|
||
current system with the snapshot.
|
||
- `script-save <file>` writes a **replay-ready text script** of every
|
||
command issued since the last `new`. The interactive bits and the
|
||
noisy commands (`clear`, `help`, …) are filtered out automatically.
|
||
- `source <file>` reads a script line by line. Comments start with
|
||
`#`, blank lines are skipped, leading `~/` in paths is expanded, and
|
||
while a script is running a centred "Computing…" modal shows the
|
||
progress (one line per ~30 ms tick).
|
||
|
||
A typical workflow: experiment in the shell, `script-save` the part
|
||
that works, hand-edit the script to introduce `$variables` (see
|
||
[`scripting.md`](scripting.md)), then `source` it whenever you start
|
||
fresh.
|
||
|
||
## Where to look next
|
||
|
||
- [`commands.md`](commands.md) — exhaustive command reference,
|
||
regenerated from the binary on every `cmake --build build --target doc`.
|
||
- [`scripting.md`](scripting.md) — `set` / `$var` / `${var}`, `source`
|
||
semantics, the script-save denylist.
|
||
- [`DESIGN.md`](../../DESIGN.md) — implementation notes, useful if
|
||
you want to add a command or a screen.
|
||
- [`../api/`](../api/) — auto-generated C++ API reference.
|