CourseTron synchronous FIFO practice — 17 November 2026

Purpose: practise a precise single-clock FIFO contract and tests independent of
the RTL pointer implementation. This is not a hardware-qualified FIFO IP core.

Run:
  python3 test_fifo.py
  node test_model.mjs

Prerequisites: Python 3, Icarus Verilog (iverilog and vvp on PATH).
Node.js is needed only for the optional browser-model comparison.
Run the Python check first; the JavaScript check uses its generated vectors.
Tests write a test-output directory and refresh test-results.json locally.

Open index.html through a local HTTP server for the interactive demonstration:
  python3 -m http.server 8000 --bind 127.0.0.1
Then visit http://127.0.0.1:8000/ . Links beginning with / refer to coursetron.com.

Contract:
- Positive clock edge; active-high synchronous reset overrides requests.
- Read and write acceptance uses pre-edge occupancy.
- No read bypass at empty and no write replacement at full.
- rd_valid pulses for an accepted read; rd_data holds otherwise.
- DEPTH and WIDTH must both be positive integers. Tested depths: 1,2,3,4,8.
- Storage is not cleared by reset. Occupancy and pointers prevent old data from
  being returned until rewritten and legitimately read.

Evidence:
- 10 parameter combinations; 13,688 vectors.
- Every occupancy/reset/read/write combination, seeded random sequences, drain.
- Three intentionally faulty RTL variants fail comparisons.
- Browser queue model matches 1,366 reference vectors at depth 4, width 8.
- No synthesis, static timing, CDC, power, hardware or silicon validation claimed.

The browser exercise uses a logical software queue. The RTL uses memory and
pointers. Their matching observable behaviour is checked; neither is presented
as a formal proof for arbitrary parameters or all possible input sequences.

Official simulator documentation:
https://steveicarus.github.io/iverilog/usage/command_line_flags.html

MIT licence: see LICENSE.txt.
