libfpga v0.1.0: a standard library for FPGAs, verified in public

Every FPGA team maintains a private folder of "the good blocks" — the FIFO that's been trusted for years, the UART someone wrote three jobs ago, the synchronizer with the war story attached. Those folders are where productivity lives, and almost none of them are public, tested in the open, or documented past a signal list.

Today we shipped ours, properly: libfpga v0.1.0 — 14 vendor-neutral building blocks, MIT licensed, every one held to a CI-enforced quality bar. It's the library this site was named for.

What's in the box

• CDC: 2-flop bit synchronizer, toggle-based pulse synchronizer, reset synchronizer (async assert, sync deassert) — the primitives from our CDC generator, now versioned and tested.
• FIFOs: a synchronous show-ahead FIFO with a count port, and the headliner — a dual-clock async FIFO with gray-coded pointers in the canonical Cummings form, the block everyone needs and nobody should copy from a random forum post.
• Streams: a full-throughput skid buffer (the standard fix for ready-path timing) and a round-robin arbiter.
• Serial: UART TX and RX (mid-bit sampling, start-bit glitch rejection) and an SPI master — mode 0, full duplex.
• Math & integrity: parallel CRC for any polynomial, a maximal-length LFSR with the XAPP052 taps built in, and Gray codecs.
• Bus: an AXI4-Lite bridge exposing a simple register interface — the natural companion to our register-map generator.

Plain Verilog-2005 throughout: the same source synthesizes on Vivado, Quartus, and the open Yosys flow. Every module's header states what it is, when to use it, and its gotchas — the comment is part of the module.

The quality bar (and what it caught this week)

Nothing merges without passing three gates, run by CI on a fully open toolchain and reproducible locally with one make:

1. A self-checking testbench (Icarus) — scoreboards with unrelated clock ratios for the CDC paths, golden check values for the math (the CRC proves itself against CCITT-FALSE 0x29B1 on every run).
2. Verilator -Wall, clean — no waivers.
3. A Yosys synthesis check with LUT/FF stats published per module in the README, so "lightweight" is a number, not an adjective.

Here's the part worth sharing honestly: building v0.1.0, that gauntlet caught a combinational feedback loop in the first cut of the async FIFO's full flag, rejected a flag-comparison shortcut that would have shortchanged synchronizer depth on real silicon, and exposed several testbench races — including two cases where the testbench's expectations were wrong and the hardware was right. Every catch happened before the code was public. That's precisely the experience we want the library to sell: blocks that arrived through the gauntlet, not around it.

Using it

Every module is self-contained — copy the file, instantiate, go:

lfpga_fifo_async #(.WIDTH(32), .DEPTH(64)) u_cdc_fifo (
    .wclk(clk_a), .wrst(rst_a), .wr_en(push), .wr_data(din), .full(full),
    .rclk(clk_b), .rrst(rst_b), .rd_en(pop),  .rd_data(dout), .empty(empty)
);

Size the depth with the FIFO calculator, constrain the crossings as each file's header describes, and paste any module into the playground to watch it simulate before you commit to it.

What's next

v0.2 is the release we've been building toward: the neural micro-kit — INT8 MAC arrays, activation blocks, weight loaders, and a complete quantized MLP inference core with a NumPy quantizer. If you've read why FPGAs are shaped like neural networks, v0.2 is that article becoming code you can clone.

Want a module prioritized? Open an issue or use the request box — and if the library is useful to you, a star on GitHub genuinely helps other engineers find it. ⭐