# Design notes The record behind each feature: the problem, the options weighed, what was decided and why, what was measured, what is still open. They are written for whoever develops YANC; the user-facing text is the manual ([../index.md](../index.md)). Each note marks what is a fact (read in the code), what was measured and what was deduced, and most end with a section "For the documentation" listing what the manual has to say. ## Rules for `SAPHO/` - **Pay only for what you use.** Every block exists only when an opcode of the program needs it: a `generate` on the opcode parameters, never left to the synthesiser to prune (measured: it does not, precision review 2026-09-15). - **No mux input at don't care (Luciano, 2026-10-16).** Every multiplexer is guided by the opcode parameters: each input is a term or a row inside the `generate` (or guard) of the operation that uses it, and what is not generated is a constant 0. No `x` default, no `x` arm, no `x` on an absent operator's output. An unused `x` input still costs logic (Yosys: +21 % in a float `ula_mux`, pipeln-and-division.md 4.3). | note | about | |---|---| | [cli-v7.1.md](cli-v7.1.md) | the v7.1 command line, the `yanc` driver and the output folder, against v6.0 | | [toma-and-cade.md](toma-and-cade.md) | two SAPHOs passing a value: the protocol, the single-link design (v7.0, superseded in part) | | [toma-and-cade-links.md](toma-and-cade-links.md) | several links per processor: chains, fan-out, fan-in, two clocks | | [myfifo.md](myfifo.md) | `myFIFO` fixed, the two-clock `myDCFIFO` | | [cpp-iostream.md](cpp-iostream.md) | ``, ``, `` for CPPComp on the keyboard and the screen, and the overload rules they needed (v9.1) | | [fround1-subtraction.md](fround1-subtraction.md) | `#FROUND 1`: its subtraction is not the exact truncation the manual promised; the fix tried, its cost and accuracy measured, and why the hardware stays (2026-10-22) | | [vga-text.md](vga-text.md) | `myVGAText`: a VGA text screen written with `toma`, the decisions and what was measured (v9.1) | | [ps2-keyboard.md](ps2-keyboard.md) | `myKeyPS2`: a PS/2 keyboard read with `cade_sync`, the decisions and what was measured (v9.0) | | [ip-protection.md](ip-protection.md) | handing SAPHO to Quartus or Vivado without showing its source: IEEE 1735, vendor schemes, a service (notes, parked until a partnership) | | [burst.md](burst.md) | a whole array through a port, one word per clock, stopping while the FIFO is full (design, not implemented) | | [array-unit.md](array-unit.md) | a dual-port memory for arrays, a controller and a MAC (`DOT`): decisions, a prototype measured (parked 2026-10-26) | | [dirac-expressions.md](dirac-expressions.md) | the Dirac notation as expressions with shapes, computed in loops, and loops with pointers and `RPT`: decisions, the parser, the loops in software measured (step b, 2026-10-30) and a prototype with pointers | | [asm-names.md](asm-names.md) | user names that collide in the assembly | | [unread-variables.md](unread-variables.md) | a variable written and never read leaves the program; `#WAVE` keeps it for the waveform (2026-11-01) | | [pipeln-and-division.md](pipeln-and-division.md) | the slow dividers: the pipeline tried and dropped, the register cuts kept (5 and 4 stages since 2026-10-16, section 4.4) | | [normalisation-survey.md](normalisation-survey.md) | the known ways to normalise a float on an FPGA: eight built, two fitted, none faster; finished, `pnorm` kept | | [fadd-survey.md](fadd-survey.md) | the known ways to align the exponents and add; the add as a separate circuit built, not fitted; finished, `pnorm` kept | | [precision-and-width-review.md](precision-and-width-review.md) | the float and word-width review (2026-09): the evidence behind TODO items 1 to 9 | | [hdl-architecture-audit.md](hdl-architecture-audit.md) | the HDL audit: the evidence behind issues #32 to #35 |