neosyn-fpga-mcp

What this host can actually do — PROBED, not assumed. Call it before deciding how to verify a design, instead of assuming a backend exists. Returns {jar, jar_present, bytecode_simulator:{available,reason,detail}, simulators:[...], tools:{iverilog,vvp,verilator,yosys,ghdl}, advice}. The fast bytecode simulator ships with the commercial Neosyn distribution and is absent from the open-source compiler, so any flat claim about it is wrong in one of the two environments. `advice` is written from what was actually found here.

Parse, scope, and type-check C⏚ source without running it. Returns {ok, diagnostics:[{file,line,message}], summary}. Call this first on any draft; fix every diagnostic before simulating. `extra_files` maps filename → content for imported bundles/tasks (e.g. {"Defs.cg": "..."}). For a MULTI-FILE project, pass `package_dir` (the folder holding your .cg files, e.g. "fpga/src/main/cg", relative to the project root): the tool then reads every sibling .cg there, so tasks defined in other files of the same package resolve — just like the IDE. A task you only got from `cg_example` is text; it must be saved to a file in that dir to resolve. `path` (F92): name the .cg FILE and the tool reads it itself -- then what is verified is what ships. Pass `path` alone, or with `source` (the two must match, or the call is refused naming the first differing line). Every result carries `verified`: {path, sha256, bytes, lines} of exactly what was checked (+ `jar_sha256` when the compiler ran; `jar_changed` if that jar was replaced after the kit started -- re-run what you verified before the change).

Fetch a markdown knowledge doc. No topic → an index of available topics, their descriptions and their SECTIONS; a topic → its full content plus its section names; a topic and a `section` → just that section. Re-reading one section is far cheaper than the whole doc -- after your context is compacted, fetch the section you need, not the whole topic. Topics: 'context' (the core C⏚ language pack — load before writing any Cg); 'handshakes' (port protocols push/stream/confirm, back-pressure, and the pacing gotcha when feeding a registered built-in — read before wiring a network); 'arithmetic' (what *, /, %, <<, >> synthesize to and when they need a std.math built-in or a barrel shifter — read before writing math); and 'riscv' (the worked RV32I CPU reference: the loadable single-cycle core and the reusable patterns for CPU-shaped hardware in Cg — barrel shifter, signed/unsigned widening, sub-word load/store, count-prefixed boot-stream program loading, and the lossless-capture / address-filtered testbench patterns — read when building or extending a processor, instruction decoder, datapath, or stack machine).

Get a VERIFIED C⏚ base to seed-and-adapt from (don't synthesize hard kernels from scratch — adapt a known-good one). This is a curated dictionary of validated code with scored lazy lookup, NOT free-form search. No pattern → a compact index (name + kind + use_when + tags). A pattern → the single best-matching source plus its metadata and 1-2 `runners_up` so you can self-correct on an ambiguous query. `k>1` also returns the next sources when the task implies composition. Matching is specificity-weighted (exact name ≫ name word ≫ full tag phrase ≫ partial overlap), so e.g. "1/sqrt" → RSqrt while a bare "sqrt" → FixedSqrt. `kind` distinguishes general PRIMITIVES (the reusable library: Recip, Divide, SeqDiv, FixedSqrt, RSqrt, SqrDist, DotProduct, Fir, Integ, Distance, Counter) from application EXAMPLES (Force, GalaxyForce). Every entry passes simulate + generate + iverilog + yosys. Workflow: cg_example → edit only the dataflow → cg_check → cg_simulate → cg_generate_verilog → cg_synth.

Show a task's compiled state machine (states + transitions). Useful to confirm an FSM has the intended number of states.

Generate synthesizable HDL from C⏚. target is 'verilog' (default) or 'vhdl'. Returns {ok, file_count, files:{path:content}}. Use after cg_simulate passes, to hand off RTL. Pass `output_dir` (e.g. "fpga/build/verilog", relative to the project root) to WRITE the files to disk and KEEP them — the result then also carries {output_dir, written:[paths]}. Without it the files are only returned inline and the temp dir is cleaned. Prefer `output_dir` when the host needs the .v on disk (to inspect or run yosys). For a MULTI-FILE project, pass `package_dir` (the folder with your .cg files) so sibling tasks in the same package resolve during generation. `path` (F92): name the .cg FILE and the tool reads it itself -- then what is verified is what ships. Pass `path` alone, or with `source` (the two must match, or the call is refused naming the first differing line). Every result carries `verified`: {path, sha256, bytes, lines} of exactly what was checked (+ `jar_sha256` when the compiler ran; `jar_changed` if that jar was replaced after the kit started -- re-run what you verified before the change).

Show a network's compiled graph (instances, ports with widths and interfaces, connections). Useful to confirm wiring.

Fast static checks for C⏚ that COMPILES CLEANLY AND IS STILL WRONG. Returns {ok, findings:[{rule, line, severity, message, fix}]}; ok is False if any finding is an error. This does NOT replace `cg_check` -- it catches what the compiler ACCEPTS. Chiefly: a `test:` fixture that drives inputs but compares no output (it passes even with a dead design -- the single most expensive failure mode in this codebase), ragged vectors in a sync fixture, a fixture key that matches no port, and a bool compared against 0/1. No jar, no simulator, no timeout -- run it on every draft before `cg_check`, and again before you claim a design is verified. `path` (F92): name the .cg FILE and the tool reads it itself -- then what is verified is what ships. Pass `path` alone, or with `source` (the two must match, or the call is refused naming the first differing line). Every result carries `verified`: {path, sha256, bytes, lines} of exactly what was checked (+ `jar_sha256` when the compiler ran; `jar_changed` if that jar was replaced after the kit started -- re-run what you verified before the change).

Finalize the FPGA report: (re)render <report_dir>/report.html — a self-contained HTML with the synthesis table (REAL/FOLDED/SUSPECT verdict + cell/arith/latch counts), the simulation PASS/FAIL + output, the generated-Verilog file list, and (best-effort) datapath schematic SVGs. This does NO synthesis — the rows are built incrementally by passing the SAME `report_dir` to cg_synth (per kernel) and cg_simulate as you run them; cg_report just aggregates those fragments + the Verilog under <report_dir>/verilog and renders. Workflow: cg_generate_verilog(output_dir="<report_dir>/verilog", package_dir=...) cg_simulate(..., report_dir="<report_dir>") cg_synth(..., report_dir="<report_dir>") # once per kernel cg_report(report_dir="<report_dir>") # finalize + schematics Returns {ok, report (the .html path), kernels, sim_ok, message}. Set `schematics=False` to skip the SVGs (faster).

START HERE when writing new C⏚ from a blank file. Returns a COMPLETE, COMPILING, SELF-CHECKING skeleton with the datapath left as marked holes — you fill in the holes instead of inferring the file skeleton, the port syntax and the test-harness shape at the same time. It is verified before you get it: the returned source compiles AND its self-test passes as handed over (`verified`). So it starts GREEN — any failure after your edit is your edit, which makes cg_simulate a real signal instead of a guess. kind: task a `sync` task whose `test:` block VALUE-CHECKS every output cycle by cycle. The default, and the strongest: prefer it whenever the design is a cycle-by-cycle function. fsm an enum-state control machine (+ the publish-before-transition timing rule, the one that bites). stream a `push`-handshake dataflow stage + driver/monitor harness. network a two-stage pipeline, showing wiring and back-pressure. generic a parameterized entity: const params + new Foo({k: 5, w: 16}). `inputs`/`outputs` are "name:type" strings (e.g. ["a:u8","b:i16"]) and apply to kind="task" and kind="stream"; a bare "a" defaults to u8. The other kinds are fixed pattern demonstrations — edit their ports in the returned source. `holes` gives the line number of every ">>> FILL IN" marker. Workflow: cg_scaffold → fill the holes → cg_check → cg_simulate → cg_generate_verilog → cg_synth. (cg_example is the complement: reach for it when a VALIDATED implementation of a known kernel already exists.)

Simulate C⏚ source. Returns {ok, simulator, timed_out, diagnostics, output}. `output` holds port values and print() lines; a `properties { test: {...} }` block self-checks and fails the run on mismatch. This is the ground-truth correctness check — iterate until ok is true. `simulator` picks the backend. 'bytecode' (default) is the fast cycle-accurate simulator — no HDL toolchain, and a `properties { test: {...} }` block self-checks. It ships with the commercial Neosyn distribution; the open-source compiler has no `simulate` verb and the call then returns `available: False` with a pointer, NOT a design error. 'iverilog' generates Verilog + a testbench and runs Icarus Verilog — a slower cross-check that needs a network whose NAME contains "Test" (capital T) on every released compiler -- a `test` property or a `_test` name also work after 3.2.0. Call cg_capabilities to see which backends this host actually has; do not assume. `path` (F92): name the .cg FILE and the tool reads it itself -- then what is verified is what ships. Pass `path` alone, or with `source` (the two must match, or the call is refused naming the first differing line). Every result carries `verified`: {path, sha256, bytes, lines} of exactly what was checked (+ `jar_sha256` when the compiler ran; `jar_changed` if that jar was replaced after the kit started -- re-run what you verified before the change).

Map a compiler error/diagnostic to the fix for it. Returns {ok, recipe, hint, source}. Two kinds of answer: - AUTHORING/WIRING errors (the file doesn't parse, a sibling entity isn't visible, the jar failed to load) → `recipe` and `source` are None and `hint` carries the whole fix, which is a one-line edit. Apply the hint literally; do NOT redesign the datapath. - SYNTHESIZABILITY errors (the construct has no hardware) → `recipe` names a validated example and `source` is its full C⏚, to adapt. div/shift-by-a-variable → Recip; a data-dependent loop bound → SeqDiv. cg_check/cg_simulate/cg_generate_verilog/cg_synth already auto-attach this as a `suggestion` when a diagnostic matches; call this directly to look one up.

Synthesize the generated Verilog with yosys — the strongest signal that a design maps to real hardware (catches non-synthesizable constructs that simulate/iverilog accept). Returns {ok, verdict, top, flow, cells, arith_ops, latches, warnings, stat, problems, output}. `verdict` is the one-word classification so you can't confabulate success: REAL (a genuine datapath), FOLDED (0 datapath cells — inputs weren't on ports, dead hardware), SUSPECT (latches inferred — a data-dependent loop / missing reset), or ERROR (yosys failed). `cells` is the gate count; `problems` lists any ERROR/Warning lines. `warnings` flags the two silent failure modes: a DEGENERATE datapath (`arith_ops == 0` → the design constant-folded; drive it with input ports) and inferred LATCHES (`latches > 0` → a data-dependent loop bound or incomplete assignment; expected a clocked FSM). A clean synth has `ok: true`, a sensible `cells`, `arith_ops > 0`, and empty `warnings`. NOT a correctness oracle: a REAL verdict means real (synthesizable) hardware, NOT *correct* hardware — it can't tell a good sequential FSM from a buggy one. `cg_simulate` (the asserting test network) is the correctness check; run it FIRST, then cg_synth to confirm the hardware is real, not folded or latched. `top` defaults to the first non-testbench task/network (the DUT); pass it when a file holds several designs. `flow` selects the synthesis flow: 'generic' (default, portable check) or a vendor FPGA family — 'ice40', 'ecp5', 'xilinx', 'gowin', 'intel' — to map to that part's primitives. Override the yosys binary with the $YOSYS env var. Run after cg_simulate passes. A constant-bound `for` synthesizes (it's unrolled); a data-dependent loop becomes an FSM (also fine). `report_dir` DEFAULTS to "fpga/build", so each synth automatically records THIS kernel's verdict + cell counts as a row in <report_dir>/report.html — synthesizing the kernels builds the whole report as a byproduct, no separate step (see cg_report). Pass report_dir="" to disable. `path` (F92): name the .cg FILE and the tool reads it itself -- then what is verified is what ships. Pass `path` alone, or with `source` (the two must match, or the call is refused naming the first differing line). Every result carries `verified`: {path, sha256, bytes, lines} of exactly what was checked (+ `jar_sha256` when the compiler ran; `jar_changed` if that jar was replaced after the kit started -- re-run what you verified before the change).