upsilon/GUIDELINES.md

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.