=======

OH! Open Hardware for Chip Designers

Introduction

OH! is an open-source library of hardware building blocks based on silicon proven design practices at 0.35um to 28nm. The library is being used by Adapteva in designing its next generation ASIC.

The library is written in standard Verilog (2005) and contains over 25,000 lines of Verilog code, over 150 separate modules. Examples of functionality include: FIFOs, SPI (master/slave), GPIO, high speed links, memories, clock circuits, synchronization primitives,interrupt controller, DMA.

Content

1. Philosophy
2. Modules
3. How to Simulate
4. How to Build
5. Design Guide
6. Coding Guide
7. Documentation Guide
8. Design Checklist
9. Recommended Reading
10. License

Philosophy

1. Make it work
2. Make it simple
3. Make it modular

Modules

FOLDER	STATUS	DESCRIPTION
accelerator	FPGA	Accelerator tutorial
axi	FPGA	AXI master and slave interfaces
chip	SI	Chip design reference flow
common	SI	Library of basic components
edma	HH	DMA engine
elink	SI	Point to point LVDS link
emailbox	FPGA	Mailbox with interrupt output
emesh	SI	Emesh interface circuits
emmu	FPGA	Memory translation unit
etrace	HH	Logic Analyzer
gpio	HH	General Purpose IO
mio	HH	Lightweight parallel link
pic	SI	Interrupt controller
parallella	FPGA	Parallella FPGA logic
risc-v	HH	RISC-V implementation
spi	HH	SPI master/slave
xilibs	FPGA	Xilinx simulation models

NOTES:

• "SI"= Silicon validated
• "FPGA" = FPGA validated
• "HH" = Hard hat area (work in progress)

---

How to simulate

Scripts are located in the './scripts' directory.

./scripts/build.sh gpio/dv/dut_gpio.v         # compile gpio testbench (example)
./scripts/sim.sh gpio/dv/tests/test_basic.emf # run "test_basic.emf" test
./scripts/view.sh                             # open the waveform with gtkwave

Short-cut:

• Builds $name/dv/dut_$name.v
• Runs test $name/dv/tests/test_basic.emf

./run.sh accelerator  # Run accelerator simulation
./run.sh elink        # Run elink simulation
./run.sh emailbox     # Run emailbox simulation
./run.sh emmu         # Run emmu simulation
./run.sh gpio         # Run gpio simulation
./run.sh mio          # run mio simulation
./run.sh spi          # Run spi simulation
./run.sh pic          # Run pic simulation

How to build

TBD

Design Guide

• Separate circuit from logic
• Separate control from the datapath
• Separate configuration from design
• Separate design from testbench
• Separate testbench from test (data)
• Use 64b boundaries for scalable registers (when reasonable)
• Place multi bit fields on nibble boundaries (when reasonable)
• Make reset values "0"
• Only reset register if absolutely necessary
• More to come...

Coding Guide

• 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 descriptive, avoid non-common abbreviations
• Make names as short as possible, but not shorter
• Use short named generate blocks "g0, g1, etc"
• Inside generate blocks use short "i" for instance
• Use _ in constants over 4 bits (eg: 8'h1100_1100)
• One module per file
• Use ".vh" suffix for header files,
• Use ".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
• With parameters, NEVER us this instantiation: "mux3 #(32) U2 (...)"
• 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,

Documentation Guide

• 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..

Tapeout Checklist

• HERE

Recommended Reading

• Verilog Reference
• Glossary
• Chip constants
• Verilator Simulator
• Emacs Verilog Mode
• Icarus Simulator
• GTKWave
• Wavedrom
• FuseSoC

License

The OH! repository source code is licensed under the MIT license unless otherwise specified. See LICENSE for MIT copyright terms. Design specific licenses can be found in the folder root (eg: aes/LICENSE)

---

picture-license