# wb2axip and the case for bus bridges that never stall > wb2axip is a collection of Verilog bus bridges and interconnect components for FPGA work, built so that multiple transactions can be in flight at once and formally verified with SymbiYosys. Its value is the verification, and its cost is that adopting it means buying a bus model you have to learn. **ZipCPU/wb2axip** — Bus bridges and other odds and ends - Repository: https://github.com/ZipCPU/wb2axip - Stars: 713 · Forks: 128 - Language: Verilog - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/zipcpu-wb2axip ## One transaction per clock is the design target, not a nice to have The opening claim is the whole thesis, and it is stated in the project guide. The bus components and bridges in this repository are unique in that they are all designed for 100% throughput with no throughput overhead, and the vast majority of the cores within have all been formally verified. The mechanism is that where the protocol allows it, multiple transactions may be in flight at a time so that protocol handling does not stall the bus. That applies to AXI4, to AXI-lite and to pipelined Wishbone B4. The comparison with other implementations is what makes this concrete. Most AXI4 implementations process a single burst transaction packet at a time and require some overhead to make this happen. The Xilinx AXI-lite implementations, both interconnect and slave implementations, only handle one request at a time. Other buses, such as Wishbone Classic, AHB or APB, will only ever process one transaction word at a time. The author is careful about the caveat: if you are coming from AXI4, AXI-lite or one of the other implementations to the components supported here, you should expect a throughput increase, given of course that you have a bus master capable of issuing multiple requests at a time. The performance difference depends on what you had before, and the numbers given range from a 16x speedup when toggling an I/O, to a 4x speedup comparing one of these slaves against a Xilinx block RAM memory controller when processing single beat transactions, to as insignificant as a 2% improvement from using the AXI4 memory-mapped to slave converters. The author notes he has not yet run that last test himself, and says the improvement extends to the crossbar implementations in the repository as well, so it may only increase when using those crossbars. ## The Wishbone to AXI4 bridge is the reason the repository exists The project was built out of necessity, around a pipelined Wishbone to AXI4 bridge designed to provide a conversion from a simpler pipelined Wishbone bus to an AXI4 bus for the purposes of driving memory transactions through Xilinx's SDRAM controllers. The width mismatch is the specific problem. The bridge is designed to connect a Wishbone bus to an AXI bus which may be wider, such as from a 32-bit Wishbone bus to a 128-bit AXI bus. If the Memory Interface Generator DDR3 controller is running at a 4:1 clock rate for memory clocks to AXI system clocks, then the translator should be able to accomplish one transaction per clock at a sustained pipelined rate, neglecting any stalls due to refresh cycles. That last clause is the one an engineer should hold on to. A pipelined rate of one transaction per clock is the ceiling, and refresh cycles are exactly the kind of thing that pushes a memory controller below its ceiling. The WB to AXI-lite bridge was added after the initial build of the original core, and it is also a pipelined bridge that has been formally verified. The repository layout is small and matches the description. At the top level there is a Makefile, a project description file, a .gitignore, an rtl/ directory for the Verilog sources, a bench/ directory for the formal testbenches and documentation in doc/, plus a wb2axip.core file for the Vivado project. ## AXI to Wishbone bridges, and how deeply each one is proven While not the original purpose of the project, the repository now has both an AXI-lite to Wishbone bridge and an AXI to Wishbone bridge. Each comes in two parts, a read half and a write half, and those halves can be used either independently, generating separate inputs to a Wishbone crossbar, or combined through a Wishbone arbiter. The verification status differs between them, and this is the detail to read carefully before choosing. The AXI-lite to Wishbone bridge has been both formally verified and FPGA proven, and that includes both the write half and the read half. The author adds that, given the reluctance of the major vendors to support high speed AXI-lite interfaces, you are unlikely to find this kind of performance elsewhere. The AXI to Wishbone bridge is a different story. Its write and read components have only been formally verified through about a dozen steps. The proof is deep enough to verify most of the bus interactions, but not nearly deep enough to verify any issues associated with internal FIFO overflows. That is a real limitation stated plainly, and it is the kind of thing that turns into a rare, hard-to-reproduce bug on hardware. A FIFO overflow that the proof does not reach is a FIFO overflow you find in the lab. So within the same repository, one bridge is proven and demonstrated on hardware, and the other is partially proven. The file names follow the same pattern throughout, with a sp suffix marking the pipelined variants and separate read and write half files. ## Building the repository is one master makefile There is no install step here, because this is gateware rather than software you link against. What there is is a master makefile at the root of the repository that tries to build all targets within the project, mostly by directing subdirectory makes. The default target is the whole thing, and it splits into the two halves of the project: ```make all: archive rtl formal ``` The archive target is what produces a dated tarball of the sources, with the date coming from a shell call to date at build time, and the rtl and formal targets are the ones that matter to a hardware engineer, since the first builds the Verilog and the second runs the proofs. A commented-out line shows the full set of targets, verilated, sw, bench and bit, for anyone who wants the simulation and bitstream steps as well. The file lists what goes into the archive by finding things rather than by naming them, which is the practical detail: ```make BENCH := `find bench -name Makefile` `find bench -name "*.cpp"` `find bench -name "*.h"` RTL := `find rtl -name "*.v"` `find rtl -name Makefile` NOTES := `find . -name "*.txt"` `find . -name "*.html"` YYMMDD:=`date +%Y%m%d` ``` So the rtl directory is where the Verilog lives, bench is where the formal testbenches and the C++ simulation harness live, and the documentation notes are collected by extension rather than by directory. The makefile header also carries the copyright and licence notice, with the project identified as WB2AXIPSP, bus bridges and other odds and ends, created by Dan Gisselquist, Ph.D. of Gisselquist Technology, LLC, and the copyright line reading 2015-2025. ## Formal property files are the deliverable that matters most The formal verification section describes what is actually in the repository, and it is the part that makes this more than a collection of Verilog files. The project contains formal specifications for an Avalon bus, for Wishbone classic, for pipelined Wishbone, for APB, and for an AXI-lite bus. There is also a partial formal property specification for a full AXI bus, but the one in the master branch is incomplete, and the complete set of AXI properties is maintained elsewhere. These properties, and the cores they have been used to verify, have all been tested and verified using SymbiYosys. The Wishbone classic and pipelined bridges come with a set of formal properties for Wishbone classic, for slaves and for masters, and both of the Wishbone to Wishbone bridges have passed their formal tests. There is also a small instructive episode about the Xilinx cores. The formal properties were first tested on a pair of Xilinx AXI demonstration cores, and those cores failed formal verification. The author has written the results up on his blog, with separate posts for AXI-lite and for full AXI, and the Xilinx cores are referenced in the bench directory for anyone who wants to repeat or examine the proofs. That is a striking thing to have in a repository: a vendor demonstration core that fails formal verification, documented rather than hidden. It tells you the property files are strict enough to catch a real problem, which is the condition under which a passing proof means something. ## AXI3 bridging is the work in progress The repository is also picking up a new family of bridges, and this one is explicitly unfinished. The author is in the process of adding AXI3 bridges, which will be necessary for working with the Zynq chips and others that are still using AXI3. While the work is ongoing, there is an AXI3 to AXI4 bridge available that is undergoing testing. The bridge supports two algorithms for W* reordering and should be suitable for most applications. Two things are worth pulling out. First, the motivation is specific: AXI3 is what the Zynq chips speak, and a design that has to talk to a Zynq processor over AXI3 needs somewhere to go. Second, the reordering algorithms are the interesting design detail, since write data reordering is where AXI implementations differ, and offering two of them means the choice is a parameter rather than a fork. This is the section to read when you are deciding how much of the repository is production-ready. The Wishbone to AXI bridges are described as verified and one of them as FPGA proven, while this one is described as under testing. ## Firewalls, the licence question and who maintains this The final section of the project documentation introduces a component type that is worth understanding on its own, because it explains part of what these cores are for. A firewall is a guarantor. Given an interface of which only one side is trusted, the firewall guarantees that the other side can trust the interface. That is a formal property rather than a marketing phrase, and it means a module placed between a trusted master and an untrusted peripheral is what makes the untrusted side safe to talk to. The licence is where the documentation is thin, and it needs care. The recorded licence identifier is unknown, and the topics list includes gplv3. The Makefile at the root carries the full Apache License 2.0 header, with the copyright line reading 2015-2025, Gisselquist Technology, LLC, and states that the WB2AXIP project contains free software and gateware licensed under the Apache License, Version 2.0. So the project files say Apache 2.0 and the recorded licence identifier is not classified at all. If you are building something commercial with these cores, that discrepancy is worth resolving with the author rather than assuming, because a file-level copyleft in a gateware file and a permissive licence have different consequences depending on how you combine the file with the rest of your design. The author is Dan Gisselquist, Ph.D., of Gisselquist Technology, and the Makefile identifies the project as WB2AXIPSP, bus bridges and other odds and ends. The last push to the repository was on 2026-09-11, and the project publishes no GitHub releases, so the master branch is the only version reference. ## Conclusion wb2axip suits a hardware engineer bridging a Wishbone core to an Xilinx memory controller, or anyone who needs an AXI4 slave that keeps more than one transaction in flight and wants the proof that it does, because the formal property files are in the repository and can be re-run. It does not suit a team that wants a vendor IP core with a support contract, since these are gateware sources from an individual and no licence identifier is recorded for the project. Before you adopt a component from it, read the verification section for that bridge, because the depth of proof differs sharply between them, and note that the AXI3 to AXI4 bridge is described as still under testing while the last push was on 2026-09-11. ## FAQ ### What is wb2axip? It is a repository of Verilog bus interconnects, bridges and related components for FPGA work, including Wishbone to AXI4 and AXI-lite bridges, AXI to Wishbone bridges, Wishbone pipelined to classic bridges, an AXI3 to AXI4 bridge, crossbars and firewalls. They are designed for 100% throughput and are largely formally verified. ### How do I use the Wishbone to AXI4 bridge in wb2axip? The bridge connects a pipelined Wishbone bus to a wider AXI bus, for example from 32-bit Wishbone to 128-bit AXI, and is meant for driving memory transactions through Xilinx SDRAM controllers. It can sustain one transaction per clock at a pipelined rate, neglecting stalls such as refresh cycles. ### Which wb2axip components are formally verified? The formal specifications in the repository cover Avalon, Wishbone classic, pipelined Wishbone, APB and AXI-lite buses, with a partial specification for full AXI in the master branch. The AXI-lite to Wishbone bridge is both formally verified and FPGA proven, while the AXI to Wishbone bridge has been proven only about a dozen steps deep, not far enough to cover internal FIFO overflows. ### What tool is used to verify the wb2axip designs? SymbiYosys. The properties and the cores they have been used to verify have all been tested and verified with it, and the repository even contains a pair of Xilinx AXI demonstration cores that failed formal verification, with the results written up by the author for anyone who wants to repeat the proofs. ### What licence applies to the wb2axip gateware? The recorded licence identifier is not classified, and the topics include gplv3, but the Makefile at the root carries an Apache License 2.0 header stating that the project contains free software and gateware licensed under that licence, with copyright 2015-2025, Gisselquist Technology, LLC. Confirm the terms with the author before combining the files into a design you redistribute. ## Sources - [Issues](https://github.com/ZipCPU/wb2axip/issues) - [README](https://github.com/ZipCPU/wb2axip/blob/master/README.md) - [ZipCPU/wb2axip on GitHub](https://github.com/ZipCPU/wb2axip) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zipcpu-wb2axip