# HDL architecture audit Date: 2026-09-15 · Scope: `SAPHO/processor.v`, `core.v`, `instr_dec.v`, `ula.v`, `myFIFO.v`, `addr_dec.v`, the generated `.v`/`_tb.v` (`hdl.c`), and the two programs that use the interrupt (`ZeroCross`, `ProcDTW`). Companion to [`precision-and-width-review.md`](precision-and-width-review.md) (which covers the float datapath). Its work items were TODO item 10; on 2026-10-27 the open ones became GitHub issues #32 (an instruction-set simulator and random differential test), #33 (the decode rows generated from `isa.tsv`), #34 (the undefined cases) and #35 (hygiene), and Luciano dropped the interrupt rework, the stack overflow pin, the I/O contract and the registered-branch option. The question asked: *where is this processor weak, and what would make it professional without losing its defining property — the hardware adapts to the assembly program, building only what the opcodes use?* --- ## 0. What the architecture is, as built A **Harvard, single-cycle accumulator machine** with a memory operand, two hardware stacks (data, return) and a two-stage overlap: ``` cycle N : instruction N leaves mem_instr (registered read) instr_dec decodes it combinationally -> push/pop, mem_wr, req_in, out_en, ldi/sti/lda/sta the data read for its operand is issued (mem_data, registered read) ula_op for it is registered cycle N+1 : ula_op and mem_data_rd arrive together, the ALU computes, racc <= ula_out ``` While instruction N executes in N+1, instruction N+1 is being decoded — and four of its decisions consume `ula_out` **combinationally, the cycle it is produced**: the `JIZ` branch (`if_acc = |ula_out` → `pc_load` → instruction address), the `LDI` read address (`ula_out[MDATAW-1:0]`), the `SET` data (`mem_data_wr = ula_out`) and the `PSH` data (`sp_in = ula_out`). That is a full bypass network: **no data hazard, no control hazard, no branch penalty, every instruction exactly one cycle**. The price is that the ALU's depth sits on the branch and address paths, so it sets the clock directly. Things this design does right that many "textbook" cores do not: - **Opcode-driven resource allocation.** Every operator, decoder compare and ALU path exists only if the program uses it (`generate` on ~110 opcode parameters); memories are sized from the program (`MDATAS`, `MINSTS`, `NBOPER`). A 20-instruction integer program is a few hundred ALMs. - **Deterministic timing.** One instruction per cycle, no cache, no stall, no speculation: the cycle count of a loop is known at compile time — the right property for DSP and control. - **Single clock, synchronous reset** on every state element (v5.3), FPGA-friendly memories (registered reads, `$readmemb` init), no CDC. - **Bypass by construction** rather than by forwarding logic. Keep all four. Everything below fits inside them. --- ## 1. Weak points, by severity ### 1.1 The interrupt is a level-sensitive PC override `prefetch` (`core.v`): `pc_l = itr | pc_load; instr_addr = itr ? ITRADD : …`. As long as `itr` is high the fetch address is forced to `ITRADD` **every cycle**: the instruction at the vector is fetched and executed once per cycle the level is held, the interrupted PC is not saved, nothing masks the input, and `RET` cannot resume because nothing was pushed. It works in DTW because the source is a FIFO-not-empty flag whose first consumer (`fin`) clears it — but `ProcDTW`'s vector instruction is `out(2, -123)`: if the level ever lasts two cycles, the port pulses twice. This is an *event restart*, not an interrupt, and its contract is implicit. **Professional version, behind `ITRADD != 0` only:** edge-detect the input (two flops, one-shot), optionally push the PC on the return stack so the handler can `RET` (one extra `isp_push` condition), and a mask bit settable by software. Cost: ~5 flops + a mux; no cost when the program has no `#PRACA`. The compilers already emit the vector; they would gain a "return from interrupt" form. ### 1.2 I/O has no flow control `INN`/`F_INN` pulse `req_in`; the generated testbench answers on the same cycle's negative edge, and `ula_in2_ctrl` samples `io_in` one cycle later. `OUT` pulses `out_en` with the data. There is no *ready*: an empty input FIFO returns stale data, a full output FIFO drops a word, and the core never knows. The DTW project copes with `almost_empty`/interrupt plumbing outside the core. Options, in order of cost: 1. **Document the contract** (respond in the cycle after `req_in`; never `OUT` into a full sink) — zero cost, overdue. 2. **Status-port convention**: reserve an input port index for status bits (`empty`, `full`) the program polls with `in()`; `hdl.c` wires it. No core change, no timing change. 3. **valid/ready with a global stall** — the ~10 register enables listed in `precision-and-width-review.md` §2.6. Changes cycle counts; only worth it if streaming peripherals become a design goal. Keep as an option behind a parameter, off by default. ### 1.3 Stack overflow and underflow are silent Both `stack` instances wrap the pointer modulo `DEPTH`; the only detection is the simulation-only `fl_full` flag. On hardware a deep call chain or a long expression silently corrupts the stack. Two fixes that fit the philosophy: (a) **let the compilers size the stacks** — for non-recursive programs `cmmcomp`/`cppcomp` know the maximum call depth and the maximum expression depth statically; `#NDSTAC`/`#SDEPTH` become an optional override, and `asmcomp` refuses a value smaller than the program needs; (b) a **sticky overflow flag** brought out as a pin, exactly like `cheguei` (two flops), so the fault is visible on a board. ### 1.4 The ALU sits on the fetch and address paths Consequence of the bypass network (§0). Measured on Cyclone V C6: a division-free float program runs at ~51 MHz (level 0), ~40 MHz (level 2); a program that divides at 14 MHz (was 8 before the explicit divider). Nothing short of an ISA change (a registered branch: `JIZ` tests `racc`, one cycle late, and the compiler schedules a NOP or an independent instruction) moves the branch decision off the ALU path — and even then `LDI` addresses would need the same treatment. Recommendation: **document, do not change**. Revisit only if Fmax becomes the limiting resource for a real project; it would be a parameter (`REGISTERED_BRANCH`) with compiler support, never the default. ### 1.5 The ISA lives in four places with no consistency check Opcode numbers are hard-coded in `ASMComp.l` (the `eval_opcode` order), `instr_dec.v` (`opcode == 7'dNN`, 108 of them), the hand-minimised 6-bit `ula_op` table (`instr_dec.v` `b5..b0`) and `core.v`'s `{{NBOPCO-5{1'b0}}, 5'd15}` literals for `JMP`/`JIZ`/`CAL`/`RET` (which silently assume those four opcodes stay below 32 and `NBOPCO >= 5`). Adding an opcode means editing all four by hand; 108 of 128 codes are used. **Professional version:** one ISA table in the repo (`ISA.csv`/`.json`: mnemonic, opcode, ALU op, operand class, stack effect, I/O effect) from which a generator emits the `.l` rules, the `instr_dec.v` compares and `ula_op` table, the `opcodes.c` names and the ISA reference — or, as a first step, a regress check that the four agree. Also lets `NBOPCO` grow to 8 when the table fills. ### 1.6 Undefined behaviours | case | today | proposal | |---|---|---| | integer `DIV`/`MOD` by zero | the array's all-ones quotient, undefined | define (quotient 0 / remainder = dividend, or saturate) in the one `DIV`+`MOD` array (`ula_idiv`) | | `LDI`/`STI` address ≥ `MDATAS` | truncated to `MDATAW` bits, wraps | document; optional overflow flag pin | | `JMP`/`JIZ`/`CAL` target ≥ `MINSTS` | truncated | document (the assembler can already reject it) | | shift by ≥ `NUBITS` | Verilog semantics (0 / sign) | document | | stack over/underflow | silent wrap | 1.3 | | float division by zero | saturates at levels ≥ 1, all-ones quotient at 0 | documented (v5.4) | ### 1.7 Parameter hygiene and lint - ~~Default parameter sets disagree~~ — **done (2026-09-18):** one set everywhere, and it is `cppcomp`'s, because that is the one actually exercised (all 81 C++ tests omit every `#pragma` and run on it, while every C± fixture writes its directives): `NUBITS 32 = NBMANT 23 + NBEXPO 8 + 1`, `NUGAIN 128`, `SDEPTH`/`DDEPTH` 128, `FFTSIZ 3`, `FROUND 0`. It is named in one comment block at the top of `processor.v`; `asmcomp` dropped its 23/16/6 (a second float format nobody reached) and `cmmcomp` its 16/6. - ~~`NUGAIN` is an untyped 32-bit parameter in `processor.v`/`core.v`~~ — **done**, typed `signed [NUBITS-1:0]` in all three. ~~`NBOPCO` is passed to `ula` and unused~~ — **done**, the parameter and the connection are gone. - ~~No invariant guard~~ — **done 2026-10-18 in asmcomp**: `NUGAIN` a power of two always; `NUBITS == NBMANT+NBEXPO+1` and `NBMANT < 2^(NBEXPO-1)` when the program uses float (a float opcode or a float word in memory). The HDL takes any format: nothing outside the float `generate` blocks depends on NBMANT/NBEXPO, and the waveform's float view is generated only when the format fills the word (precision-and-width-review.md 1.3). - Verilator runs with `-Wno-WIDTH -Wno-UNOPTFLAT -Wno-CASEINCOMPLETE …`. A professional flow is lint-clean at `-Wall`; the remaining WIDTH warnings are few and mechanical. - `mem_instr` carries a fake write (`if (wr) mem[addr] <= 0` with `wr = 0`) to coax RAM inference — needs a comment or removal. - `myFIFO` reads combinationally (`always @(*) q = mem[addr_r]`), which keeps it out of block RAM (M10K is synchronous-read only): fine at 128 × 16, wasteful larger. `full` depends combinationally on `wrreq`. (2026-10-09: that `full`, the delayed write and `empty` lost words; fixed, docs/design/myfifo.md. Measured the same day, with Yosys only: the combinational read maps to LUT RAM (MLAB / RAM64M), and a registered read to block RAM from about 1024 words. Corrected 2026-10-27: Quartus puts `myFIFO` in block RAM as written, folding the read address register into the RAM; Vivado uses distributed RAM at 128 x 16. myfifo.md "Memory".) ### 1.8 Verification is golden-only The regress compares 125 self-blessed outputs; the only external reference is `test50` (host IEEE, quantised to 1e-6). There is no per-module testbench, no directed test of the control paths (branches, call/return depth, `LDI`/`STI` addressing, I/O handshake, interrupt), no coverage of `#FROUND 1/2` beyond two fixtures, and no assertions. `simulacao.c` is a trace writer, not a simulator. **The standard answer for a small CPU is cheap here:** an instruction-set simulator (ISS) in C — the ISA is ~110 opcodes with one-cycle semantics — and a random-program generator; run thousands of random programs through the ISS and through Icarus/Verilator and compare traces. That catches control bugs goldens never will, gives users a fast software simulator, and is the natural home for the ULA unit testbench already planned with the 64-bit work. ### 1.9 There is no ISA reference Encoding, per-instruction semantics and timing, the I/O and interrupt contracts, reset behaviour and the parameter list live in code comments, the README and Claude's memory notes. A `docs/isa.md` (generated from the table of 1.5, ideally) is what a new user or a reviewer needs first. *Since done:* [`docs/reference/instructions.md`](../reference/instructions.md), generated from `Compilers/common/isa.tsv` by `Scripts/gen_isa_doc.py`. --- ## 2. What "professional" adds, in order, all opcode-tailored | # | item | changes ISA/timing? | cost | why first | |---|---|---|---|---| | 1 | ISS + random differential test (1.8) | no | tooling, ~1 week | every later change gets verified for free | | 2 | single-source ISA table + consistency check (1.5, 1.9) | no | tooling | removes the four-place edit; produces the reference doc | | 3 | interrupt: one-shot + optional PC save/`RET` + mask (1.1) | adds a return form | ~5 flops, behind `ITRADD` | turns an implicit contract into a real interrupt | | 4 | stacks sized by the compiler + overflow pin (1.3) | no | compilers + 2 flops | removes the user's guess; faults become visible | | 5 | defined behaviour for every undefined case (1.6) | no | tiny | correctness on hardware | | 6 | I/O contract documented + status-port convention (1.2) | no | doc + `hdl.c` | streaming without guessing | | 7 | parameter/lint hygiene, invariant guard (1.7) | no | small | one afternoon | | 8 | valid/ready I/O behind a parameter (1.2 option 3) | cycle counts | ~10 enables | only if streaming peripherals become a goal | | 9 | registered-branch option (1.4) | yes | HDL + compilers | only if Fmax ever matters more than 1-cycle branches | Not on the list, on purpose: pipelining the ALU, caches, multi-cycle operators, a register file. Each would buy Fmax or generality by giving up the one-instruction-one-cycle determinism and the "pay only for what you use" allocation — the two properties that make this core what it is.