electronics/essim
1
0
Fork 0
Code Issues 3 Pull Requests Packages Releases Wiki Activity

docs: document the BSDL workflow + add a batch/TUI tutorial

Browse Source 
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>
This commit is contained in:
Foué
2026-06-03 15:46:56 +02:00
parent 581028a83d
commit a4f8254cb3
5 changed files with 274 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
doc/user/commands.md
View File

@@ -37,7 +37,7 @@ browse modules → parts/signals/connections → details (interactive)
---
### `export` *(interactive)*
export structured data to CSV (kinds: connections; bare form opens the file-picker dialog)
export structured data to CSV / ODS (kinds: connections; bare form opens the file-picker dialog)
**Arguments**
@@ -88,6 +88,21 @@ tag a part's connector type for transform lookup
detect signal groups (diff pairs, buses) and structural anomalies
**No arguments.**
---
### `attach-bsdl`
attach a BSDL (.bsd) model to a part and populate pin specs
**Arguments**
1. `module`
2. `part (name or pattern)`
3. `bsdl file (.bsd path)`
**Notes**
- no per-arg prompt: pass all args inline (or run bare for an empty-args path)
---
### `clear`
@@ -238,7 +253,7 @@ execute a file of commands line by line (interactive cmds rejected)
---
### `verify`
check pin roles locally and signal-type consistency across bridged nets
check pin roles, bridged-net consistency, and model-driven pin specs (contention/undriven/NC)
**No arguments.**
---

9
doc/user/index.md
View File

@@ -1,8 +1,9 @@
# 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,
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
@@ -91,6 +92,8 @@ 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

225
doc/user/tutorial.md Normal file
View File

@@ -0,0 +1,225 @@
# essim — tutorial
Two end-to-end walkthroughs of the same work. The **batch** one runs everything
from a script with no terminal UI (ideal for CI or quick reproducible checks);
the **TUI** one drives the same operations interactively.
Both assume essim is built (`cmake -S . -B build && cmake --build build -j` — see
the [README](../../README.md)). For the exhaustive command list see
[`commands.md`](commands.md); for `$variable` expansion see
[`scripting.md`](scripting.md).
---
## 1. Batch mode
`essim --batch --source FILE` runs an essim script and prints the console output
to stdout, then exits — no TUI. The script is the same language you'd type at the
prompt: one command per line, `#` comments, blank lines ignored, `$variables`
expanded, `~/` paths supported.
### 1.1 A first script
Create `bring-up.essim`:
```text
# Load two cards, tag + wire their VPX connectors, then verify.
new
set nl /path/to/netlists
load backplane $nl/backplane.NET altium
load payload1 $nl/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 system.essim
```
Run it:
```sh
./build/essim --batch --source bring-up.essim
```
Each command is echoed with its result, e.g.:
```text
> load backplane /path/to/netlists/backplane.NET altium
loaded 'backplane' from /path/to/netlists/backplane.NET
> connect backplane J20 payload1 P0
connected: backplane/J20 <-> payload1/P0 via vpx-3u-p0 (59 wires)
> verify
verify: 0 local mismatch(es) over 0 typed pin(s).
verify: 0 inconsistent net(s) over 1 bridged net(s) (... total).
...
```
### 1.2 Attaching a BSDL model and checking the JTAG chain
For complex ICs (FPGAs, big SoCs) you can attach a **BSDL** (`.bsd`) device model
to a part. essim binds each BSDL port to a pin — **by port name first, then by
package ball** — and fills the pin's direction / function / pad. `verify` then
runs model-driven checks on top of the basic ones.
Add this before `verify`:
```text
attach-bsdl payload1 U14 /path/to/bsdl/xcku15p_ffve1517.bsd
```
`attach-bsdl` reports the binding:
```text
payload1/U14: attached BSDL 'XCKU15P_FFVE1517' — 1517/1517 ports bound
```
and `verify` now also prints the model-driven and JTAG passes, e.g.:
```text
verify: 0 model-driven pin anomaly(ies).
[jtag-bus-unbridged] TMS is not common to all TAP devices (off-bus: ...)
[jtag-chain-break] JTAG chain is not a single daisy chain: 3 head(s), 3 tail(s) over 3 TAP device(s)
verify: 3 JTAG chain anomaly(ies).
```
What the new findings mean:
| Finding | Meaning |
|---|---|
| `drive-contention` | ≥2 push-pull outputs share a net |
| `undriven-net` | a **fully-modelled** net has input(s) but no driver |
| `nc-wired` | a no-connect pin is wired onto a multi-pin net |
| `jtag-tap-incomplete` | a TAP device is missing TDI/TDO/TMS/TCK |
| `jtag-bus-unbridged` | TMS or TCK isn't common to every TAP device |
| `jtag-chain-break` | the TDO→TDI daisy chain dangles, forks, or isn't a single path |
`undriven-net` only fires when *every* pin on the net is modelled — otherwise the
driver might sit on a part with no model, so essim stays quiet rather than guess.
The attached `.bsd` path is stored in the `save` snapshot and re-applied on
`restore` (the path is persisted, not the derived pin data), so the model survives
round-trips.
### 1.3 Capturing and chaining
`--batch` exits 0 after the script, so pipe/grep the output like any tool:
```sh
./build/essim --batch --source bring-up.essim | grep -E '\[jtag-|verify:'
```
Layer a script on top of a saved snapshot with `--restore`:
```sh
./build/essim --batch --restore system.essim --source extra.essim
```
---
## 2. TUI mode
Launch with no script:
```sh
./build/essim
```
You land on the **dashboard** — a read-only overview (module / part / signal /
connection counts, health rows, a per-module table). It's the home screen.
### 2.1 Getting around
Dashboard single-key shortcuts:
| Key | Goes to |
|---|---|
| `c` | console (type commands, read output) |
| `p` | plug / connect screen |
| `t` | set-connector-type screen |
| `e` | explore screen |
| `a` | analyze screen |
| `q` | quit |
From anywhere, `Ctrl-P` opens the **command palette** (fuzzy-find a command, or
jump to a module / signal). `Esc` backs out of a screen or cancels a prompt.
### 2.2 The console
Press `c`. This is the textual shell — the same commands as the batch script,
typed one at a time:
```text
> new
> load backplane ~/netlists/backplane.NET altium
> set-connector-type backplane J20 vpx-3u-bkp-p0
> verify
```
Helpers:
| Action | How |
|---|---|
| List commands / help on one | `help`, `help <name>` |
| Tab-complete a command or path | `‹Tab›` |
| Recall previous commands | ↑ / ↓ |
| Scroll output | `PageUp`/`PageDown`, `Home`/`End` |
| Cancel a multi-step prompt | `Esc` |
Any command works inline (`set-connector-type backplane J20 vpx-3u-bkp-p0`) or
**bare** to open its interactive screen (`set-connector-type` then Enter).
### 2.3 Interactive screens
Bare `connect`, `set-connector-type`, `explore`, `analyze` open a full-screen
layout. Conventions: a title bar at the top, `Tab` cycles fields (the active one
flips to reverse video), `Esc` returns to the prompt.
- **connect** (`p`) — pick module A, filter + pick its part, module B, its part,
then Apply. The transform is chosen from the two `connector_type`s.
- **set-connector-type** (`t`) — pick a module, filter + pick a part, type the
kind, Apply. Materialises any missing layout pins and fills each pin's expected
spec.
- **explore** (`e`) — browse modules → parts / signals → pins. Selecting a signal
shows its net (the members reached across connections); Enter on a signal opens
the power / gnd / other popup.
- **analyze** (`a`) — Issues / Groups / Types panes: pin-role mismatches,
bridged-net inconsistencies, diff pairs, buses, structural anomalies.
### 2.4 Attaching BSDL in the TUI
`attach-bsdl` has no dedicated screen — run it inline from the console:
```text
> attach-bsdl payload1 U14 ~/bsdl/xcku15p_ffve1517.bsd
payload1/U14: attached BSDL 'XCKU15P_FFVE1517' — 1517/1517 ports bound
> verify
```
The model-driven and JTAG findings appear in the console output (see §1.2).
(Surfacing them on the analyze screen is planned.)
### 2.5 Saving your work
| Command | Writes |
|---|---|
| `save <file>` | full snapshot (including attached BSDL paths) |
| `script-save <file>` | replay-ready script of this session |
| `source <file>` | run a script line by line |
A common loop: experiment in the console, `script-save` what works, hand-edit it
into a parametrised `$variable` script, then `--batch --source` it for repeatable
runs.
---
## Where to look next
- [`index.md`](index.md) — the user-guide overview.
- [`commands.md`](commands.md) — every command, regenerated from the binary.
- [`analysis.md`](analysis.md) — signal classification, buses, diff pairs.
- [`scripting.md`](scripting.md) — `set` / `$var`, `source` semantics.
- [`../../DESIGN.md`](../../DESIGN.md) — implementation notes (BSDL ingest, checks).