# Design This file fixes the circuits, the timings and the dumps a build must match. The toolchain can vary, as long as the numbers here hold. ## Budget 4096 gates or cells, as counted by the shipped script (the file states the exact Yosys command or the cell library). The default 320 by 240 design must fit. Larger buffers may exceed it and are then out of the cap check, as the file says. ## Goldens `fixtures/demo-frames/` holds frame 0 and frame N. Pixel tolerance: 0 (exact) for a digital dump, or 2 levels if a dither is documented. ## Frames N is 3 (the fourth frame, 0-based), or as in `fixtures/demo-timing.json`. Clock rate and reset cycles are in that file. ## Inputs | Key | Label | Default | Notes | | --- | --- | --- | --- | | `title` | Demo title | A tiny scene | Shown in the first frames, if the design has a font, or only in the README if not. | | `width` | Framebuffer width | 320 | 160, 320 or 640. | | `height` | Framebuffer height | 240 | 120, 240 or 480. | | `audio` | A tiny audio register | off | A documented register dumped by the testbench; no speaker is required. | | `scanline` | A visible scanline effect | on | A documented effect in the framebuffer. | | `sim` | Simulator | verilator | Either must pass the same testbench and goldens, within a documented pixel tolerance if timing differs by a cycle at reset. | ## Acceptance at the defaults A small HDL demo: a 320 × 240 (or documented 160 × 120) framebuffer, a bouncing mark, and a scanline option. The testbench dumps frames. | Quantity | Value | Tolerance | Source | | --- | --- | --- | --- | | Frame size | 320 × 240 | exact | Default; 160 × 120 is accepted if documented | | Frame count in the loop | 60 | 0 | A full cycle of the bounce | | Background colour | #10141c | — | As 24-bit RGB in the dump | | Mark size | 16 × 16 | 0 | The bouncing rectangle | | Scanline darkening | 12% | 2% | When `scanline` is on, odd rows | A Verilog (or VHDL) testbench clocks the design and writes PPM or raw frames. Frame 0, the mid bounce, and frame 59 are compared to goldens. No FPGA board is required. Icarus or Verilator is enough. ## Screenshots These pictures are dumps of a working reference model of the core, in `reference/preview.py`, at the default inputs. They are not drawings of a product that has not been built or simulated. The first picture is the one Spekkr shows on the spec's card. A build may ship its own goldens; those goldens are of that build and do not have to match these frames pixel-for-pixel. | File | What it shows | | --- | --- | | `shots/frame-0.png` | Frame 0 320 × 240, mark in the corner, scanlines on | | `shots/mid-bounce.png` | Mid-bounce the 16 × 16 mark, scanlines on | ## How to verify 1. Run the simulation or the HDL testbench at the defaults, with no physical board. 2. Compare periods, trip points, register dumps or frames to the acceptance table in this file. 3. Corrupt one documented value on purpose and confirm the check fails. 4. A Verilog testbench dumps a framebuffer that matches golden frames. A documented gate-count script stays at or under the cap. Two runs are deterministic. No FPGA, no handheld, and no tapeout are required.