======= # OH! Open hardware for Chips and FPGAs 1. Make it work 2. Make it simpler 3. Make it modular ![alt tag](common/docs/lego.jpg) ## CONTENT | FOLDER | STATUS| DESCRIPTION | |--------------------------|-------|--------------------------------------| |[accelerator](accelerator)| FPGA | Accelerator tutorial | |[axi](axi) | FPGA | AXI master and slave interfaces | |[c2c](c2c) | HH | Protocol agnostic chip to chip link | |[chip](chip) | SI | Chip design reference flow | |[common](common) | SI | Library of basic components | |[elink](elink) | SI | Point to point LVDS link | |[emailbox](emailbox) | FPGA | Mailbox with interrupt output | |[emesh](emesh) | SI | Emesh interface utility circuits | |[emmu](emmu) | FPGA | Memory transaction translation unit | |[etrace](etrace) | HH | Logic Analyzer | |[gpio](gpio) | HH | General Purpose IO | |[pic](pic) | SI | Programmable interrupt controller | |[parallella](parallella) | FPGA | Parallella FPGA logic | |[risc-v](risc-v) | HH | RISC-V implementation | |[spi](spi) | HH | SPI master/slave | |[verilog](verilog) | HH | Verilog referenca material | |[xilibs](xilibs) | FPGA | Xilinx simulation models | **NOTES:** * "SI"= Silicon validated * "FPGA" = FPGA validated * "HH" = Hard hat area (work in progress) ## LICENSE The OH! repository source code is licensed under the MIT license unless otherwise specified. See [LICENSE](LICENSE) for MIT copyright terms. Design specific licenses can be found in the folder root (eg: aes/LICENSE) ## CONTRIBUTING Instructions for contributing can be found [HERE](CONTRIBUTING.md). ## REFERENCES MANUALS * [Verilog Reference](verilog/verilog_reference.md) * [Verilog Coding Methodology](https://github.com/parallella/oh/blob/master/CODING-METHODOLOGY.md) * [Glossary](chip/docs/glossary.md) * [Chip constants](chip/docs/constants.md) ## RECOMMENDED TOOLS * [Verilator Simulator](http://www.veripool.org/wiki/verilator) * [Emacs Verilog Mode](http://www.veripool.org/wiki/verilog-mode) * [Icarus Simulator](http://iverilog.icarus.com) * [GTKWave](http://gtkwave.sourceforge.net) * [Wavedrom](http://wavedrom.com/editor.html) * [FuseSoC](https://github.com/olofk/fusesoc) # VERILOG CODING METHODOLOGY * Max 80 chars per line * One input/output statement per line * Only single line // comments, no /*..*/ * Use vector sizes in every statement, ie "assign a[7:0] = myvec[7:0];" * Use parameters for reusability and readability * Use many short statements in place of one big one * Define wires/regs at beginning of file * Align input names/comments in column like fashion * Avoid redundant begin..end statements * Capitalize macros and constants * Use lower case for all signal names * User upper case for all parameters and constants * Use y down to x vectors * Use a naming methodology and document it * Comment every module port * Do not hard code numerical values in body of code * Keep parameter names short * Use common names: nreset, clk, din, dout, en, rd, wr, addr, etc * Make names as short as possible, but not shorter * Use _ in constants over 4 bits (eg: 8'h1100_1100) * One module per file * Use ".vh" suffix for header files, * yse ".v" for verilog source files * Use `include files for constants * Use `ifndef _CONSTANTS_V to include file only once * No timescales in design files (only in testbench) * No delay statements in design * No logic statements in top level design structures * Prefer parameters in place of global defines * Do not use casex * Use active low reset * Avoid redundant resets * Avoid heavily nested if, else statements * Don't use defparams, place #(.DW(DW)) in module instantation * Always use connection by name (not by order) in module instantiatoin * Parametrize as much as possible but not more * Place a useful comment every 5-20 lines * If you are going to use async reset, use oh_rsync.v * Use for loops to reduce bloat and to improve readability * If you have to mix clock edges, isolate to discrete modules * Use nonblocking (<=) in all sequential statements * Use default statements in all case statements * Don't use proprietary EDA tool pragmas (use parameters) * Only use synthesizable constructs * Use $signed() for arithmetic operations on signed types * Allowed keywords: assign, always, input, output, wire, reg, module, endmodule, if/else, case, casez, ~,|,&,^,==, >>, <<, >, <,?,posedge, negedge, generate, for(...), begin, end, $signed, # DESIGN GUIDELINES * When possible/reasonable use 64b boundaries for scalable registers * When posible place multi bit fields on nibble boundaries * All registers should have "0" as default value on reset * Only include reset values if absolutely needed * Separate the design from the testbench * Separate the test from the testbench * More to come... # DOCUMENTATION GUIDELINES * Write docs in markdown * Specify which registers are reset * Put lsb on right side, lsb is bit zero * Indicate type (read/write/etc) * Indicate what * All signal should be summarized in a table (markdown) * All signals should have waveforms (wavedrom) * List internal block hierarhcy (need script for this) * Unused/reserved bits in all register should be written as zero * In tables, place registers in address order * In description section, place registeres in alphabetical order * Include links in table to descriptions * Include "internal register map" * Base address of chip/block * Table of interrupts.. * Show how to compile.. * Show how to simulate... * Show how to synthesize/build.. * Show how to use.. # MODULE SIGNOFF CHECKLIST * Is the block datasheet complete and accurate? * Is there a user guide? * Is there a script/make file for building/testing the design? * Is there a self testing testbench? * Is there an auotomated synthesis script? * Is the driver written? * Is there a demo example? * Is the the block Silicon and FPGA validated? ---- [picture-license](https://commons.wikimedia.org/wiki/File:Lego_Color_Bricks.jpg)