Skip to content

pulp-platform/common_cells

BranchesTags

Repository files navigation

Build Status GitHub tag (latest SemVer) SHL-0.51 license

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

About

Common SystemVerilog components

Resources

Readme

License

View license
Activity
Custom properties

Stars

531 stars

Watchers

19 watching

Forks

145 forks
Report repository

Releases 35

v1.37.0 Latest
Jul 18, 2024
+ 34 releases

Contributors 43
+ 29 contributors

Languages