User-facing docs: --commands-md flag, doc/user/ tree, anonymised script.
- `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>
This commit is contained in:
242
doc/user/commands.md
Normal file
242
doc/user/commands.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# essim — command reference
|
||||
|
||||
Auto-generated from the live command registry. Regenerate with
|
||||
`cmake --build build --target doc` after adding or changing
|
||||
commands; the binary itself is the single source of truth.
|
||||
|
||||
Keys global to the shell: `Esc` cancels a multi-step prompt or
|
||||
leaves an interactive screen; `Tab` completes commands/paths
|
||||
(top-level prompt) or cycles focus inside an interactive
|
||||
screen; `PageUp` / `PageDown` scroll output by 10 lines,
|
||||
`Home` / `End` jump to top / bottom; ↑ / ↓ walk command
|
||||
history.
|
||||
|
||||
## Interactive commands
|
||||
|
||||
### `connect` *(interactive)*
|
||||
|
||||
connect a part across two modules (interactive screen if no args)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `module1`
|
||||
2. `part1 (name or pattern)`
|
||||
3. `module2`
|
||||
4. `part2 (name or pattern)`
|
||||
|
||||
**Notes**
|
||||
|
||||
- bare form opens an interactive screen; inline form (all args) is scriptable
|
||||
|
||||
---
|
||||
### `explore` *(interactive)*
|
||||
|
||||
browse modules → parts/signals/connections → details (interactive)
|
||||
|
||||
**No arguments.**
|
||||
**Notes**
|
||||
|
||||
- bare form opens an interactive screen; inline form (all args) is scriptable
|
||||
- not recorded by `script-save` and rejected by `source`
|
||||
|
||||
---
|
||||
### `net` *(interactive)*
|
||||
|
||||
show all signals reachable from <module>/<signal> through connections (interactive screen if no args)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `module`
|
||||
2. `signal name`
|
||||
|
||||
**Notes**
|
||||
|
||||
- bare form opens an interactive screen; inline form (all args) is scriptable
|
||||
|
||||
---
|
||||
### `search` *(interactive)*
|
||||
|
||||
list parts/signals matching a pattern (interactive screen if no args)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `module`
|
||||
2. `kind [parts|signals]`
|
||||
3. `pattern`
|
||||
|
||||
**Notes**
|
||||
|
||||
- bare form opens an interactive screen; inline form (all args) is scriptable
|
||||
|
||||
---
|
||||
### `set-type` *(interactive)*
|
||||
|
||||
tag a part's connector type for transform lookup
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `module`
|
||||
2. `part (name or pattern)`
|
||||
3. `connector type (free string, e.g. vpx-bp, vpx-payload)`
|
||||
|
||||
**Notes**
|
||||
|
||||
- bare form opens an interactive screen; inline form (all args) is scriptable
|
||||
|
||||
---
|
||||
|
||||
## Other commands
|
||||
|
||||
### `clear`
|
||||
|
||||
clear the visualization area
|
||||
|
||||
**No arguments.**
|
||||
---
|
||||
### `duplicate`
|
||||
|
||||
clone a module under a new name (parts, pins, signals; no connections)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `source module`
|
||||
2. `new module name`
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `exit`
|
||||
|
||||
leave essim (alias of quit)
|
||||
|
||||
**No arguments.**
|
||||
---
|
||||
### `help`
|
||||
|
||||
show command help (optionally for a specific command)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `command name (optional)` *(Tab → command completion)*
|
||||
|
||||
**Notes**
|
||||
|
||||
- no per-arg prompt: pass all args inline (or run bare for an empty-args path)
|
||||
|
||||
---
|
||||
### `load`
|
||||
|
||||
load a module from a netlist / pinout file (mentor, altium, ods)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `module name`
|
||||
2. `filename` *(Tab → path completion)*
|
||||
3. `import type [mentor|altium|ods]`
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `new`
|
||||
|
||||
create a new (empty) system; resets the script-save buffer and $vars
|
||||
|
||||
**No arguments.**
|
||||
---
|
||||
### `quit`
|
||||
|
||||
leave essim
|
||||
|
||||
**No arguments.**
|
||||
---
|
||||
### `restore`
|
||||
|
||||
replace the current system with a saved snapshot
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `filename` *(Tab → path completion)*
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `save`
|
||||
|
||||
write the current system snapshot to a file
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `filename` *(Tab → path completion)*
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `script-save`
|
||||
|
||||
write commands run since last 'new' as a replay-ready script
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `filename` *(Tab → path completion)*
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `set`
|
||||
|
||||
define a $variable for substitution in subsequent commands (no args = list defined vars)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `name`
|
||||
2. `value`
|
||||
|
||||
**Notes**
|
||||
|
||||
- no per-arg prompt: pass all args inline (or run bare for an empty-args path)
|
||||
|
||||
---
|
||||
### `set-signal-type`
|
||||
|
||||
override the auto-detected signal type (power | gnd | other)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `module`
|
||||
2. `signal name`
|
||||
3. `type [power|gnd|other]`
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `source`
|
||||
|
||||
execute a file of commands line by line (interactive cmds rejected)
|
||||
|
||||
**Arguments**
|
||||
|
||||
1. `filename` *(Tab → path completion)*
|
||||
|
||||
**Notes**
|
||||
|
||||
- missing args trigger one prompt each
|
||||
|
||||
---
|
||||
### `verify`
|
||||
|
||||
check pin roles locally and signal-type consistency across bridged nets
|
||||
|
||||
**No arguments.**
|
||||
---
|
||||
100
doc/user/index.md
Normal file
100
doc/user/index.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# 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.
|
||||
132
doc/user/scripting.md
Normal file
132
doc/user/scripting.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# essim — scripting
|
||||
|
||||
This page covers the two facilities that make essim sessions
|
||||
reproducible: `source` (replay a file) and `set` (declare named
|
||||
variables that subsequent commands expand). For the per-command
|
||||
reference, see [`commands.md`](commands.md).
|
||||
|
||||
## File format
|
||||
|
||||
A script is a plain text file, one command per line. The format is
|
||||
intentionally minimal:
|
||||
|
||||
- Lines starting with `#` are comments — skipped.
|
||||
- Blank lines are skipped.
|
||||
- Leading / trailing whitespace is trimmed.
|
||||
- A leading `~/` in arguments is expanded to `$HOME` (paths only).
|
||||
- Each line goes through the same `Submit` path as if typed at the
|
||||
prompt, so anything that works interactively works in a script
|
||||
*except* commands that open an interactive screen (see below).
|
||||
|
||||
By convention essim scripts use the `.essim` extension.
|
||||
|
||||
## Variables — `set` and `$expansion`
|
||||
|
||||
`set <name> <value>` declares a **session-scoped** variable. Subsequent
|
||||
commands expand `$name` and `${name}` in their arguments:
|
||||
|
||||
```text
|
||||
> set netlist_dir /path/to/netlists
|
||||
> set backplane_nets $netlist_dir/backplane.NET
|
||||
> load backplane $backplane_nets altium
|
||||
```
|
||||
|
||||
Names must match `[A-Za-z_][A-Za-z0-9_]*`. Unknown variables are left
|
||||
literal (`$undef` stays `$undef`) so a typo surfaces as a "file not
|
||||
found" or "unknown module" error rather than a silent empty string.
|
||||
|
||||
The expansion happens at **dispatch time**, between recording the
|
||||
canonical form and calling the action. So:
|
||||
|
||||
- `history` and `script-save` keep the **unexpanded** form (`$backplane_nets`
|
||||
is preserved as `$backplane_nets`), which makes the recorded script
|
||||
portable across sessions if you set the variables before sourcing it.
|
||||
- The action itself sees the resolved value (the actual filesystem
|
||||
path).
|
||||
|
||||
`new` resets the variable table to empty.
|
||||
|
||||
## Replaying — `source <file>`
|
||||
|
||||
`source <file>` runs the script line by line. Three behavioural
|
||||
details are worth knowing:
|
||||
|
||||
1. **Event-paced execution.** The runtime processes one effective line
|
||||
(skipping comments / blanks) every ~30 ms tick, dispatched by a
|
||||
background thread that posts FTXUI events. This lets the screen
|
||||
redraw between lines and surface a centred `Computing…` modal with
|
||||
a `N / M lines` counter. Without this pacing, FTXUI would batch
|
||||
queued events and freeze the modal until the entire script is done.
|
||||
|
||||
2. **Interactive screens are rejected.** If a sourced line opens a
|
||||
full-screen mode (`screen_idx != 0` after `Submit`), the script is
|
||||
aborted with `source: line <N> is interactive (would open a
|
||||
screen) — aborting.`. The fix is to use the inline form of that
|
||||
command (e.g. `connect backplane J20 payload1 P0` instead of a bare
|
||||
`connect`).
|
||||
|
||||
3. **Pending prompts are filled by subsequent lines.** A multi-step
|
||||
command split across lines is treated as one logical unit. If the
|
||||
first line says `load`, the next non-blank line answers the
|
||||
`module name?` prompt, then `filename?`, then `import type?`.
|
||||
|
||||
While `in_source = true`:
|
||||
- `Dispatch` / `Finalize` skip writing to memory + on-disk history.
|
||||
- The `recorded` buffer (used by `script-save`) is still populated
|
||||
with each effective line; so sourcing a script and immediately
|
||||
running `script-save` produces a self-contained replay even if the
|
||||
original source path is lost.
|
||||
|
||||
## Recording — `script-save <file>`
|
||||
|
||||
`script-save <file>` dumps every command issued since the last `new`
|
||||
into `<file>`, one line per command, in canonical inline form. The
|
||||
following commands are deliberately **not** recorded:
|
||||
|
||||
```
|
||||
clear, help, quit, exit, source, script-save
|
||||
```
|
||||
|
||||
`source` is excluded for a subtle reason: when you source a script,
|
||||
the individual lines inside it go through `Finalize` and *are*
|
||||
recorded, so the saved replay reproduces the same end-state without
|
||||
the indirection.
|
||||
|
||||
`set` lines and `$var` references are recorded as typed, so the saved
|
||||
script keeps its abstraction.
|
||||
|
||||
## Worked example
|
||||
|
||||
The `test/system.essim` script (committed in the repo) is the
|
||||
canonical anonymised bring-up — one backplane, four payload cards,
|
||||
three peripherals:
|
||||
|
||||
```text
|
||||
new
|
||||
|
||||
# variables
|
||||
set netlist_dir /path/to/netlists
|
||||
set peripheral1_nets $netlist_dir/peripheral1.qcv
|
||||
set backplane_nets $netlist_dir/backplane.NET
|
||||
# ... more set lines ...
|
||||
|
||||
# modules
|
||||
load payload1 $payload_nets mentor
|
||||
duplicate payload1 payload2
|
||||
duplicate payload1 payload3
|
||||
load peripheral1 $peripheral1_nets mentor
|
||||
load backplane $backplane_nets altium
|
||||
# ... more loads ...
|
||||
|
||||
# connector type tagging
|
||||
set-type backplane J20 vpx-3u-bkp-p0
|
||||
set-type payload1 P0 vpx-3u-payload-p0
|
||||
# ... more tags ...
|
||||
|
||||
# wiring
|
||||
connect backplane J20 payload1 P0
|
||||
# ... more connects ...
|
||||
```
|
||||
|
||||
Run it with `source test/system.essim` after adjusting `$netlist_dir`
|
||||
to point at your real netlist files.
|
||||
Reference in New Issue
Block a user