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.

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.

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