François
300e871aed
- New `screen_help.cpp` (`screen_idx = 6`). Left column: menu of 13 topics (Overview, Dashboard, Console, Palette, Explore, Connect/plug, set-connector-type, Signal types, NC pins, Analyze, Scripting, Save/restore, Quitting). Centre column: paragraphs of the focused topic, word-wrapped via `paragraph()` and scrollable. Right column: standard help panel. - `help` bare → opens the screen; `help <name>` keeps the existing textual command-help behaviour for scripts. - Dashboard `[h]` shortcut opens the screen, and the dashboard help panel (both the loaded and the no-system branch) lists it. - Console: title gets the standard breadcrumb (`essim → console — type commands, read textual output`). Module/connection counters moved off (they live on the dashboard now). - Explore Enter on a part jumps to `set-connector-type` with the exact-match index pre-computed in the filtered list (avoids the substring-match collision where `J20` would land on the wrong row when J200/J21 also matched). - set-connector-type screen: bind `focused_entry` to `selected` on both menus so the cursor `>` tracks the selected row when state is pre-seeded from outside. Right column drops its strict `size(WIDTH, EQUAL, 40)` in favour of `flex`, and the `new type` input uses `xflex` so it actually stretches across the column. - Esc on `set-connector-type` honours `screen_back_idx` — when entered via Enter on a part in `explore`, Esc returns to explore; otherwise it returns to the dashboard like every other screen. Standalone command entries explicitly reset the back-link. - Net-member rows in the explore detail pane carry a `module\tsignal` payload so Enter opens the popup scoped to the peer module rather than mis-firing on the locally selected one. Same scheme for local-pin rows. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
145 lines
6.3 KiB
Markdown
145 lines
6.3 KiB
Markdown
# essim — how the analysis classifies things
|
|
|
|
essim looks at signal names and the way pins are wired to decide
|
|
whether a net is a **power rail**, a **ground**, a **diff pair**, a
|
|
**bus**, etc. This page summarises those rules in plain language so you
|
|
know what to expect when you run `analyze` (the `[a]` shortcut on the
|
|
dashboard) or when you read the numbers on the home screen.
|
|
|
|
Nothing here mutates anything you cannot fix manually: every
|
|
inference can be overridden with `set-signal-type`, and the rules are
|
|
re-run on every `load` so the picture stays consistent with the
|
|
netlists currently in memory.
|
|
|
|
## Signal type — Power / Gnd / Other
|
|
|
|
Every signal is classified into one of three buckets.
|
|
|
|
**Gnd** if the name matches one of:
|
|
`GND`, `GROUND`, `EARTH`, `SHIELD`, `CHASSIS` (or starts with any of
|
|
those followed by `_`). The name alone is enough — false positives
|
|
here are essentially nil.
|
|
|
|
**Power** is a two-stage decision:
|
|
|
|
1. The name has to suggest power — it contains `PWR`, `POWER`,
|
|
`VCC`, `VDD`, `VEE`, `VSS`, `VBAT`, or starts with `VS_`, `VS3_`,
|
|
`+5V`-style or `-12V`-style prefixes.
|
|
2. The wiring has to corroborate it. essim requires at least one of:
|
|
- the signal lands on **4 or more pins** (a real rail goes to
|
|
decouplers + ICs + connectors, so it almost always has many
|
|
pads), or
|
|
- the name contains a **voltage value** — `3V3`, `5V`, `12V`,
|
|
`0V9`, `5V0`, etc. (any `V` next to a digit).
|
|
|
|
*Hard floor*: a signal touching **fewer than 3 pins** is
|
|
**never** Power, even if both 1 and the voltage motif are
|
|
present. Physically you cannot have a rail on 1 or 2 pads.
|
|
|
|
**Other** in every other case.
|
|
|
|
This rule deliberately rejects things that look like power but
|
|
aren't: `PWR_OK` (status), `VSEL_0` (voltage select), `VDD_SENSE`
|
|
(sense feedback) — they all match step 1 but fail steps 2/3. The
|
|
analyze screen lists them under **Suspect Power** with the reason
|
|
attached (`fan-out 1, no voltage` etc.). Inspect, then either accept
|
|
the suspect status or force it back with `set-signal-type`.
|
|
|
|
## NC (no-connect) pins
|
|
|
|
A pin is shown as `(NC)` in the explore detail when it has no signal
|
|
attached. essim distinguishes three reasons:
|
|
|
|
- **Imported NC** — the netlist explicitly says the pin is
|
|
unconnected (Mentor format: signal name `unconnected` or
|
|
`unconnected (by TERM)`; Altium format: the pin is simply omitted
|
|
from every signal block).
|
|
- **Dropped singleton** — after import, essim removes every signal
|
|
that touches exactly one pin. A net with a single endpoint cannot
|
|
carry signal anywhere, so the pin is detached and tagged. This
|
|
catches both intentional sentinels and the per-IC `NC_*` labels
|
|
that customers often put on dead pads.
|
|
- **Filled at connect** — when you `connect` two parts that don't
|
|
agree on which pins exist (a Mentor part may have all pads, an
|
|
Altium part only the wired ones), essim materialises the missing
|
|
pads on the smaller side. They are unconnected *locally* on that
|
|
module but are bridged to a real signal on the other module via
|
|
the connection — so they do not count as orphans.
|
|
|
|
The dashboard's "NC" row summarises orphan counts (imported and
|
|
dropped only; filled-at-connect pins are excluded). The analyze
|
|
screen's "Types" tab adds a trailing line with the totals.
|
|
|
|
## Signal groups
|
|
|
|
essim groups signals that share an obvious structural pattern. They
|
|
are detected per module — a multi-card bus on the system is the BFS
|
|
union of the per-module groups it touches.
|
|
|
|
**Diff pair** — two signals named `STEM_P` and `STEM_N`
|
|
(case-insensitive, `_` required before the polarity letter). Both
|
|
halves must be present. Lone `_P` halves are flagged as orphans;
|
|
lone `_N` halves are *not* flagged (the `_N` suffix is overloaded
|
|
with active-low semantics — `RESET_N`, `BOOTMODE_N` — and flagging
|
|
them would flood the report).
|
|
|
|
**Diff bus** — at least two diff pairs whose stems share a common
|
|
prefix and only differ by a trailing index: `MDI0_P`/`MDI0_N`,
|
|
`MDI1_P`/`MDI1_N`, … → `MDI[0..3]_P/N`. Both `STEMN` and `STEM_N`
|
|
forms work (`MDI0`, `PCIE_TX_0`).
|
|
|
|
**Bus** — at least two signals with a common stem and a trailing
|
|
integer index. Two notations: `DATA[0]`, `DATA[1]`, … (bracketed)
|
|
or `ADDR_0`, `ADDR_1`, … (underscore — *strict*: an underscore is
|
|
required between the stem and the digits, so a name like
|
|
`GETH_01_VDD12` is *not* a bus).
|
|
|
|
**Anomalies** are emitted alongside groups:
|
|
|
|
- *Diff pair orphan*: a `_P` with no matching `_N`.
|
|
- *Diff bus gap*: e.g. `MDI[0..3]` has `MDI0`, `MDI1`, `MDI3` (`MDI2`
|
|
missing).
|
|
- *Bus gap*: same idea on plain buses.
|
|
|
|
Internal Mentor net names that start with `$` (like `$N12345`) are
|
|
skipped from every group/bus detection.
|
|
|
|
## Issues reported by `analyze`
|
|
|
|
The Issues tab of the analyze screen aggregates everything that
|
|
deserves attention:
|
|
|
|
| Tag | What it means |
|
|
|---|---|
|
|
| `[pin-role]` | A connector pin is typed (via `set-connector-type`) as Power or Gnd but the actual signal landing on it disagrees. |
|
|
| `[net-mix]` | A net bridged across modules carries both Power and Gnd signals — almost always a topology mistake. |
|
|
| `[diff-pair-orphan]` | `STEM_P` with no `STEM_N` in the same module. |
|
|
| `[bus-gap]` | A bus is missing one or more index values inside its range. |
|
|
| `[diff-bus-gap]` | A diff bus is missing one or more lane indices. |
|
|
|
|
Zero issues = the module passes every structural check essim knows
|
|
how to run today.
|
|
|
|
## Overrides
|
|
|
|
Every classification is advisory. To force a different type:
|
|
|
|
- **Signal type**: from the `explore` screen, press Enter on a
|
|
signal entry → a popup lets you pick `power` / `gnd` / `other`.
|
|
The same popup also opens when you press Enter on a pin row in
|
|
the parts detail (changes the pin's signal type) or on a net
|
|
member row in the signal detail (works across modules). Or type
|
|
`set-signal-type <module> <signal> <type>` in the console (or
|
|
from the palette).
|
|
- **Connector type**: from `explore` with `type = parts`, press
|
|
Enter on a part to jump to the dedicated `set-connector-type`
|
|
screen with that part pre-selected and the cursor on the type
|
|
input. The `set-connector-type` command also keeps working from
|
|
the console / palette.
|
|
- **Connector type**: `set-connector-type <module> <part> <connector-kind>`
|
|
(also via the dashboard `[t]` shortcut). This drives the pin role
|
|
expectations, which feed the `pin-role` check.
|
|
|
|
Overrides survive `save`/`restore` but are recomputed at every
|
|
`load` (i.e. the inference re-runs).
|