Awesome

Common Cells Repository

Maintainer: Nils Wistoff nwistoff@iis.ee.ethz.ch

This repository contains commonly used cells and headers for use in various projects.

Cell Contents

This repository currently contains the following cells, ordered by categories. Please note that cells with status deprecated are not to be used for new designs and only serve to provide compatibility with old code.

Clocks and Resets

Name	Description	Status	Superseded By
`clk_int_div`	Arbitrary integer clock divider with config interface and 50% output clock duty cycle	active
`clk_int_div_static`	A convenience wrapper around `clk_int_div` with static division factor.	active
`clk_div`	Clock divider with integer divisor	deprecated	`clk_int_div`
`clock_divider`	Clock divider with configuration registers	deprecated	`clk_int_div`
`clock_divider_counter`	Clock divider using a counter	deprecated	`clk_int_div`
`rstgen`	Reset synchronizer	active
`rstgen_bypass`	Reset synchronizer with dedicated test reset bypass	active

Clock Domains and Asynchronous Crossings

Name	Description	Status	Superseded By
`cdc_4phase`	Clock domain crossing using 4-phase handshake, with ready/valid interface	active
`cdc_2phase`	Clock domain crossing using two-phase handshake, with ready/valid interface	active
`cdc_2phase_clearable`	Identical to `cdc_2phase` but supports one-sided async/sync resetting of either src or dst	active
`cdc_fifo_2phase`	Clock domain crossing FIFO using two-phase handshake, with ready/valid interface	active
`cdc_fifo_gray`	Clock domain crossing FIFO using a gray-counter, with ready/valid interface	active
`cdc_fifo_gray_clearable`	Identical to `cdc_fifo_gray` but supports one-sided async/sync resetting of either src or dst	active
`cdc_reset_ctrlr`	Lock-step reset sequencer accross clock domains (internally used by clearable CDCs)	active
`clk_mux_glitch_free`	A glitch-free clock multiplexer with parametrizeable number of inputs.	active
`edge_detect`	Rising/falling edge detector	active
`edge_propagator`	Propagates a single-cycle pulse across an asynchronous clock domain crossing	active
`edge_propagator_ack`	`edge_propagator` with sender-synchronous acknowledge pin (flags received pulse)	active
`edge_propagator_rx`	Receive slice of `edge_propagator`, requires only the receiver clock	active
`edge_propagator_tx`	Transmit slice of `edge_propagator`, requires only the sender clock	active
`isochronous_spill_register`	Isochronous clock domain crossing and full handshake (like `spill_register`)	active
`isochronous_4phase_handshake`	Isochronous four-phase handshake.	active
`pulp_sync`	Serial line synchronizer	deprecated	`sync`
`pulp_sync_wedge`	Serial line synchronizer with edge detector	deprecated	`sync_wedge`
`serial_deglitch`	Serial line deglitcher	active
`sync`	Serial line synchronizer	active
`sync_wedge`	Serial line synchronizer with edge detector	active

Counters and Shift Registers

Name	Description	Status	Superseded By
`counter`	Generic up/down counter with overflow detection	active
`credit_counter`	Up/down counter for credit	active
`delta_counter`	Up/down counter with variable delta and overflow detection	active
`generic_LFSR_8bit`	8-bit linear feedback shift register (LFSR)	deprecated	`lfsr_8bit`
`lfsr_8bit`	8-bit linear feedback shift register (LFSR)	active
`lfsr_16bit`	16-bit linear feedback shift register (LFSR)	active
`lfsr`	4...64-bit parametric Galois LFSR with optional whitening feature	active
`max_counter`	Up/down counter with variable delta that tracks its maximum value	active
`mv_filter`	ZARUBAF ADD DESCRIPTION	active

Data Path Elements

Name	Description	Status	Superseded By
`addr_decode`	Address map decoder	active
`addr_decode_dync`	Address map decoder extended to support dynamic online configuration	active
`addr_decode_napot`	Address map decoder using naturally-aligned power of two (NAPOT) regions	active
`multiaddr_decode`	Address map decoder using NAPOT regions and allowing for multiple address inputs	active
`ecc_decode`	SECDED Decoder (Single Error Correction, Double Error Detection)	active
`ecc_encode`	SECDED Encoder (Single Error Correction, Double Error Detection)	active
`binary_to_gray`	Binary to gray code converter	active
`find_first_one`	Leading-one finder / leading-zero counter	deprecated	`lzc`
`gray_to_binary`	Gray code to binary converter	active
`lzc`	Leading/trailing-zero counter	active
`onehot_to_bin`	One-hot to binary converter	active
`shift_reg`	Shift register for arbitrary types	active
`shift_reg_gated`	Shift register with ICG for arbitrary types	active
`rr_arb_tree`	Round-robin arbiter for req/gnt and vld/rdy interfaces with optional priority	active
`rrarbiter`	Round-robin arbiter for req/ack interface with look-ahead	deprecated	`rr_arb_tree`
`prioarbiter`	Priority arbiter arbiter for req/ack interface with look-ahead	deprecated	`rr_arb_tree`
`fall_through_register`	Fall-through register with ready/valid interface	active
`spill_register_flushable`	Register with ready/valid interface to cut all combinational interface paths and additional flush signal.	active
`spill_register`	Register with ready/valid interface to cut all combinational interface paths	active
`stream_arbiter`	Round-robin arbiter for ready/valid stream interface	active
`stream_arbiter_flushable`	Round-robin arbiter for ready/valid stream interface and flush functionality	active
`stream_demux`	Ready/valid interface demultiplexer	active
`lossy_valid_to_stream`	Convert Valid-only to ready/valid by updating in-flight transaction	active
`stream_join`	Ready/valid handshake join multiple to one common	active
`stream_join_dynamic`	Ready/valid handshake join multiple to one common, dynamically configurable subset selection	active
`stream_mux`	Ready/valid interface multiplexer	active
`stream_register`	Register with ready/valid interface	active
`stream_fork`	Ready/valid fork	active
`stream_fork_dynamic`	Ready/valid fork, with selection mask for partial forking	active
`stream_filter`	Ready/valid filter	active
`stream_delay`	Randomize or delay ready/valid interface	active
`stream_to_mem`	Use memories without flow control for output data in streams.	active
`stream_xbar`	Fully connected crossbar with ready/valid interface.	active
`stream_omega_net`	One-way stream omega-net with ready/valid interface. Isomorphic to a butterfly.	active
`stream_throttle`	Restrict the number of outstanding transfers in a stream.	active
`sub_per_hash`	Substitution-permutation hash function	active
`popcount`	Combinatorial popcount (hamming weight)	active
`mem_to_banks_detailed`	Split memory access over multiple parallel banks with detailed response signals	active
`mem_to_banks`	Split memory access over multiple parallel banks	active

Data Structures

Name	Description	Status	Superseded By
`cb_filter`	Counting-Bloom-Filter with combinational lookup	active
`fifo`	FIFO register with upper threshold	deprecated	`fifo_v3`
`fifo_v2`	FIFO register with upper and lower threshold	deprecated	`fifo_v3`
`fifo_v3`	FIFO register with generic fill counts	active
`passthrough_stream_fifo`	FIFO register with ready/valid interface and same-cycle push/pop when full	active
`stream_fifo`	FIFO register with ready/valid interface	active
`stream_fifo_optimal_wrap`	Wrapper that optimally selects either a spill register or a FIFO	active
`generic_fifo`	FIFO register without thresholds	deprecated	`fifo_v3`
`generic_fifo_adv`	FIFO register without thresholds	deprecated	`fifo_v3`
`sram`	SRAM behavioral model	active
`plru_tree`	Pseudo least recently used tree	active
`unread`	Empty module to sink unconnected outputs into	active
`read`	Dummy module that prevents a signal from being removed during synthesis	active

Header Contents

This repository currently contains the following header files.

RTL Register Macros

The header file registers.svh contains macros that expand to descriptions of registers. To avoid misuse of always_ff blocks, only the following macros shall be used to describe sequential behavior. The use of linter rules that flag explicit uses of always_ff in source code is encouraged.

Macro	Arguments	Description
`FF	`q_sig`, `d_sig`, `rst_val`, (`clk_sig`, `arstn_sig`)	Flip-flop with asynchronous active-low reset
`FFAR	`q_sig`, `d_sig`, `rst_val`, `clk_sig`, `arst_sig`	Flip-flop with asynchronous active-high reset
`FFARN	`q_sig`, `d_sig`, `rst_val`, `clk_sig`, `arstn_sig`	deprecated Flip-flop with asynchronous active-low reset
`FFSR	`q_sig`, `d_sig`, `rst_val`, `clk_sig`, `rst_sig`	Flip-flop with synchronous active-high reset
`FFSRN	`q_sig`, `d_sig`, `rst_val`, `clk_sig`, `rstn_sig`	Flip-flop with synchronous active-low reset
`FFNR	`q_sig`, `d_sig`, `clk_sig`	Flip-flop without reset

`FFL	`q_sig`, `d_sig`, `load_ena`, `rst_val`, (`clk_sig`, `arstn_sig`)	Flip-flop with load-enable and asynchronous active-low reset
`FFLAR	`q_sig`, `d_sig`, `load_ena`, `rst_val`, `clk_sig`, `arst_sig`	Flip-flop with load-enable and asynchronous active-high reset
`FFLARN	`q_sig`, `d_sig`, `load_ena`, `rst_val`, `clk_sig`, `arstn_sig`	deprecated Flip-flop with load-enable and asynchronous active-low reset
`FFLSR	`q_sig`, `d_sig`, `load_ena`, `rst_val`, `clk_sig`, `rst_sig`	Flip-flop with load-enable and synchronous active-high reset
`FFLSRN	`q_sig`, `d_sig`, `load_ena`, `rst_val`, `clk_sig`, `rstn_sig`	Flip-flop with load-enable and synchronous active-low reset
`FFLNR	`q_sig`, `d_sig`, `load_ena`, `clk_sig`	Flip-flop with load-enable without reset

The name of the clock and reset signals for implicit variants is clk_i and rst_ni, respectively.
Argument suffix _sig indicates signal names for present and next state as well as clocks and resets.
Argument rst_val specifies the value literal to be assigned upon reset.
Argument load_ena specifies the boolean expression that forms the load enable of the register.

SystemVerilog Assertion Macros

The header file assertions.svh contains macros that expand to assertion blocks. These macros should recduce the effort in writing many assertions and make it easier to use them. They are similar to but incompatible with the macros used by lowrisc.

Simple Assertion and Cover Macros

Macro	Arguments	Description
`ASSERT_I	`__name`, `__prop`, (`__desc`)	Immediate assertion
`ASSERT_INIT	`__name`, `__prop`, (`__desc`)	Assertion in initial block. Can be used for things like parameter checking
`ASSERT_FINAL	`__name`, `__prop`, (`__desc`)	Assertion in final block
`ASSERT	`__name`, `__prop`, (`__clk`, `__rst`, `__desc`)	Assert a concurrent property directly
`ASSERT_NEVER	`__name`, `__prop`, (`__clk`, `__rst`, `__desc`)	Assert a concurrent property NEVER happens
`ASSERT_KNOWN	`__name`, `__sig`, (`__clk`, `__rst`, `__desc`)	Concurrent clocked assertion with custom error message
`COVER	`__name`, `__prop`, (`__clk`, `__rst`)	Cover a concurrent property

The name of the clock and reset signals for implicit variants is clk_i and rst_ni, respectively.
__desc is an optional string argument describing the failure causing the assertion to be violated that is embedded into the error report and defaults to "".

Complex Assertion Macros

Macro	Arguments	Description
`ASSERT_PULSE	`__name`, `__sig`, (`__clk`, `__rst`, `__desc`)	Assert that signal is an active-high pulse with pulse length of 1 clock cycle
`ASSERT_IF	`__name`, `__prop`, `__enable`, (`__clk`, `__rst`, `__desc`)	Assert that a property is true only when an enable signal is set
`ASSERT_KNOWN_IF	`__name`, `__sig`, `__enable`, (`__clk`, `__rst`, `__desc`)	Assert that signal has a known value (each bit is either '0' or '1') after reset if enable is set

The name of the clock and reset signals for implicit variants is clk_i and rst_ni, respectively.
__desc is an optional string argument describing the failure causing the assertion to be violated that is embedded into the error report and defaults to "".

Assumption Macros

Macro	Arguments	Description
`ASSUME	`__name`, `__prop`, (`__clk`, `__rst`, `__desc`)	Assume a concurrent property
`ASSUME_I	`__name`, `__prop`, (`__desc`)	Assume an immediate property

The name of the clock and reset signals for implicit variants is clk_i and rst_ni, respectively.
__desc is an optional string argument describing the failure causing the assertion to be violated that is embedded into the error report and defaults to "".

Formal Verification Macros

Macro	Arguments	Description
`ASSUME_FPV	`__name`, `__prop`, (`__clk`, `__rst`, `__desc`)	Assume a concurrent property during formal verification only
`ASSUME_I_FPV	`__name`, `__prop`, (`__desc`)	Assume a concurrent property during formal verification only
`COVER_FPV	`__name`, `__prop`, (`__clk`, `__rst`)	Cover a concurrent property during formal verification

The name of the clock and reset signals for implicit variants is clk_i and rst_ni, respectively.
__desc is an optional string argument describing the failure causing the assertion to be violated that is embedded into the error report and defaults to "".