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](../../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).