upsilon/GUIDELINES.md

2.3 KiB

Firmware

See also Dan Gisselquist's rules for FPGA development.

  • Use free and open source IP only. IP must be compatible with both the GPL v3.0 and the CERN OHL-v2-S.
  • Stick to Verilog 2005. F4PGA will accept SystemVerilog but yosys sometimes synthesizes it incorrectly.
  • Do not use parameters that are calculated from other parameters (yosys will not parse them correctly). Use macros instead.
  • Only use Verlog macros for basic expression replacement (replacing calculated parameters). For more advanced code generation, use m4 (see base.m4 as an example).
  • Add undefineall at the end of every single module. If you do not, you will get many confusing errors.
  • Do all code and test generation in Makefiles.
  • Simulate every module, even the trivial ones using Verilator. Simulation must be simulatable with open-source software (Verilator is preferred, but Icarus Verilog and similar are fine). Put test code in the same directory as the Verilog module, unless the Verilog module is external.
  • Synthesize and verify large modules independently on hardware using the LiteX SoC generator. Put the generator source code (along with the hardware test driver) in the repository.
  • Write only synthesizable verilog (except for direct test-bench code), even for modules that will not be synthesized.
  • Dump traces using .fst format.
  • Use only one clock.
  • Only transition on the positive edge of the system clock.
  • Do not use asynchronous resets.
  • Don't write Wishbone bus code in Verilog modules. LiteX automatically takes care of connecting modules together and assigning each register a memory location.
  • Keep all Verilog as generic as possible.

Software

  • Use free and open source libraries only. All libraries must be compatible with the GNU GPL v3.0.
  • Do not dynamically allocate memory.
  • Use the SEI CERT C Coding Standard as a guideline.
  • Use the Linux kernel style guide as a guideline (many parts of it are not relevant for this project).
  • Try to offload as much processing as possible to the computer.