diff --git a/GUIDELINES.md b/GUIDELINES.md new file mode 100644 index 0000000..bd74744 --- /dev/null +++ b/GUIDELINES.md @@ -0,0 +1,41 @@ +# Firmware + +See also [Dan Gisselquist][1]'s rules for FPGA development. + +[1]: https://zipcpu.com/blog/2017/08/21/rules-for-newbies.html + +* 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. +* Simulate *every* module, even the trivial ones using Verilator. Do not + write tests in Verilog. 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 test shims, like commands + to dump a trace), 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][2] as a guideline. +* Use the [Linux kernel style guide][3] as a guideline (many parts of it + are not relevant for this project). +* Try to offload as much processing as possible to the computer. + +[2]: https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard +[3]: https://www.kernel.org/doc/Documentation/process/coding-style.