Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 62 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -552,7 +552,8 @@ each visible trace in its own `TraceStore` color. A wire tree two visible
traces go through is striped in their colors (`NetRoute::stripeColors`,
dashes anchored to world coordinates; plain convergence color when zoomed
too far out to read them), and a gate they share is outlined in the
near-black convergence color -- only a gate each trace's own reply listed
near-black convergence color (unless the gate is styled or
`convergence_outline` is off) -- only a gate each trace's own reply listed
on the net (`Equipotential::traceInstances`): a trace's partial net folded
into a fuller one already shown doesn't reach that net's other readers. A
diagnosis color
Expand Down Expand Up @@ -722,14 +723,41 @@ intercepts it (`Renderer.render_outputs()`); the session doesn't.

`view_options` is a server push setting how the viewer draws, not what:
`{"response":"view_options","instance_label":"name|model|both",
"sink_rows":8,"max_sinks":32,"group_by":"model|hierarchy|role"}`, keys
"sink_rows":8,"max_sinks":32,"group_by":"model|hierarchy|role|pin",
"convergence_outline":true}`, keys
absent kept (`ViewOptions::apply()`; `protocol.view_options()` validates,
`DEFAULT_VIEW_OPTIONS` mirrors the C++ defaults). Not cleared by a root
load; the session re-sends it after each `root_response` anyway, first.
render.py sends it in full at the start of every drawing. Also the View
menu (Instance Labels, Fanout) and the CLIs' flags. Fanout summaries are
pseudo-instances under a made-up path segment (id >= `kSummaryIdBase` in
`EquipotentialView.cpp`), never sent to the host; see `planFanout()`.
`convergence_outline` (`--no-convergence-outline`, View > Outline Trace
Convergence): the near-black outline of a box two visible traces go
through; never drawn on a box a style names (`StyleStore::instanceStyle()`),
since it reads as an error or a selection in a figure. Like the four
export decorations below, it's left out of `ViewOptions::layoutJson()`.
Four keys only decorate exports (SVG and PNG), never the canvas, and are
left out of `ViewOptions::layoutJson()` so changing them doesn't refit:
`"title"`/`"caption"` (text bands above/below the drawing, `\n` breaks
lines), `"legend"` (a swatch + label per visible trace and per net a style
labels, `SchematicView::legend`, filled by `EquipotentialView`) and
`"hide_ui_glyphs"` (no open-pin stubs or "•••" dots,
`SchematicView::hideUiGlyphs` on the export copy). `export_svg()`/
`export_png()` take them as keywords too (`protocol.EXPORT_DECORATIONS`);
CLIs: `--title`, `--caption`, `--legend`, `--hide-ui-glyphs`.
`group_by: "role"` groups sinks by the receiving pin's naja role
(`fanoutRoleGroup()`: "clock", "reset", "set", "enable", "scan",
"address", else "data"), read from the sparse `"role"` on term and
occurrence entries: naja's `SNLDesignModeling::getTermRole()` in snake
case (`"clock"`, `"async_reset"`, `"enable"`, `"memory_write_enable"`,
...), sent only for a non-data role (DataInput/DataOutput/Other: none),
from the `SNLInstTerm` on occurrences (parameter-driven roles) --
`termRoleName()`/`setTermRole()` in `LocalSNLProvider.cpp`,
`term_role()`/`with_clock()` in `protocol.py`, kept in step (shared
cases: `tests/data/role_protocol_cases.json`). A pin naja
models as a clock with no role set counts as "clock". `"pin"` is the
older grouping: by pin name, clock pins together.

`export_svg` is a server push too, `{"response":"export_svg"}`, from
`Schematic.export_svg()` (`ViewerSession.export_svg()`): the viewer sets
Expand Down Expand Up @@ -806,8 +834,13 @@ it must name a pin the viewer draws -- a leaf pin or a top-level port.
Python resolves every item (`session.style_response()`, `ValueError` on
a bad one) and sends a `net` item once per bit on its net's driver (a
top-level port, else an output leaf pin: the pin a trace's partial net
also lists), whatever pin or `target` (an instance or pin as
`show_instance()`/`show_net()` take) named it. An `instance` item fills
also lists), whatever pin or `target` named it: an instance or pin as
`show_instance()`/`show_net()` take, or -- what a JSON style file can
say -- `render`'s `--instance`/`--net` text (`"u1/u2"`, `"u1:A[3]"`,
`"y"`, matched against the design), a pin as a `[instance, terminal(,
bit)]` list or a `{"path"|"id_path", "terminal", "bit"}` object
(`session.style_target()`). `target` is the Python host's: the native
`StyleStore::parse()` refuses it. An `instance` item fills
the box (also gate symbols, port flags; module frames keep their
translucency), outlines it in `color`/`width`, and `label` replaces the
drawn name (`InstanceShape::label`, so the layout makes room for it). A
Expand Down Expand Up @@ -1119,7 +1152,16 @@ path the host read, used by the native "Open in Editor".
- `layoutHierarchyGroups()`: module frames.
- Fanout: `layeredPlacement(..., maxSinkRows)` deals a column's sinks
(nodes driving nothing placed) into a grid of columns, each its own
level; `planFanout()` picks which sinks of a wide net are drawn and
level, with a band of rows per driver (a sink's nearest one): every
band starts in the grid's first column and is placed level with its
driver, `kBandGap` under the band above, so no net's wire crosses
another net's sinks (`MultiDriverFanout` tests in
`tests/FanoutTest.cpp`). Sinks a crossing-reduction sweep can't tell
apart (the loads of one pin) keep `PlaceNode::rank` order: the
natural order of their names (`naturalLess()`/`naturalPathLess()`,
`lut_111` before `lut_1037`), summaries last; the receivers
`planFanout()` sees are sorted the same way, so the first max_sinks
drawn are the naturally first. `planFanout()` picks which sinks of a wide net are drawn and
gathers the rest into groups (never a driver, a pinned instance, an
expanded group or a group of one). The model label is a `kNameH` row
under the symbol (`shownModel()`, `modelRect()`, `footprintHeight()`).
Expand Down Expand Up @@ -1159,6 +1201,21 @@ path the host read, used by the native "Open in Editor".
(native: `NativeFileDialog::saveFile()`; WASM: a Blob download,
`najaDownloadText` in `AppLogic.cpp`). New drawing code goes through
the painter, never straight to an `ImDrawList`, or it won't reach exports.
`BeginGroup()`/`EndGroup()` give the SVG its structure (no-ops for the
other painters): `SchematicView::render()` wraps each route/net
(`netGroup()`: `class="net"`, `data-net`, `data-driver` "path:pin" or a
port name, `data-driver-id-path`, `data-label`), box
(`instanceGroup()`: `class="instance"`, `data-path`, `data-id-path`,
`data-model`), port flag (`class="port"`, `data-name`,
`data-direction`), summary (`class="summary"`, `data-group`,
`data-count`) and module frame (`class="module"`), plus
`data-path-json`/`data-driver-json` when a name is empty or holds `/` or
`:`. Groups and decorations must not change the drawing:
`tests/SvgExportTest.cpp` compares an undecorated export, group tags
stripped, to `tests/data/export_golden.svg` (rewrite it with
`NAJA_SCHEMATIC_UPDATE_GOLDEN=1` only for a deliberate drawing change).
The decorated page (`layoutPage()`/`paintPage()`) is shared by
`exportSvg()` and `exportPng()`.
- **`SchematicInteraction`** — the pure side of the schematic's pin
interactions: `pickPin()` (nearest-pin hit test, radius capped in world
units so a pin doesn't swallow box-body clicks at low zoom) and
Expand Down
3 changes: 3 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,9 @@ if(NOT EMSCRIPTEN_BUILD)
${NAJA_SCHEMATIC_TEST_SOURCES}
)
target_link_libraries(naja-schematic-tests PRIVATE gtest_main)
target_compile_definitions(naja-schematic-tests PRIVATE
NAJA_SCHEMATIC_TEST_DATA="${CMAKE_CURRENT_SOURCE_DIR}/tests/data"
)

# LocalSNLProvider against the wire-protocol cases shared with the
# Python backend (tests/data/anonymous_protocol_cases.json, also run by
Expand Down
75 changes: 71 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ plus options, in any order. Their flags differ slightly:
| `--liberty a.lib --liberty b.lib` | `--liberty a.lib b.lib` | Liberty cell libraries (Verilog only) |
| | `--py-primitives prims.py` | Primitives defined in Python: a `.py` file or module whose `load(db)` builds them (repeatable) |
| `--diagnosis report.json` | `--diagnosis report.json` | Show a diagnosis report on the design |
| `--style styles.json` | `--style styles.json` | Color, widen, fill and label nets, instances and pins (`{"items": [...]}`, see `style_response` in [CLAUDE.md](CLAUDE.md)) |
| `--style styles.json` | `--style styles.json` | Color, widen, fill and label nets, instances and pins (see [Style files](#style-files)) |
| `--yosys-src` | `--yosys-src` | Read Yosys `(* src *)` attributes, so Show Sources leads back to the RTL (Verilog only) |
| `--source-root dir` | `--source-root dir` | Where to look for relative source paths (repeatable) |
| `--source-map FROM=TO` | `--source-map FROM=TO` | Rewrite source paths recorded on another machine (repeatable) |
Expand All @@ -111,6 +111,51 @@ order, then in the current directory. `--source-map /home/ci/flow=/work/flow`
finds a file recorded as `/home/ci/flow/rtl/top.v` at
`/work/flow/rtl/top.v`.

### Style files

`--style` reads a JSON file listing what to color, widen, fill or label.
It's kept across reloads and in SVG/PNG exports:

```json
{"items": [
{"kind": "net", "target": "en", "color": "#ff7f0e", "width": 3, "label": "en"},
{"kind": "net", "target": "u_ctrl/en_reg:Q", "color": "#1f77b4", "width": 2.5},
{"kind": "net", "target": [["u_core", "u_alu"], "A", 3], "color": "#2ca02c"},
{"kind": "instance", "target": "u_core/u_alu", "fill": "#2ca02c55", "label": "ALU"},
{"kind": "term", "path": ["u_ctrl", "en_reg"], "terminal": "CE", "color": "#d62728"}
]}
```

A bare list of items works too. Each item has:

- `kind`: `"net"` (every wire of the net through that pin), `"instance"`
(the default; also gate symbols and port flags) or `"term"` (one pin).
- What it styles, either as a `target` or as `path`/`id_path` plus, for a
pin, `terminal`/`term_id` and `bit`:
- an instance: `"u1/u2"`, as `naja-schematic render --instance` takes
it, or a list of names or ids (`["u1", "u2"]`, `[3, 7]`);
- a pin: `"u1/u2:A"`, `"u1/u2:A[3]"`, or `"y"` / `"d[1]"` for a
top-level port, as `--net` takes it; or a list `[instance, terminal]`
/ `[instance, terminal, bit]`, the instance as above and `[]` for a
top-level port (`[[], "en"]`); or `{"path": [...], "terminal": "A",
"bit": 3}`.

Text is matched against the design, so an escaped name containing `/`
or `:` still resolves. If the text could mean more than one object,
the item is refused and you need the list form. `path` is a list of
instance names (`[]` = the top), and `id_path` the same with instance
ids (needed for anonymous instances).
- Any of `color` (`"#rrggbb"` or `"#rrggbbaa"`), `width` (wires and pins,
in SVG pixels at 1x), `fill` (instances; a translucent fill tints the
box) and `label` (replaces the drawn name).

Items on one object merge in order. A diagnosis color beats a style
color, and a style color beats a trace color. The browser server and
`naja-schematic render` check every item before drawing: one that doesn't
resolve is an error, and nothing is drawn. `target` is resolved by those
Python hosts. The desktop app's `--style` takes `path`/`id_path` and
`terminal`/`bit` only.

### Headless SVG export

The desktop app can draw a schematic to an SVG file without opening a
Expand Down Expand Up @@ -154,14 +199,36 @@ On the command line they're flags (desktop app, `naja-schematic` server and
| Option | Values | |
|---|---|---|
| `--instance-label` | `name` (default), `model`, `both` | The instance name above a box, its cell model under it, or both |
| `--sink-rows N` | default 8, 0 = no limit | A column with more sinks (boxes driving nothing shown) than this becomes a grid of columns |
| `--max-sinks N` | default 32, 0 = no limit | A net with more sinks draws the first N. The rest go into stacked summary boxes ("DFF ×812"), and clicking one shows its sinks |
| `--group-by` | `model` (default), `hierarchy`, `role` | How sinks are gathered into summaries: by cell model, by the module holding them, or by the pin they're on (clock pins together, other pins by name) |
| `--sink-rows N` | default 8, 0 = no limit | A column with more sinks (boxes driving nothing shown) than this becomes a grid of columns. With several drivers, each driver's sinks get a band of rows level with it, all bands starting in the same column, so no net's wires cross another net's sinks |
| `--max-sinks N` | default 32, applied when not given; `0` turns it off | A net with more sinks draws the first N, in natural name order (`lut_111` before `lut_1037`). The rest go into stacked summary boxes ("DFF ×812"), and clicking one shows its sinks. To draw every sink, pass `--max-sinks 0` (`view_options={"max_sinks": 0}`) |
| `--group-by` | `model` (default), `hierarchy`, `role`, `pin` | How sinks are gathered into summaries: by cell model, by the module holding them, by the role naja gives the pin they're on (`SNLBitTerm.getRole()`: "clock ×812", "reset ×40", "enable ×8", and "data ×165" for pins with a data role or none), or by that pin's name (clock pins together, other pins by name) |
| `--no-convergence-outline` | outline on by default | A box two or more traces go through gets a near-black outline (never a box a style names). This turns it off (View > Outline Trace Convergence, `convergence_outline`) |

A net's driver is always drawn as a box. So is an instance that is drawn
for another reason: it drives something shown, is selected, has a
diagnosis or a style.

These only change exports (SVG and PNG), never the canvas:

| Option | Values | |
|---|---|---|
| `--title TEXT` | default none | Text in a band above the drawing |
| `--caption TEXT` | default none | Text in a band below the drawing |
| `--legend` | off by default | A color swatch and label below the drawing for each trace, and each net a style labels |
| `--hide-ui-glyphs` | off by default | No hollow stubs on open pins, no "•••" on boxes showing some of their pins |

An exported SVG is structured, so a script or a page can find what's in it
without reading geometry. Every net is a `<g class="net">` (wires, junction
dots, bus marks, label) with `data-net`, `data-driver` (`u1/u2:Q`, or a
top-level port's name) and `data-driver-id-path`; every box a
`<g class="instance">` with `data-path` (`u1/u2`), `data-id-path` (`3,7`)
and `data-model`; every top-level port flag a `<g class="port">` with
`data-name` and `data-direction`; every summary box a
`<g class="summary">` with `data-group` and `data-count`; every module
frame a `<g class="module">`. When a name holds `/` or `:` (escaped
Verilog names can) or is empty, `data-path-json`/`data-driver-json` give
the path as JSON too. The groups change nothing in the drawing.

## Controls

The same list is in the app under **Help > Keyboard Shortcuts**. "Ctrl" is
Expand Down
4 changes: 4 additions & 0 deletions REUSE.toml
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ path = [
"python/tests/data/design.v",
"python/tests/data/fanout.v",
"python/tests/data/wide_fanout.v",
"python/tests/data/role_fanout.v",
"python/tests/data/py_design.v",
"python/tests/data/py_prims.py",
"python/tests/test_design_generations.py",
Expand Down Expand Up @@ -156,13 +157,16 @@ path = [
"tests/StyleStoreTest.cpp",
"tests/RasterTest.cpp",
"tests/FanoutTest.cpp",
"tests/SvgExportTest.cpp",
"tests/SchematicLayoutTest.cpp",
"tests/SourceStoreTest.cpp",
"tests/TraceTest.cpp",
"tests/TypesJsonTest.cpp",
"tests/VerilogLanguageTest.cpp",
"tests/data/anonymous_protocol_cases.json",
"tests/data/source_protocol_cases.json",
"tests/data/role_protocol_cases.json",
"tests/data/export_golden.svg",
"tests/data/sv/gates.sv",
"tests/data/sv/operators.sv",
"tests/data/sv/two_tops.sv",
Expand Down
42 changes: 39 additions & 3 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,18 +45,45 @@ view
Nets, instances and pins can also be styled -- a color and width for a
net's wires, a fill for a box, labels -- kept across reloads and in SVG
exports. A `"net"` item colors the whole net through the pin it names;
`"target"` takes anything `show_instance()`/`show_net()` take:
`"target"` takes anything `show_instance()`/`show_net()` take, and also
the text forms of `naja-schematic render`'s `--instance`/`--net`
(`"u1/u2"`, `"drv_0:O"`, `"en"` for a top-level port):

```python
view.style([
{"kind": "net", "target": ([], "en"), "color": "#ff7f0e", "width": 3, "label": "en"},
{"kind": "net", "target": (["drv_0"], "O"), "color": "#1f77b4"},
{"kind": "net", "target": "drv_0:O", "color": "#1f77b4"},
{"kind": "instance", "target": ["s0"], "fill": "#1f77b455"}, # a tint
])
```

Diagnosis colors win over styles, and styles over trace colors.

The same items, in a JSON file, are what `--style FILE` reads (on
`naja-schematic` and `naja-schematic render`). JSON has no tuples: a pin
there is text, a list `[instance, terminal]` / `[instance, terminal,
bit]` (`[]` = a top-level port), or `{"path": [...], "terminal": ...,
"bit": ...}`:

```json
{"items": [
{"kind": "net", "target": [[], "en"], "color": "#ff7f0e", "width": 3, "label": "en"},
{"kind": "net", "target": "drv_0:O", "color": "#1f77b4", "width": 2.5},
{"kind": "net", "target": [["u_core", "u_alu"], "A", 3], "color": "#2ca02c"},
{"kind": "instance", "target": "u_core/u_alu", "fill": "#2ca02c55", "label": "ALU"},
{"kind": "term", "path": ["s0"], "terminal": "CE", "color": "#d62728"}
]}
```

`kind` is `"net"`, `"instance"` (the default) or `"term"`. Instead of
`target`, an item can give `path` (instance names, `[]` = the top) or
`id_path` (instance ids), plus `terminal`/`term_id` and `bit` for a pin.
The style fields are `color` (`"#rrggbb"`/`"#rrggbbaa"`), `width`,
`fill` and `label`. Text is matched against the design. Text that names
nothing, or more than one object, is an error. So is any item that
doesn't resolve, and then nothing is drawn. See [Style
files](../README.md#style-files) for details.

The view and your najaeda code can point each other at instances.
`show_instance()` takes a najaeda `Instance` or a naja `SNLPath`, a list
of instance ids (as `Instance.pathIDs`) or a list of instance names (a plain string is one
Expand Down Expand Up @@ -129,6 +156,12 @@ naja_schematic.export_svg(
view_options={"instance_label": "both", # name above each box, cell model under it
"max_sinks": 16, "group_by": "model"}, # a net's sinks past 16: "DFF x812"
)
naja_schematic.export_svg(
traces=[(["u1"], "D")], path="report.svg",
title="Fan-in of u1/D", caption="after the edit", # bands above / below the drawing
legend=True, # a swatch per trace and labeled net
hide_ui_glyphs=True, # no open-pin stubs or "more pins" dots
)
svgs = naja_schematic.export_svgs([ # several drawings, one renderer
{"instances": [["u1", "u2"]], "path": "u2.svg"},
{"traces": [(["u3"], "A", 0)], "path": "u3_a0.svg"},
Expand All @@ -149,7 +182,10 @@ naja-schematic render --verilog design.v --py-primitives prims.py --top top \
```

`view_options` (and the flags `--instance-label`, `--sink-rows`,
`--max-sinks`, `--group-by`) set how the schematic is drawn: see
`--max-sinks`, `--group-by`; for exports only, `--title`, `--caption`,
`--legend`, `--hide-ui-glyphs`, also `export_svg()`/`export_png()`
keywords) set how the schematic is drawn, and the SVG's `<g>` groups
name every net, instance and port in it: see
[How the schematic is drawn](../README.md#how-the-schematic-is-drawn). In
a notebook they're `show(view_options=...)` / `view.view_options(...)`,
and on a server `ViewerServer(view_options=...)`, the same flags on
Expand Down
2 changes: 1 addition & 1 deletion python/naja_schematic/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"""
# Single version for the whole project: CMakeLists.txt reads this line into the
# C++ app too (NAJA_SCHEMATIC_VERSION_STRING), so keep it a plain literal.
__version__ = "0.2.1"
__version__ = "0.3.0"

from .protocol import diagnosis_response, handle_request
from .render import RenderError, export_png, export_svg, export_svgs
Expand Down
Loading
Loading