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.