Common Cells Repository

Maintainer: Philippe Sauter phsauter@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
cc_clk_int_div	Arbitrary integer clock divider with config interface and 50% output clock duty cycle	active
cc_clk_int_div_static	A convenience wrapper around cc_clk_int_div with static division factor.	active
cc_rstgen	Reset synchronizer	active
cc_rstgen_bypass	Reset synchronizer with dedicated test reset bypass	active

Clock Domains and Asynchronous Crossings

Name	Description	Status	Superseded By
cc_cdc_4phase	Clock domain crossing using 4-phase handshake, with ready/valid interface	active
cc_cdc_2phase	Clock domain crossing using two-phase handshake, with ready/valid interface	active
cc_cdc_2phase_clearable	Identical to cc_cdc_2phase but supports one-sided async/sync resetting of either src or dst	active
cc_cdc_fifo_2phase	Clock domain crossing FIFO using two-phase handshake, with ready/valid interface	active
cc_cdc_fifo_gray	Clock domain crossing FIFO using a gray-counter, with ready/valid interface	active
cc_cdc_fifo_gray_clearable	Identical to cc_cdc_fifo_gray but supports one-sided async/sync resetting of either src or dst	active
cc_cdc_reset_ctrlr	Lock-step reset sequencer across clock domains, internally used by clearable CDCs	active
cc_clk_mux_glitch_free	A glitch-free clock multiplexer with parameterizable number of inputs.	active
cc_edge_detect

The generic synchronizer is provided by the tech_cells_generic dependency as tc_sync.

Counters and Shift Registers

Name	Description	Status	Superseded By
cc_counter	Generic up/down counter with overflow detection	active
cc_credit_counter	Up/down counter for credit	active
cc_delta_counter	Up/down counter with variable delta and overflow detection	active
cc_exp_backoff	Exponential backoff counter with randomization	active
cc_lfsr_8bit	8-bit linear feedback shift register (LFSR)	active
cc_lfsr_16bit	16-bit linear feedback shift register (LFSR)	active
cc_lfsr	4...64-bit parametric Galois LFSR with optional whitening feature	active
cc_max_counter	Up/down counter with variable delta that tracks its maximum value	active
cc_trip_counter	Counter that resets automatically when it reaches a specified bound	active

Data Path Elements

Name	Description	Status	Superseded By
cc_addr_decode	Address map decoder	active
cc_addr_decode_dync	Address map decoder extended to support dynamic online configuration	active
cc_addr_decode_napot	Address map decoder using naturally-aligned power of two (NAPOT) regions	active
cc_multiaddr_decode	Address map decoder using NAPOT regions and allowing for multiple address inputs	active
cc_ecc_decode	SECDED Decoder (Single Error Correction, Double Error Detection)	active
cc_ecc_encode	SECDED Encoder (Single Error Correction, Double Error Detection)	active
cc_binary_to_gray	Binary to gray code converter	active
cc_gray_to_binary	Gray code to binary converter	active
cc_lzc	Leading/trailing-zero counter	active
cc_onehot	Hardware implementation of SystemVerilog's function

Data Structures

Name	Description	Status	Superseded By
cc_cb_filter	Counting-Bloom-Filter with combinational lookup	active
cc_fifo	FIFO register with generic fill counts	active
cc_id_queue	Queue that preserves FIFO order for entries with the same ID	active
cc_passthrough_stream_fifo	FIFO register with ready/valid interface and same-cycle push/pop when full	active
cc_ring_buffer	Ring buffer with sequential write and random-access read interfaces	active
cc_stream_fifo	FIFO register with ready/valid interface	active
cc_stream_fifo_optimal_wrap	Wrapper that optimally selects either a spill register or a FIFO	active
cc_plru_tree	Pseudo least recently used tree	active
cc_unread	Empty module to sink unconnected outputs into	active
cc_read	Dummy module that prevents a signal from being removed during synthesis

Packages and Interfaces

Name	Description	Status	Superseded By
cc_pkg	Shared package for common functions, types, and encodings	active
cc_stream_dv	Ready/valid stream interface with a custom payload type	active

Ports

Generally, modules with sequential logic receive at least the following inputs. Intentional exceptions are clock, reset, cdc cells, and any cells that receive multiple clock inputs.

Name	Description
clk_i	Clock driving sequential logic.
rst_ni	Asynchronous reset, active-low. Brings the module to its reset state.
clr_i	Synchronous clear, active-high. Brings the module to its reset state in the next clock cycle. Can be driven by synchronous logic or tied to 1'b0 if unused.

Use of Macros

Internally, the cells use macros to implement sequential logic (flip-flops) and assertions. These macros are defined in this repo; see RTL Register Macros and SVA Macros below for more details.

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
`FFARNC	q_sig, d_sig, clr_sig, rst_val, (clk_sig, arstn_sig)	Flip-flop with asynchronous active-low reset and synchronous active-high clear
`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
`FFLARNC	q_sig, d_sig, load_ena, clr_sig, rst_val, (clk_sig, arstn_sig)	Flip-flop with load-enable, asynchronous active-low reset and synchronous active-high clear
`FFLSR	q_sig, d_sig, load_ena, rst_val, ,

• The name of the clock signal for implicit variants is clk_i.
• The name of the reset signal for implicit variants is rst_i or rst_ni, respectively for active-high and active-low variants.
• Argument suffix _sig indicates signal names for present and next state as well as clocks, resets and synchronous clear signals.
• 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.
• Arguments clr_sig, rst_sig and rstn_sig must be plain signal names, not expressions.

SystemVerilog Assertion Macros

The header file assertions.svh contains macros that expand to assertion blocks. These macros should reduce 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
`ASSERT_STABLE	__name, __valid, __ready, __data, (__mask, __clk, __rst, __desc)	Assert that the unmasked data on a ready-valid interface is kept stable after valid is asserted, until ready is asserted

• 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 an immediate 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 "".