docs: rewrite DESIGN + README for the core/frontends structure
DESIGN.md: new layered Build section (essim_core + ESSIM_FRONTEND, FTXUI per
frontend, split tests), a rewritten Layout tree (src/core/{domain,imports,app},
src/frontends/tui, tests/{,tui}), and a new "Architecture — core vs frontends"
section stating the rule (core never depends on a frontend) with the export
operation as the worked example. README: layered-build note, FTXUI-is-the-tui-
frontend's dependency, core-vs-frontend test split, nested project-layout tree.
Also keep the binary at ./build/essim via RUNTIME_OUTPUT_DIRECTORY now that the
exe is produced from the frontend subdir.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
171
DESIGN.md
171
DESIGN.md
@@ -10,72 +10,99 @@ cmake --build build -j
|
||||
./build/essim
|
||||
```
|
||||
|
||||
- CMake **3.14+** required (uses `FetchContent_MakeAvailable`).
|
||||
- FTXUI is fetched at configure time from GitHub (`v6.1.9`, shallow clone). First configure pays ~20 s for the clone; subsequent ones are cached in `build/_deps/`.
|
||||
- **System dependencies** (resolved via `find_package`): `libzip` (target `libzip::zip`) and `pugixml` (target `pugixml::pugixml`). Used by the ODS importer. Arch: `pacman -S libzip pugixml`; Debian/Ubuntu: `libzip-dev libpugixml-dev`.
|
||||
- **`libbsdl`** (standalone BSDL parser, LGPL-2.1) is the sibling repo at `../libbsdl`, pulled in via `add_subdirectory` (path overridable with `-DBSDL_DIR=...`) and linked dynamically (`bsdl::bsdl`; an LGPL `.so` is fine from EUPL essim). Powers the BSDL ingest behind `attach-bsdl`.
|
||||
- Sources are collected with `file(GLOB_RECURSE ALL_SOURCES "src/*.cpp")`. **After adding a new `.cpp`, re-run `cmake -S . -B build`** — CMake does not re-glob automatically and link will fail with "undefined reference".
|
||||
- CMake **3.14+** (uses `FetchContent_MakeAvailable`).
|
||||
- **Layered build** (see *Architecture* below). `essim_core` is the
|
||||
frontend-agnostic business library; a frontend under `src/frontends/<name>/`
|
||||
links it and produces the `essim` binary. Choose it with
|
||||
`-DESSIM_FRONTEND=<name>` (default `tui`). **`-DESSIM_FRONTEND=none` builds the
|
||||
core + tests only — no GUI toolkit is fetched.**
|
||||
- **Core system dependencies** (via `find_package`): `libzip` (`libzip::zip`)
|
||||
and `pugixml` (`pugixml::pugixml`) for the ODS importer. Arch:
|
||||
`pacman -S libzip pugixml`; Debian/Ubuntu: `libzip-dev libpugixml-dev`.
|
||||
- **`libbsdl`** (standalone BSDL parser, LGPL-2.1) — sibling repo at
|
||||
`../libbsdl`, `add_subdirectory` (override `-DBSDL_DIR=...`), linked
|
||||
dynamically **into the core** (`bsdl::bsdl`).
|
||||
- **FTXUI** is fetched by the **tui frontend only**
|
||||
(`src/frontends/tui/CMakeLists.txt`), never by the core.
|
||||
- Sources are globbed per layer: `src/core/*.cpp` → `essim_core`,
|
||||
`src/frontends/<fe>/*.cpp` → that frontend's lib + the `essim` binary.
|
||||
**After adding a `.cpp`, re-run `cmake -S . -B build`** — CMake doesn't re-glob.
|
||||
- **Tests** are split: `essim_tests` links `essim_core` (no FTXUI) from
|
||||
`tests/*.cpp`; per-frontend tests like `essim_tui_tests` link `essim_tui` from
|
||||
`tests/<frontend>/*.cpp`.
|
||||
- **Headless / batch**: `essim --batch --source FILE` runs a script and prints its console output to stdout, then exits without the TUI (good for CI / capturing `verify`). Also `--restore FILE` and `--commands-md [FILE]`. `BootDispatch` runs `--restore`/`--source` synchronously before the event loop (`Source` takes its headless drain branch when no screen is attached), so the console buffer is complete by the time `--batch` dumps it (`Tui::DumpOutput`).
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
src/
|
||||
main.cpp -- launches Tui
|
||||
system/ -- domain model
|
||||
syselmts.hpp SystemElement + SystemElementContainer<T> (templated, get/merge/iterate)
|
||||
modules.{hpp,cpp} Module, Modules
|
||||
parts.{hpp,cpp} Part (carries `kind` + `connector_type`), Parts
|
||||
pins.{hpp,cpp} Pin (carries PinSpec `spec`), Pins
|
||||
signals.{hpp,cpp} Signal, Signals
|
||||
signal_type.hpp SignalType + helpers
|
||||
pin_spec.hpp PinSpec (function/direction/pad/source) + SignalType mapping
|
||||
component_kind.{hpp,cpp} ComponentKind enum + infer_component_kind(name)
|
||||
pin_name.{hpp,cpp} canonical_pin_name(s) — zero-pad digit suffix to 3
|
||||
connect.{hpp,cpp} Connection, Connections
|
||||
transform.{hpp,cpp} Transform / IdentityTransform / TransformRegistry +
|
||||
CheckIdentityCompatible + FillIdentityNCs
|
||||
pin_role.{hpp,cpp} pin_role(kind, name) → PinSpec, pin_layout(kind),
|
||||
FillPartFromLayout(part, kind)
|
||||
pin_model.{hpp,cpp} PinModel + apply_model(Part*, model) + ConnectorModel
|
||||
bsdl_model.{hpp,cpp} BsdlModel (libbsdl wrapper) + BsdlPinModel + apply_bsdl
|
||||
bsdl_check.{hpp,cpp} check_pin_specs / check_jtag_chain → vector<Anomaly>
|
||||
nets.{hpp,cpp} find_net / compute_all_nets / net_type_consistent
|
||||
analysis.{hpp,cpp} analyze_system → AnalysisReport (diff pairs, buses, anomalies)
|
||||
persist.{hpp,cpp} save / restore (tab-delimited)
|
||||
system.{hpp,cpp} System: owns Modules + Connections, exposes Load()
|
||||
imports/ -- adapters that populate or emit the domain
|
||||
import_base.hpp ImportBase interface
|
||||
import_mentor.{hpp,cpp} Mentor Graphics netlist parser
|
||||
import_altium.{hpp,cpp} Altium netlist parser (`[ ]` parts, `( )` signals)
|
||||
import_ods.{hpp,cpp} ODS spreadsheet pinout (libzip + pugixml)
|
||||
ods_writer.{hpp,cpp} Minimal .ods writer (multi-sheet, string cells)
|
||||
tui/ -- FTXUI shell, split by responsibility
|
||||
tui.{hpp,cpp} Class Tui (state + Run() orchestrator + screen-mode event dispatcher)
|
||||
tui_helpers.{hpp,cpp} Free helpers: ToLower, NaturalLess, LongestCommonPrefix
|
||||
shell.cpp Print, Submit, Dispatch, Finalize, Tokenize, history persistence
|
||||
completion.cpp CompleteCommand, CompletePath, CompleteInline
|
||||
commands.cpp RegisterCommands (orchestrator + lifecycle / shell / topology commands)
|
||||
commands_export.cpp RegisterExportCommands (export → CSV / ODS, file-dialog hook)
|
||||
screen_main.cpp BuildMainScreen (visualisation area + bottom input)
|
||||
screen_connect.cpp BuildConnectScreen + shared RefreshFilteredPartList helper
|
||||
screen_settype.cpp BuildSettypeScreen
|
||||
screen_explore.cpp BuildExploreScreen (browse modules → parts/signals/connections → details; not scriptable)
|
||||
screen_dashboard.cpp BuildDashboardScreen (read-only system overview)
|
||||
screen_analyze.cpp BuildAnalyzeScreen (anomalies / groups / power decisions)
|
||||
screen_palette.cpp BuildPaletteModal (global Ctrl-P fuzzy launcher)
|
||||
screen_filedialog.cpp BuildFileDialog + OpenFileDialog (reusable file picker)
|
||||
screen_error.cpp BuildErrorModal + ShowError (centred error popup)
|
||||
screen_help.cpp BuildHelpScreen (topic-driven feature reference)
|
||||
screen_sigtype_modal.cpp BuildSignalTypeModal (popup attached to explore via Modal())
|
||||
doc/classes.puml -- PlantUML class diagram
|
||||
core/ -- business logic; NO GUI toolkit (builds libessim_core)
|
||||
domain/ -- the model + read-only analyses
|
||||
syselmts.hpp SystemElement + SystemElementContainer<T> (get/merge/iterate)
|
||||
modules.{hpp,cpp} Module, Modules
|
||||
parts.{hpp,cpp} Part (kind, connector_type, bsdl_path; PinSpec per pin)
|
||||
pins.{hpp,cpp} Pin (carries PinSpec `spec`), Pins
|
||||
signals.{hpp,cpp} Signal, Signals
|
||||
signal_type.hpp SignalType + helpers
|
||||
pin_spec.hpp PinSpec (function/direction/pad/source), mappings, spec_source_rank
|
||||
component_kind.{hpp,cpp} ComponentKind + infer_component_kind(name)
|
||||
pin_name.{hpp,cpp} canonical_pin_name (zero-pad digit suffix to 3)
|
||||
connect.{hpp,cpp} Connection, Connections
|
||||
transform*.{hpp,cpp} Transform / IdentityTransform / TransformRegistry, VPX transform
|
||||
pin_role.{hpp,cpp} pin_role(kind,name) -> PinSpec, pin_layout, FillPartFromLayout
|
||||
pin_model.{hpp,cpp} PinModel + apply_model(Part*, model) + ConnectorModel
|
||||
bsdl_model.{hpp,cpp} BsdlModel (libbsdl wrapper) + BsdlPinModel + apply_bsdl
|
||||
bsdl_check.{hpp,cpp} check_pin_specs / _jtag_chain / _source_conflicts / _bsdl_completeness
|
||||
nets.{hpp,cpp} find_net / compute_all_nets / net_type_consistent
|
||||
analysis.{hpp,cpp} analyze_system -> AnalysisReport (diff pairs, buses, anomalies)
|
||||
persist.{hpp,cpp} save / restore (tab-delimited; `B` tag = bsdl_path)
|
||||
system.{hpp,cpp} System: owns Modules + Connections, Load()
|
||||
imports/ -- netlist / pinout adapters
|
||||
import_base.hpp / import_{mentor,altium,ods}.{hpp,cpp} / ods_writer.{hpp,cpp}
|
||||
app/ -- application operations (UI-independent use cases)
|
||||
export.{hpp,cpp} export_connections(System*, path, format) -> ExportResult
|
||||
frontends/ -- one directory per GUI/TUI engine; each links essim_core
|
||||
tui/ -- FTXUI shell (builds libessim_tui + the `essim` binary)
|
||||
CMakeLists.txt fetches FTXUI; builds essim_tui + essim
|
||||
main.cpp entry point (CLI flags -> Tui)
|
||||
tui.{hpp,cpp} class Tui (state + Run() + screen-mode event dispatch)
|
||||
tui_helpers.{hpp,cpp} ToLower, NaturalLess, RenderHelpPanel
|
||||
shell.cpp Print, Submit, Dispatch, Source / ProcessNextSourceLine
|
||||
completion.cpp CompleteCommand / CompletePath / CompleteInline
|
||||
commands.cpp RegisterCommands (thin: resolve args -> call core -> render)
|
||||
commands_export.cpp thin wrapper over app::export_connections
|
||||
screen_*.cpp dashboard, connect, settype, explore, analyze, help, main
|
||||
(console), palette, file dialog, error/confirm, sigtype modal
|
||||
tests/ -- core tests (link essim_core)
|
||||
tui/ -- frontend tests (link essim_tui)
|
||||
doc/ , test/ -- docs; sample netlists + system.essim bring-up script
|
||||
```
|
||||
|
||||
`include/` and `lib/` are kept empty by design — FTXUI used to live there as precompiled `.a` + headers, now it comes through FetchContent.
|
||||
## Architecture — core vs frontends
|
||||
|
||||
The hard rule: **`src/core/` never depends on a frontend** — no `#include
|
||||
"frontends/…"`, no GUI toolkit. Frontends depend on the core, never the reverse
|
||||
(`essim_core` links libzip / pugixml / bsdl only).
|
||||
|
||||
- **Domain** (`core/domain/`) — the model and the read-only analyses
|
||||
(`analyze_system`, the `check_*` passes, `compute_all_nets`).
|
||||
- **Application** (`core/app/`) — use-case operations a frontend invokes, e.g.
|
||||
`export_connections(System*, path, format) -> ExportResult`. An operation
|
||||
builds its artefact and returns data/stats; it **never** prints or opens a
|
||||
dialog. (Anti-pattern being removed: the export command used to build the file
|
||||
inside its lambda. The TUI command is now a thin wrapper — resolve args/dialog
|
||||
→ call the core op → render the result.)
|
||||
- **Frontends** (`frontends/<name>/`) — thin: map UI events to core calls and
|
||||
render results. Add one by creating `src/frontends/<name>/CMakeLists.txt` (build
|
||||
`essim_<name>` linking `essim_core`, produce the `essim` binary) and configuring
|
||||
`-DESSIM_FRONTEND=<name>`.
|
||||
|
||||
Because the core links no toolkit, the suite links `essim_core` directly and
|
||||
`-DESSIM_FRONTEND=none` builds + tests the whole core with FTXUI never fetched.
|
||||
|
||||
## Domain conventions
|
||||
|
||||
- Everything in `system/` is **pointer-based** (commit `d8122d1`: "everything is pointer"). Containers store `T*`, ownership lives with the container.
|
||||
- Everything in `core/domain/` is **pointer-based** (commit `d8122d1`: "everything is pointer"). Containers store `T*`, ownership lives with the container.
|
||||
- `SystemElementContainer<T>::merge(name)` is the get-or-create primitive — call it instead of `add` when you don't know whether the element already exists. `add` throws on duplicate names or empty names.
|
||||
- `using namespace std;` is present in `syselmts.hpp` — pre-existing, don't add more `using namespace` in headers.
|
||||
- Include guards `_NAME_HPP_` *and* `#pragma once` are both used. Match the existing style.
|
||||
@@ -110,11 +137,11 @@ Built-in commands: `new`, `set`, `load`, `duplicate`, `save`, `restore`, `source
|
||||
|
||||
Pending prompts (from incomplete inline commands) are NOT considered interactive and are filled by subsequent script lines, the way you'd expect. Lines starting with `#` and blank lines are skipped; leading/trailing whitespace is trimmed; `~/` is expanded.
|
||||
|
||||
`save` / `restore` (`src/system/persist.{hpp,cpp}`): tab-delimited line format, no extra deps. Tags: `M` (module), `P` (part with `connector_type`), `B` (part's attached BSDL `.bsd` path — re-parsed and re-applied on restore; the path is persisted, **not** the derived pin specs), `N` (pin → signal name; empty = NC; optional 4th field carries `nc_origin_tag()`: `U` = ImportedUnconnected, `D` = DroppedSingleton — omitted when the pin has a signal or when origin is `None`), `S` (signal → type override; only emitted for non-default), `C` (connection header with endpoints + `transform_name`), `W` (wire pair within the current connection). The 4th N field is backward-compatible: pre-existing snapshots without it restore with `nc_origin = None`.
|
||||
`save` / `restore` (`src/core/domain/persist.{hpp,cpp}`): tab-delimited line format, no extra deps. Tags: `M` (module), `P` (part with `connector_type`), `B` (part's attached BSDL `.bsd` path — re-parsed and re-applied on restore; the path is persisted, **not** the derived pin specs), `N` (pin → signal name; empty = NC; optional 4th field carries `nc_origin_tag()`: `U` = ImportedUnconnected, `D` = DroppedSingleton — omitted when the pin has a signal or when origin is `None`), `S` (signal → type override; only emitted for non-default), `C` (connection header with endpoints + `transform_name`), `W` (wire pair within the current connection). The 4th N field is backward-compatible: pre-existing snapshots without it restore with `nc_origin = None`.
|
||||
|
||||
**Signals** carry a `type` (`SignalType::Power | GndShield | Other`). The `Signal` constructor **defaults to `Other`** — auto-inference no longer happens at construction. Types are set in three ways, in priority order:
|
||||
|
||||
1. **`infer_signal_types(System*)`** (`src/system/analysis.{hpp,cpp}`) runs at the end of every `load` (after `drop_singleton_signals`). It assigns:
|
||||
1. **`infer_signal_types(System*)`** (`src/core/domain/analysis.{hpp,cpp}`) runs at the end of every `load` (after `drop_singleton_signals`). It assigns:
|
||||
- `GndShield` when the **name alone** is unambiguous (`GND`, `SHIELD`, `CHASSIS`, `EARTH`, …) — false-positive rate is essentially zero on these.
|
||||
- `Power` requires (a) the name heuristic (`infer_signal_type` says Power), (b) a **hard fan-out floor**: signals with fewer than `POWER_FANOUT_HARD_FLOOR = 3` pins are *always* refused, regardless of name or voltage pattern (a real rail physically cannot land on just 1-2 pads), and (c) at least one positive structural signal — fan-out ≥ `POWER_FANOUT_CONFIRM_MIN = 4` **or** a voltage pattern in the name (`3V3`, `5V`, `12V`, …; detector: a `V` adjacent to a digit). This catches `VSEL_*`, `PWR_OK`, `_VDD_SENSE` etc. which look like Power by name but aren't real rails. Both thresholds are exposed in `analysis.hpp` so the analyze screen can render the same reasoning without duplicating constants.
|
||||
- `Other` otherwise. The "name-said-Power-but-refuted-by-structure" count is reported by `load`.
|
||||
@@ -123,17 +150,17 @@ Pending prompts (from incomplete inline commands) are NOT considered interactive
|
||||
|
||||
The explore screen shows the type in the signal detail header.
|
||||
|
||||
**Pin spec (expected attributes)**: every Pin carries a `PinSpec spec` (`src/system/pin_spec.hpp`) — the *expected* half of verification, set from a model: `function` (Power/Ground/Signal/Clock/NoConnect/Jtag*), `direction` (In/Out/Bidir/Passive/Power), `pad` (physical package terminal, e.g. a BSDL ball), and `source` (which model wrote it). `set-connector-type` populates it via `pin_role(connector_type, pin_name) → PinSpec`. `Pin::expected_signal_type()` is now a **derived accessor** — `to_signal_type(spec.function)` (Power→Power, Ground→GndShield, else Other) — not a stored field; the *observed* half stays `Pin::signal()` + the net + inference, and `verify` diffs the two. The VPX 3U connector lookup (`vpx_3u_role`) is still a stub returning Other, so connector-typed pins resolve to function Unknown until that table is filled. **`direction`/`function`/`pad` are populated from BSDL** via `attach-bsdl` (see below) and consumed by the model-driven checks (`check_pin_specs`: contention / undriven / NC-wired) and the JTAG chain check (`check_jtag_chain`), both run by `verify`.
|
||||
**Pin spec (expected attributes)**: every Pin carries a `PinSpec spec` (`src/core/domain/pin_spec.hpp`) — the *expected* half of verification, set from a model: `function` (Power/Ground/Signal/Clock/NoConnect/Jtag*), `direction` (In/Out/Bidir/Passive/Power), `pad` (physical package terminal, e.g. a BSDL ball), and `source` (which model wrote it). `set-connector-type` populates it via `pin_role(connector_type, pin_name) → PinSpec`. `Pin::expected_signal_type()` is now a **derived accessor** — `to_signal_type(spec.function)` (Power→Power, Ground→GndShield, else Other) — not a stored field; the *observed* half stays `Pin::signal()` + the net + inference, and `verify` diffs the two. The VPX 3U connector lookup (`vpx_3u_role`) is still a stub returning Other, so connector-typed pins resolve to function Unknown until that table is filled. **`direction`/`function`/`pad` are populated from BSDL** via `attach-bsdl` (see below) and consumed by the model-driven checks (`check_pin_specs`: contention / undriven / NC-wired) and the JTAG chain check (`check_jtag_chain`), both run by `verify`.
|
||||
|
||||
**Connector pin layout (preparation)**: `pin_layout(connector_type)` returns the canonical full pin-name list for a known connector kind, and `FillPartFromLayout(part, kind)` materialises NC pins for any layout position absent from the imported netlist. `set-connector-type` calls it after setting `connector_type` (no-op today since `pin_layout` is a stub returning `{}` for everything — populate alongside `vpx_3u_role`). End-to-end chain in place: `set-connector-type → FillPartFromLayout → pin_role`.
|
||||
|
||||
**BSDL models (`attach-bsdl`)**: `attach-bsdl <module> <part> <file.bsd>` parses a BSDL device through `libbsdl` (wrapped by `BsdlModel`, `src/system/bsdl_model.{hpp,cpp}`), then `apply_bsdl(part, model)` binds each port to a Pin **by port name first, then by physical pad** — so a netlist that names IC pins either by signal or by package ball both bind. Each bound pin gets its `spec` set: `direction` (BSDL in/out/inout/linkage), `function` (TAP role → Jtag\*, `linkage` → Power/Ground/NoConnect by name, else Signal), `pad` (PIN_MAP ball), `source = Bsdl`. The `.bsd` path is stored on `Part::bsdl_path`, persisted via the `B` tag and re-applied on `restore`. Real-world check: an `xcku15p` FPGA in a VPX system binds 1517/1517 ports.
|
||||
**BSDL models (`attach-bsdl`)**: `attach-bsdl <module> <part> <file.bsd>` parses a BSDL device through `libbsdl` (wrapped by `BsdlModel`, `src/core/domain/bsdl_model.{hpp,cpp}`), then `apply_bsdl(part, model)` binds each port to a Pin **by port name first, then by physical pad** — so a netlist that names IC pins either by signal or by package ball both bind. Each bound pin gets its `spec` set: `direction` (BSDL in/out/inout/linkage), `function` (TAP role → Jtag\*, `linkage` → Power/Ground/NoConnect by name, else Signal), `pad` (PIN_MAP ball), `source = Bsdl`. The `.bsd` path is stored on `Part::bsdl_path`, persisted via the `B` tag and re-applied on `restore`. Real-world check: an `xcku15p` FPGA in a VPX system binds 1517/1517 ports.
|
||||
|
||||
**Unified application (`apply_model`)**: connector layout and BSDL are two implementations of one `PinModel` interface (`src/system/pin_model.{hpp,cpp}`: `spec_for(pin_name)`, `layout()`, `source()`). `ConnectorModel` wraps `pin_role`/`pin_layout`; `BsdlPinModel` wraps a parsed `BsdlModel`, indexed by both port name and physical pad. A single `apply_model(Part*, const PinModel&)` materialises the layout pins missing from the netlist, then sets each pin's `spec` **only where the model speaks** (`spec.source != None`). Sources are ranked (`spec_source_rank` in `pin_spec.hpp`: UserOverride > Bsdl > ConnectorModel > Inferred > Imported) and apply_model refuses to overwrite a spec owned by a higher-rank source — so one source never clobbers a more authoritative one, which is also the basis for `check_source_conflicts`. `set-connector-type` and `attach-bsdl` both funnel through it (the latter via the thin `apply_bsdl` adapter); `verify` stays agnostic of where a spec came from. A future SPICE/Modelica source would be a third `PinModel`.
|
||||
**Unified application (`apply_model`)**: connector layout and BSDL are two implementations of one `PinModel` interface (`src/core/domain/pin_model.{hpp,cpp}`: `spec_for(pin_name)`, `layout()`, `source()`). `ConnectorModel` wraps `pin_role`/`pin_layout`; `BsdlPinModel` wraps a parsed `BsdlModel`, indexed by both port name and physical pad. A single `apply_model(Part*, const PinModel&)` materialises the layout pins missing from the netlist, then sets each pin's `spec` **only where the model speaks** (`spec.source != None`). Sources are ranked (`spec_source_rank` in `pin_spec.hpp`: UserOverride > Bsdl > ConnectorModel > Inferred > Imported) and apply_model refuses to overwrite a spec owned by a higher-rank source — so one source never clobbers a more authoritative one, which is also the basis for `check_source_conflicts`. `set-connector-type` and `attach-bsdl` both funnel through it (the latter via the thin `apply_bsdl` adapter); `verify` stays agnostic of where a spec came from. A future SPICE/Modelica source would be a third `PinModel`.
|
||||
|
||||
**`verify` (seven passes)**: (1) typed pins — local mismatch between each pin's `expected_signal_type()` (derived from its `PinSpec`) and the actual signal type; (2) bridged nets — Power↔GndShield inconsistencies; (3) orphan summary `N orphan pin(s) at import (X imported NC, Y dropped singleton)` (filters out pins bridged via any `Connection::pin_map` — typically `FillIdentityNCs`-materialised); (4) **model-driven pin checks** (`check_pin_specs`): `DriveContention` (≥2 push-pull `Out` on a net), `UndrivenNet` (a **fully-modelled** net with input(s) but no driver — nets with any Unknown-direction pin are skipped, so un-modelled drivers don't cause false positives), `NcWired` (a no-connect pin on a multi-pin net); (5) **JTAG chain** (`check_jtag_chain`): collects TAP pins by `spec.function`, maps each to its net, emits `JtagTapIncomplete` / `JtagBusUnbridged` (TMS or TCK not common to all TAP devices) / `JtagChainBreak` (dangling TDO/TDI, chain fan-out, or not a single head→tail daisy chain); (6) **source conflicts** (`check_source_conflicts`): a pin the BSDL declares power/ground (a must-connect rail) that the netlist leaves unconnected — a rail floated in the schematic (`SourceConflict`; the reverse, a BSDL no-connect that *is* wired, is the `NcWired` check); (7) **BSDL completeness** (`check_bsdl_completeness`): device power/ground ports (from the attached `.bsd`, re-parsed) with no matching pin on the netlist part — a rail the schematic symbol is missing (`BsdlPinMissing`, one aggregated finding per part). The BFS-reached `(module, signal)` set for any signal is shown live in `explore`'s detail pane when a signal entry is selected.
|
||||
|
||||
**`analyze` (post-processing pass)**: `analyze_system(System*) → AnalysisReport` (`src/system/analysis.{hpp,cpp}`) is a stateless read-only pass that detects structural signal groups and anomalies. Per-module (signals are module-scoped):
|
||||
**`analyze` (post-processing pass)**: `analyze_system(System*) → AnalysisReport` (`src/core/domain/analysis.{hpp,cpp}`) is a stateless read-only pass that detects structural signal groups and anomalies. Per-module (signals are module-scoped):
|
||||
|
||||
- **Diff pairs**: signal names ending `_P` / `_N` (case-insensitive) grouped by stem. Both halves present → candidate matched pair.
|
||||
- **Diff buses**: ≥ 2 matched diff pairs whose pair-stems share a common outer-stem after stripping a trailing integer (`MDI0` / `MDI1` / `MDI2` → outer `MDI` + indices). The strict `_` rule from plain buses does NOT apply to this trailing-index split: `_P`/`_N` was already stripped, so we know remaining digits are an index. Two index variants accepted: contiguous (`MDI0`) and underscore-separated (`PCIE_TX_0`). Emitted as `SignalGroup{kind=DiffBus, lo, hi}` with label `OUTER[lo..hi]_P/N`. Members include all 2·N constituent signals. A "bus" of size 1 falls back to `DiffPair` (single index does not a bus make).
|
||||
@@ -145,13 +172,13 @@ Exposed as the `analyze` shell command which prints groups (sorted by module + l
|
||||
|
||||
**Component classification**: every `Part` carries a `ComponentKind kind` (`Passive | Semiconductor | IntegratedCircuit | Connector | TestPoint | Switch | Crystal | Mechanical | Other`) inferred at construction by `infer_component_kind(name)` from the leading reference-designator letter(s) (longest-match: `LED/TP/SW/FB/MK/MP/MH/HS/RA/RN/RP/RV` first, then single-letter R/C/L/F/D/Q/U/J/P/Y/X/S). Recomputed on `restore` (no persistence tag). Not yet exposed in TUI commands — branchpoints will be `set-connector-type` guard, `explore` filter, and `explore` header.
|
||||
|
||||
`SignalType` lives in its own header `src/system/signal_type.hpp` (extracted from signals to avoid a pins↔signals include cycle).
|
||||
`SignalType` lives in its own header `src/core/domain/signal_type.hpp` (extracted from signals to avoid a pins↔signals include cycle).
|
||||
|
||||
**Pins** are either NC (`signal() == nullptr`) or connected to exactly one signal. The ODS importer creates a Pin for every row that has a non-empty pin name, even when the signal column is empty or `"NC"` — the pin stays in the Part as NC. `restore` replaces `Tui::sys` entirely (`unique_ptr::reset`). Names are stored as-is — must not contain TAB or newline (true for the EE netlists we ingest). Format is versioned by the `# essim system snapshot v1` header for future compatibility.
|
||||
|
||||
**NC origin tag**: each `Pin` carries `NcOrigin nc_origin` (`None | ImportedUnconnected | DroppedSingleton`, default `None`). Set in three places: (a) Mentor importer when the signal field starts with `unconnected` → `ImportedUnconnected`; (b) `drop_singleton_signals(Signals*)` called at the end of `load` → `DroppedSingleton` on each detached pin (signals with exactly one pin are NC by definition — see commits motivating this); (c) `duplicate` propagates the tag. Pins materialised by `FillIdentityNCs` keep `None` — they have no local signal but are bridged via `pin_map` and shouldn't be counted as orphans. The tag is persisted (see `N` record), reported as a total in `verify`, and tested in `tests/test_nc_origin.cpp`.
|
||||
|
||||
**Connector types & transforms**: every `Part` carries a `connector_type` string (default `""`, set via the `set-connector-type` command — inline `set-connector-type m p kind` or bare which opens a TUI screen with module menu, part filter+menu, type input, list of types already in use, and an Apply button). When `connect` validates a pair, it consults `TransformRegistry::lookup(p1->connector_type, p2->connector_type)` (defined in `src/system/transform.{hpp,cpp}`) — both directions of the pair are tried. If neither is registered, an `IdentityTransform` fallback wires each pin of A to the canonical-equivalent pin of B (when present). The resulting `(Pin*, Pin*)` list and the transform's name are stored on the `Connection` (`pin_map`, `transform_name`). To register a real transform: define a `Transform` subclass in `transform.cpp` and call `TransformRegistry::get().add("kindA", "kindB", new MyTransform())` at init — there's no startup hook for this yet, so a small `RegisterBuiltinTransforms()` helper is the natural place to add when more types appear.
|
||||
**Connector types & transforms**: every `Part` carries a `connector_type` string (default `""`, set via the `set-connector-type` command — inline `set-connector-type m p kind` or bare which opens a TUI screen with module menu, part filter+menu, type input, list of types already in use, and an Apply button). When `connect` validates a pair, it consults `TransformRegistry::lookup(p1->connector_type, p2->connector_type)` (defined in `src/core/domain/transform.{hpp,cpp}`) — both directions of the pair are tried. If neither is registered, an `IdentityTransform` fallback wires each pin of A to the canonical-equivalent pin of B (when present). The resulting `(Pin*, Pin*)` list and the transform's name are stored on the `Connection` (`pin_map`, `transform_name`). To register a real transform: define a `Transform` subclass in `transform.cpp` and call `TransformRegistry::get().add("kindA", "kindB", new MyTransform())` at init — there's no startup hook for this yet, so a small `RegisterBuiltinTransforms()` helper is the natural place to add when more types appear.
|
||||
|
||||
**Identity wiring uses canonical names**: `IdentityTransform::apply` builds `unordered_map<canonical, Pin*>` for side B and looks up each side-A pin by its canonical form. So `A1` (one card) auto-pairs with `A001` (the other) thanks to `canonical_pin_name` (`pre + zero-padded(3) digit suffix`; mixed/non-numeric returns the original). Same canonicalisation in `CheckIdentityCompatible`. **`pin_role` doesn't need canonicalisation** because `parse_pin` extracts `(col, row)` via `stoi` which already strips leading zeros.
|
||||
|
||||
@@ -188,7 +215,7 @@ Today the only caller is `export` (`{"CSV", ".csv"}, {"ODS", ".ods"}` filters, k
|
||||
|
||||
**Per-key path persistence** (`SaveLastUsed(key, dir, filename)` / `LoadLastUsed(key, &dir, &filename)` in `shell.cpp`): each key writes a tiny two-line file (`dir\nfilename\n`) under `UserDataDir() / <key>.last`. `UserDataDir()` is the cross-platform `XDG_DATA_HOME` / `LOCALAPPDATA` etc. helper also used by the command history file. Free functions, not Tui members, so any module (the file dialog today; could be the script-save buffer or the save command tomorrow) can use them with the same minimal API.
|
||||
|
||||
**ODS writer** (`src/imports/ods_writer.{hpp,cpp}`): minimal OpenDocument Spreadsheet writer. Backed by libzip + pugixml (both already pulled in by the ODS importer). Class hierarchy is two structs:
|
||||
**ODS writer** (`src/core/imports/ods_writer.{hpp,cpp}`): minimal OpenDocument Spreadsheet writer. Backed by libzip + pugixml (both already pulled in by the ODS importer). Class hierarchy is two structs:
|
||||
|
||||
- `OdsSheet` — sparse row-major grid of string cells (`set(row, col, value)`).
|
||||
- `OdsWriter` — owns the sheets, emits a valid `.ods` archive with `mimetype` (stored uncompressed, magic header), `META-INF/manifest.xml`, and `content.xml`.
|
||||
@@ -248,9 +275,9 @@ Everything in this section is a precise description of how signals, pins, parts,
|
||||
|
||||
Default: `Signal::type = SignalType::Other` (constructor does no inference).
|
||||
|
||||
Type is set by `infer_signal_types(System*)` (`src/system/analysis.cpp`), called at the end of every `load` and after `duplicate`. The decision per signal:
|
||||
Type is set by `infer_signal_types(System*)` (`src/core/domain/analysis.cpp`), called at the end of every `load` and after `duplicate`. The decision per signal:
|
||||
|
||||
1. Compute `named = infer_signal_type(name)` (`src/system/signals.cpp`):
|
||||
1. Compute `named = infer_signal_type(name)` (`src/core/domain/signals.cpp`):
|
||||
- `GndShield` if name matches **case-insensitively**: `GND`, `GROUND`, `EARTH`, `SHIELD`, `CHASSIS`, or starts with `GND_` / `GROUND_` / `EARTH_` / `SHIELD_` / `CHASSIS_`.
|
||||
- `Power` if the name contains any of `PWR`, `POWER`, `VCC`, `VDD`, `VEE`, `VSS`, `VBAT`, or starts with `VS_`, `VS3_`, `+`, `-` followed by a digit.
|
||||
- Else `Other`.
|
||||
@@ -264,15 +291,15 @@ Type is set by `infer_signal_types(System*)` (`src/system/analysis.cpp`), called
|
||||
|
||||
### NC pin origin
|
||||
|
||||
`Pin::nc_origin` (`src/system/pins.hpp`). Default `NcOrigin::None`. Set by:
|
||||
`Pin::nc_origin` (`src/core/domain/pins.hpp`). Default `NcOrigin::None`. Set by:
|
||||
|
||||
- **`NcOrigin::ImportedUnconnected`** — Mentor importer (`src/imports/import_mentor.cpp`): the signal field of an `Explicit Pin:` row starts case-insensitively with `unconnected` (e.g. `'unconnected'`, `'unconnected (by TERM)'`). The pin is kept on the part with no signal.
|
||||
- **`NcOrigin::DroppedSingleton`** — `drop_singleton_signals(Signals*)` (`src/system/signals.cpp`) called at the end of `load`: any signal whose pin set has size exactly 1 is unconnected by definition. The pin is detached (`sig = nullptr`) and tagged; the `Signal` object is deleted.
|
||||
- **`NcOrigin::ImportedUnconnected`** — Mentor importer (`src/core/imports/import_mentor.cpp`): the signal field of an `Explicit Pin:` row starts case-insensitively with `unconnected` (e.g. `'unconnected'`, `'unconnected (by TERM)'`). The pin is kept on the part with no signal.
|
||||
- **`NcOrigin::DroppedSingleton`** — `drop_singleton_signals(Signals*)` (`src/core/domain/signals.cpp`) called at the end of `load`: any signal whose pin set has size exactly 1 is unconnected by definition. The pin is detached (`sig = nullptr`) and tagged; the `Signal` object is deleted.
|
||||
- **`NcOrigin::None` (no tag)** — pins materialised by `FillIdentityNCs` at `connect` time. These are unconnected locally but bridged to a real signal on the peer module via `Connection::pin_map`; they are explicitly excluded from the "orphan" count in `verify` and the analyze screen.
|
||||
|
||||
### Signal groups
|
||||
|
||||
`analyze_system(System*)` (`src/system/analysis.cpp`) emits `SignalGroup`s **per module** (signals are module-scoped). Internal names (starting with `$` — Mentor's `$Nxxxx` convention) are skipped wholesale at every step.
|
||||
`analyze_system(System*)` (`src/core/domain/analysis.cpp`) emits `SignalGroup`s **per module** (signals are module-scoped). Internal names (starting with `$` — Mentor's `$Nxxxx` convention) are skipped wholesale at every step.
|
||||
|
||||
**DiffPair** (`GroupKind::DiffPair`):
|
||||
- Signal name ends `_P` or `_N` (case-insensitive). The character before the suffix must be `_`.
|
||||
@@ -303,7 +330,7 @@ The `verify` command (not the analyze screen, yet) also emits the **model-driven
|
||||
|
||||
### Component kind
|
||||
|
||||
`Part::kind` is inferred at construction (`src/system/component_kind.cpp`) from the leading reference-designator letter(s) of the part name. **Longest-match wins**:
|
||||
`Part::kind` is inferred at construction (`src/core/domain/component_kind.cpp`) from the leading reference-designator letter(s) of the part name. **Longest-match wins**:
|
||||
|
||||
- Two-letter prefixes (checked first, case-insensitive): `LED → Semiconductor`, `TP → TestPoint`, `SW → Switch`, `FB → Passive`, `MK / MP / MH → Mechanical`, `HS → Mechanical`, `RA / RN / RP / RV → Passive`.
|
||||
- Single-letter fallback: `R / C / L / F → Passive`, `D / Q → Semiconductor`, `U → IntegratedCircuit`, `J / P → Connector`, `Y / X → Crystal`, `S → Switch`.
|
||||
@@ -315,7 +342,7 @@ Recomputed on `restore` (no persistence tag). Currently not used by any decision
|
||||
|
||||
`connect` looks up a registered transform for `(p1->connector_type, p2->connector_type)` via `TransformRegistry::lookup`, tried in both directions. Fall-through is `IdentityTransform`:
|
||||
|
||||
- Compares pin sets by **canonical name** (`canonical_pin_name(s)`, `src/system/pin_name.cpp`): split into prefix + digit suffix; if the suffix is pure digits, zero-pad to width 3 (`A1` → `A001`, `A001` → `A001`, `A1B` → `A1B`, `VCC` → `VCC`).
|
||||
- Compares pin sets by **canonical name** (`canonical_pin_name(s)`, `src/core/domain/pin_name.cpp`): split into prefix + digit suffix; if the suffix is pure digits, zero-pad to width 3 (`A1` → `A001`, `A001` → `A001`, `A1B` → `A1B`, `VCC` → `VCC`).
|
||||
- `CheckIdentityCompatible(a, b)` accepts the **subset case** (one side's canonical set is a subset of the other's — typical because Altium drops NC, Mentor doesn't). Bidirectional mismatch (both sides have orphans) is refused.
|
||||
- After acceptance, `FillIdentityNCs(p1, p2)` **materialises** the missing canonical positions on the smaller side as new NC pins (`new Pin(other_side_name)`, no signal attached, `nc_origin = None`). Idempotent.
|
||||
|
||||
|
||||
35
README.md
35
README.md
@@ -15,6 +15,13 @@ cmake --build build -j
|
||||
./build/essim
|
||||
```
|
||||
|
||||
The build is **layered**: `essim_core` is the frontend-agnostic business
|
||||
library (domain + importers + operations); the `essim` binary comes from a
|
||||
**frontend** under `src/frontends/<name>/` that links it. Select one with
|
||||
`-DESSIM_FRONTEND=<name>` (default `tui`); `-DESSIM_FRONTEND=none` builds the
|
||||
core + tests only, with no GUI toolkit fetched. Architecture in
|
||||
[`DESIGN.md`](DESIGN.md).
|
||||
|
||||
Inside the shell, type `help` for the live command list — or read the
|
||||
auto-generated reference at [`doc/user/commands.md`](doc/user/commands.md).
|
||||
A worked bring-up script is at [`test/system.essim`](test/system.essim);
|
||||
@@ -41,10 +48,14 @@ Step-by-step walkthroughs for both the batch and TUI workflows are in
|
||||
`../libbsdl`, pulled in via `add_subdirectory` and linked dynamically.
|
||||
Override its location with `-DBSDL_DIR=/path/to/libbsdl`. Powers the
|
||||
`attach-bsdl` command and the pin/JTAG checks.
|
||||
- Fetched automatically at configure time via `FetchContent` (nothing to
|
||||
install): **FTXUI** v6.1.9 and **doctest** v2.4.11.
|
||||
- Fetched automatically via `FetchContent` (nothing to install): **FTXUI**
|
||||
v6.1.9 — only when building the **tui** frontend — and **doctest** v2.4.11
|
||||
for the tests.
|
||||
- Optional, only for the `doc` target: **doxygen** and **python3**.
|
||||
|
||||
libzip, pugixml and libbsdl are the **core** dependencies; FTXUI belongs to the
|
||||
tui frontend, so a `-DESSIM_FRONTEND=none` build needs none of it.
|
||||
|
||||
## Tests
|
||||
|
||||
```sh
|
||||
@@ -53,6 +64,9 @@ Step-by-step walkthroughs for both the batch and TUI workflows are in
|
||||
ctest --test-dir build
|
||||
```
|
||||
|
||||
`ctest` runs `essim_tests` (core — links `essim_core`, no GUI toolkit) and
|
||||
`essim_tui_tests` (the FTXUI frontend's tests, under `tests/tui/`).
|
||||
|
||||
Skip building tests entirely:
|
||||
|
||||
```sh
|
||||
@@ -76,12 +90,17 @@ cmake --build build --target doc # needs doxygen + python3
|
||||
## Project layout
|
||||
|
||||
```
|
||||
src/system/ domain model (Module/Part/Pin/Signal, Connection, Transform, …)
|
||||
src/imports/ Mentor / Altium / ODS netlist importers
|
||||
src/tui/ FTXUI shell (commands, screens, completion, history)
|
||||
tests/ doctest suite
|
||||
doc/ api/ + user/ Markdown trees, Doxyfile.in, gen_api_md.py
|
||||
test/ sample netlists + system.essim bring-up script
|
||||
src/
|
||||
core/ business logic, NO GUI toolkit (→ libessim_core)
|
||||
domain/ model (Module/Part/Pin/Signal, Connection, Transform…) + analyses
|
||||
imports/ Mentor / Altium / ODS netlist importers + ODS writer
|
||||
app/ use-case operations (export → CSV/ODS, …)
|
||||
frontends/ one dir per GUI/TUI engine, each links essim_core
|
||||
tui/ FTXUI shell + main.cpp (→ libessim_tui + the `essim` binary)
|
||||
tests/ core tests (link essim_core)
|
||||
tui/ frontend tests (link essim_tui)
|
||||
doc/ api/ + user/ Markdown, Doxyfile.in, gen_api_md.py
|
||||
test/ sample netlists + system.essim bring-up script
|
||||
```
|
||||
|
||||
Full layout & rationale in [`DESIGN.md`](DESIGN.md).
|
||||
|
||||
@@ -33,3 +33,7 @@ target_link_libraries(essim_tui
|
||||
|
||||
add_executable(essim "${CMAKE_CURRENT_SOURCE_DIR}/main.cpp")
|
||||
target_link_libraries(essim PRIVATE essim_tui)
|
||||
|
||||
# Keep the binary at the top of the build tree (./build/essim), regardless of
|
||||
# which frontend subdir produced it.
|
||||
set_target_properties(essim PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}")
|
||||
|
||||
Reference in New Issue
Block a user