essim/doc/user/tutorial.md

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). For the exhaustive command list see commands.md; for $variable expansion see 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:

# 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:

./build/essim --batch --source bring-up.essim

Each command is echoed with its result, e.g.:

> 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:

attach-bsdl payload1 U14 /path/to/bsdl/xcku15p_ffve1517.bsd

attach-bsdl reports the binding:

payload1/U14: attached BSDL 'XCKU15P_FFVE1517' — 1517/1517 ports bound

and verify now also prints the model-driven and JTAG passes, e.g.:

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:

./build/essim --batch --source bring-up.essim | grep -E '\[jtag-|verify:'

Layer a script on top of a saved snapshot with --restore:

./build/essim --batch --restore system.essim --source extra.essim

---

2. TUI mode

Launch with no script:

./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:

> 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_types.
• 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:

> 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 — the user-guide overview.
• commands.md — every command, regenerated from the binary.
• analysis.md — signal classification, buses, diff pairs.
• scripting.md — set / $var, source semantics.
• ../../DESIGN.md — implementation notes (BSDL ingest, checks).