Skip to content

Best practices for sharing gateware

The Open Hardware Association (OSHWA) has released an excellent set of best practices; please read this first. It focuses on FPGA design, but most recommendations will apply also to ASIC design. The OSHWA guidelines will help you in particular not to forget that sharing the HDL design files is the bare minimum. There are many other files — such as testbenches, scripts and documentation — that you need to share if you want users to be able to use and improve your work efficiently.

In terms of using a collaboration platform (GitHub, GitLab) to share your designs with the world, gateware is very similar to software. In particular:

  • Your design is mostly based on HDL files, which are text-based and therefore Git-friendly. So please use the Git repository in your project to host them.
  • A README.md file in your top-most directory should explain the basics of your project, provide instructions on how to validate/simulate, guidelines on how to contribute to the project, and the licensing terms.
  • Continuous Integration and Continuous Delivery (CI/CD) are an integral part of best practices in open-source HDL design. You can see here how to set them up at CERN for gateware projects.

Among the things you may want to include in your CI pipelines is linting, to check compliance with coding guidelines. It is important to consistently stick to the guidelines, so your work can easily be understood by your colleagues and your future self. There are many guidelines out there, all with their pros and cons. Here are the VHDL guidelines and linting tool used in BE-CEM-EDL, as an example.

Finally, here are some tools which can help you manage your HDL projects more efficiently:

  • HDLMake, a tool for generating multi-purpose (simulation, synthesis, project files) makefiles for HDL projects.
  • Hog (HDL on git), a set of Tcl/Shell scripts accompanied by a methodology suitable for managing HDL designs in a Git repository.
  • FuseSoC, a package manager and a set of build tools for HDL code.
  • Cheby, a tool which takes a text-based description of the memory map for your project and generates HDL, drivers and documentation from it.