SAPHO/myFIFO.v: three defects, fixed 2026-10-09¶
(The two-clock version, myDCFIFO, is the second half of this note.)
myFIFO replaces the Quartus FIFO IP. It is meant for passing a buffer of
words between SAPHOs (or between a SAPHO and other logic) when word-by-word
toma/cade (docs/design/toma-and-cade.md) is not what the design needs. Users
in this repository: the DTW project
(Compilers/CMMComp/Tests/DTW/TopLevel/top_level.v, fed by its
testbench) and the FIFO project pass (fed by a SAPHO, below).
Suspected while designing toma/cade (docs/design/toma-and-cade.md section 7),
confirmed in simulation and fixed on 2026-10-09 (TODO.md item 22).
The defects (code up to commit 9c3b2d5)¶
reg wr=0; always @ (posedge clk) if (sclr) wr <= 1'b0; else wr <= wrreq;
...
else if (wr & !full) begin mem[addr_w] <= data; addr_w <= addr_w+1'b1; end
...
assign full = (addr_w+1'b1 == addr_r) & wrreq;
assign empty = (addr_w == addr_r) & ~wr;
The word written was the one on
dataone cycle AFTERwrreq. The write usedwr,wrreqdelayed by one cycle. A SAPHO’soutbus holds a value only in the cycleout_enis high (it is the ALU output; the next instruction changes it). Measured with a SAPHO writer (out(0,1); out(0,2); out(0,3); out(0,4);thenout()in loops, 12 values,wrreq = out_en[0],data = out): the bus was right in everywrreqcycle, the FIFO held2 3 4 5 5 6 7 8 11 12 13 14. Values written from a loop came out right, back-to-backout()did not: it depended on the instruction the compiler puts afterOUT.A write into a full FIFO was not refused, and everything stored was lost.
fullwas gated by the currentwrreqwhile the write happened a cycle later withwr, whenwrreqis usually low again: the write went in,addr_wreachedaddr_rand the FIFO said it was empty. Measured (LENGTH 4, three words in, a fourth write): 0 words left instead of1 2 3. A writer looking atfullalso saw 0 on a full FIFO whenever itswrreqwas low.A read in the cycle after a write into an empty FIFO returned a stale word.
emptyfell whenwrrose, before the word was in memory. Measured: wrote 7, read 1 (left over from an earlier case), the 7 lost.
Why the DTW project never showed them (deduced from top_level_tb.v): it
writes one word every two cycles, holds data for both, and never fills
the FIFO.
The fix¶
Write in the wrreq cycle; full, empty and usedw from the pointers
only (the behaviour of the Quartus scfifo it replaces, show-ahead read):
else if (wrreq & !full) begin mem[addr_w] <= data; addr_w <= addr_w+1'b1; end
...
assign full = (addr_w+1'b1 == addr_r);
assign empty = (addr_w == addr_r);
assign usedw = addr_w - addr_r;
Capacity stays LENGTH-1 words (one slot tells full from empty), as before.
Checks (2026-10-09)¶
Scripts/hw/tb_fifo.v, the FIFO alone, three cases (word of thewrreqcycle, write into a full FIFO, read right after a write): before the fix 3 of 3 FAIL, after it 3 of 3 PASS.Regress
FIFOproject pass: the C+- programTests/fifo_wwrites into the FIFO (Tests/FIFO/TopLevel/fifo_tb.v, wires only), the testbench drains it; it must hold1 2 3 4 5 6 7 8 11 12 13 14. The same pass runstb_fifo.v. Both checked on their own before the full regress.DTW project: its six outputs identical to the golden,
output_dtw_1still 459908.Not run yet: the full regress (held by Luciano on 2026-10-09).
Other notes on this module (docs/design/hdl-architecture-audit.md): the read is
combinational on a registered address (q = mem[addr_r]); Quartus folds
that register into the RAM and builds block RAM (section “Memory” below).
SAPHO/myDCFIFO.v: the same FIFO between two clock domains (2026-10-09)¶
Asked by Luciano on 2026-10-09: a FIFO with one clock per SAPHO. Choices he
made: the same read as myFIFO (combinational, show-ahead) and the name
myDCFIFO, with ports in the style of the Quartus dcfifo it can stand in
for. myFIFO stays as it is for one clock (no synchronizers to pay for).
Ports¶
port |
side |
what |
|---|---|---|
|
both |
asynchronous clear; each side leaves it on its own clock (two flip-flops), so hold it for a few cycles of the slower clock |
|
writer |
the word on |
|
writer |
full, as the writer sees it |
|
writer |
words in, as the writer sees them ($clog2(LENGTH)+1 bits: it reaches LENGTH) |
|
reader |
|
|
reader |
the oldest word (show-ahead, combinational read) |
|
reader |
empty / fewer than ALMOST words, as the reader sees them |
|
reader |
words in, as the reader sees them |
Parameters: WORD, LENGTH (a power of two, at least 4), ALMOST. Unlike
myFIFO, it holds LENGTH words, not LENGTH-1 (one more pointer bit tells
full from empty).
How it works¶
Each side keeps its pointer (binary, one bit more than the address) and a Gray-code copy of it, and reads the other side’s Gray pointer through two flip-flops on its own clock. One Gray bit changes per step, so a copy taken mid-change is the old value or the new one, never a mix.
wrfullcompares the writer’s Gray pointer with the reader’s copy (equal but for the two top bits);rdemptycompares the reader’s Gray pointer with the writer’s copy. The copies are 2-3 cycles old, so both flags can stay on a little longer than true, never turn off early: nothing is overwritten, nothing read twice.A word written is visible to the reader 2-3
rdclkcycles later (measured: 2). The word is in memory from thewrreqedge on, before the reader can see the pointer that announces it, so the data needs no synchronizer.
Wiring two SAPHOs (as Tests/FIFO/TopLevel/dcfifo_tb.v does)¶
// writer: out() on port 0
fifo_w W (.clk(clk_a), .rst(rst_a), .out(w_out), .out_en(w_en));
myDCFIFO #(.WORD(16), .LENGTH(16)) D (.aclr(rst),
.wrclk(clk_a), .data(w_out), .wrreq(w_en[0]), .wrfull(full), ...
.rdclk(clk_b), .rdreq(r_req[0]), .rdempty(empty), .q(q), ...);
// reader: in(1) is the empty flag, in(0) takes the oldest word
assign r_in = r_req[1] ? {15'd0, empty} : q;
fifo_r R (.clk(clk_b), .rst(rst_b), .in(r_in), .req_in(r_req), .out(r_out), .out_en(r_en));
The reader program (Tests/FIFO/fifo_r.cmm) waits with
while (in(1)) ...; and then takes the word with x = in(0);. A writer
that may outrun the reader should read wrfull the same way before each
out(); fifo_w writes 12 words into 16 places and does not need to.
Checks (2026-10-09)¶
Scripts/hw/tb_dcfifo.v, the FIFO alone, 20 ns / 27.3 ns clocks both ways round: the word of thewrreqcycle, LENGTH words fit and the next is refused, a word reaches the reader (2rdclkcycles), and 300 words with both sides pausing at random arrive once and in order. 4 of 4 PASS both ways. The testbench was checked against two broken copies: one that never says full (2 of 4 FAIL, one of them a stuck stream caught by the testbench’s time limit) and one that stores the next cycle’s word (4 of 4 FAIL).Regress
FIFOpass, second part: the SAPHO writerfifo_wand the SAPHO readerfifo_ron 20 ns and 27.3 ns, writer faster and reader faster; both readers put out1 2 3 4 5 6 7 8 11 12 13 14. The pass also runstb_dcfifo.vboth ways. Run on its own; the full regress is owed.Yosys synthesizes it; the control is 66 flip-flops (4 of them the clear synchronizers). Where the memory goes: section “Memory” below. (The first note here said “2048 flip-flops”: that was Yosys’ generic
synth, which maps no memory to any RAM; corrected the same day.)Verilator lint (
-Wall): onlyPROCASSINIT(registers with an initial value and a reset, the style of the rest of SAPHO/);processorwithTOM,CADandLINKAS = 1lints clean (2026-10-09;LINKASis gone since 2026-10-11, the links are synchronized by default).What simulation cannot show: metastability. The crossing is safe by construction (Gray pointers through two flip-flops), but on the board Quartus needs constraints on the two Gray pointer crossings: a
set_max_delay(data path only) of about one period of the destination clock, so the Gray bits arrive close together, or theset_false_path+ skew constraint the Inteldcfifouses. The exact.sdclines are not written yet; to be done with the board check of the links (docs/design/toma-and-cade-links.md section 10).
Memory: RAM as written, no registered read needed¶
Correction (2026-10-27). The vendor tools build memory from both FIFOs
as they are, so the registered read below (RAMBLK) is not needed and was
dropped. In the warning survey of 2026-10-21, with myFIFO and myDCFIFO
at 128 x 16:
Quartus 24.1, Cyclone V 5CSEMA5F31C6: an
altsyncraminferred for each, “Total block memory bits: 4,096” (2 x 2048), so block RAM. FormyFIFOit warns that it added pass-through logic for a read and a write on one address in one cycle (issue #8);myDCFIFOgets the usual dual-clock warning.Vivado 2025.2, Zynq-7010: distributed RAM,
RAM64Mx 12 each, the usual choice for a RAM this small.
The read address is a register, and Quartus absorbs it into the RAM’s input register, which Yosys’ mapper did not do. The measurements below are Yosys only and say nothing about the vendor tools; a FIFO of 1024 words was not run in Quartus or Vivado.
What follows is the note of 2026-10-09, kept as written.
Asked by Luciano on 2026-10-09 (“can it never become memory?”). It does become RAM, just not block RAM. Measured with Yosys 0.56, FPGA mapping, WORD 16 (Quartus and Vivado not run: they are the reference):
FIFO |
LENGTH |
read |
ZYBO ( |
Cyclone V ( |
|---|---|---|---|---|
|
128 |
combinational (today) |
12 |
64 |
|
128 |
combinational (today) |
12 |
64 |
|
128 |
registered (variant) |
12 |
64 |
|
1024 |
combinational (today) |
96 |
512 |
|
1024 |
registered (variant) |
1 |
512 |
Block RAM (M10K on the Cyclone V, RAMB on the ZYBO) reads synchronously: a combinational read can only be LUT RAM. That is the real limit, not “never memory”.
The registered read that keeps the show-ahead behaviour: read every edge with the address of the NEXT pointer, so after each edge
qis the word at the read pointer:reg [WORD-1:0] q_r = 0; always @ (posedge rdclk) q_r <= mem[rbin_n[A-1:0]]; assign q = q_r;
In
myDCFIFOthis costs nothing in behaviour: a word written is announced to the reader 2rdclkcycles later, and the read is redone at every edge, soqis fresh beforerdemptyfalls. The variant passedtb_dcfifo.v4 of 4 both ways (scratch, not committed).In
myFIFO(one clock) it needs one more piece: a word written into an empty FIFO at edge t is readable right after t, but the registered read at t took the old content (read-before-write). Either forwarddatawhen the write goes to the address being read, or letemptyfall one cycle later. Not tried.Small FIFOs stay in LUT RAM anyway: at 128 words the tools keep LUT RAM even with the registered read (above). Block RAM pays from about 1024 words.
The Cyclone V column is Yosys’ mapper, which put everything in MLABs; whether Quartus puts the registered variant in M10K is not known yet (
quartus_mapon the variant answers it).
Not decided: whether to adopt the registered read (as a parameter, or for
myDCFIFO only). It changes no behaviour in myDCFIFO; in myFIFO it
needs the bypass above.
Timing constraints the board will need (both FIFOs and the links)¶
Static timing sees paths between the two clocks that the logic makes safe
but the analyser cannot know about. Each needs a constraint (exact .sdc
lines to be written and checked on the board):
myDCFIFO: the Gray pointers into the other side’s first synchronizer stage (rg1,wg1): a data-path-onlyset_max_delayof about one destination period, so the bits arrive close together;myDCFIFO: the read path from the memory (written onwrclk) throughqinto the reader SAPHO’s input register (onrdclk): safe because a word is announced 2 cycles after it is written;set_false_pathor a relaxedset_max_delay. With the registered read this path becomes a block RAM dual-clock port, which the tools handle themselves;the
toma/cadelinks between two clocks: written and checked in Quartus and Vivado (set_clock_groups -asynchronous, docs/design/toma-and-cade-links.md section 10); the board run is still to come.
For the documentation (issue #40)¶
The user-facing text says: when the two SAPHOs run on different clocks use
myDCFIFO (ports in the table above); wire the writer’s out_en bit to
wrreq and out to data, give the reader the empty flag on one input
port and q on another, with rdreq from that port’s req_in; hold
aclr for a few cycles of the slower clock; a word takes 2-3 reader cycles
to show up; capacity is LENGTH words; the Quartus constraints.
For the documentation (issue #40)¶
The user-facing text says: wire wrreq to the writer’s out_en bit and
data to its out; the word is taken in that cycle; q shows the oldest
word and rdreq moves to the next; full and empty are valid at any
time; capacity is LENGTH-1 words.