Skip to content
BranchesTags

Repository files navigation

common RTL foundation

common is a self-contained SystemVerilog component layer for SoC IP. It provides clock/reset, CDC, stream, storage, address, register, and technology model primitives without requiring a parent SoC repository.

The preferred public directories are rtl/base, rtl/stream, rtl/bus, rtl/clock, rtl/cdc, and rtl/memory. Existing interfaces remain at their legacy paths for current users in the IP workspace.

Quick start

make doctor
make license-check
make format-check
make docs-check
make test-iverilog
make test-verilator
make synth
make formal

flist/rtl.f is the ordered synthesis/simulation source list. Unit tests are self-checking and write only below build/. format-check validates all tracked SystemVerilog sources with Verible and tracked Makefile sources with mbake using .bake.toml. docs-check verifies that every declared RTL unit has a maintained reference page. See docs/reference/ for the full catalog, docs/design.md for contracts, and AGENTS.md for contribution rules.

license-check requires every tracked SystemVerilog source to carry an SPDX identifier or an upstream license notice in its first 40 lines.

Register Primitives

rtl/utils/register.sv keeps the existing module names as a compatibility surface. Select the primitive by clock edge, reset style, reset value, and enable requirement:

Primitive family Clock edge Reset Enable
dff rising none no
dffl rising none yes
dffr, dffer rising asynchronous active-low, zero no / yes
dffrh, dfferh rising asynchronous active-low, all ones no / yes
dffrc, dfferc rising asynchronous active-low, configurable no / yes
dffsr, dffesr rising synchronous active-low, zero no / yes
dffsrc, dffesrc rising synchronous active-low, configurable no / yes
ndffr, ndffer falling asynchronous active-low, zero no / yes
dfferm rising asynchronous active-low, per-array policy per element

Reset has priority over enable. A low enable holds the previous value. The dffercn type-parameterized asynchronous-reset variant remains for existing users; new fixed-width code should prefer dfferc. Register enable expresses data retention semantics. It does not guarantee clock-gate insertion; use the Common clk_icg/technology ICG wrapper at module level when clock gating is required and verify the mapped gate-level netlist.

The repository is licensed under Mulan PSL v2 unless an individual source file states another compatible upstream license. Third-party attributions and license notices are recorded in NOTICE and licenses/.

Third-Party Notices

The repository-level Mulan PSL v2 license applies unless an individual source file declares a compatible upstream license. Per-file copyright and SPDX notices take precedence. The following table is a concise attribution guide; NOTICE, licenses/README.md, and source headers are the authoritative records.

Material Copyright and license Affected scope and authoritative record
PULP platform common_cells ETH Zurich and University of Bologna; individual source notices identify additional authors. SHL-0.51. PULP-derived RTL carrying that SPDX identifier. The complete source-to-component mapping and reference snapshot are in licenses/pulp_common_cells_manifest.tsv and NOTICE.
PULP common_cells signal helpers ETH Zurich, University of Bologna, EPFL, and OpenHW Group. Apache-2.0 WITH SHL-2.1. rtl/base/signal_helpers.sv, derived from PULP cc_read and cc_unread; see its exact source header and NOTICE.
lowRISC OpenTitan register field material lowRISC contributors. Apache-2.0. rtl/utils/regfield.sv; see NOTICE.

Component Reference

Each declared RTL unit has a detailed integration page. The catalog is generated from rtl/; use the linked page for parameters, complete interfaces, reset/CDC constraints, and an instantiation example.

base

Component Type Function summary
bit_count module Combinational population-count primitive.
component_math_pkg package Compile-time arithmetic helpers for parameterized components.
counting_bloom_filter module Counting Bloom filter with explicit counter saturation.
credit_pool module Saturating available-credit tracker for resource flow control.
hash_indicator_bank module Multi-hash indicator-vector generator.
index_to_onehot module Bounded index-to-one-hot decoder.
interval_ones_mask module Inclusive contiguous mask generator between two bit positions.
leading_zero_count module Combinational leading-zero counter with all-zero indication.
loop_trip_counter module Programmable terminal-count loop counter.
onehot_check module One-hot validity checker with optional all-zero acceptance.
onehot_to_index module One-hot vector to index converter with validity output.
permutation_hash module Deterministic non-cryptographic bit-mixing hash.
plru_victim_selector module Power-of-two pseudo-LRU cache-way victim selector.
prefix_ones_mask module Low-order prefix-ones mask generator.
retry_backoff module Pseudo-random exponential retry-delay controller.
sample_majority_filter module Sliding-window N-of-M single-bit sample filter.
secded_decode module Extended-Hamming SECDED decoder, corrector, and error classifier.
secded_encode module Extended-Hamming SECDED encoder.
secded_layout_pkg package Shared SECDED codeword-layout helpers.
signal_sink module Intentional unused-signal terminator.
signal_tap module Named combinational signal pass-through for observability.
stable_level_filter module Consecutive-sample debounce and stability filter.
trailing_zero_count module Combinational trailing-zero counter with all-zero indication.

bus

Component Type Function summary
address_map module Masked address-map decoder with deterministic lowest-index priority.
address_range_decoder module Inclusive address-range decoder.
address_region module Masked address-region matcher.
address_set_decoder module Decoder for a set of independently configured address regions.
axi4_regslice module Elastic register slice for all five AXI4 channels.

cdc

Component Type Function summary
async_gray_queue module Gray-pointer asynchronous FIFO wrapper.
async_reqack module One-entry four-phase asynchronous data mailbox.
cdc_2phase module Two-phase asynchronous request/acknowledge transfer.
cdc_2phase_dst module Destination-side implementation of the two-phase CDC link.
cdc_2phase_src module Source-side implementation of the two-phase CDC link.
cdc_2phase_warm_flush module Source-initiated warm-clear wrapper for a two-phase CDC link.
cdc_event_bridge module Pulse/event transport over an asynchronous mailbox.
cdc_event_bridge_ack module Acknowledged asynchronous event transport.
cdc_fifo module Gray-pointer asynchronous FIFO.
cdc_fifo_dst module Destination-side implementation of the asynchronous FIFO.
cdc_fifo_src module Source-side implementation of the asynchronous FIFO.
cdc_fifo_warm_flush module Source-initiated warm-clear wrapper for an asynchronous FIFO.
cdc_remote_clear_request module Retained remote-clear request channel.
cdc_reset_barrier module Two-domain reset barrier with synchronized release.
cdc_sync module Multi-flop synchronizer for a control bit or independently encoded vector.
cdc_sync_det module Synchronized control input with edge detection.
cdc_warm_flush_controller module Acknowledged isolate-reset-resume controller for CDC warm flush.
clearable_async_queue module Asynchronous queue with coordinated endpoint clear.
clearable_two_phase_link module Two-phase link with coordinated endpoint clear.
four_phase_mailbox module Public wrapper for the four-phase asynchronous mailbox API.
isochronous_handshake module Handshake for fixed-ratio, STA-constrained isochronous clocks.
isochronous_stream_buffer module Stream buffer for fixed-ratio, STA-constrained isochronous clocks.
synchronized_edge module Synchronizes a control transition and emits a local edge indication.
test_reset_synchronizer module Verification-oriented reset synchronization helper.
two_phase_async_queue module Queue API built from two-phase asynchronous transfers.

clkrst

Component Type Function summary
clk_int_div_simple module Runtime-programmable integer divider with safe low-phase updates.
clk_int_even_div module Even clock divider retaining requests until a safe boundary.
clk_int_even_div_static module Static even integer clock divider.
clk_int_odd_div_static module Static odd integer clock divider.
peak_delta_counter module Up/down counter with retained high-water mark.
rs_counter module Resettable up/down counter.
rs_delta_counter module Delta-counting counter.
rst_sync module Asynchronous-assert, synchronous-release reset synchronizer.

clock

Component Type Function summary
clock_divider module Runtime-programmable divider that changes only at an output-low boundary.
clock_or_tree module OR tree for clocks already proven safe to combine.
safe_clock_mux module Glitch-safe handover mux for two continuously running clocks.

interface

Component Type Function summary
ahbl_if interface Typed AHB-Lite interface with master and slave modports.
apb4_if interface Clocked APB4 interface with master and slave modports.
apb4_pure_if interface Clockless APB4 signal interface with master and slave modports.
axi4_addr_gen module AXI4 next-address generator for FIXED, INCR, and legal WRAP bursts.
axi4_if interface Typed AXI4 interface with master and slave modports.
axi4_stream_if interface Typed AXI4-Stream interface with source, sink, and monitor modports.
ram_if interface Simple RAM request/response interface with master and slave modports.
ready_valid_if interface Typed ready/valid interface with source, sink, and monitor modports.
ribp_if interface RIBP request/response interface with response-error signaling.

memory

Component Type Function summary
circular_store module Sequential circular store with bounded random reads.
memory_bank_adapter module Public banked-memory request and response adapter.
memory_bank_adapter_detail module Banked-memory request splitter and response gatherer.
sync_memory module Portable synchronous memory model with positive-logic controls.
tag_order_queue module Shared-pool queue preserving FIFO order within each tag.

model

Component Type Function summary
apb4_master_model module Simulation APB4 master model.

stream

Component Type Function summary
axi4_stream_regslice module Elastic AXI4-Stream register slice.
bypass_buffer module Combinational valid/ready stream pass-through.
latest_value_stream module Valid-only stream adapter retaining the newest pending value.
memory_response_bridge module Response-order bridge between memory and stream interfaces.
round_robin_arbiter module Fair transfer-driven round-robin arbiter.
stream_buffer module Valid/ready stream wrapper around a spill register.
stream_collector module Collects selected valid/ready inputs into one stream output.
stream_credit_limiter module Limits stream acceptance by available credits.
stream_crossbar module Arbitrates and routes multiple stream inputs to multiple outputs.
stream_delay_injector module Controlled stream delay injector for verification and stress.
stream_discard_gate module Consumes input transfers while discard is asserted.
stream_elastic_register module One-entry elastic valid/ready register stage.
stream_fair_arbiter module Fair round-robin arbiter for valid/ready stream inputs.
stream_fallthrough_buffer module One-entry fall-through valid/ready buffer.
stream_queue module Parameterized valid/ready queue with optional fall-through.
stream_replicator module Registered one-item stream distributor with per-target completion.
stream_router module Routes one valid/ready input to a selected output.
stream_selector module Selects one of several valid/ready inputs.
stream_shuffle_network module Deterministic stream-lane permutation network.
stream_window_guard module Limits outstanding stream requests with explicit retire accounting.

tech

Component Type Function summary
clk_an2 module Behavioral two-input clock AND model.
clk_buf module Behavioral clock buffer model.
clk_icg module Behavioral integrated clock-gate model.
clk_icg2 module Behavioral two-input integrated clock-gate model.
clk_mux2 module Behavioral two-input clock mux model.
clk_n module Behavioral clock inverter model.
clk_nd2 module Behavioral two-input clock NAND model.
clk_xor2 module Behavioral two-input clock XOR model.
osc_pad_h module Horizontal oscillator pad abstraction.
osc_pad_v module Vertical oscillator pad abstraction.
tech_pll module Technology PLL abstraction.
tech_ram module Behavioral single-port technology RAM model.
tech_ram_bm module Behavioral byte-masked technology RAM model.
tech_regfile module Behavioral technology register-file model.
tech_regfile_bm module Behavioral byte-masked technology register-file model.
tri_pd_pad_h module Horizontal pull-down pad abstraction.
tri_pd_pad_v module Vertical pull-down pad abstraction.
tri_pdu_pad_h module Horizontal pull-down-up pad abstraction.
tri_pdu_pad_v module Vertical pull-down-up pad abstraction.
tri_pu_pad_h module Horizontal pull-up pad abstraction.
tri_pu_pad_v module Vertical pull-up pad abstraction.

utils

Component Type Function summary
bin2gray module Combinational binary-to-Gray code converter.
dff module Plain D flip-flop primitive.
dffer module Enabled D flip-flop with asynchronous reset.
dfferc module Enabled D flip-flop with configurable reset value.
dffercn module Enabled D flip-flop with active-low configurable reset value.
dfferh module Enabled D flip-flop with all-one reset value.
dfferm module Masked-update D flip-flop with reset.
dffesr module Enabled D flip-flop with synchronous reset.
dffesrc module Enabled D flip-flop with synchronous reset and configurable reset value.
dffl module Level-sensitive latch primitive.
dffr module D flip-flop with asynchronous active-low reset.
dffrc module D flip-flop with configurable reset value.
dffrh module D flip-flop with all-one reset value.
dffsr module D flip-flop with synchronous reset.
dffsrc module D flip-flop with synchronous reset and configurable reset value.
edge_det module Single-bit rising and falling edge detector.
edge_det_fe module Single-bit falling-edge detector.
edge_det_re module Single-bit rising-edge detector.
edge_det_sync module Synchronized single-bit rising and falling edge detector.
edge_det_sync_fe module Synchronized single-bit falling-edge detector.
edge_det_sync_re module Synchronized single-bit rising-edge detector.
fifo module Power-of-two synchronous FIFO with combinational head read.
gray2bin module Combinational Gray-to-binary code converter.
lfsr_fibonacci module Fibonacci-form pseudo-random linear-feedback shift register.
lfsr_galois module Galois-form pseudo-random linear-feedback shift register.
ndffer module Enabled D flip-flop with falling-edge clock and asynchronous reset.
ndffr module Resettable multi-stage synchronizer register chain.
regfield module Masked register-field update primitive.
shift_reg module Parameterized sequential shift register.
spill_register module Two-register spill stage for breaking ready timing paths.
stream_fifo module Legacy valid/ready wrapper around the synchronous FIFO.
valid_delay_line module Valid-only parameterized sequential delay line.
xchecker module Simulation unknown-value checker.

About

A SystemVerilog Components Library

Resources

Readme
MulanPSL-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

4 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages