François
a4f8254cb3
DESIGN.md: libbsdl dependency and --batch headless mode; bsdl_model/bsdl_check in the layout; the attach-bsdl command and the `B` persist tag; PinSpec is now BSDL-populated; verify's five passes incl. the model-driven and JTAG checks and the new AnomalyKinds. README: libbsdl dependency, --batch usage, tutorial link. New doc/user/tutorial.md: end-to-end batch and TUI walkthroughs (load → tag → connect → attach-bsdl → verify, with the pin/JTAG findings explained). Regenerated commands.md (adds attach-bsdl); index.md links the tutorial. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
# essim — user guide
|
||
|
||
A short, task-oriented introduction to using essim. For step-by-step
|
||
**batch** and **TUI** walkthroughs, see [`tutorial.md`](tutorial.md). 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-connector-type backplane J20 vpx-3u-bkp-p0
|
||
> set-connector-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-connector-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`, `set-connector-type`,
|
||
`explore`, `analyze`. 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
|
||
|
||
- [`tutorial.md`](tutorial.md) — end-to-end batch and TUI walkthroughs,
|
||
including BSDL attach + the pin/JTAG checks.
|
||
- [`commands.md`](commands.md) — exhaustive command reference,
|
||
regenerated from the binary on every `cmake --build build --target doc`.
|
||
- [`analysis.md`](analysis.md) — how essim classifies signals
|
||
(Power / Gnd / Other), how it detects buses and diff pairs, what
|
||
the `analyze` screen actually reports and why.
|
||
- [`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.
|