BaseJump STL: a hardware library of SystemVerilog building blocks

A library built out of tapeouts

BaseJump STL is described as a comprehensive hardware library for SystemVerilog that seeks to contain all of the commonly used hardware primitives. The phrase seeks to contain is doing work there, since the scope of what a hardware team rewrites for every chip is large.

What makes the library unusual is where it comes from. The README points at the HammerBlade manycore repository, the BlackParrot repository and the BaseJump STL testing repository for example usage, which means these are not toy modules written to be read. They are the parts that shipped in real processors, and the standard library of a research silicon programme that has taped out more than once.

The documentation situation is the weak point. The description of the design and usage is a paper, the DAC 2018 camera ready PDF under docs/, and the conventions are described in the BSG SystemVerilog Style Guide, a separate Google document. There is no API reference, no tutorial and no per-module documentation beyond the source comments. That is normal for a hardware library of this kind, where the design document plus the code plus the style guide is the documentation, but it means a new user is expected to read a lot of SystemVerilog before writing anything.

The homepage is bjump.org and the licence is a custom one that GitHub cannot classify, so the LICENSE file is the reference for terms.

The directories map to a chip's block inventory

The top level of the repository is effectively a parts list for a processor, and reading the directory names tells you what the library thinks a chip needs.

bsg_misc holds the digital building blocks, counters, reset timers and gray to binary coders among them, and it also holds the file that everything else depends on: bsg_misc/bsg_defines.sv contains many macros used by BaseJump STL, and the README is explicit that you must make sure it is in your include path. That is a small operational detail that will cost you an afternoon if you miss it.

bsg_dataflow is for standalone modules involved in data plumbing, with two-element FIFOs, FIFO to FIFO transfer engines, sbox units, compare and swap, and array pack and unpack. bsg_async is for asynchronous building blocks, the bsg_async_fifo, synchronizers and credit counters, and here the README adds a note that for tapeouts you need to pay attention to the physical design and timing constraints for these components, which is a reminder that an asynchronous primitive is only half the design.

bsg_mem provides portable SRAM and RF interfaces, bsg_noc holds network on chip implementations, bsg_cache a reusable cache implementation, and bsg_link a high speed off-chip communication link over LVCMOS I/Os that can hit 1.2 Gbps per pin to an FPGA, described as a unidirectional off-chip high-speed source synchronous communication interface and also used as an FPGA bridge. bsg_clk_gen is an open source portable clock generator built from standard cells, bsg_tag a high speed SPI-like interface for configuration state, and bsg_dmc an LPDDR1 DRAM controller and PHY that requires advanced knowledge to tape out and is still experimental.

The repository also holds directories the contents list does not describe individually: bsg_axi, bsg_comm_link, bsg_fpu, bsg_legacy, bsg_math, bsg_mesosync_io and distrib. A library this size always accumulates more than the summary admits.

Experimental and hard are warnings, not categories

Two directories in the top level are labelled in a way that deserves attention before you copy anything out of them.

experimental is described as containing meaty blocks that are potentially useful but may require additional verification, with the note that with further iteration they may be promoted out of experimental. The hard directory mirrors the other directories and contains replacement files for specific process technologies.

The first of those is a candid statement that the code is not finished. A block that may require additional verification is a block whose timing closure, metastability behaviour or power behaviour you should not assume. The second is subtler and more dangerous for someone evaluating the library. A replacement file for a specific process technology is a cell that has been characterised for one foundry's standard cell library, and dropping it into a design built for a different process is not a portability win, it is a tapeout risk. Nothing in the summary of the README tells you which process each replacement targets, so that is something you have to learn from the source.

The testing directory mirrors the other directories with tests, which is the most reassuring signal in the whole list. A hardware library where every directory has a mirrored test suite is a library that has been kept honest. It also means the test structure is the fastest way to understand the intended usage of any module, since the tests show the module being instantiated and driven.

The bsg_dmc entry is the clearest statement of maturity in the README, and it is worth reading as a template for the rest: an LPDDR1 DRAM controller and PHY that requires advanced knowledge to tape out, and is still experimental. It is in the library, and the library is honest that using it is a specialised project rather than a drop-in.

The style guide is the real interface

The README asks readers to see the BSG SystemVerilog Style Guide, which describes many of the conventions used in the library, including the variants of the valid and ready handshaking protocols.

That clause is the important one. A handshake protocol has several legitimate variants, and if two modules in your design use different variants the failure mode is subtle: a valid signal that arrives when the consumer is not ready, or a transfer that stalls in a way neither module expects. When a library provides a family of modules that are meant to be interchanged, the handshake convention is the contract that makes them interchangeable, and it has to be shared across every module and every team using them.

So the style guide is not documentation polish. It is part of the interface of the library, in the same way that a header file describing a calling convention is part of an API. A team adopting BaseJump STL inherits the variants of the valid and ready protocols, and the way to get that right is to follow the guide rather than to guess from the code.

The paper covers the design and usage, which is where the higher-level questions live: how the modules are meant to be parameterised, what the intended composition patterns are, and which parts of the library are load-bearing for a particular architecture. For a library whose example usage is found in the HammerBlade manycore repository and the BlackParrot repository, that paper is the closest thing to a design rationale document, and it is the first thing to read before the source.

For people coming from a high-level HDL world, the other adjustment is that this is a hardware library rather than a software one. The units are cycles and clock domains, the resources are area and timing, and the failure modes are physical. That is why the tapeout caveats appear in the README at all, and why a FIFO in this library is not the same object as a queue in a standard library.

How to get the library and where to look first

There is no installation command, and the README does not describe a package manager workflow, a fetch script or a repository to clone from with a specific branch. What it does give you is the paper for the design and usage, the style guide for the conventions, the public homepage at bjump.org, and pointers to three example repositories.

For a first pass, the examples are the right entry point. The HammerBlade manycore repository and the BlackParrot repository show the modules in a context where they were designed to work, and the testing directory inside the library itself shows each block with its testbench. Reading a test tells you how a module is instantiated, which parameters it takes and what behaviour is expected, which is usually faster than reading the module itself.

The include path detail deserves one more mention because it is the kind of thing that stops a build. bsg_misc/bsg_defines.sv holds the macros used across the library, and it has to be reachable by the compiler. If you add the library as a git submodule, which the presence of a .gitmodules file in the top level suggests is the expected arrangement, the include path is a matter of pointing your build at the right directory, and the README tells you the requirement without telling you the flag.

The licence is a custom one that GitHub cannot classify, so treat the LICENSE file as the authority rather than assuming a standard open source grant. The repository has no GitHub releases, so there is no tagged version to pin either, and the default branch is master. The last push to the repository was on 2026-10-12 and the repository is not archived, so the code is being changed even though nothing is versioned in the release sense.

Where a hardware primitive library is the wrong answer

The first limitation is that this is a tapeout library, and the audience it serves is someone building silicon. If your project is an FPGA design with vendor IP and an existing vendor FIFO, a SystemVerilog library written for a standard cell flow and for research manycores adds process assumptions, timing conventions and verification obligations that you have no use for.

The second limitation is documentation. The design and usage are described in a paper, the conventions in a style guide, and everything else has to be read out of the source and the tests. That is workable when you intend to read thousands of lines anyway, because you are going to integrate these modules rather than call them. It is not workable if you want to evaluate a single module in an afternoon.

The third limitation is the absence of a stability guarantee, and it follows from the release situation. There are no GitHub releases, the default branch is master, and the last push was on 2026-10-12, which means you take master as it is on the day you clone it. For a library used in silicon, that is a real operational difference from a versioned dependency, and a team that wants a reproducible build needs to pin a commit and own the update process.

The real alternatives are not other SystemVerilog libraries so much as other ways to get primitives. One is a vendor's design kit, which comes with verified IP and a support contract and covers the same FIFOs, arbiters and memories, at the price of a licence and a dependency on the vendor's flow. The other is a smaller open collection, such as the utility libraries that accompany particular HDL toolchains, which are less ambitious in scope but also less demanding in verification and documentation.

The difference in approach is what decides it. BaseJump STL offers depth that most alternatives do not: a reusable cache, a network on chip, an LPDDR1 controller and PHY, a portable clock generator and a high speed off-chip link, all sharing one set of handshake conventions and one testing discipline. If you are building a processor and you have to decide what to write yourself, that coherence is worth a lot. If you need one well-characterised FIFO, it is much more than you need, and the vendor's is better characterised than anything in a research library.

Editorial conclusion

Adopt BaseJump STL if you are building a SystemVerilog chip and want the FIFOs, caches and NoCs that the BlackParrot and HammerBlade teams have already hardened, and if you can live with a library whose documentation is a paper and a style guide rather than a manual. Do not adopt it for a pure FPGA project, and do not adopt the experimental or hard directories without reading what they contain, since the README describes them as potentially useful blocks that may require additional verification and as replacement files for specific process technologies. Before you start, read the BSG SystemVerilog Style Guide, because the valid and ready handshake conventions it defines are what make the modules interchangeable, and check bsg_misc/bsg_defines.sv, which holds the macros the rest of the library depends on and has to be on your include path.

Frequently asked questions

Official sources

1. bespoke-silicon-group/basejump_stl on GitHub
2. Issues
3. Project website
4. README