admin/common
1
0 Fork 0
mirror of https://github.com/retroSoC/common.git synced 2026-11-04 22:32:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add documentation for new utility components and scripts

Browse Source 
- Created documentation for , , , and  modules, detailing their functionality, parameters, and usage examples.
- Implemented a script  to ensure required headings and content are present in documentation files.
- Developed  to generate and update documentation pages from SystemVerilog declarations, ensuring consistency and completeness.
This commit is contained in:
maksyuki committed 2026-08-04 16:35:53 +08:00
1 parent cbbc335159
commit 3b6a925a51
157 files changed
+12973 -4
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/workflows/rtl.yml
+2
View File
@@ -30,6 +30,8 @@ jobs:
run: make license-check
- name: Format
run: make format-check
- name: Component documentation
run: make docs-check
- name: Lint
run: make lint
- name: Icarus regression
AGENTS.md
+4
View File
@@ -11,6 +11,9 @@ library, SoC repository, or verification package outside this tree.
- `rtl/utils`, `rtl/clkrst`, `rtl/tech`, and `rtl/interface` retain compatible
interfaces for existing IP. Do not remove or rename these paths without a
release-note migration plan.
- `docs/reference` contains one generated, checked-in Markdown page for every
declared RTL `module`, `interface`, and `package`. Update its renderer and
regenerate the pages whenever a public declaration or its contract changes.
- `dv/unit` contains self-checking simulation tests. `formal` contains bounded
property checks. Generated artifacts belong under `build/` only.
@@ -34,6 +37,7 @@ Run the following before submitting a change:
```sh
make format-check
make mk-validate
make docs-check
make license-check
make lint
make test-iverilog
Makefile
+5 -1
View File
@@ -18,7 +18,7 @@ RTL_FILES := $(shell scripts/rtl_files.sh)
MAKE_FILES := $(shell git ls-files --cached --others --exclude-standard | rg '(^|/)(Makefile|[^/]+\.mk)$$' | while IFS= read -r file; do test -f "$$file" && printf '%s\n' "$$file"; done)
SV_FILES := $(shell git ls-files --cached --others --exclude-standard | rg '\.sv$$' | while IFS= read -r file; do test -f "$$file" && printf '%s\n' "$$file"; done)
.PHONY: help doctor format format-check mk-format mk-format-check mk-validate rtl-format rtl-format-check license-check lint test test-iverilog test-verilator synth formal clean
.PHONY: help doctor format format-check mk-format mk-format-check mk-validate rtl-format rtl-format-check docs-check license-check lint test test-iverilog test-verilator synth formal clean
help:
@printf '%s\n' \
@@ -27,6 +27,7 @@ help:
' format | format-check apply/check Makefile and RTL formatting' \
' mk-format | mk-format-check apply/check tracked Makefile formatting with mbake' \
' mk-validate validate Makefile with GNU make via mbake' \
' docs-check validate component-reference documentation coverage' \
' rtl-format | rtl-format-check apply/check tracked SystemVerilog formatting' \
' license-check verify SystemVerilog license headers' \
' lint run Verible and Verilator lint' \
@@ -54,6 +55,9 @@ mk-format-check:
mk-validate:
$(MBAKE) validate --config .bake.toml Makefile
docs-check:
bash scripts/check_component_docs.sh
rtl-format:
$(VERIBLE_FORMAT) --flagfile=.verible-format --failsafe_success=false --inplace $(SV_FILES)
README.md
+214 -3
View File
@@ -14,6 +14,7 @@ legacy paths for current users in the IP workspace.
make doctor
make license-check
make format-check
make docs-check
make test-iverilog
make test-verilator
make synth
@@ -23,9 +24,9 @@ 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`. See
`docs/components.md` for the public catalog, `docs/design.md` for contracts,
and `AGENTS.md` for contribution rules.
`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.
@@ -33,3 +34,213 @@ 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/`.
<!-- COMPONENT_REFERENCE:START -->
## 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`](docs/reference/base/bit_count.md) | `module` | Combinational population-count primitive. |
| [`component_math_pkg`](docs/reference/base/component_math_pkg.md) | `package` | Compile-time arithmetic helpers for parameterized components. |
| [`counting_bloom_filter`](docs/reference/base/counting_bloom_filter.md) | `module` | Counting Bloom filter with explicit counter saturation. |
| [`credit_pool`](docs/reference/base/credit_pool.md) | `module` | Saturating available-credit tracker for resource flow control. |
| [`hash_indicator_bank`](docs/reference/base/hash_indicator_bank.md) | `module` | Multi-hash indicator-vector generator. |
| [`index_to_onehot`](docs/reference/base/index_to_onehot.md) | `module` | Bounded index-to-one-hot decoder. |
| [`interval_ones_mask`](docs/reference/base/interval_ones_mask.md) | `module` | Inclusive contiguous mask generator between two bit positions. |
| [`leading_zero_count`](docs/reference/base/leading_zero_count.md) | `module` | Combinational leading-zero counter with all-zero indication. |
| [`loop_trip_counter`](docs/reference/base/loop_trip_counter.md) | `module` | Programmable terminal-count loop counter. |
| [`onehot_check`](docs/reference/base/onehot_check.md) | `module` | One-hot validity checker with optional all-zero acceptance. |
| [`onehot_to_index`](docs/reference/base/onehot_to_index.md) | `module` | One-hot vector to index converter with validity output. |
| [`permutation_hash`](docs/reference/base/permutation_hash.md) | `module` | Deterministic non-cryptographic bit-mixing hash. |
| [`plru_victim_selector`](docs/reference/base/plru_victim_selector.md) | `module` | Power-of-two pseudo-LRU cache-way victim selector. |
| [`prefix_ones_mask`](docs/reference/base/prefix_ones_mask.md) | `module` | Low-order prefix-ones mask generator. |
| [`retry_backoff`](docs/reference/base/retry_backoff.md) | `module` | Pseudo-random exponential retry-delay controller. |
| [`sample_majority_filter`](docs/reference/base/sample_majority_filter.md) | `module` | Sliding-window N-of-M single-bit sample filter. |
| [`secded_decode`](docs/reference/base/secded_decode.md) | `module` | Extended-Hamming SECDED decoder, corrector, and error classifier. |
| [`secded_encode`](docs/reference/base/secded_encode.md) | `module` | Extended-Hamming SECDED encoder. |
| [`secded_layout_pkg`](docs/reference/base/secded_layout_pkg.md) | `package` | Shared SECDED codeword-layout helpers. |
| [`signal_sink`](docs/reference/base/signal_sink.md) | `module` | Intentional unused-signal terminator. |
| [`signal_tap`](docs/reference/base/signal_tap.md) | `module` | Named combinational signal pass-through for observability. |
| [`stable_level_filter`](docs/reference/base/stable_level_filter.md) | `module` | Consecutive-sample debounce and stability filter. |
| [`trailing_zero_count`](docs/reference/base/trailing_zero_count.md) | `module` | Combinational trailing-zero counter with all-zero indication. |
### `bus`
| Component | Type | Function summary |
| --- | --- | --- |
| [`address_map`](docs/reference/bus/address_map.md) | `module` | Masked address-map decoder with deterministic lowest-index priority. |
| [`address_range_decoder`](docs/reference/bus/address_range_decoder.md) | `module` | Inclusive address-range decoder. |
| [`address_region`](docs/reference/bus/address_region.md) | `module` | Masked address-region matcher. |
| [`address_set_decoder`](docs/reference/bus/address_set_decoder.md) | `module` | Decoder for a set of independently configured address regions. |
### `cdc`
| Component | Type | Function summary |
| --- | --- | --- |
| [`async_gray_queue`](docs/reference/cdc/async_gray_queue.md) | `module` | Gray-pointer asynchronous FIFO wrapper. |
| [`async_reqack`](docs/reference/cdc/async_reqack.md) | `module` | One-entry four-phase asynchronous data mailbox. |
| [`cdc_2phase`](docs/reference/cdc/cdc_2phase.md) | `module` | Two-phase asynchronous request/acknowledge transfer. |
| [`cdc_2phase_dst`](docs/reference/cdc/cdc_2phase_dst.md) | `module` | Destination-side implementation of the two-phase CDC link. |
| [`cdc_2phase_src`](docs/reference/cdc/cdc_2phase_src.md) | `module` | Source-side implementation of the two-phase CDC link. |
| [`cdc_2phase_warm_flush`](docs/reference/cdc/cdc_2phase_warm_flush.md) | `module` | Source-initiated warm-clear wrapper for a two-phase CDC link. |
| [`cdc_event_bridge`](docs/reference/cdc/cdc_event_bridge.md) | `module` | Pulse/event transport over an asynchronous mailbox. |
| [`cdc_event_bridge_ack`](docs/reference/cdc/cdc_event_bridge_ack.md) | `module` | Acknowledged asynchronous event transport. |
| [`cdc_fifo`](docs/reference/cdc/cdc_fifo.md) | `module` | Gray-pointer asynchronous FIFO. |
| [`cdc_fifo_dst`](docs/reference/cdc/cdc_fifo_dst.md) | `module` | Destination-side implementation of the asynchronous FIFO. |
| [`cdc_fifo_src`](docs/reference/cdc/cdc_fifo_src.md) | `module` | Source-side implementation of the asynchronous FIFO. |
| [`cdc_fifo_warm_flush`](docs/reference/cdc/cdc_fifo_warm_flush.md) | `module` | Source-initiated warm-clear wrapper for an asynchronous FIFO. |
| [`cdc_remote_clear_request`](docs/reference/cdc/cdc_remote_clear_request.md) | `module` | Retained remote-clear request channel. |
| [`cdc_reset_barrier`](docs/reference/cdc/cdc_reset_barrier.md) | `module` | Two-domain reset barrier with synchronized release. |
| [`cdc_sync`](docs/reference/cdc/cdc_sync.md) | `module` | Multi-flop synchronizer for a control bit or independently encoded vector. |
| [`cdc_sync_det`](docs/reference/cdc/cdc_sync_det.md) | `module` | Synchronized control input with edge detection. |
| [`cdc_warm_flush_controller`](docs/reference/cdc/cdc_warm_flush_controller.md) | `module` | Acknowledged isolate-reset-resume controller for CDC warm flush. |
| [`clearable_async_queue`](docs/reference/cdc/clearable_async_queue.md) | `module` | Asynchronous queue with coordinated endpoint clear. |
| [`clearable_two_phase_link`](docs/reference/cdc/clearable_two_phase_link.md) | `module` | Two-phase link with coordinated endpoint clear. |
| [`four_phase_mailbox`](docs/reference/cdc/four_phase_mailbox.md) | `module` | Public wrapper for the four-phase asynchronous mailbox API. |
| [`isochronous_handshake`](docs/reference/cdc/isochronous_handshake.md) | `module` | Handshake for fixed-ratio, STA-constrained isochronous clocks. |
| [`isochronous_stream_buffer`](docs/reference/cdc/isochronous_stream_buffer.md) | `module` | Stream buffer for fixed-ratio, STA-constrained isochronous clocks. |
| [`synchronized_edge`](docs/reference/cdc/synchronized_edge.md) | `module` | Synchronizes a control transition and emits a local edge indication. |
| [`test_reset_synchronizer`](docs/reference/cdc/test_reset_synchronizer.md) | `module` | Verification-oriented reset synchronization helper. |
| [`two_phase_async_queue`](docs/reference/cdc/two_phase_async_queue.md) | `module` | Queue API built from two-phase asynchronous transfers. |
### `clkrst`
| Component | Type | Function summary |
| --- | --- | --- |
| [`clk_int_div_simple`](docs/reference/clkrst/clk_int_div_simple.md) | `module` | Runtime-programmable integer divider with safe low-phase updates. |
| [`clk_int_even_div`](docs/reference/clkrst/clk_int_even_div.md) | `module` | Even clock divider retaining requests until a safe boundary. |
| [`clk_int_even_div_static`](docs/reference/clkrst/clk_int_even_div_static.md) | `module` | Static even integer clock divider. |
| [`clk_int_odd_div_static`](docs/reference/clkrst/clk_int_odd_div_static.md) | `module` | Static odd integer clock divider. |
| [`peak_delta_counter`](docs/reference/clkrst/peak_delta_counter.md) | `module` | Up/down counter with retained high-water mark. |
| [`rs_counter`](docs/reference/clkrst/rs_counter.md) | `module` | Resettable up/down counter. |
| [`rs_delta_counter`](docs/reference/clkrst/rs_delta_counter.md) | `module` | Delta-counting counter. |
| [`rst_sync`](docs/reference/clkrst/rst_sync.md) | `module` | Asynchronous-assert, synchronous-release reset synchronizer. |
### `clock`
| Component | Type | Function summary |
| --- | --- | --- |
| [`clock_divider`](docs/reference/clock/clock_divider.md) | `module` | Runtime-programmable divider that changes only at an output-low boundary. |
| [`clock_or_tree`](docs/reference/clock/clock_or_tree.md) | `module` | OR tree for clocks already proven safe to combine. |
| [`safe_clock_mux`](docs/reference/clock/safe_clock_mux.md) | `module` | Glitch-safe handover mux for two continuously running clocks. |
### `interface`
| Component | Type | Function summary |
| --- | --- | --- |
| [`ahbl_if`](docs/reference/interface/ahbl_if.md) | `interface` | Typed AHB-Lite interface with master and slave modports. |
| [`apb4_if`](docs/reference/interface/apb4_if.md) | `interface` | Clocked APB4 interface with master and slave modports. |
| [`apb4_pure_if`](docs/reference/interface/apb4_pure_if.md) | `interface` | Clockless APB4 signal interface with master and slave modports. |
| [`axi4_addr_gen`](docs/reference/interface/axi4_addr_gen.md) | `module` | AXI4 next-address generator for FIXED, INCR, and legal WRAP bursts. |
| [`axi4_if`](docs/reference/interface/axi4_if.md) | `interface` | Typed AXI4 interface with master and slave modports. |
| [`ram_if`](docs/reference/interface/ram_if.md) | `interface` | Simple RAM request/response interface with master and slave modports. |
| [`ready_valid_if`](docs/reference/interface/ready_valid_if.md) | `interface` | Typed ready/valid interface with source, sink, and monitor modports. |
| [`ribp_if`](docs/reference/interface/ribp_if.md) | `interface` | RIBP request/response interface with response-error signaling. |
### `memory`
| Component | Type | Function summary |
| --- | --- | --- |
| [`circular_store`](docs/reference/memory/circular_store.md) | `module` | Sequential circular store with bounded random reads. |
| [`memory_bank_adapter`](docs/reference/memory/memory_bank_adapter.md) | `module` | Public banked-memory request and response adapter. |
| [`memory_bank_adapter_detail`](docs/reference/memory/memory_bank_adapter_detail.md) | `module` | Banked-memory request splitter and response gatherer. |
| [`sync_memory`](docs/reference/memory/sync_memory.md) | `module` | Portable synchronous memory model with positive-logic controls. |
| [`tag_order_queue`](docs/reference/memory/tag_order_queue.md) | `module` | Shared-pool queue preserving FIFO order within each tag. |
### `model`
| Component | Type | Function summary |
| --- | --- | --- |
| [`apb4_master_model`](docs/reference/model/apb4_master_model.md) | `module` | Simulation APB4 master model. |
### `stream`
| Component | Type | Function summary |
| --- | --- | --- |
| [`bypass_buffer`](docs/reference/stream/bypass_buffer.md) | `module` | Combinational valid/ready stream pass-through. |
| [`latest_value_stream`](docs/reference/stream/latest_value_stream.md) | `module` | Valid-only stream adapter retaining the newest pending value. |
| [`memory_response_bridge`](docs/reference/stream/memory_response_bridge.md) | `module` | Response-order bridge between memory and stream interfaces. |
| [`round_robin_arbiter`](docs/reference/stream/round_robin_arbiter.md) | `module` | Fair transfer-driven round-robin arbiter. |
| [`stream_buffer`](docs/reference/stream/stream_buffer.md) | `module` | Valid/ready stream wrapper around a spill register. |
| [`stream_collector`](docs/reference/stream/stream_collector.md) | `module` | Collects selected valid/ready inputs into one stream output. |
| [`stream_credit_limiter`](docs/reference/stream/stream_credit_limiter.md) | `module` | Limits stream acceptance by available credits. |
| [`stream_crossbar`](docs/reference/stream/stream_crossbar.md) | `module` | Arbitrates and routes multiple stream inputs to multiple outputs. |
| [`stream_delay_injector`](docs/reference/stream/stream_delay_injector.md) | `module` | Controlled stream delay injector for verification and stress. |
| [`stream_discard_gate`](docs/reference/stream/stream_discard_gate.md) | `module` | Consumes input transfers while discard is asserted. |
| [`stream_elastic_register`](docs/reference/stream/stream_elastic_register.md) | `module` | One-entry elastic valid/ready register stage. |
| [`stream_fair_arbiter`](docs/reference/stream/stream_fair_arbiter.md) | `module` | Fair round-robin arbiter for valid/ready stream inputs. |
| [`stream_fallthrough_buffer`](docs/reference/stream/stream_fallthrough_buffer.md) | `module` | One-entry fall-through valid/ready buffer. |
| [`stream_queue`](docs/reference/stream/stream_queue.md) | `module` | Parameterized valid/ready queue with optional fall-through. |
| [`stream_replicator`](docs/reference/stream/stream_replicator.md) | `module` | Registered one-item stream distributor with per-target completion. |
| [`stream_router`](docs/reference/stream/stream_router.md) | `module` | Routes one valid/ready input to a selected output. |
| [`stream_selector`](docs/reference/stream/stream_selector.md) | `module` | Selects one of several valid/ready inputs. |
| [`stream_shuffle_network`](docs/reference/stream/stream_shuffle_network.md) | `module` | Deterministic stream-lane permutation network. |
| [`stream_window_guard`](docs/reference/stream/stream_window_guard.md) | `module` | Limits outstanding stream requests with explicit retire accounting. |
### `tech`
| Component | Type | Function summary |
| --- | --- | --- |
| [`clk_an2`](docs/reference/tech/clk_an2.md) | `module` | Behavioral two-input clock AND model. |
| [`clk_buf`](docs/reference/tech/clk_buf.md) | `module` | Behavioral clock buffer model. |
| [`clk_icg`](docs/reference/tech/clk_icg.md) | `module` | Behavioral integrated clock-gate model. |
| [`clk_icg2`](docs/reference/tech/clk_icg2.md) | `module` | Behavioral two-input integrated clock-gate model. |
| [`clk_mux2`](docs/reference/tech/clk_mux2.md) | `module` | Behavioral two-input clock mux model. |
| [`clk_n`](docs/reference/tech/clk_n.md) | `module` | Behavioral clock inverter model. |
| [`clk_nd2`](docs/reference/tech/clk_nd2.md) | `module` | Behavioral two-input clock NAND model. |
| [`clk_xor2`](docs/reference/tech/clk_xor2.md) | `module` | Behavioral two-input clock XOR model. |
| [`osc_pad_h`](docs/reference/tech/osc_pad_h.md) | `module` | Horizontal oscillator pad abstraction. |
| [`osc_pad_v`](docs/reference/tech/osc_pad_v.md) | `module` | Vertical oscillator pad abstraction. |
| [`tech_pll`](docs/reference/tech/tech_pll.md) | `module` | Technology PLL abstraction. |
| [`tech_ram`](docs/reference/tech/tech_ram.md) | `module` | Behavioral single-port technology RAM model. |
| [`tech_ram_bm`](docs/reference/tech/tech_ram_bm.md) | `module` | Behavioral byte-masked technology RAM model. |
| [`tech_regfile`](docs/reference/tech/tech_regfile.md) | `module` | Behavioral technology register-file model. |
| [`tech_regfile_bm`](docs/reference/tech/tech_regfile_bm.md) | `module` | Behavioral byte-masked technology register-file model. |
| [`tri_pd_pad_h`](docs/reference/tech/tri_pd_pad_h.md) | `module` | Horizontal pull-down pad abstraction. |
| [`tri_pd_pad_v`](docs/reference/tech/tri_pd_pad_v.md) | `module` | Vertical pull-down pad abstraction. |
| [`tri_pdu_pad_h`](docs/reference/tech/tri_pdu_pad_h.md) | `module` | Horizontal pull-down-up pad abstraction. |
| [`tri_pdu_pad_v`](docs/reference/tech/tri_pdu_pad_v.md) | `module` | Vertical pull-down-up pad abstraction. |
| [`tri_pu_pad_h`](docs/reference/tech/tri_pu_pad_h.md) | `module` | Horizontal pull-up pad abstraction. |
| [`tri_pu_pad_v`](docs/reference/tech/tri_pu_pad_v.md) | `module` | Vertical pull-up pad abstraction. |
### `utils`
| Component | Type | Function summary |
| --- | --- | --- |
| [`bin2gray`](docs/reference/utils/bin2gray.md) | `module` | Combinational binary-to-Gray code converter. |
| [`dff`](docs/reference/utils/dff.md) | `module` | Plain D flip-flop primitive. |
| [`dffer`](docs/reference/utils/dffer.md) | `module` | Enabled D flip-flop with asynchronous reset. |
| [`dfferc`](docs/reference/utils/dfferc.md) | `module` | Enabled D flip-flop with configurable reset value. |
| [`dffercn`](docs/reference/utils/dffercn.md) | `module` | Enabled D flip-flop with active-low configurable reset value. |
| [`dfferh`](docs/reference/utils/dfferh.md) | `module` | Enabled D flip-flop with all-one reset value. |
| [`dfferm`](docs/reference/utils/dfferm.md) | `module` | Masked-update D flip-flop with reset. |
| [`dffesr`](docs/reference/utils/dffesr.md) | `module` | Enabled D flip-flop with synchronous reset. |
| [`dffl`](docs/reference/utils/dffl.md) | `module` | Level-sensitive latch primitive. |
| [`dffr`](docs/reference/utils/dffr.md) | `module` | D flip-flop with asynchronous active-low reset. |
| [`dffrc`](docs/reference/utils/dffrc.md) | `module` | D flip-flop with configurable reset value. |
| [`dffrh`](docs/reference/utils/dffrh.md) | `module` | D flip-flop with all-one reset value. |
| [`dffsr`](docs/reference/utils/dffsr.md) | `module` | D flip-flop with synchronous reset. |
| [`edge_det`](docs/reference/utils/edge_det.md) | `module` | Single-bit rising and falling edge detector. |
| [`edge_det_fe`](docs/reference/utils/edge_det_fe.md) | `module` | Single-bit falling-edge detector. |
| [`edge_det_re`](docs/reference/utils/edge_det_re.md) | `module` | Single-bit rising-edge detector. |
| [`edge_det_sync`](docs/reference/utils/edge_det_sync.md) | `module` | Synchronized single-bit rising and falling edge detector. |
| [`edge_det_sync_fe`](docs/reference/utils/edge_det_sync_fe.md) | `module` | Synchronized single-bit falling-edge detector. |
| [`edge_det_sync_re`](docs/reference/utils/edge_det_sync_re.md) | `module` | Synchronized single-bit rising-edge detector. |
| [`fifo`](docs/reference/utils/fifo.md) | `module` | Power-of-two synchronous FIFO with combinational head read. |
| [`gray2bin`](docs/reference/utils/gray2bin.md) | `module` | Combinational Gray-to-binary code converter. |
| [`lfsr_fibonacci`](docs/reference/utils/lfsr_fibonacci.md) | `module` | Fibonacci-form pseudo-random linear-feedback shift register. |
| [`lfsr_galois`](docs/reference/utils/lfsr_galois.md) | `module` | Galois-form pseudo-random linear-feedback shift register. |
| [`ndffr`](docs/reference/utils/ndffr.md) | `module` | Resettable multi-stage synchronizer register chain. |
| [`regfield`](docs/reference/utils/regfield.md) | `module` | Masked register-field update primitive. |
| [`shift_reg`](docs/reference/utils/shift_reg.md) | `module` | Parameterized sequential shift register. |
| [`spill_register`](docs/reference/utils/spill_register.md) | `module` | Two-register spill stage for breaking ready timing paths. |
| [`stream_fifo`](docs/reference/utils/stream_fifo.md) | `module` | Legacy valid/ready wrapper around the synchronous FIFO. |
| [`valid_delay_line`](docs/reference/utils/valid_delay_line.md) | `module` | Valid-only parameterized sequential delay line. |
| [`xchecker`](docs/reference/utils/xchecker.md) | `module` | Simulation unknown-value checker. |
<!-- COMPONENT_REFERENCE:END -->
docs/components.md
+6
View File
@@ -1,5 +1,11 @@
# Component Catalog
The repository [README](../README.md#component-reference) is the canonical,
machine-checked catalog for every declared RTL unit. Each entry links to a
page in [`docs/reference`](reference/README.md) with its exact declaration,
functional behavior, suitable applications, integration constraints, and use
fragment. This document is retained as a curated family-level overview.
## Base and stream
- `bit_count`, `leading_zero_count`, `onehot_check`, and `onehot_to_index` are
docs/datasheet.md
+5
View File
@@ -5,6 +5,11 @@ and are verified with Icarus Verilog and Verilator. The portable behavioral
storage models are for simulation, FPGA prototyping, and generic synthesis;
ASIC projects must replace `tech_*` models through their technology flow.
The per-component integration reference is in [`docs/reference`](reference/README.md).
Each page contains the exact declaration, functional behavior, application
guidance, use fragment, and component-specific constraints. This datasheet and
[`docs/design.md`](design.md) define contracts shared across component families.
The source list additionally contains the self-contained base replacement and
SECDED cells, stream-control cells, and warm-flush CDC wrappers. They depend
only on RTL files in this repository. The SECDED package is ordered before its
docs/design.md
+4
View File
@@ -1,5 +1,9 @@
# Design Contracts
This document records contracts shared across component families. For a
component's exact declaration, local behavior, use fragment, and integration
constraints, start at [`docs/reference`](reference/README.md).
Every component documents its reset and transfer contracts in the source.
Reset assertion may be asynchronous where `rst_n_i` is used; reset release is
synchronized only by the explicit reset/CDC components. Do not treat reset
docs/reference/README.md
+21
View File
@@ -0,0 +1,21 @@
# RTL Reference
One checked-in page exists for every declared SystemVerilog `module`, `interface`, and `package` under `rtl/`. The pages mirror RTL categories and reproduce the canonical source declaration.
After changing a declaration or its integration contract, run `python3 scripts/render_component_docs.py` and then `make docs-check`. The latter rejects stale pages, missing coverage, malformed required sections, and a stale README catalog.
`rtl/verif` contains class-based verification support rather than RTL declarations. `rtl/clkrst/clk_frac_div.sv` is a compatibility source with no declaration because fractional division is intentionally not provided.
## Categories
- `base`: [`bit_count`](base/bit_count.md), [`component_math_pkg`](base/component_math_pkg.md), [`counting_bloom_filter`](base/counting_bloom_filter.md), [`credit_pool`](base/credit_pool.md), [`hash_indicator_bank`](base/hash_indicator_bank.md), [`index_to_onehot`](base/index_to_onehot.md), [`interval_ones_mask`](base/interval_ones_mask.md), [`leading_zero_count`](base/leading_zero_count.md), [`loop_trip_counter`](base/loop_trip_counter.md), [`onehot_check`](base/onehot_check.md), [`onehot_to_index`](base/onehot_to_index.md), [`permutation_hash`](base/permutation_hash.md), [`plru_victim_selector`](base/plru_victim_selector.md), [`prefix_ones_mask`](base/prefix_ones_mask.md), [`retry_backoff`](base/retry_backoff.md), [`sample_majority_filter`](base/sample_majority_filter.md), [`secded_decode`](base/secded_decode.md), [`secded_encode`](base/secded_encode.md), [`secded_layout_pkg`](base/secded_layout_pkg.md), [`signal_sink`](base/signal_sink.md), [`signal_tap`](base/signal_tap.md), [`stable_level_filter`](base/stable_level_filter.md), [`trailing_zero_count`](base/trailing_zero_count.md)
- `bus`: [`address_map`](bus/address_map.md), [`address_range_decoder`](bus/address_range_decoder.md), [`address_region`](bus/address_region.md), [`address_set_decoder`](bus/address_set_decoder.md)
- `cdc`: [`async_gray_queue`](cdc/async_gray_queue.md), [`async_reqack`](cdc/async_reqack.md), [`cdc_2phase`](cdc/cdc_2phase.md), [`cdc_2phase_dst`](cdc/cdc_2phase_dst.md), [`cdc_2phase_src`](cdc/cdc_2phase_src.md), [`cdc_2phase_warm_flush`](cdc/cdc_2phase_warm_flush.md), [`cdc_event_bridge`](cdc/cdc_event_bridge.md), [`cdc_event_bridge_ack`](cdc/cdc_event_bridge_ack.md), [`cdc_fifo`](cdc/cdc_fifo.md), [`cdc_fifo_dst`](cdc/cdc_fifo_dst.md), [`cdc_fifo_src`](cdc/cdc_fifo_src.md), [`cdc_fifo_warm_flush`](cdc/cdc_fifo_warm_flush.md), [`cdc_remote_clear_request`](cdc/cdc_remote_clear_request.md), [`cdc_reset_barrier`](cdc/cdc_reset_barrier.md), [`cdc_sync`](cdc/cdc_sync.md), [`cdc_sync_det`](cdc/cdc_sync_det.md), [`cdc_warm_flush_controller`](cdc/cdc_warm_flush_controller.md), [`clearable_async_queue`](cdc/clearable_async_queue.md), [`clearable_two_phase_link`](cdc/clearable_two_phase_link.md), [`four_phase_mailbox`](cdc/four_phase_mailbox.md), [`isochronous_handshake`](cdc/isochronous_handshake.md), [`isochronous_stream_buffer`](cdc/isochronous_stream_buffer.md), [`synchronized_edge`](cdc/synchronized_edge.md), [`test_reset_synchronizer`](cdc/test_reset_synchronizer.md), [`two_phase_async_queue`](cdc/two_phase_async_queue.md)
- `clkrst`: [`clk_int_div_simple`](clkrst/clk_int_div_simple.md), [`clk_int_even_div`](clkrst/clk_int_even_div.md), [`clk_int_even_div_static`](clkrst/clk_int_even_div_static.md), [`clk_int_odd_div_static`](clkrst/clk_int_odd_div_static.md), [`peak_delta_counter`](clkrst/peak_delta_counter.md), [`rs_counter`](clkrst/rs_counter.md), [`rs_delta_counter`](clkrst/rs_delta_counter.md), [`rst_sync`](clkrst/rst_sync.md)
- `clock`: [`clock_divider`](clock/clock_divider.md), [`clock_or_tree`](clock/clock_or_tree.md), [`safe_clock_mux`](clock/safe_clock_mux.md)
- `interface`: [`ahbl_if`](interface/ahbl_if.md), [`apb4_if`](interface/apb4_if.md), [`apb4_pure_if`](interface/apb4_pure_if.md), [`axi4_addr_gen`](interface/axi4_addr_gen.md), [`axi4_if`](interface/axi4_if.md), [`ram_if`](interface/ram_if.md), [`ready_valid_if`](interface/ready_valid_if.md), [`ribp_if`](interface/ribp_if.md)
- `memory`: [`circular_store`](memory/circular_store.md), [`memory_bank_adapter`](memory/memory_bank_adapter.md), [`memory_bank_adapter_detail`](memory/memory_bank_adapter_detail.md), [`sync_memory`](memory/sync_memory.md), [`tag_order_queue`](memory/tag_order_queue.md)
- `model`: [`apb4_master_model`](model/apb4_master_model.md)
- `stream`: [`bypass_buffer`](stream/bypass_buffer.md), [`latest_value_stream`](stream/latest_value_stream.md), [`memory_response_bridge`](stream/memory_response_bridge.md), [`round_robin_arbiter`](stream/round_robin_arbiter.md), [`stream_buffer`](stream/stream_buffer.md), [`stream_collector`](stream/stream_collector.md), [`stream_credit_limiter`](stream/stream_credit_limiter.md), [`stream_crossbar`](stream/stream_crossbar.md), [`stream_delay_injector`](stream/stream_delay_injector.md), [`stream_discard_gate`](stream/stream_discard_gate.md), [`stream_elastic_register`](stream/stream_elastic_register.md), [`stream_fair_arbiter`](stream/stream_fair_arbiter.md), [`stream_fallthrough_buffer`](stream/stream_fallthrough_buffer.md), [`stream_queue`](stream/stream_queue.md), [`stream_replicator`](stream/stream_replicator.md), [`stream_router`](stream/stream_router.md), [`stream_selector`](stream/stream_selector.md), [`stream_shuffle_network`](stream/stream_shuffle_network.md), [`stream_window_guard`](stream/stream_window_guard.md)
- `tech`: [`clk_an2`](tech/clk_an2.md), [`clk_buf`](tech/clk_buf.md), [`clk_icg`](tech/clk_icg.md), [`clk_icg2`](tech/clk_icg2.md), [`clk_mux2`](tech/clk_mux2.md), [`clk_n`](tech/clk_n.md), [`clk_nd2`](tech/clk_nd2.md), [`clk_xor2`](tech/clk_xor2.md), [`osc_pad_h`](tech/osc_pad_h.md), [`osc_pad_v`](tech/osc_pad_v.md), [`tech_pll`](tech/tech_pll.md), [`tech_ram`](tech/tech_ram.md), [`tech_ram_bm`](tech/tech_ram_bm.md), [`tech_regfile`](tech/tech_regfile.md), [`tech_regfile_bm`](tech/tech_regfile_bm.md), [`tri_pd_pad_h`](tech/tri_pd_pad_h.md), [`tri_pd_pad_v`](tech/tri_pd_pad_v.md), [`tri_pdu_pad_h`](tech/tri_pdu_pad_h.md), [`tri_pdu_pad_v`](tech/tri_pdu_pad_v.md), [`tri_pu_pad_h`](tech/tri_pu_pad_h.md), [`tri_pu_pad_v`](tech/tri_pu_pad_v.md)
- `utils`: [`bin2gray`](utils/bin2gray.md), [`dff`](utils/dff.md), [`dffer`](utils/dffer.md), [`dfferc`](utils/dfferc.md), [`dffercn`](utils/dffercn.md), [`dfferh`](utils/dfferh.md), [`dfferm`](utils/dfferm.md), [`dffesr`](utils/dffesr.md), [`dffl`](utils/dffl.md), [`dffr`](utils/dffr.md), [`dffrc`](utils/dffrc.md), [`dffrh`](utils/dffrh.md), [`dffsr`](utils/dffsr.md), [`edge_det`](utils/edge_det.md), [`edge_det_fe`](utils/edge_det_fe.md), [`edge_det_re`](utils/edge_det_re.md), [`edge_det_sync`](utils/edge_det_sync.md), [`edge_det_sync_fe`](utils/edge_det_sync_fe.md), [`edge_det_sync_re`](utils/edge_det_sync_re.md), [`fifo`](utils/fifo.md), [`gray2bin`](utils/gray2bin.md), [`lfsr_fibonacci`](utils/lfsr_fibonacci.md), [`lfsr_galois`](utils/lfsr_galois.md), [`ndffr`](utils/ndffr.md), [`regfield`](utils/regfield.md), [`shift_reg`](utils/shift_reg.md), [`spill_register`](utils/spill_register.md), [`stream_fifo`](utils/stream_fifo.md), [`valid_delay_line`](utils/valid_delay_line.md), [`xchecker`](utils/xchecker.md)
docs/reference/base/bit_count.md
+69
View File
@@ -0,0 +1,69 @@
# bit_count
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/bit_ops.sv`](../../../rtl/base/bit_ops.sv) |
| Availability | Synthesizable RTL |
## Summary
Combinational population-count primitive.
## Functional Behavior
Combinational population-count primitive. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(WIDTH + 1)` |
## Interface Definition
```systemverilog
module bit_count #(
parameter int WIDTH = 32,
parameter int COUNT_WIDTH = $clog2(WIDTH + 1)
) (
input logic [ WIDTH-1:0] value_i,
output logic [COUNT_WIDTH-1:0] count_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `value_i` | `input` | `input logic [ WIDTH-1:0] value_i` |
| `count_o` | `output` | `output logic [COUNT_WIDTH-1:0] count_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
bit_count #(
.WIDTH(WIDTH),
.COUNT_WIDTH(COUNT_WIDTH)
) u_bit_count (
.value_i(value_i),
.count_o(count_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/component_math_pkg.md
+66
View File
@@ -0,0 +1,66 @@
# component_math_pkg
| Property | Value |
| --- | --- |
| Kind | `package` |
| RTL source | [`rtl/base/component_math_pkg.sv`](../../../rtl/base/component_math_pkg.sv) |
| Availability | SystemVerilog integration API |
## Summary
Compile-time arithmetic helpers for parameterized components.
## Functional Behavior
Compile-time arithmetic helpers for parameterized components. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The package declaration below is canonical for exported types, constants, and functions.
## Interface Definition
```systemverilog
package component_math_pkg;
function automatic int unsigned ceil_divide(input int unsigned numerator,
input int unsigned denominator);
if (denominator == 0) begin
$fatal(1, "ceil_divide: denominator must be non-zero");
end
return (numerator / denominator) + ((numerator % denominator) != 0);
endfunction
function automatic int unsigned index_bits(input int unsigned item_count);
return (item_count > 1) ? $clog2(item_count) : 1;
endfunction
function automatic int unsigned counter_bits(input int unsigned maximum);
return index_bits(maximum + 1);
endfunction
function automatic bit power_of_two(input int unsigned value);
return (value != 0) && ((value & (value - 1)) == 0);
endfunction
endpackage
```
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
import component_math_pkg::*;
// Use exported types, constants, or functions here.
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/counting_bloom_filter.md
+114
View File
@@ -0,0 +1,114 @@
# counting_bloom_filter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/hash_cells.sv`](../../../rtl/base/hash_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Counting Bloom filter with explicit counter saturation.
## Functional Behavior
Counting Bloom filter with explicit counter saturation. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `HASH_WIDTH` | `parameter int HASH_WIDTH = 5` |
| `HASHES` | `parameter int HASHES = 3` |
| `BUCKET_WIDTH` | `parameter int BUCKET_WIDTH = 4` |
| `ROUNDS` | `parameter int ROUNDS = 2` |
| `SEED` | `parameter logic [31:0] SEED = 32'hC0DE_1234` |
## Interface Definition
```systemverilog
module counting_bloom_filter #(
parameter int DATA_WIDTH = 32,
parameter int HASH_WIDTH = 5,
parameter int HASHES = 3,
parameter int BUCKET_WIDTH = 4,
parameter int ROUNDS = 2,
parameter logic [31:0] SEED = 32'hC0DE_1234
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic [DATA_WIDTH-1:0] lookup_data_i,
output logic member_o,
input logic [DATA_WIDTH-1:0] insert_data_i,
input logic insert_i,
input logic [DATA_WIDTH-1:0] remove_data_i,
input logic remove_i,
output logic [ HASH_WIDTH:0] usage_o,
output logic empty_o,
output logic full_o,
output logic saturated_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `lookup_data_i` | `input` | `input logic [DATA_WIDTH-1:0] lookup_data_i` |
| `member_o` | `output` | `output logic member_o` |
| `insert_data_i` | `input` | `input logic [DATA_WIDTH-1:0] insert_data_i` |
| `insert_i` | `input` | `input logic insert_i` |
| `remove_data_i` | `input` | `input logic [DATA_WIDTH-1:0] remove_data_i` |
| `remove_i` | `input` | `input logic remove_i` |
| `usage_o` | `output` | `output logic [ HASH_WIDTH:0] usage_o` |
| `empty_o` | `output` | `output logic empty_o` |
| `full_o` | `output` | `output logic full_o` |
| `saturated_o` | `output` | `output logic saturated_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
counting_bloom_filter #(
.DATA_WIDTH(DATA_WIDTH),
.HASH_WIDTH(HASH_WIDTH),
.HASHES(HASHES),
.BUCKET_WIDTH(BUCKET_WIDTH),
.ROUNDS(ROUNDS),
.SEED(SEED)
) u_counting_bloom_filter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.lookup_data_i(lookup_data_i),
.member_o(member_o),
.insert_data_i(insert_data_i),
.insert_i(insert_i),
.remove_data_i(remove_data_i),
.remove_i(remove_i),
.usage_o(usage_o),
.empty_o(empty_o),
.full_o(full_o),
.saturated_o(saturated_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/credit_pool.md
+93
View File
@@ -0,0 +1,93 @@
# credit_pool
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/control_cells.sv`](../../../rtl/base/control_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Saturating available-credit tracker for resource flow control.
## Functional Behavior
Tracks returned (`give_i`) and consumed (`take_i`) credits. Simultaneous give/take has zero net change; full, empty, and one-from-full outputs observe the current state.
## Suitable Applications
Use for bounded request windows, queue slots, buffer credits, and response throttling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `MAX_CREDITS` | `parameter int MAX_CREDITS = 4` |
| `EMPTY_ON_RESET` | `parameter bit EMPTY_ON_RESET = 1'b0` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(MAX_CREDITS + 1)` |
## Interface Definition
```systemverilog
module credit_pool #(
parameter int MAX_CREDITS = 4,
parameter bit EMPTY_ON_RESET = 1'b0,
parameter int COUNT_WIDTH = $clog2(MAX_CREDITS + 1)
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic give_i,
input logic take_i,
output logic [COUNT_WIDTH-1:0] available_o,
output logic has_credit_o,
output logic one_from_full_o,
output logic full_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `give_i` | `input` | `input logic give_i` |
| `take_i` | `input` | `input logic take_i` |
| `available_o` | `output` | `output logic [COUNT_WIDTH-1:0] available_o` |
| `has_credit_o` | `output` | `output logic has_credit_o` |
| `one_from_full_o` | `output` | `output logic one_from_full_o` |
| `full_o` | `output` | `output logic full_o` |
## Integration and Use
Do not issue unpaired gives or takes. `clear_i` is synchronous; choose `EMPTY_ON_RESET` to match resource ownership after reset.
```systemverilog
credit_pool #(
.MAX_CREDITS(MAX_CREDITS),
.EMPTY_ON_RESET(EMPTY_ON_RESET),
.COUNT_WIDTH(COUNT_WIDTH)
) u_credit_pool (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.give_i(give_i),
.take_i(take_i),
.available_o(available_o),
.has_credit_o(has_credit_o),
.one_from_full_o(one_from_full_o),
.full_o(full_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/hash_indicator_bank.md
+78
View File
@@ -0,0 +1,78 @@
# hash_indicator_bank
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/hash_cells.sv`](../../../rtl/base/hash_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Multi-hash indicator-vector generator.
## Functional Behavior
Multi-hash indicator-vector generator. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `HASH_WIDTH` | `parameter int HASH_WIDTH = 5` |
| `HASHES` | `parameter int HASHES = 3` |
| `ROUNDS` | `parameter int ROUNDS = 2` |
| `SEED` | `parameter logic [31:0] SEED = 32'hC0DE_1234` |
## Interface Definition
```systemverilog
module hash_indicator_bank #(
parameter int DATA_WIDTH = 32,
parameter int HASH_WIDTH = 5,
parameter int HASHES = 3,
parameter int ROUNDS = 2,
parameter logic [31:0] SEED = 32'hC0DE_1234
) (
input logic [ DATA_WIDTH-1:0] data_i,
output logic [(1 << HASH_WIDTH)-1:0] indicator_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `data_i` | `input` | `input logic [ DATA_WIDTH-1:0] data_i` |
| `indicator_o` | `output` | `output logic [(1 << HASH_WIDTH)-1:0] indicator_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
hash_indicator_bank #(
.DATA_WIDTH(DATA_WIDTH),
.HASH_WIDTH(HASH_WIDTH),
.HASHES(HASHES),
.ROUNDS(ROUNDS),
.SEED(SEED)
) u_hash_indicator_bank (
.data_i(data_i),
.indicator_o(indicator_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/index_to_onehot.md
+75
View File
@@ -0,0 +1,75 @@
# index_to_onehot
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/mask_cells.sv`](../../../rtl/base/mask_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Bounded index-to-one-hot decoder.
## Functional Behavior
Bounded index-to-one-hot decoder. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1` |
## Interface Definition
```systemverilog
module index_to_onehot #(
parameter int WIDTH = 32,
parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1
) (
input logic [INDEX_WIDTH-1:0] index_i,
input logic enable_i,
output logic [ WIDTH-1:0] onehot_o,
output logic valid_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `index_i` | `input` | `input logic [INDEX_WIDTH-1:0] index_i` |
| `enable_i` | `input` | `input logic enable_i` |
| `onehot_o` | `output` | `output logic [ WIDTH-1:0] onehot_o` |
| `valid_o` | `output` | `output logic valid_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
index_to_onehot #(
.WIDTH(WIDTH),
.INDEX_WIDTH(INDEX_WIDTH)
) u_index_to_onehot (
.index_i(index_i),
.enable_i(enable_i),
.onehot_o(onehot_o),
.valid_o(valid_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/interval_ones_mask.md
+72
View File
@@ -0,0 +1,72 @@
# interval_ones_mask
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/mask_cells.sv`](../../../rtl/base/mask_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Inclusive contiguous mask generator between two bit positions.
## Functional Behavior
Inclusive contiguous mask generator between two bit positions. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1` |
## Interface Definition
```systemverilog
module interval_ones_mask #(
parameter int WIDTH = 32,
parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1
) (
input logic [INDEX_WIDTH-1:0] lower_i,
input logic [INDEX_WIDTH-1:0] upper_i,
output logic [ WIDTH-1:0] mask_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `lower_i` | `input` | `input logic [INDEX_WIDTH-1:0] lower_i` |
| `upper_i` | `input` | `input logic [INDEX_WIDTH-1:0] upper_i` |
| `mask_o` | `output` | `output logic [ WIDTH-1:0] mask_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
interval_ones_mask #(
.WIDTH(WIDTH),
.INDEX_WIDTH(INDEX_WIDTH)
) u_interval_ones_mask (
.lower_i(lower_i),
.upper_i(upper_i),
.mask_o(mask_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/leading_zero_count.md
+72
View File
@@ -0,0 +1,72 @@
# leading_zero_count
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/bit_ops.sv`](../../../rtl/base/bit_ops.sv) |
| Availability | Synthesizable RTL |
## Summary
Combinational leading-zero counter with all-zero indication.
## Functional Behavior
Combinational leading-zero counter with all-zero indication. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(WIDTH + 1)` |
## Interface Definition
```systemverilog
module leading_zero_count #(
parameter int WIDTH = 32,
parameter int COUNT_WIDTH = $clog2(WIDTH + 1)
) (
input logic [ WIDTH-1:0] value_i,
output logic [COUNT_WIDTH-1:0] count_o,
output logic all_zero_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `value_i` | `input` | `input logic [ WIDTH-1:0] value_i` |
| `count_o` | `output` | `output logic [COUNT_WIDTH-1:0] count_o` |
| `all_zero_o` | `output` | `output logic all_zero_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
leading_zero_count #(
.WIDTH(WIDTH),
.COUNT_WIDTH(COUNT_WIDTH)
) u_leading_zero_count (
.value_i(value_i),
.count_o(count_o),
.all_zero_o(all_zero_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/loop_trip_counter.md
+87
View File
@@ -0,0 +1,87 @@
# loop_trip_counter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/control_cells.sv`](../../../rtl/base/control_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Programmable terminal-count loop counter.
## Functional Behavior
Increments by `step_i` on `advance_i`. When the stored value equals `limit_i`, the next advance pulses `wrap_o` and returns the state to zero.
## Suitable Applications
Use for bounded loops, beat scheduling, table traversal, and phase sequencing.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 4` |
## Interface Definition
```systemverilog
module loop_trip_counter #(
parameter int DATA_WIDTH = 4
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic advance_i,
input logic [DATA_WIDTH-1:0] step_i,
input logic [DATA_WIDTH-1:0] limit_i,
output logic [DATA_WIDTH-1:0] value_o,
output logic at_limit_o,
output logic wrap_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `advance_i` | `input` | `input logic advance_i` |
| `step_i` | `input` | `input logic [DATA_WIDTH-1:0] step_i` |
| `limit_i` | `input` | `input logic [DATA_WIDTH-1:0] limit_i` |
| `value_o` | `output` | `output logic [DATA_WIDTH-1:0] value_o` |
| `at_limit_o` | `output` | `output logic at_limit_o` |
| `wrap_o` | `output` | `output logic wrap_o` |
## Integration and Use
A nonzero step must reach the limit exactly. This is not an arbitrary modulo counter; skipping the terminal value is an error.
```systemverilog
loop_trip_counter #(
.DATA_WIDTH(DATA_WIDTH)
) u_loop_trip_counter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.advance_i(advance_i),
.step_i(step_i),
.limit_i(limit_i),
.value_o(value_o),
.at_limit_o(at_limit_o),
.wrap_o(wrap_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/onehot_check.md
+69
View File
@@ -0,0 +1,69 @@
# onehot_check
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/bit_ops.sv`](../../../rtl/base/bit_ops.sv) |
| Availability | Synthesizable RTL |
## Summary
One-hot validity checker with optional all-zero acceptance.
## Functional Behavior
One-hot validity checker with optional all-zero acceptance. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `ALLOW_ZERO` | `parameter bit ALLOW_ZERO = 1'b0` |
## Interface Definition
```systemverilog
module onehot_check #(
parameter int WIDTH = 32,
parameter bit ALLOW_ZERO = 1'b0
) (
input logic [WIDTH-1:0] value_i,
output logic valid_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `value_i` | `input` | `input logic [WIDTH-1:0] value_i` |
| `valid_o` | `output` | `output logic valid_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
onehot_check #(
.WIDTH(WIDTH),
.ALLOW_ZERO(ALLOW_ZERO)
) u_onehot_check (
.value_i(value_i),
.valid_o(valid_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/onehot_to_index.md
+72
View File
@@ -0,0 +1,72 @@
# onehot_to_index
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/bit_ops.sv`](../../../rtl/base/bit_ops.sv) |
| Availability | Synthesizable RTL |
## Summary
One-hot vector to index converter with validity output.
## Functional Behavior
One-hot vector to index converter with validity output. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1` |
## Interface Definition
```systemverilog
module onehot_to_index #(
parameter int WIDTH = 32,
parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1
) (
input logic [ WIDTH-1:0] value_i,
output logic [INDEX_WIDTH-1:0] index_o,
output logic valid_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `value_i` | `input` | `input logic [ WIDTH-1:0] value_i` |
| `index_o` | `output` | `output logic [INDEX_WIDTH-1:0] index_o` |
| `valid_o` | `output` | `output logic valid_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
onehot_to_index #(
.WIDTH(WIDTH),
.INDEX_WIDTH(INDEX_WIDTH)
) u_onehot_to_index (
.value_i(value_i),
.index_o(index_o),
.valid_o(valid_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/permutation_hash.md
+81
View File
@@ -0,0 +1,81 @@
# permutation_hash
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/hash_cells.sv`](../../../rtl/base/hash_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Deterministic non-cryptographic bit-mixing hash.
## Functional Behavior
Deterministic non-cryptographic bit-mixing hash. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `HASH_WIDTH` | `parameter int HASH_WIDTH = 5` |
| `ROUNDS` | `parameter int ROUNDS = 2` |
| `PERMUTE_KEY` | `parameter logic [31:0] PERMUTE_KEY = 32'h11C0_FFEE` |
| `MIX_KEY` | `parameter logic [31:0] MIX_KEY = 32'h7A31_9B45` |
## Interface Definition
```systemverilog
module permutation_hash #(
parameter int DATA_WIDTH = 32,
parameter int HASH_WIDTH = 5,
parameter int ROUNDS = 2,
parameter logic [31:0] PERMUTE_KEY = 32'h11C0_FFEE,
parameter logic [31:0] MIX_KEY = 32'h7A31_9B45
) (
input logic [ DATA_WIDTH-1:0] data_i,
output logic [ HASH_WIDTH-1:0] hash_o,
output logic [(1 << HASH_WIDTH)-1:0] indicator_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `data_i` | `input` | `input logic [ DATA_WIDTH-1:0] data_i` |
| `hash_o` | `output` | `output logic [ HASH_WIDTH-1:0] hash_o` |
| `indicator_o` | `output` | `output logic [(1 << HASH_WIDTH)-1:0] indicator_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
permutation_hash #(
.DATA_WIDTH(DATA_WIDTH),
.HASH_WIDTH(HASH_WIDTH),
.ROUNDS(ROUNDS),
.PERMUTE_KEY(PERMUTE_KEY),
.MIX_KEY(MIX_KEY)
) u_permutation_hash (
.data_i(data_i),
.hash_o(hash_o),
.indicator_o(indicator_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/plru_victim_selector.md
+75
View File
@@ -0,0 +1,75 @@
# plru_victim_selector
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/replacement.sv`](../../../rtl/base/replacement.sv) |
| Availability | Synthesizable RTL |
## Summary
Power-of-two pseudo-LRU cache-way victim selector.
## Functional Behavior
Power-of-two pseudo-LRU cache-way victim selector. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WAYS` | `parameter int WAYS = 4` |
## Interface Definition
```systemverilog
module plru_victim_selector #(
parameter int WAYS = 4
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic [WAYS-1:0] touch_i,
output logic [WAYS-1:0] victim_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `touch_i` | `input` | `input logic [WAYS-1:0] touch_i` |
| `victim_o` | `output` | `output logic [WAYS-1:0] victim_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
plru_victim_selector #(
.WAYS(WAYS)
) u_plru_victim_selector (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.touch_i(touch_i),
.victim_o(victim_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/prefix_ones_mask.md
+69
View File
@@ -0,0 +1,69 @@
# prefix_ones_mask
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/mask_cells.sv`](../../../rtl/base/mask_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Low-order prefix-ones mask generator.
## Functional Behavior
Low-order prefix-ones mask generator. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1` |
## Interface Definition
```systemverilog
module prefix_ones_mask #(
parameter int WIDTH = 32,
parameter int INDEX_WIDTH = (WIDTH > 1) ? $clog2(WIDTH) : 1
) (
input logic [INDEX_WIDTH-1:0] position_i,
output logic [ WIDTH-1:0] mask_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `position_i` | `input` | `input logic [INDEX_WIDTH-1:0] position_i` |
| `mask_o` | `output` | `output logic [ WIDTH-1:0] mask_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
prefix_ones_mask #(
.WIDTH(WIDTH),
.INDEX_WIDTH(INDEX_WIDTH)
) u_prefix_ones_mask (
.position_i(position_i),
.mask_o(mask_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/retry_backoff.md
+87
View File
@@ -0,0 +1,87 @@
# retry_backoff
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/control_cells.sv`](../../../rtl/base/control_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Pseudo-random exponential retry-delay controller.
## Functional Behavior
Samples a local Galois-LFSR through an expanding low-bit mask after failure. A nonzero sampled delay deasserts `ready_o` until its wait counter reaches zero; success clears the retry window.
## Suitable Applications
Use for contention retries, shared-resource collision recovery, and congestion backoff.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 16` |
| `MAX_EXPONENT` | `parameter int MAX_EXPONENT = DATA_WIDTH` |
| `POLYNOMIAL` | `parameter logic [DATA_WIDTH-1:0] POLYNOMIAL = 16'hB400` |
| `SEED` | `parameter logic [DATA_WIDTH-1:0] SEED = {{(DATA_WIDTH - 1) {1'b0}}, 1'b1}` |
## Interface Definition
```systemverilog
module retry_backoff #(
parameter int DATA_WIDTH = 16,
parameter int MAX_EXPONENT = DATA_WIDTH,
parameter logic [DATA_WIDTH-1:0] POLYNOMIAL = 16'hB400,
parameter logic [DATA_WIDTH-1:0] SEED = {{(DATA_WIDTH - 1) {1'b0}}, 1'b1}
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic failure_i,
input logic success_i,
output logic ready_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `failure_i` | `input` | `input logic failure_i` |
| `success_i` | `input` | `input logic success_i` |
| `ready_o` | `output` | `output logic ready_o` |
## Integration and Use
Gate attempts with `ready_o`. A failure during an active wait replaces the delay, while success cancels it.
```systemverilog
retry_backoff #(
.DATA_WIDTH(DATA_WIDTH),
.MAX_EXPONENT(MAX_EXPONENT),
.POLYNOMIAL(POLYNOMIAL),
.SEED(SEED)
) u_retry_backoff (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.failure_i(failure_i),
.success_i(success_i),
.ready_o(ready_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/sample_majority_filter.md
+84
View File
@@ -0,0 +1,84 @@
# sample_majority_filter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/control_cells.sv`](../../../rtl/base/control_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Sliding-window N-of-M single-bit sample filter.
## Functional Behavior
Retains the most recent enabled samples and asserts when their population count reaches `ASSERT_THRESHOLD`; the default is strict majority.
## Suitable Applications
Use for noisy status pins, repeated sensor samples, redundant indications, and temporal voting.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WINDOW_LENGTH` | `parameter int WINDOW_LENGTH = 4` |
| `ASSERT_THRESHOLD` | `parameter int ASSERT_THRESHOLD = (WINDOW_LENGTH / 2) + 1` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(WINDOW_LENGTH + 1)` |
## Interface Definition
```systemverilog
module sample_majority_filter #(
parameter int WINDOW_LENGTH = 4,
parameter int ASSERT_THRESHOLD = (WINDOW_LENGTH / 2) + 1,
parameter int COUNT_WIDTH = $clog2(WINDOW_LENGTH + 1)
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic enable_i,
input logic sample_i,
output logic level_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `enable_i` | `input` | `input logic enable_i` |
| `sample_i` | `input` | `input logic sample_i` |
| `level_o` | `output` | `output logic level_o` |
## Integration and Use
This is a population filter, not a synchronizer or consecutive-stability filter. Choose the threshold deliberately.
```systemverilog
sample_majority_filter #(
.WINDOW_LENGTH(WINDOW_LENGTH),
.ASSERT_THRESHOLD(ASSERT_THRESHOLD),
.COUNT_WIDTH(COUNT_WIDTH)
) u_sample_majority_filter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.enable_i(enable_i),
.sample_i(sample_i),
.level_o(level_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/secded_decode.md
+78
View File
@@ -0,0 +1,78 @@
# secded_decode
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/ecc_secded.sv`](../../../rtl/base/ecc_secded.sv) |
| Availability | Synthesizable RTL |
## Summary
Extended-Hamming SECDED decoder, corrector, and error classifier.
## Functional Behavior
Computes a Hamming syndrome and overall parity, corrects a correctable single-bit fault, reports an overall-parity-only error, and flags uncorrectable double errors without changing the codeword.
## Suitable Applications
Use on protected memory reads and protected interconnect payloads.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 64` |
## Interface Definition
```systemverilog
module secded_decode #(
parameter int DATA_WIDTH = 64
) (
input logic [DATA_WIDTH+secded_layout_pkg::check_bits_for(DATA_WIDTH):0] code_i,
output logic [DATA_WIDTH-1:0] data_o,
output logic [secded_layout_pkg::check_bits_for(DATA_WIDTH)-1:0] syndrome_o,
output logic corrected_o,
output logic overall_parity_error_o,
output logic uncorrectable_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `code_i` | `input` | `input logic [DATA_WIDTH+secded_layout_pkg::check_bits_for(DATA_WIDTH):0] code_i` |
| `data_o` | `output` | `output logic [DATA_WIDTH-1:0] data_o` |
| `syndrome_o` | `output` | `output logic [secded_layout_pkg::check_bits_for(DATA_WIDTH)-1:0] syndrome_o` |
| `corrected_o` | `output` | `output logic corrected_o` |
| `overall_parity_error_o` | `output` | `output logic overall_parity_error_o` |
| `uncorrectable_o` | `output` | `output logic uncorrectable_o` |
## Integration and Use
Treat decoded data as invalid when `uncorrectable_o` is high and use exactly the matching encoder geometry.
```systemverilog
secded_decode #(
.DATA_WIDTH(DATA_WIDTH)
) u_secded_decode (
.code_i(code_i),
.data_o(data_o),
.syndrome_o(syndrome_o),
.corrected_o(corrected_o),
.overall_parity_error_o(overall_parity_error_o),
.uncorrectable_o(uncorrectable_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/secded_encode.md
+66
View File
@@ -0,0 +1,66 @@
# secded_encode
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/ecc_secded.sv`](../../../rtl/base/ecc_secded.sv) |
| Availability | Synthesizable RTL |
## Summary
Extended-Hamming SECDED encoder.
## Functional Behavior
Places data in the shared SECDED layout, generates Hamming parity positions, and appends overall parity for single-error correction and double-error detection.
## Suitable Applications
Use before writing protected memories or sending protected link data.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 64` |
## Interface Definition
```systemverilog
module secded_encode #(
parameter int DATA_WIDTH = 64
) (
input logic [ DATA_WIDTH-1:0] data_i,
output logic [DATA_WIDTH+secded_layout_pkg::check_bits_for(DATA_WIDTH):0] code_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `data_i` | `input` | `input logic [ DATA_WIDTH-1:0] data_i` |
| `code_o` | `output` | `output logic [DATA_WIDTH+secded_layout_pkg::check_bits_for(DATA_WIDTH):0] code_o` |
## Integration and Use
Pair only with `secded_decode` built from the same parameters and layout package.
```systemverilog
secded_encode #(
.DATA_WIDTH(DATA_WIDTH)
) u_secded_encode (
.data_i(data_i),
.code_o(code_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/secded_layout_pkg.md
+63
View File
@@ -0,0 +1,63 @@
# secded_layout_pkg
| Property | Value |
| --- | --- |
| Kind | `package` |
| RTL source | [`rtl/base/ecc_secded.sv`](../../../rtl/base/ecc_secded.sv) |
| Availability | SystemVerilog integration API |
## Summary
Shared SECDED codeword-layout helpers.
## Functional Behavior
Shared SECDED codeword-layout helpers. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The package declaration below is canonical for exported types, constants, and functions.
## Interface Definition
```systemverilog
package secded_layout_pkg;
function automatic integer check_bits_for(input integer data_width);
integer check_bits;
begin
check_bits = 0;
while ((1 << check_bits) < (data_width + check_bits + 1)) begin
check_bits++;
end
check_bits_for = check_bits;
end
endfunction
function automatic logic is_check_position(input int position);
begin
is_check_position = (position > 0) && ((position & (position - 1)) == 0);
end
endfunction
endpackage
```
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
import secded_layout_pkg::*;
// Use exported types, constants, or functions here.
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/signal_sink.md
+55
View File
@@ -0,0 +1,55 @@
# signal_sink
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/signal_helpers.sv`](../../../rtl/base/signal_helpers.sv) |
| Availability | Synthesizable RTL |
## Summary
Intentional unused-signal terminator.
## Functional Behavior
Intentional unused-signal terminator. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
module signal_sink (
input logic signal_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `signal_i` | `input` | `input logic signal_i` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
signal_sink u_signal_sink (
.signal_i(signal_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/signal_tap.md
+66
View File
@@ -0,0 +1,66 @@
# signal_tap
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/signal_helpers.sv`](../../../rtl/base/signal_helpers.sv) |
| Availability | Synthesizable RTL |
## Summary
Named combinational signal pass-through for observability.
## Functional Behavior
Named combinational signal pass-through for observability. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 1` |
## Interface Definition
```systemverilog
module signal_tap #(
parameter int DATA_WIDTH = 1
) (
input logic [DATA_WIDTH-1:0] signal_i,
output logic [DATA_WIDTH-1:0] signal_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `signal_i` | `input` | `input logic [DATA_WIDTH-1:0] signal_i` |
| `signal_o` | `output` | `output logic [DATA_WIDTH-1:0] signal_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
signal_tap #(
.DATA_WIDTH(DATA_WIDTH)
) u_signal_tap (
.signal_i(signal_i),
.signal_o(signal_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/stable_level_filter.md
+84
View File
@@ -0,0 +1,84 @@
# stable_level_filter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/control_cells.sv`](../../../rtl/base/control_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Consecutive-sample debounce and stability filter.
## Functional Behavior
Changes the output only after the sampled level differs from the current output for `STABLE_CYCLES` enabled consecutive clocks. `restart_i` accepts the current sample immediately.
## Suitable Applications
Use for debounced controls, lock indications, slow GPIO state, and reset-status qualification.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `STABLE_CYCLES` | `parameter int STABLE_CYCLES = 4` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = (STABLE_CYCLES > 1) ? $clog2(STABLE_CYCLES) : 1` |
## Interface Definition
```systemverilog
module stable_level_filter #(
parameter int STABLE_CYCLES = 4,
parameter int COUNT_WIDTH = (STABLE_CYCLES > 1) ? $clog2(STABLE_CYCLES) : 1
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic restart_i,
input logic enable_i,
input logic sample_i,
output logic level_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `restart_i` | `input` | `input logic restart_i` |
| `enable_i` | `input` | `input logic enable_i` |
| `sample_i` | `input` | `input logic sample_i` |
| `level_o` | `output` | `output logic level_o` |
## Integration and Use
Synchronize an asynchronous source first. Disabling the filter clears accumulated evidence; `STABLE_CYCLES=1` accepts every enabled sample.
```systemverilog
stable_level_filter #(
.STABLE_CYCLES(STABLE_CYCLES),
.COUNT_WIDTH(COUNT_WIDTH)
) u_stable_level_filter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.restart_i(restart_i),
.enable_i(enable_i),
.sample_i(sample_i),
.level_o(level_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/base/trailing_zero_count.md
+72
View File
@@ -0,0 +1,72 @@
# trailing_zero_count
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/base/mask_cells.sv`](../../../rtl/base/mask_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Combinational trailing-zero counter with all-zero indication.
## Functional Behavior
Combinational trailing-zero counter with all-zero indication. It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.
## Suitable Applications
Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `WIDTH` | `parameter int WIDTH = 32` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(WIDTH + 1)` |
## Interface Definition
```systemverilog
module trailing_zero_count #(
parameter int WIDTH = 32,
parameter int COUNT_WIDTH = $clog2(WIDTH + 1)
) (
input logic [ WIDTH-1:0] value_i,
output logic [COUNT_WIDTH-1:0] count_o,
output logic all_zero_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `value_i` | `input` | `input logic [ WIDTH-1:0] value_i` |
| `count_o` | `output` | `output logic [COUNT_WIDTH-1:0] count_o` |
| `all_zero_o` | `output` | `output logic all_zero_o` |
## Integration and Use
Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.
```systemverilog
trailing_zero_count #(
.WIDTH(WIDTH),
.COUNT_WIDTH(COUNT_WIDTH)
) u_trailing_zero_count (
.value_i(value_i),
.count_o(count_o),
.all_zero_o(all_zero_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/bus/address_map.md
+84
View File
@@ -0,0 +1,84 @@
# address_map
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/bus/address_decode.sv`](../../../rtl/bus/address_decode.sv) |
| Availability | Synthesizable RTL |
## Summary
Masked address-map decoder with deterministic lowest-index priority.
## Functional Behavior
Masked address-map decoder with deterministic lowest-index priority. It classifies the presented address using the configured decode rule and returns the documented selection/match result combinationally.
## Suitable Applications
Use for memory maps, peripheral selection, firewall regions, and target routing.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = 32` |
| `REGIONS` | `parameter int REGIONS = 4` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (REGIONS > 1) ? $clog2(REGIONS) : 1` |
## Interface Definition
```systemverilog
module address_map #(
parameter int ADDR_WIDTH = 32,
parameter int REGIONS = 4,
parameter int INDEX_WIDTH = (REGIONS > 1) ? $clog2(REGIONS) : 1
) (
input logic [ ADDR_WIDTH-1:0] addr_i,
input logic [ REGIONS-1:0][ADDR_WIDTH-1:0] base_i,
input logic [ REGIONS-1:0][ADDR_WIDTH-1:0] mask_i,
output logic [ REGIONS-1:0] hit_o,
output logic [INDEX_WIDTH-1:0] selected_o,
output logic valid_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `addr_i` | `input` | `input logic [ ADDR_WIDTH-1:0] addr_i` |
| `base_i` | `input` | `input logic [ REGIONS-1:0][ADDR_WIDTH-1:0] base_i` |
| `mask_i` | `input` | `input logic [ REGIONS-1:0][ADDR_WIDTH-1:0] mask_i` |
| `hit_o` | `output` | `output logic [ REGIONS-1:0] hit_o` |
| `selected_o` | `output` | `output logic [INDEX_WIDTH-1:0] selected_o` |
| `valid_o` | `output` | `output logic valid_o` |
## Integration and Use
Check overlaps and priority deliberately. Decode does not by itself complete or validate a bus transaction.
```systemverilog
address_map #(
.ADDR_WIDTH(ADDR_WIDTH),
.REGIONS(REGIONS),
.INDEX_WIDTH(INDEX_WIDTH)
) u_address_map (
.addr_i(addr_i),
.base_i(base_i),
.mask_i(mask_i),
.hit_o(hit_o),
.selected_o(selected_o),
.valid_o(valid_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/bus/address_range_decoder.md
+102
View File
@@ -0,0 +1,102 @@
# address_range_decoder
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/bus/address_advanced.sv`](../../../rtl/bus/address_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Inclusive address-range decoder.
## Functional Behavior
Inclusive address-range decoder. It classifies the presented address using the configured decode rule and returns the documented selection/match result combinationally.
## Suitable Applications
Use for memory maps, peripheral selection, firewall regions, and target routing.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = 32` |
| `RULES` | `parameter int RULES = 4` |
| `TARGETS` | `parameter int TARGETS = 4` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (TARGETS > 1) ? $clog2(TARGETS) : 1` |
## Interface Definition
```systemverilog
module address_range_decoder #(
parameter int ADDR_WIDTH = 32,
parameter int RULES = 4,
parameter int TARGETS = 4,
parameter int INDEX_WIDTH = (TARGETS > 1) ? $clog2(TARGETS) : 1
) (
input logic [ ADDR_WIDTH-1:0] addr_i,
input logic [ RULES-1:0][INDEX_WIDTH-1:0] target_i,
input logic [ RULES-1:0][ ADDR_WIDTH-1:0] first_i,
input logic [ RULES-1:0][ ADDR_WIDTH-1:0] last_i,
input logic updating_i,
input logic default_enable_i,
input logic [INDEX_WIDTH-1:0] default_target_i,
output logic [ TARGETS-1:0] select_o,
output logic [INDEX_WIDTH-1:0] target_o,
output logic valid_o,
output logic error_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `addr_i` | `input` | `input logic [ ADDR_WIDTH-1:0] addr_i` |
| `target_i` | `input` | `input logic [ RULES-1:0][INDEX_WIDTH-1:0] target_i` |
| `first_i` | `input` | `input logic [ RULES-1:0][ ADDR_WIDTH-1:0] first_i` |
| `last_i` | `input` | `input logic [ RULES-1:0][ ADDR_WIDTH-1:0] last_i` |
| `updating_i` | `input` | `input logic updating_i` |
| `default_enable_i` | `input` | `input logic default_enable_i` |
| `default_target_i` | `input` | `input logic [INDEX_WIDTH-1:0] default_target_i` |
| `select_o` | `output` | `output logic [ TARGETS-1:0] select_o` |
| `target_o` | `output` | `output logic [INDEX_WIDTH-1:0] target_o` |
| `valid_o` | `output` | `output logic valid_o` |
| `error_o` | `output` | `output logic error_o` |
## Integration and Use
Check overlaps and priority deliberately. Decode does not by itself complete or validate a bus transaction.
```systemverilog
address_range_decoder #(
.ADDR_WIDTH(ADDR_WIDTH),
.RULES(RULES),
.TARGETS(TARGETS),
.INDEX_WIDTH(INDEX_WIDTH)
) u_address_range_decoder (
.addr_i(addr_i),
.target_i(target_i),
.first_i(first_i),
.last_i(last_i),
.updating_i(updating_i),
.default_enable_i(default_enable_i),
.default_target_i(default_target_i),
.select_o(select_o),
.target_o(target_o),
.valid_o(valid_o),
.error_o(error_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/bus/address_region.md
+72
View File
@@ -0,0 +1,72 @@
# address_region
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/bus/address_decode.sv`](../../../rtl/bus/address_decode.sv) |
| Availability | Synthesizable RTL |
## Summary
Masked address-region matcher.
## Functional Behavior
Masked address-region matcher. It classifies the presented address using the configured decode rule and returns the documented selection/match result combinationally.
## Suitable Applications
Use for memory maps, peripheral selection, firewall regions, and target routing.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = 32` |
| `BASE` | `parameter logic [ADDR_WIDTH-1:0] BASE = '0` |
| `MASK` | `parameter logic [ADDR_WIDTH-1:0] MASK = '0` |
## Interface Definition
```systemverilog
module address_region #(
parameter int ADDR_WIDTH = 32,
parameter logic [ADDR_WIDTH-1:0] BASE = '0,
parameter logic [ADDR_WIDTH-1:0] MASK = '0
) (
input logic [ADDR_WIDTH-1:0] addr_i,
output logic match_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] addr_i` |
| `match_o` | `output` | `output logic match_o` |
## Integration and Use
Check overlaps and priority deliberately. Decode does not by itself complete or validate a bus transaction.
```systemverilog
address_region #(
.ADDR_WIDTH(ADDR_WIDTH),
.BASE(BASE),
.MASK(MASK)
) u_address_region (
.addr_i(addr_i),
.match_o(match_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/bus/address_set_decoder.md
+105
View File
@@ -0,0 +1,105 @@
# address_set_decoder
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/bus/address_advanced.sv`](../../../rtl/bus/address_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Decoder for a set of independently configured address regions.
## Functional Behavior
Decoder for a set of independently configured address regions. It classifies the presented address using the configured decode rule and returns the documented selection/match result combinationally.
## Suitable Applications
Use for memory maps, peripheral selection, firewall regions, and target routing.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = 32` |
| `RULES` | `parameter int RULES = 4` |
| `TARGETS` | `parameter int TARGETS = 4` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (TARGETS > 1) ? $clog2(TARGETS) : 1` |
## Interface Definition
```systemverilog
module address_set_decoder #(
parameter int ADDR_WIDTH = 32,
parameter int RULES = 4,
parameter int TARGETS = 4,
parameter int INDEX_WIDTH = (TARGETS > 1) ? $clog2(TARGETS) : 1
) (
input logic [ ADDR_WIDTH-1:0] addr_i,
input logic [ ADDR_WIDTH-1:0] wildcard_i,
input logic [ RULES-1:0][INDEX_WIDTH-1:0] target_i,
input logic [ RULES-1:0][ ADDR_WIDTH-1:0] rule_addr_i,
input logic [ RULES-1:0][ ADDR_WIDTH-1:0] rule_wildcard_i,
input logic default_enable_i,
input logic [INDEX_WIDTH-1:0] default_target_i,
output logic [ TARGETS-1:0] select_o,
output logic [ TARGETS-1:0][ ADDR_WIDTH-1:0] addr_o,
output logic [ TARGETS-1:0][ ADDR_WIDTH-1:0] wildcard_o,
output logic valid_o,
output logic error_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `addr_i` | `input` | `input logic [ ADDR_WIDTH-1:0] addr_i` |
| `wildcard_i` | `input` | `input logic [ ADDR_WIDTH-1:0] wildcard_i` |
| `target_i` | `input` | `input logic [ RULES-1:0][INDEX_WIDTH-1:0] target_i` |
| `rule_addr_i` | `input` | `input logic [ RULES-1:0][ ADDR_WIDTH-1:0] rule_addr_i` |
| `rule_wildcard_i` | `input` | `input logic [ RULES-1:0][ ADDR_WIDTH-1:0] rule_wildcard_i` |
| `default_enable_i` | `input` | `input logic default_enable_i` |
| `default_target_i` | `input` | `input logic [INDEX_WIDTH-1:0] default_target_i` |
| `select_o` | `output` | `output logic [ TARGETS-1:0] select_o` |
| `addr_o` | `output` | `output logic [ TARGETS-1:0][ ADDR_WIDTH-1:0] addr_o` |
| `wildcard_o` | `output` | `output logic [ TARGETS-1:0][ ADDR_WIDTH-1:0] wildcard_o` |
| `valid_o` | `output` | `output logic valid_o` |
| `error_o` | `output` | `output logic error_o` |
## Integration and Use
Check overlaps and priority deliberately. Decode does not by itself complete or validate a bus transaction.
```systemverilog
address_set_decoder #(
.ADDR_WIDTH(ADDR_WIDTH),
.RULES(RULES),
.TARGETS(TARGETS),
.INDEX_WIDTH(INDEX_WIDTH)
) u_address_set_decoder (
.addr_i(addr_i),
.wildcard_i(wildcard_i),
.target_i(target_i),
.rule_addr_i(rule_addr_i),
.rule_wildcard_i(rule_wildcard_i),
.default_enable_i(default_enable_i),
.default_target_i(default_target_i),
.select_o(select_o),
.addr_o(addr_o),
.wildcard_o(wildcard_o),
.valid_o(valid_o),
.error_o(error_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/async_gray_queue.md
+96
View File
@@ -0,0 +1,96 @@
# async_gray_queue
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/async_reqack.sv`](../../../rtl/cdc/async_reqack.sv) |
| Availability | Synthesizable RTL |
## Summary
Gray-pointer asynchronous FIFO wrapper.
## Functional Behavior
Gray-pointer asynchronous FIFO wrapper. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BUFFER_DEPTH` | `parameter int BUFFER_DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module async_gray_queue #(
parameter int DATA_WIDTH = 32,
parameter int BUFFER_DEPTH = 8,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
async_gray_queue #(
.DATA_WIDTH(DATA_WIDTH),
.BUFFER_DEPTH(BUFFER_DEPTH),
.SYNC_STAGES(SYNC_STAGES)
) u_async_gray_queue (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/async_reqack.md
+93
View File
@@ -0,0 +1,93 @@
# async_reqack
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/async_reqack.sv`](../../../rtl/cdc/async_reqack.sv) |
| Availability | Synthesizable RTL |
## Summary
One-entry four-phase asynchronous data mailbox.
## Functional Behavior
Captures one source payload, transfers it through a four-phase request/acknowledge protocol, and suppresses destination valid after acceptance so return-to-zero cannot create a duplicate delivery.
## Suitable Applications
Use for low-throughput asynchronous control or data mailboxes.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module async_reqack #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_valid_i,
output logic src_ready_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_valid_o,
input logic dst_ready_i,
output logic [DATA_WIDTH-1:0] dst_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
## Integration and Use
Hold source payload only through the source valid/ready handshake. Reset at either endpoint aborts an in-flight item; this is a one-entry link.
```systemverilog
async_reqack #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_async_reqack (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.src_data_i(src_data_i),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i),
.dst_data_o(dst_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_2phase.md
+94
View File
@@ -0,0 +1,94 @@
# cdc_2phase
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_2phase.sv`](../../../rtl/cdc/cdc_2phase.sv) |
| Availability | Synthesizable RTL |
## Summary
Two-phase asynchronous request/acknowledge transfer.
## Functional Behavior
Two-phase asynchronous request/acknowledge transfer. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_2phase #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_2phase #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_2phase (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_2phase_dst.md
+87
View File
@@ -0,0 +1,87 @@
# cdc_2phase_dst
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_2phase.sv`](../../../rtl/cdc/cdc_2phase.sv) |
| Availability | Synthesizable RTL |
## Summary
Destination-side implementation of the two-phase CDC link.
## Functional Behavior
Destination-side implementation of the two-phase CDC link. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_2phase_dst #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 2
) (
input logic rst_n_i,
input logic clk_i,
output logic [DATA_WIDTH-1:0] data_o,
output logic valid_o,
input logic ready_i,
input logic async_req_i,
output logic async_ack_o,
input logic [DATA_WIDTH-1:0] async_data_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clk_i` | `input` | `input logic clk_i` |
| `data_o` | `output` | `output logic [DATA_WIDTH-1:0] data_o` |
| `valid_o` | `output` | `output logic valid_o` |
| `ready_i` | `input` | `input logic ready_i` |
| `async_req_i` | `input` | `input logic async_req_i` |
| `async_ack_o` | `output` | `output logic async_ack_o` |
| `async_data_i` | `input` | `input logic [DATA_WIDTH-1:0] async_data_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_2phase_dst #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_2phase_dst (
.rst_n_i(rst_n_i),
.clk_i(clk_i),
.data_o(data_o),
.valid_o(valid_o),
.ready_i(ready_i),
.async_req_i(async_req_i),
.async_ack_o(async_ack_o),
.async_data_i(async_data_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_2phase_src.md
+87
View File
@@ -0,0 +1,87 @@
# cdc_2phase_src
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_2phase.sv`](../../../rtl/cdc/cdc_2phase.sv) |
| Availability | Synthesizable RTL |
## Summary
Source-side implementation of the two-phase CDC link.
## Functional Behavior
Source-side implementation of the two-phase CDC link. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_2phase_src #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 2
) (
input logic clk_i,
input logic rst_n_i,
input logic [DATA_WIDTH-1:0] data_i,
input logic valid_i,
output logic ready_o,
output logic async_req_o,
input logic async_ack_i,
output logic [DATA_WIDTH-1:0] async_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `data_i` | `input` | `input logic [DATA_WIDTH-1:0] data_i` |
| `valid_i` | `input` | `input logic valid_i` |
| `ready_o` | `output` | `output logic ready_o` |
| `async_req_o` | `output` | `output logic async_req_o` |
| `async_ack_i` | `input` | `input logic async_ack_i` |
| `async_data_o` | `output` | `output logic [DATA_WIDTH-1:0] async_data_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_2phase_src #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_2phase_src (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.data_i(data_i),
.valid_i(valid_i),
.ready_o(ready_o),
.async_req_o(async_req_o),
.async_ack_i(async_ack_i),
.async_data_o(async_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_2phase_warm_flush.md
+103
View File
@@ -0,0 +1,103 @@
# cdc_2phase_warm_flush
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_warm_flush.sv`](../../../rtl/cdc/cdc_warm_flush.sv) |
| Availability | Synthesizable RTL |
## Summary
Source-initiated warm-clear wrapper for a two-phase CDC link.
## Functional Behavior
Source-initiated warm-clear wrapper for a two-phase CDC link. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_2phase_warm_flush #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_clear_i,
output logic src_clear_busy_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_clear_busy_o,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_clear_i` | `input` | `input logic src_clear_i` |
| `src_clear_busy_o` | `output` | `output logic src_clear_busy_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_clear_busy_o` | `output` | `output logic dst_clear_busy_o` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_2phase_warm_flush #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_2phase_warm_flush (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_clear_i(src_clear_i),
.src_clear_busy_o(src_clear_busy_o),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_clear_busy_o(dst_clear_busy_o),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_event_bridge.md
+84
View File
@@ -0,0 +1,84 @@
# cdc_event_bridge
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Pulse/event transport over an asynchronous mailbox.
## Functional Behavior
Pulse/event transport over an asynchronous mailbox. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_event_bridge #(
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic event_i,
output logic source_ready_o,
output logic source_busy_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic event_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `event_i` | `input` | `input logic event_i` |
| `source_ready_o` | `output` | `output logic source_ready_o` |
| `source_busy_o` | `output` | `output logic source_busy_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `event_o` | `output` | `output logic event_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_event_bridge #(
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_event_bridge (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.event_i(event_i),
.source_ready_o(source_ready_o),
.source_busy_o(source_busy_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.event_o(event_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_event_bridge_ack.md
+84
View File
@@ -0,0 +1,84 @@
# cdc_event_bridge_ack
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Acknowledged asynchronous event transport.
## Functional Behavior
Acknowledged asynchronous event transport. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_event_bridge_ack #(
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic event_i,
output logic accepted_o,
output logic completed_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic event_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `event_i` | `input` | `input logic event_i` |
| `accepted_o` | `output` | `output logic accepted_o` |
| `completed_o` | `output` | `output logic completed_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `event_o` | `output` | `output logic event_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_event_bridge_ack #(
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_event_bridge_ack (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.event_i(event_i),
.accepted_o(accepted_o),
.completed_o(completed_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.event_o(event_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_fifo.md
+97
View File
@@ -0,0 +1,97 @@
# cdc_fifo
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_fifo.sv`](../../../rtl/cdc/cdc_fifo.sv) |
| Availability | Synthesizable RTL |
## Summary
Gray-pointer asynchronous FIFO.
## Functional Behavior
Gray-pointer asynchronous FIFO. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BUFFER_DEPTH` | `parameter int BUFFER_DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_fifo #(
parameter int DATA_WIDTH = 32,
parameter int BUFFER_DEPTH = 8,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_fifo #(
.DATA_WIDTH(DATA_WIDTH),
.BUFFER_DEPTH(BUFFER_DEPTH),
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_fifo (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_fifo_dst.md
+93
View File
@@ -0,0 +1,93 @@
# cdc_fifo_dst
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_fifo.sv`](../../../rtl/cdc/cdc_fifo.sv) |
| Availability | Synthesizable RTL |
## Summary
Destination-side implementation of the asynchronous FIFO.
## Functional Behavior
Destination-side implementation of the asynchronous FIFO. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BUFFER_DEPTH` | `parameter int BUFFER_DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
| `LOG_BUFFER_DEPTH` | `parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1` |
## Interface Definition
```systemverilog
module cdc_fifo_dst #(
parameter int DATA_WIDTH = 32,
parameter int BUFFER_DEPTH = 8,
parameter int SYNC_STAGES = 2,
parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1
) (
input logic clk_i,
input logic rst_n_i,
output logic [ DATA_WIDTH-1:0] data_o,
output logic valid_o,
input logic ready_i,
input logic [ BUFFER_DEPTH-1:0][DATA_WIDTH-1:0] async_data_i,
input logic [LOG_BUFFER_DEPTH:0] async_wr_ptr_i,
output logic [LOG_BUFFER_DEPTH:0] async_rd_ptr_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `data_o` | `output` | `output logic [ DATA_WIDTH-1:0] data_o` |
| `valid_o` | `output` | `output logic valid_o` |
| `ready_i` | `input` | `input logic ready_i` |
| `async_data_i` | `input` | `input logic [ BUFFER_DEPTH-1:0][DATA_WIDTH-1:0] async_data_i` |
| `async_wr_ptr_i` | `input` | `input logic [LOG_BUFFER_DEPTH:0] async_wr_ptr_i` |
| `async_rd_ptr_o` | `output` | `output logic [LOG_BUFFER_DEPTH:0] async_rd_ptr_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_fifo_dst #(
.DATA_WIDTH(DATA_WIDTH),
.BUFFER_DEPTH(BUFFER_DEPTH),
.SYNC_STAGES(SYNC_STAGES),
.LOG_BUFFER_DEPTH(LOG_BUFFER_DEPTH)
) u_cdc_fifo_dst (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.data_o(data_o),
.valid_o(valid_o),
.ready_i(ready_i),
.async_data_i(async_data_i),
.async_wr_ptr_i(async_wr_ptr_i),
.async_rd_ptr_o(async_rd_ptr_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_fifo_src.md
+93
View File
@@ -0,0 +1,93 @@
# cdc_fifo_src
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_fifo.sv`](../../../rtl/cdc/cdc_fifo.sv) |
| Availability | Synthesizable RTL |
## Summary
Source-side implementation of the asynchronous FIFO.
## Functional Behavior
Source-side implementation of the asynchronous FIFO. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BUFFER_DEPTH` | `parameter int BUFFER_DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
| `LOG_BUFFER_DEPTH` | `parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1` |
## Interface Definition
```systemverilog
module cdc_fifo_src #(
parameter int DATA_WIDTH = 32,
parameter int BUFFER_DEPTH = 8,
parameter int SYNC_STAGES = 2,
parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1
) (
input logic clk_i,
input logic rst_n_i,
input logic [ DATA_WIDTH-1:0] data_i,
input logic valid_i,
output logic ready_o,
output logic [ BUFFER_DEPTH-1:0][DATA_WIDTH-1:0] async_data_o,
output logic [LOG_BUFFER_DEPTH:0] async_wr_ptr_o,
input logic [LOG_BUFFER_DEPTH:0] async_rd_ptr_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `data_i` | `input` | `input logic [ DATA_WIDTH-1:0] data_i` |
| `valid_i` | `input` | `input logic valid_i` |
| `ready_o` | `output` | `output logic ready_o` |
| `async_data_o` | `output` | `output logic [ BUFFER_DEPTH-1:0][DATA_WIDTH-1:0] async_data_o` |
| `async_wr_ptr_o` | `output` | `output logic [LOG_BUFFER_DEPTH:0] async_wr_ptr_o` |
| `async_rd_ptr_i` | `input` | `input logic [LOG_BUFFER_DEPTH:0] async_rd_ptr_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_fifo_src #(
.DATA_WIDTH(DATA_WIDTH),
.BUFFER_DEPTH(BUFFER_DEPTH),
.SYNC_STAGES(SYNC_STAGES),
.LOG_BUFFER_DEPTH(LOG_BUFFER_DEPTH)
) u_cdc_fifo_src (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.data_i(data_i),
.valid_i(valid_i),
.ready_o(ready_o),
.async_data_o(async_data_o),
.async_wr_ptr_o(async_wr_ptr_o),
.async_rd_ptr_i(async_rd_ptr_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_fifo_warm_flush.md
+106
View File
@@ -0,0 +1,106 @@
# cdc_fifo_warm_flush
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_warm_flush.sv`](../../../rtl/cdc/cdc_warm_flush.sv) |
| Availability | Synthesizable RTL |
## Summary
Source-initiated warm-clear wrapper for an asynchronous FIFO.
## Functional Behavior
Source-initiated warm-clear wrapper for an asynchronous FIFO. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BUFFER_DEPTH` | `parameter int BUFFER_DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_fifo_warm_flush #(
parameter int DATA_WIDTH = 32,
parameter int BUFFER_DEPTH = 8,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_clear_i,
output logic src_clear_busy_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_clear_busy_o,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_clear_i` | `input` | `input logic src_clear_i` |
| `src_clear_busy_o` | `output` | `output logic src_clear_busy_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_clear_busy_o` | `output` | `output logic dst_clear_busy_o` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_fifo_warm_flush #(
.DATA_WIDTH(DATA_WIDTH),
.BUFFER_DEPTH(BUFFER_DEPTH),
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_fifo_warm_flush (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_clear_i(src_clear_i),
.src_clear_busy_o(src_clear_busy_o),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_clear_busy_o(dst_clear_busy_o),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_remote_clear_request.md
+84
View File
@@ -0,0 +1,84 @@
# cdc_remote_clear_request
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Retained remote-clear request channel.
## Functional Behavior
Retained remote-clear request channel. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 3` |
## Interface Definition
```systemverilog
module cdc_remote_clear_request #(
parameter int SYNC_STAGES = 3
) (
input logic request_clk_i,
input logic request_rst_n_i,
input logic request_i,
output logic request_busy_o,
input logic accept_clk_i,
input logic accept_rst_n_i,
output logic accept_valid_o,
input logic accept_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `request_clk_i` | `input` | `input logic request_clk_i` |
| `request_rst_n_i` | `input` | `input logic request_rst_n_i` |
| `request_i` | `input` | `input logic request_i` |
| `request_busy_o` | `output` | `output logic request_busy_o` |
| `accept_clk_i` | `input` | `input logic accept_clk_i` |
| `accept_rst_n_i` | `input` | `input logic accept_rst_n_i` |
| `accept_valid_o` | `output` | `output logic accept_valid_o` |
| `accept_ready_i` | `input` | `input logic accept_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_remote_clear_request #(
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_remote_clear_request (
.request_clk_i(request_clk_i),
.request_rst_n_i(request_rst_n_i),
.request_i(request_i),
.request_busy_o(request_busy_o),
.accept_clk_i(accept_clk_i),
.accept_rst_n_i(accept_rst_n_i),
.accept_valid_o(accept_valid_o),
.accept_ready_i(accept_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_reset_barrier.md
+78
View File
@@ -0,0 +1,78 @@
# cdc_reset_barrier
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_rst_ctrlr.sv`](../../../rtl/cdc/cdc_rst_ctrlr.sv) |
| Availability | Synthesizable RTL |
## Summary
Two-domain reset barrier with synchronized release.
## Functional Behavior
Asynchronously asserts local reset and releases it through synchronized reset chains in both supplied clock domains, preventing either side from running before the shared reset epoch is released.
## Suitable Applications
Use when two collaborating domains need a coordinated reset release before starting a CDC protocol.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `STAGES` | `parameter int STAGES = 3` |
## Interface Definition
```systemverilog
module cdc_reset_barrier #(
parameter int STAGES = 3
) (
input logic clk_a_i,
input logic clk_b_i,
input logic rst_n_i,
input logic release_i,
output logic rst_a_n_o,
output logic rst_b_n_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_a_i` | `input` | `input logic clk_a_i` |
| `clk_b_i` | `input` | `input logic clk_b_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `release_i` | `input` | `input logic release_i` |
| `rst_a_n_o` | `output` | `output logic rst_a_n_o` |
| `rst_b_n_o` | `output` | `output logic rst_b_n_o` |
## Integration and Use
It does not transfer data or replace reset-domain signoff. Both clocks must run for reset release to complete.
```systemverilog
cdc_reset_barrier #(
.STAGES(STAGES)
) u_cdc_reset_barrier (
.clk_a_i(clk_a_i),
.clk_b_i(clk_b_i),
.rst_n_i(rst_n_i),
.release_i(release_i),
.rst_a_n_o(rst_a_n_o),
.rst_b_n_o(rst_b_n_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_sync.md
+75
View File
@@ -0,0 +1,75 @@
# cdc_sync
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_sync.sv`](../../../rtl/cdc/cdc_sync.sv) |
| Availability | Synthesizable RTL |
## Summary
Multi-flop synchronizer for a control bit or independently encoded vector.
## Functional Behavior
Multi-flop synchronizer for a control bit or independently encoded vector. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `STAGE` | `parameter int STAGE = 2` |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 1` |
## Interface Definition
```systemverilog
module cdc_sync #(
parameter int STAGE = 2,
parameter int DATA_WIDTH = 1
) (
input logic clk_i,
input logic rst_n_i,
input logic [DATA_WIDTH-1:0] dat_i,
output logic [DATA_WIDTH-1:0] dat_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `dat_i` | `input` | `input logic [DATA_WIDTH-1:0] dat_i` |
| `dat_o` | `output` | `output logic [DATA_WIDTH-1:0] dat_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_sync #(
.STAGE(STAGE),
.DATA_WIDTH(DATA_WIDTH)
) u_cdc_sync (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.dat_i(dat_i),
.dat_o(dat_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_sync_det.md
+78
View File
@@ -0,0 +1,78 @@
# cdc_sync_det
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_sync.sv`](../../../rtl/cdc/cdc_sync.sv) |
| Availability | Synthesizable RTL |
## Summary
Synchronized control input with edge detection.
## Functional Behavior
Synchronized control input with edge detection. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `STAGE` | `parameter int STAGE = 2` |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 1` |
## Interface Definition
```systemverilog
module cdc_sync_det #(
parameter int STAGE = 2,
parameter int DATA_WIDTH = 1
) (
input logic clk_i,
input logic rst_n_i,
input logic [DATA_WIDTH-1:0] dat_i,
output logic [DATA_WIDTH-1:0] dat_pre_o,
output logic [DATA_WIDTH-1:0] dat_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `dat_i` | `input` | `input logic [DATA_WIDTH-1:0] dat_i` |
| `dat_pre_o` | `output` | `output logic [DATA_WIDTH-1:0] dat_pre_o` |
| `dat_o` | `output` | `output logic [DATA_WIDTH-1:0] dat_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_sync_det #(
.STAGE(STAGE),
.DATA_WIDTH(DATA_WIDTH)
) u_cdc_sync_det (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.dat_i(dat_i),
.dat_pre_o(dat_pre_o),
.dat_o(dat_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/cdc_warm_flush_controller.md
+94
View File
@@ -0,0 +1,94 @@
# cdc_warm_flush_controller
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_warm_flush.sv`](../../../rtl/cdc/cdc_warm_flush.sv) |
| Availability | Synthesizable RTL |
## Summary
Acknowledged isolate-reset-resume controller for CDC warm flush.
## Functional Behavior
Acknowledged isolate-reset-resume controller for CDC warm flush. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module cdc_warm_flush_controller #(
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_clear_i,
output logic src_isolate_o,
output logic src_reset_o,
output logic src_busy_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_isolate_o,
output logic dst_reset_o,
output logic dst_busy_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_clear_i` | `input` | `input logic src_clear_i` |
| `src_isolate_o` | `output` | `output logic src_isolate_o` |
| `src_reset_o` | `output` | `output logic src_reset_o` |
| `src_busy_o` | `output` | `output logic src_busy_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_isolate_o` | `output` | `output logic dst_isolate_o` |
| `dst_reset_o` | `output` | `output logic dst_reset_o` |
| `dst_busy_o` | `output` | `output logic dst_busy_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
cdc_warm_flush_controller #(
.SYNC_STAGES(SYNC_STAGES)
) u_cdc_warm_flush_controller (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_clear_i(src_clear_i),
.src_isolate_o(src_isolate_o),
.src_reset_o(src_reset_o),
.src_busy_o(src_busy_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_isolate_o(dst_isolate_o),
.dst_reset_o(dst_reset_o),
.dst_busy_o(dst_busy_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/clearable_async_queue.md
+108
View File
@@ -0,0 +1,108 @@
# clearable_async_queue
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Asynchronous queue with coordinated endpoint clear.
## Functional Behavior
Asynchronous queue with coordinated endpoint clear. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `DEPTH` | `parameter int DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 3` |
## Interface Definition
```systemverilog
module clearable_async_queue #(
parameter int DATA_WIDTH = 32,
parameter int DEPTH = 8,
parameter int SYNC_STAGES = 3
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_clear_i,
output logic src_clear_busy_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
input logic dst_clear_i,
output logic dst_clear_busy_o,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_clear_i` | `input` | `input logic src_clear_i` |
| `src_clear_busy_o` | `output` | `output logic src_clear_busy_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_clear_i` | `input` | `input logic dst_clear_i` |
| `dst_clear_busy_o` | `output` | `output logic dst_clear_busy_o` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
clearable_async_queue #(
.DATA_WIDTH(DATA_WIDTH),
.DEPTH(DEPTH),
.SYNC_STAGES(SYNC_STAGES)
) u_clearable_async_queue (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_clear_i(src_clear_i),
.src_clear_busy_o(src_clear_busy_o),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_clear_i(dst_clear_i),
.dst_clear_busy_o(dst_clear_busy_o),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/clearable_two_phase_link.md
+105
View File
@@ -0,0 +1,105 @@
# clearable_two_phase_link
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Two-phase link with coordinated endpoint clear.
## Functional Behavior
Two-phase link with coordinated endpoint clear. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 3` |
## Interface Definition
```systemverilog
module clearable_two_phase_link #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 3
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_clear_i,
output logic src_clear_busy_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
input logic dst_clear_i,
output logic dst_clear_busy_o,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_clear_i` | `input` | `input logic src_clear_i` |
| `src_clear_busy_o` | `output` | `output logic src_clear_busy_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_clear_i` | `input` | `input logic dst_clear_i` |
| `dst_clear_busy_o` | `output` | `output logic dst_clear_busy_o` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
clearable_two_phase_link #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_clearable_two_phase_link (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_clear_i(src_clear_i),
.src_clear_busy_o(src_clear_busy_o),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_clear_i(dst_clear_i),
.dst_clear_busy_o(dst_clear_busy_o),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/four_phase_mailbox.md
+93
View File
@@ -0,0 +1,93 @@
# four_phase_mailbox
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Public wrapper for the four-phase asynchronous mailbox API.
## Functional Behavior
Public wrapper for the four-phase asynchronous mailbox API. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module four_phase_mailbox #(
parameter int DATA_WIDTH = 32,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_valid_i,
output logic src_ready_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_valid_o,
input logic dst_ready_i,
output logic [DATA_WIDTH-1:0] dst_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
four_phase_mailbox #(
.DATA_WIDTH(DATA_WIDTH),
.SYNC_STAGES(SYNC_STAGES)
) u_four_phase_mailbox (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.src_data_i(src_data_i),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i),
.dst_data_o(dst_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/isochronous_handshake.md
+76
View File
@@ -0,0 +1,76 @@
# isochronous_handshake
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Handshake for fixed-ratio, STA-constrained isochronous clocks.
## Functional Behavior
Handshake for fixed-ratio, STA-constrained isochronous clocks. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
module isochronous_handshake (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
isochronous_handshake u_isochronous_handshake (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/isochronous_stream_buffer.md
+93
View File
@@ -0,0 +1,93 @@
# isochronous_stream_buffer
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Stream buffer for fixed-ratio, STA-constrained isochronous clocks.
## Functional Behavior
Stream buffer for fixed-ratio, STA-constrained isochronous clocks. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BYPASS` | `parameter bit BYPASS = 1'b0` |
## Interface Definition
```systemverilog
module isochronous_stream_buffer #(
parameter int DATA_WIDTH = 32,
parameter bit BYPASS = 1'b0
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic src_valid_i,
output logic src_ready_o,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic dst_valid_o,
input logic dst_ready_i,
output logic [DATA_WIDTH-1:0] dst_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
isochronous_stream_buffer #(
.DATA_WIDTH(DATA_WIDTH),
.BYPASS(BYPASS)
) u_isochronous_stream_buffer (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.src_data_i(src_data_i),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i),
.dst_data_o(dst_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/synchronized_edge.md
+84
View File
@@ -0,0 +1,84 @@
# synchronized_edge
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Synchronizes a control transition and emits a local edge indication.
## Functional Behavior
Synchronizes a control transition and emits a local edge indication. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module synchronized_edge #(
parameter int SYNC_STAGES = 2
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic enable_i,
input logic async_level_i,
output logic level_o,
output logic rise_o,
output logic fall_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `enable_i` | `input` | `input logic enable_i` |
| `async_level_i` | `input` | `input logic async_level_i` |
| `level_o` | `output` | `output logic level_o` |
| `rise_o` | `output` | `output logic rise_o` |
| `fall_o` | `output` | `output logic fall_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
synchronized_edge #(
.SYNC_STAGES(SYNC_STAGES)
) u_synchronized_edge (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.enable_i(enable_i),
.async_level_i(async_level_i),
.level_o(level_o),
.rise_o(rise_o),
.fall_o(fall_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/test_reset_synchronizer.md
+78
View File
@@ -0,0 +1,78 @@
# test_reset_synchronizer
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Verification-oriented helper |
## Summary
Verification-oriented reset synchronization helper.
## Functional Behavior
Verification-oriented reset synchronization helper. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `STAGES` | `parameter int STAGES = 3` |
## Interface Definition
```systemverilog
module test_reset_synchronizer #(
parameter int STAGES = 3
) (
input logic clk_i,
input logic functional_rst_n_i,
input logic test_rst_n_i,
input logic test_mode_i,
output logic rst_n_o,
output logic init_n_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `functional_rst_n_i` | `input` | `input logic functional_rst_n_i` |
| `test_rst_n_i` | `input` | `input logic test_rst_n_i` |
| `test_mode_i` | `input` | `input logic test_mode_i` |
| `rst_n_o` | `output` | `output logic rst_n_o` |
| `init_n_o` | `output` | `output logic init_n_o` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
test_reset_synchronizer #(
.STAGES(STAGES)
) u_test_reset_synchronizer (
.clk_i(clk_i),
.functional_rst_n_i(functional_rst_n_i),
.test_rst_n_i(test_rst_n_i),
.test_mode_i(test_mode_i),
.rst_n_o(rst_n_o),
.init_n_o(init_n_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/cdc/two_phase_async_queue.md
+96
View File
@@ -0,0 +1,96 @@
# two_phase_async_queue
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/cdc/cdc_advanced.sv`](../../../rtl/cdc/cdc_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Queue API built from two-phase asynchronous transfers.
## Functional Behavior
Queue API built from two-phase asynchronous transfers. It carries the declared control, event, or data contract through the stated synchronizer, handshake, or Gray-pointer mechanism. Endpoint reset discards in-flight data unless the page identifies an acknowledged warm-clear path.
## Suitable Applications
Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `DEPTH` | `parameter int DEPTH = 8` |
| `SYNC_STAGES` | `parameter int SYNC_STAGES = 2` |
## Interface Definition
```systemverilog
module two_phase_async_queue #(
parameter int DATA_WIDTH = 32,
parameter int DEPTH = 8,
parameter int SYNC_STAGES = 2
) (
input logic src_clk_i,
input logic src_rst_n_i,
input logic [DATA_WIDTH-1:0] src_data_i,
input logic src_valid_i,
output logic src_ready_o,
input logic dst_clk_i,
input logic dst_rst_n_i,
output logic [DATA_WIDTH-1:0] dst_data_o,
output logic dst_valid_o,
input logic dst_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `src_clk_i` | `input` | `input logic src_clk_i` |
| `src_rst_n_i` | `input` | `input logic src_rst_n_i` |
| `src_data_i` | `input` | `input logic [DATA_WIDTH-1:0] src_data_i` |
| `src_valid_i` | `input` | `input logic src_valid_i` |
| `src_ready_o` | `output` | `output logic src_ready_o` |
| `dst_clk_i` | `input` | `input logic dst_clk_i` |
| `dst_rst_n_i` | `input` | `input logic dst_rst_n_i` |
| `dst_data_o` | `output` | `output logic [DATA_WIDTH-1:0] dst_data_o` |
| `dst_valid_o` | `output` | `output logic dst_valid_o` |
| `dst_ready_i` | `input` | `input logic dst_ready_i` |
## Integration and Use
Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.
```systemverilog
two_phase_async_queue #(
.DATA_WIDTH(DATA_WIDTH),
.DEPTH(DEPTH),
.SYNC_STAGES(SYNC_STAGES)
) u_two_phase_async_queue (
.src_clk_i(src_clk_i),
.src_rst_n_i(src_rst_n_i),
.src_data_i(src_data_i),
.src_valid_i(src_valid_i),
.src_ready_o(src_ready_o),
.dst_clk_i(dst_clk_i),
.dst_rst_n_i(dst_rst_n_i),
.dst_data_o(dst_data_o),
.dst_valid_o(dst_valid_o),
.dst_ready_i(dst_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/clk_int_div_simple.md
+96
View File
@@ -0,0 +1,96 @@
# clk_int_div_simple
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/clk_int_div.sv`](../../../rtl/clkrst/clk_int_div.sv) |
| Availability | Synthesizable RTL |
## Summary
Runtime-programmable integer divider with safe low-phase updates.
## Functional Behavior
Runtime-programmable integer divider with safe low-phase updates. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DIV_VALUE_WIDTH` | `parameter int DIV_VALUE_WIDTH = 32` |
| `DONE_DELAY_WIDTH` | `parameter int DONE_DELAY_WIDTH = 3` |
## Interface Definition
```systemverilog
module clk_int_div_simple #(
parameter int DIV_VALUE_WIDTH = 32,
parameter int DONE_DELAY_WIDTH = 3
) (
input logic clk_i,
input logic rst_n_i,
input logic [DIV_VALUE_WIDTH-1:0] div_i,
input logic clk_init_i,
input logic div_valid_i,
output logic div_ready_o,
output logic div_done_o,
output logic [DIV_VALUE_WIDTH-1:0] clk_cnt_o,
output logic clk_fir_trg_o,
output logic clk_sec_trg_o,
output logic clk_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `div_i` | `input` | `input logic [DIV_VALUE_WIDTH-1:0] div_i` |
| `clk_init_i` | `input` | `input logic clk_init_i` |
| `div_valid_i` | `input` | `input logic div_valid_i` |
| `div_ready_o` | `output` | `output logic div_ready_o` |
| `div_done_o` | `output` | `output logic div_done_o` |
| `clk_cnt_o` | `output` | `output logic [DIV_VALUE_WIDTH-1:0] clk_cnt_o` |
| `clk_fir_trg_o` | `output` | `output logic clk_fir_trg_o` |
| `clk_sec_trg_o` | `output` | `output logic clk_sec_trg_o` |
| `clk_o` | `output` | `output logic clk_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
clk_int_div_simple #(
.DIV_VALUE_WIDTH(DIV_VALUE_WIDTH),
.DONE_DELAY_WIDTH(DONE_DELAY_WIDTH)
) u_clk_int_div_simple (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.div_i(div_i),
.clk_init_i(clk_init_i),
.div_valid_i(div_valid_i),
.div_ready_o(div_ready_o),
.div_done_o(div_done_o),
.clk_cnt_o(clk_cnt_o),
.clk_fir_trg_o(clk_fir_trg_o),
.clk_sec_trg_o(clk_sec_trg_o),
.clk_o(clk_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/clk_int_even_div.md
+84
View File
@@ -0,0 +1,84 @@
# clk_int_even_div
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/clk_int_div.sv`](../../../rtl/clkrst/clk_int_div.sv) |
| Availability | Synthesizable RTL |
## Summary
Even clock divider retaining requests until a safe boundary.
## Functional Behavior
Even clock divider retaining requests until a safe boundary. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DIV_VALUE` | `parameter int DIV_VALUE = 2` |
| `ENABLE_CLOCK_IN_RESET` | `parameter bit ENABLE_CLOCK_IN_RESET = 1'b0` |
## Interface Definition
```systemverilog
module clk_int_even_div #(
parameter int DIV_VALUE = 2,
parameter bit ENABLE_CLOCK_IN_RESET = 1'b0
) (
input logic clk_i,
input logic rst_n_i,
input logic en_i,
input logic div_i,
input logic div_valid_i,
output logic div_done_o,
output logic clk_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `en_i` | `input` | `input logic en_i` |
| `div_i` | `input` | `input logic div_i` |
| `div_valid_i` | `input` | `input logic div_valid_i` |
| `div_done_o` | `output` | `output logic div_done_o` |
| `clk_o` | `output` | `output logic clk_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
clk_int_even_div #(
.DIV_VALUE(DIV_VALUE),
.ENABLE_CLOCK_IN_RESET(ENABLE_CLOCK_IN_RESET)
) u_clk_int_even_div (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.en_i(en_i),
.div_i(div_i),
.div_valid_i(div_valid_i),
.div_done_o(div_done_o),
.clk_o(clk_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/clk_int_even_div_static.md
+69
View File
@@ -0,0 +1,69 @@
# clk_int_even_div_static
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/clk_int_div.sv`](../../../rtl/clkrst/clk_int_div.sv) |
| Availability | Synthesizable RTL |
## Summary
Static even integer clock divider.
## Functional Behavior
Static even integer clock divider. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DIV_VALUE_WIDTH` | `parameter int DIV_VALUE_WIDTH = 2` |
## Interface Definition
```systemverilog
module clk_int_even_div_static #(
parameter int DIV_VALUE_WIDTH = 2
) (
input logic clk_i,
input logic rst_n_i,
output logic clk_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clk_o` | `output` | `output logic clk_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
clk_int_even_div_static #(
.DIV_VALUE_WIDTH(DIV_VALUE_WIDTH)
) u_clk_int_even_div_static (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clk_o(clk_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/clk_int_odd_div_static.md
+69
View File
@@ -0,0 +1,69 @@
# clk_int_odd_div_static
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/clk_int_div.sv`](../../../rtl/clkrst/clk_int_div.sv) |
| Availability | Synthesizable RTL |
## Summary
Static odd integer clock divider.
## Functional Behavior
Static odd integer clock divider. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DIV_VALUE` | `parameter int DIV_VALUE = 3` |
## Interface Definition
```systemverilog
module clk_int_odd_div_static #(
parameter int DIV_VALUE = 3
) (
input logic clk_i,
input logic rst_n_i,
output logic clk_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clk_o` | `output` | `output logic clk_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
clk_int_odd_div_static #(
.DIV_VALUE(DIV_VALUE)
) u_clk_int_odd_div_static (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clk_o(clk_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/peak_delta_counter.md
+102
View File
@@ -0,0 +1,102 @@
# peak_delta_counter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/counter.sv`](../../../rtl/clkrst/counter.sv) |
| Availability | Synthesizable RTL |
## Summary
Up/down counter with retained high-water mark.
## Functional Behavior
Up/down counter with retained high-water mark. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 4` |
## Interface Definition
```systemverilog
module peak_delta_counter #(
parameter int DATA_WIDTH = 4
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic clear_value_i,
input logic clear_peak_i,
input logic enable_i,
input logic load_i,
input logic subtract_i,
input logic [DATA_WIDTH-1:0] step_i,
input logic [DATA_WIDTH-1:0] load_value_i,
output logic [DATA_WIDTH-1:0] value_o,
output logic [DATA_WIDTH-1:0] peak_o,
output logic value_overflow_o,
output logic peak_overflow_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `clear_value_i` | `input` | `input logic clear_value_i` |
| `clear_peak_i` | `input` | `input logic clear_peak_i` |
| `enable_i` | `input` | `input logic enable_i` |
| `load_i` | `input` | `input logic load_i` |
| `subtract_i` | `input` | `input logic subtract_i` |
| `step_i` | `input` | `input logic [DATA_WIDTH-1:0] step_i` |
| `load_value_i` | `input` | `input logic [DATA_WIDTH-1:0] load_value_i` |
| `value_o` | `output` | `output logic [DATA_WIDTH-1:0] value_o` |
| `peak_o` | `output` | `output logic [DATA_WIDTH-1:0] peak_o` |
| `value_overflow_o` | `output` | `output logic value_overflow_o` |
| `peak_overflow_o` | `output` | `output logic peak_overflow_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
peak_delta_counter #(
.DATA_WIDTH(DATA_WIDTH)
) u_peak_delta_counter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.clear_value_i(clear_value_i),
.clear_peak_i(clear_peak_i),
.enable_i(enable_i),
.load_i(load_i),
.subtract_i(subtract_i),
.step_i(step_i),
.load_value_i(load_value_i),
.value_o(value_o),
.peak_o(peak_o),
.value_overflow_o(value_overflow_o),
.peak_overflow_o(peak_overflow_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/rs_counter.md
+87
View File
@@ -0,0 +1,87 @@
# rs_counter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/counter.sv`](../../../rtl/clkrst/counter.sv) |
| Availability | Synthesizable RTL |
## Summary
Resettable up/down counter.
## Functional Behavior
Resettable up/down counter. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 4` |
## Interface Definition
```systemverilog
module rs_counter #(
parameter int DATA_WIDTH = 4
) (
input logic clk_i,
input logic rst_n_i,
input logic clr_i,
input logic en_i,
input logic load_i,
input logic down_i,
input logic [DATA_WIDTH-1:0] dat_i,
output logic [DATA_WIDTH-1:0] dat_o,
output logic ovf_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clr_i` | `input` | `input logic clr_i` |
| `en_i` | `input` | `input logic en_i` |
| `load_i` | `input` | `input logic load_i` |
| `down_i` | `input` | `input logic down_i` |
| `dat_i` | `input` | `input logic [DATA_WIDTH-1:0] dat_i` |
| `dat_o` | `output` | `output logic [DATA_WIDTH-1:0] dat_o` |
| `ovf_o` | `output` | `output logic ovf_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
rs_counter #(
.DATA_WIDTH(DATA_WIDTH)
) u_rs_counter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clr_i(clr_i),
.en_i(en_i),
.load_i(load_i),
.down_i(down_i),
.dat_i(dat_i),
.dat_o(dat_o),
.ovf_o(ovf_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/rs_delta_counter.md
+90
View File
@@ -0,0 +1,90 @@
# rs_delta_counter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/counter.sv`](../../../rtl/clkrst/counter.sv) |
| Availability | Synthesizable RTL |
## Summary
Delta-counting counter.
## Functional Behavior
Delta-counting counter. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 4` |
## Interface Definition
```systemverilog
module rs_delta_counter #(
parameter int DATA_WIDTH = 4
) (
input logic clk_i,
input logic rst_n_i,
input logic clr_i,
input logic en_i,
input logic load_i,
input logic down_i,
input logic [DATA_WIDTH-1:0] delta_i,
input logic [DATA_WIDTH-1:0] dat_i,
output logic [DATA_WIDTH-1:0] dat_o,
output logic ovf_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clr_i` | `input` | `input logic clr_i` |
| `en_i` | `input` | `input logic en_i` |
| `load_i` | `input` | `input logic load_i` |
| `down_i` | `input` | `input logic down_i` |
| `delta_i` | `input` | `input logic [DATA_WIDTH-1:0] delta_i` |
| `dat_i` | `input` | `input logic [DATA_WIDTH-1:0] dat_i` |
| `dat_o` | `output` | `output logic [DATA_WIDTH-1:0] dat_o` |
| `ovf_o` | `output` | `output logic ovf_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
rs_delta_counter #(
.DATA_WIDTH(DATA_WIDTH)
) u_rs_delta_counter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clr_i(clr_i),
.en_i(en_i),
.load_i(load_i),
.down_i(down_i),
.delta_i(delta_i),
.dat_i(dat_i),
.dat_o(dat_o),
.ovf_o(ovf_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clkrst/rst_sync.md
+69
View File
@@ -0,0 +1,69 @@
# rst_sync
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clkrst/rst_sync.sv`](../../../rtl/clkrst/rst_sync.sv) |
| Availability | Synthesizable RTL |
## Summary
Asynchronous-assert, synchronous-release reset synchronizer.
## Functional Behavior
Asynchronous-assert, synchronous-release reset synchronizer. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `STAGE` | `parameter int STAGE = 3` |
## Interface Definition
```systemverilog
module rst_sync #(
parameter int STAGE = 3
) (
input logic clk_i,
input logic rst_n_i,
output logic rst_n_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `rst_n_o` | `output` | `output logic rst_n_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
rst_sync #(
.STAGE(STAGE)
) u_rst_sync (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.rst_n_o(rst_n_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clock/clock_divider.md
+87
View File
@@ -0,0 +1,87 @@
# clock_divider
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clock/clock_divider.sv`](../../../rtl/clock/clock_divider.sv) |
| Availability | Synthesizable RTL |
## Summary
Runtime-programmable divider that changes only at an output-low boundary.
## Functional Behavior
Runtime-programmable divider that changes only at an output-low boundary. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DIV_WIDTH` | `parameter int DIV_WIDTH = 16` |
| `RESET_DIV` | `parameter logic [DIV_WIDTH-1:0] RESET_DIV = 1` |
## Interface Definition
```systemverilog
module clock_divider #(
parameter int DIV_WIDTH = 16,
parameter logic [DIV_WIDTH-1:0] RESET_DIV = 1
) (
input logic clk_i,
input logic rst_n_i,
input logic enable_i,
input logic [DIV_WIDTH-1:0] div_i,
input logic div_valid_i,
output logic div_ready_o,
output logic clk_o,
output logic [DIV_WIDTH-1:0] count_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `enable_i` | `input` | `input logic enable_i` |
| `div_i` | `input` | `input logic [DIV_WIDTH-1:0] div_i` |
| `div_valid_i` | `input` | `input logic div_valid_i` |
| `div_ready_o` | `output` | `output logic div_ready_o` |
| `clk_o` | `output` | `output logic clk_o` |
| `count_o` | `output` | `output logic [DIV_WIDTH-1:0] count_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
clock_divider #(
.DIV_WIDTH(DIV_WIDTH),
.RESET_DIV(RESET_DIV)
) u_clock_divider (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.enable_i(enable_i),
.div_i(div_i),
.div_valid_i(div_valid_i),
.div_ready_o(div_ready_o),
.clk_o(clk_o),
.count_o(count_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clock/clock_or_tree.md
+66
View File
@@ -0,0 +1,66 @@
# clock_or_tree
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clock/clock_tree.sv`](../../../rtl/clock/clock_tree.sv) |
| Availability | Synthesizable RTL |
## Summary
OR tree for clocks already proven safe to combine.
## Functional Behavior
OR tree for clocks already proven safe to combine. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `CLOCKS` | `parameter int CLOCKS = 2` |
## Interface Definition
```systemverilog
module clock_or_tree #(
parameter int CLOCKS = 2
) (
input logic [CLOCKS-1:0] clock_i,
output logic clock_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clock_i` | `input` | `input logic [CLOCKS-1:0] clock_i` |
| `clock_o` | `output` | `output logic clock_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
clock_or_tree #(
.CLOCKS(CLOCKS)
) u_clock_or_tree (
.clock_i(clock_i),
.clock_o(clock_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/clock/safe_clock_mux.md
+67
View File
@@ -0,0 +1,67 @@
# safe_clock_mux
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/clock/safe_clock_mux.sv`](../../../rtl/clock/safe_clock_mux.sv) |
| Availability | Synthesizable RTL |
## Summary
Glitch-safe handover mux for two continuously running clocks.
## Functional Behavior
Glitch-safe handover mux for two continuously running clocks. It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.
## Suitable Applications
Use in controlled clock/reset infrastructure with explicit physical-design ownership.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
module safe_clock_mux (
input logic clk0_i,
input logic clk1_i,
input logic rst_n_i,
input logic select_i,
output logic clk_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk0_i` | `input` | `input logic clk0_i` |
| `clk1_i` | `input` | `input logic clk1_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `select_i` | `input` | `input logic select_i` |
| `clk_o` | `output` | `output logic clk_o` |
## Integration and Use
Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.
```systemverilog
safe_clock_mux u_safe_clock_mux (
.clk0_i(clk0_i),
.clk1_i(clk1_i),
.rst_n_i(rst_n_i),
.select_i(select_i),
.clk_o(clk_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/ahbl_if.md
+104
View File
@@ -0,0 +1,104 @@
# ahbl_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/ahbl_if.sv`](../../../rtl/interface/ahbl_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
Typed AHB-Lite interface with master and slave modports.
## Functional Behavior
Typed AHB-Lite interface with master and slave modports. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
interface ahbl_if (
input logic hclk,
input logic hresetn
);
logic [31:0] haddr;
logic hwrite;
logic [ 2:0] hsize;
logic [ 2:0] hburst;
logic [ 3:0] hprot;
logic [ 1:0] htrans;
logic hmastlock;
logic [31:0] hwdata;
logic hready;
logic hresp;
logic [31:0] hrdata;
modport slave(
input hclk,
input hresetn,
input haddr,
input hwrite,
input hsize,
input hburst,
input hprot,
input htrans,
input hmastlock,
input hwdata,
output hready,
output hresp,
output hrdata
);
modport master(
input hclk,
input hresetn,
output haddr,
output hwrite,
output hsize,
output hburst,
output hprot,
output htrans,
output hmastlock,
output hwdata,
input hready,
input hresp,
input hrdata
);
endinterface
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `hclk` | `input` | `input logic hclk` |
| `hresetn` | `input` | `input logic hresetn` |
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
ahbl_if ahbl_if_i(.hclk(hclk), .hresetn(hresetn));
// Example: consumer u_consumer (.bus_i(ahbl_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/apb4_if.md
+110
View File
@@ -0,0 +1,110 @@
# apb4_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/apb4_if.sv`](../../../rtl/interface/apb4_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
Clocked APB4 interface with master and slave modports.
## Functional Behavior
Clocked APB4 interface with master and slave modports. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `APB_ADDR_WIDTH` | `parameter int APB_ADDR_WIDTH = 32` |
| `APB_DATA_WIDTH` | `parameter int APB_DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
interface apb4_if #(
parameter int APB_ADDR_WIDTH = 32,
parameter int APB_DATA_WIDTH = 32
) (
input logic pclk,
input logic presetn
);
logic [ APB_ADDR_WIDTH-1:0] paddr;
logic [ 2:0] pprot;
logic psel;
logic penable;
logic pwrite;
logic [ APB_DATA_WIDTH-1:0] pwdata;
logic [APB_DATA_WIDTH/8-1:0] pstrb;
logic pready;
logic [ APB_DATA_WIDTH-1:0] prdata;
logic pslverr;
modport slave(
input pclk,
input presetn,
input paddr,
input pprot,
input psel,
input penable,
input pwrite,
input pwdata,
input pstrb,
output pready,
output prdata,
output pslverr
);
modport master(
input pclk,
input presetn,
output paddr,
output pprot,
output psel,
output penable,
output pwrite,
output pwdata,
output pstrb,
input pready,
input prdata,
input pslverr
);
endinterface
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `pclk` | `input` | `input logic pclk` |
| `presetn` | `input` | `input logic presetn` |
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
apb4_if #(
.APB_ADDR_WIDTH(APB_ADDR_WIDTH),
.APB_DATA_WIDTH(APB_DATA_WIDTH)
) apb4_if_i(.pclk(pclk), .presetn(presetn));
// Example: consumer u_consumer (.bus_i(apb4_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/apb4_pure_if.md
+96
View File
@@ -0,0 +1,96 @@
# apb4_pure_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/apb4_pure_if.sv`](../../../rtl/interface/apb4_pure_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
Clockless APB4 signal interface with master and slave modports.
## Functional Behavior
Clockless APB4 signal interface with master and slave modports. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `APB_ADDR_WIDTH` | `parameter int APB_ADDR_WIDTH = 32` |
| `APB_DATA_WIDTH` | `parameter int APB_DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
interface apb4_pure_if #(
parameter int APB_ADDR_WIDTH = 32,
parameter int APB_DATA_WIDTH = 32
) ();
logic [ APB_ADDR_WIDTH-1:0] paddr;
logic [ 2:0] pprot;
logic psel;
logic penable;
logic pwrite;
logic [ APB_DATA_WIDTH-1:0] pwdata;
logic [APB_DATA_WIDTH/8-1:0] pstrb;
logic pready;
logic [ APB_DATA_WIDTH-1:0] prdata;
logic pslverr;
modport slave(
input paddr,
input pprot,
input psel,
input penable,
input pwrite,
input pwdata,
input pstrb,
output pready,
output prdata,
output pslverr
);
modport master(
output paddr,
output pprot,
output psel,
output penable,
output pwrite,
output pwdata,
output pstrb,
input pready,
input prdata,
input pslverr
);
endinterface
```
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
apb4_pure_if #(
.APB_ADDR_WIDTH(APB_ADDR_WIDTH),
.APB_DATA_WIDTH(APB_DATA_WIDTH)
) apb4_pure_if_i();
// Example: consumer u_consumer (.bus_i(apb4_pure_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/axi4_addr_gen.md
+67
View File
@@ -0,0 +1,67 @@
# axi4_addr_gen
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/interface/axi4_addr_gen.sv`](../../../rtl/interface/axi4_addr_gen.sv) |
| Availability | Synthesizable RTL |
## Summary
AXI4 next-address generator for FIXED, INCR, and legal WRAP bursts.
## Functional Behavior
AXI4 next-address generator for FIXED, INCR, and legal WRAP bursts. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
module axi4_addr_gen (
input logic [ 7:0] alen_i,
input logic [ 2:0] asize_i,
input logic [ 1:0] aburst_i,
input logic [`AXI4_ADDR_OFT_WIDTH-1:0] addr_i,
output logic [`AXI4_ADDR_OFT_WIDTH-1:0] addr_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `alen_i` | `input` | `input logic [ 7:0] alen_i` |
| `asize_i` | `input` | `input logic [ 2:0] asize_i` |
| `aburst_i` | `input` | `input logic [ 1:0] aburst_i` |
| `addr_i` | `input` | `input logic [`AXI4_ADDR_OFT_WIDTH-1:0] addr_i` |
| `addr_o` | `output` | `output logic [`AXI4_ADDR_OFT_WIDTH-1:0] addr_o` |
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
axi4_addr_gen u_axi4_addr_gen (
.alen_i(alen_i),
.asize_i(asize_i),
.aburst_i(aburst_i),
.addr_i(addr_i),
.addr_o(addr_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/axi4_if.md
+214
View File
@@ -0,0 +1,214 @@
# axi4_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/axi4_if.sv`](../../../rtl/interface/axi4_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
Typed AXI4 interface with master and slave modports.
## Functional Behavior
Typed AXI4 interface with master and slave modports. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
interface axi4_if (
input logic aclk,
input logic aresetn
);
logic [ `AXI4_ID_WIDTH-1:0] awid;
logic [ `AXI4_ADDR_WIDTH-1:0] awaddr;
logic [ 7:0] awlen;
logic [ 2:0] awsize;
logic [ 1:0] awburst;
logic awlock;
logic [ 3:0] awcache;
logic [ 2:0] awprot;
logic [ 3:0] awqos;
logic [ 3:0] awregion;
logic [ `AXI4_USER_WIDTH-1:0] awuser;
logic awvalid;
logic awready;
logic [ `AXI4_DATA_WIDTH-1:0] wdata;
logic [`AXI4_DATA_WIDTH/8-1:0] wstrb;
logic wlast;
logic [ `AXI4_USER_WIDTH-1:0] wuser;
logic wvalid;
logic wready;
logic [ `AXI4_ID_WIDTH-1:0] bid;
logic [ 1:0] bresp;
logic [ `AXI4_USER_WIDTH-1:0] buser;
logic bvalid;
logic bready;
logic [ `AXI4_ID_WIDTH-1:0] arid;
logic [ `AXI4_ADDR_WIDTH-1:0] araddr;
logic [ 7:0] arlen;
logic [ 2:0] arsize;
logic [ 1:0] arburst;
logic arlock;
logic [ 3:0] arcache;
logic [ 2:0] arprot;
logic [ 3:0] arqos;
logic [ 3:0] arregion;
logic [ `AXI4_USER_WIDTH-1:0] aruser;
logic arvalid;
logic arready;
logic [ `AXI4_ID_WIDTH-1:0] rid;
logic [ `AXI4_DATA_WIDTH-1:0] rdata;
logic [ 1:0] rresp;
logic rlast;
logic [ `AXI4_USER_WIDTH-1:0] ruser;
logic rvalid;
logic rready;
modport slave(
input aclk,
input aresetn,
input awid,
input awaddr,
input awlen,
input awsize,
input awburst,
input awlock,
input awcache,
input awprot,
input awqos,
input awregion,
input awuser,
input awvalid,
output awready,
input wdata,
input wstrb,
input wlast,
input wuser,
input wvalid,
output wready,
output bid,
output bresp,
output buser,
output bvalid,
input bready,
input arid,
input araddr,
input arlen,
input arsize,
input arburst,
input arlock,
input arcache,
input arprot,
input arqos,
input arregion,
input aruser,
input arvalid,
output arready,
output rid,
output rdata,
output rresp,
output rlast,
output ruser,
output rvalid,
input rready
);
modport master(
input aclk,
input aresetn,
output awid,
output awaddr,
output awlen,
output awsize,
output awburst,
output awlock,
output awcache,
output awprot,
output awqos,
output awregion,
output awuser,
output awvalid,
input awready,
output wdata,
output wstrb,
output wlast,
output wuser,
output wvalid,
input wready,
input bid,
input bresp,
input buser,
input bvalid,
output bready,
output arid,
output araddr,
output arlen,
output arsize,
output arburst,
output arlock,
output arcache,
output arprot,
output arqos,
output arregion,
output aruser,
output arvalid,
input arready,
input rid,
input rdata,
input rresp,
input rlast,
input ruser,
input rvalid,
output rready
);
endinterface
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `aclk` | `input` | `input logic aclk` |
| `aresetn` | `input` | `input logic aresetn` |
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
axi4_if axi4_if_i(.aclk(aclk), .aresetn(aresetn));
// Example: consumer u_consumer (.bus_i(axi4_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/ram_if.md
+55
View File
@@ -0,0 +1,55 @@
# ram_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/ram_if.sv`](../../../rtl/interface/ram_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
Simple RAM request/response interface with master and slave modports.
## Functional Behavior
Simple RAM request/response interface with master and slave modports. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
interface ram_if ();
logic [14:0] addr;
logic [31:0] wdata;
logic [ 3:0] wstrb;
logic [31:0] rdata;
modport slave(input addr, input wdata, input wstrb, output rdata);
modport master(output addr, output wdata, output wstrb, input rdata);
endinterface
```
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
ram_if ram_if_i();
// Example: consumer u_consumer (.bus_i(ram_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/ready_valid_if.md
+84
View File
@@ -0,0 +1,84 @@
# ready_valid_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/ready_valid_if.sv`](../../../rtl/interface/ready_valid_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
Typed ready/valid interface with source, sink, and monitor modports.
## Functional Behavior
Typed ready/valid interface with source, sink, and monitor modports. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
interface ready_valid_if #(
parameter int DATA_WIDTH = 32
) (
input logic clk_i
);
logic [DATA_WIDTH-1:0] data;
logic valid;
logic ready;
modport source(output data, valid, input ready);
modport sink(input data, valid, output ready);
modport monitor(input data, valid, ready);
`ifndef SV_ASSRT_DISABLE
property stable_while_stalled;
@(posedge clk_i) valid && !ready |=> valid && $stable(
data
);
endproperty
assert property (stable_while_stalled)
else $error("ready_valid_if: source changed data while stalled");
`endif
initial begin
if (DATA_WIDTH < 1) $fatal(1, "ready_valid_if: DATA_WIDTH must be positive");
end
endinterface
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
ready_valid_if #(
.DATA_WIDTH(DATA_WIDTH)
) ready_valid_if_i(.clk_i(clk_i));
// Example: consumer u_consumer (.bus_i(ready_valid_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/interface/ribp_if.md
+74
View File
@@ -0,0 +1,74 @@
# ribp_if
| Property | Value |
| --- | --- |
| Kind | `interface` |
| RTL source | [`rtl/interface/ribp_if.sv`](../../../rtl/interface/ribp_if.sv) |
| Availability | SystemVerilog integration API |
## Summary
RIBP request/response interface with response-error signaling.
## Functional Behavior
RIBP request/response interface with response-error signaling. It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.
## Suitable Applications
Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
interface ribp_if ();
logic valid;
logic [31:0] addr;
logic [31:0] wdata;
logic [ 3:0] wstrb;
logic [31:0] rdata;
logic ready;
logic resp_err;
modport slave(
input valid,
input addr,
input wdata,
input wstrb,
output rdata,
output ready,
output resp_err
);
modport master(
output valid,
output addr,
output wdata,
output wstrb,
input rdata,
input ready,
input resp_err
);
endinterface
```
## Integration and Use
Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.
```systemverilog
ribp_if ribp_if_i();
// Example: consumer u_consumer (.bus_i(ribp_if_i.slave));
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/memory/circular_store.md
+117
View File
@@ -0,0 +1,117 @@
# circular_store
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/memory/data_structures.sv`](../../../rtl/memory/data_structures.sv) |
| Availability | Synthesizable RTL |
## Summary
Sequential circular store with bounded random reads.
## Functional Behavior
Sequential circular store with bounded random reads. It implements the declared storage, ordering, banking, or response contract with explicit bounds rather than silently dropping malformed transactions.
## Suitable Applications
Use for local queues, reorder structures, banked stores, and portable memory-backed blocks.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `DEPTH` | `parameter int DEPTH = 8` |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = (DEPTH > 1) ? $clog2(DEPTH) : 1` |
| `STEP_WIDTH` | `parameter int STEP_WIDTH = $clog2(DEPTH + 1)` |
## Interface Definition
```systemverilog
module circular_store #(
parameter int DATA_WIDTH = 32,
parameter int DEPTH = 8,
parameter int ADDR_WIDTH = (DEPTH > 1) ? $clog2(DEPTH) : 1,
parameter int STEP_WIDTH = $clog2(DEPTH + 1)
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic write_valid_i,
output logic write_ready_o,
input logic [DATA_WIDTH-1:0] write_data_i,
input logic read_valid_i,
output logic read_ready_o,
input logic [ADDR_WIDTH-1:0] read_addr_i,
output logic [DATA_WIDTH-1:0] read_data_o,
input logic retire_i,
input logic [STEP_WIDTH-1:0] retire_count_i,
output logic [ADDR_WIDTH-1:0] write_ptr_o,
output logic [ADDR_WIDTH-1:0] read_ptr_o,
output logic full_o,
output logic empty_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `write_valid_i` | `input` | `input logic write_valid_i` |
| `write_ready_o` | `output` | `output logic write_ready_o` |
| `write_data_i` | `input` | `input logic [DATA_WIDTH-1:0] write_data_i` |
| `read_valid_i` | `input` | `input logic read_valid_i` |
| `read_ready_o` | `output` | `output logic read_ready_o` |
| `read_addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] read_addr_i` |
| `read_data_o` | `output` | `output logic [DATA_WIDTH-1:0] read_data_o` |
| `retire_i` | `input` | `input logic retire_i` |
| `retire_count_i` | `input` | `input logic [STEP_WIDTH-1:0] retire_count_i` |
| `write_ptr_o` | `output` | `output logic [ADDR_WIDTH-1:0] write_ptr_o` |
| `read_ptr_o` | `output` | `output logic [ADDR_WIDTH-1:0] read_ptr_o` |
| `full_o` | `output` | `output logic full_o` |
| `empty_o` | `output` | `output logic empty_o` |
## Integration and Use
Follow address, depth, outstanding-request, and response-order constraints exactly. Reset state does not imply initialized storage contents unless documented.
```systemverilog
circular_store #(
.DATA_WIDTH(DATA_WIDTH),
.DEPTH(DEPTH),
.ADDR_WIDTH(ADDR_WIDTH),
.STEP_WIDTH(STEP_WIDTH)
) u_circular_store (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.write_valid_i(write_valid_i),
.write_ready_o(write_ready_o),
.write_data_i(write_data_i),
.read_valid_i(read_valid_i),
.read_ready_o(read_ready_o),
.read_addr_i(read_addr_i),
.read_data_o(read_data_o),
.retire_i(retire_i),
.retire_count_i(retire_count_i),
.write_ptr_o(write_ptr_o),
.read_ptr_o(read_ptr_o),
.full_o(full_o),
.empty_o(empty_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/memory/memory_bank_adapter.md
+129
View File
@@ -0,0 +1,129 @@
# memory_bank_adapter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/memory/data_structures.sv`](../../../rtl/memory/data_structures.sv) |
| Availability | Synthesizable RTL |
## Summary
Public banked-memory request and response adapter.
## Functional Behavior
Public banked-memory request and response adapter. It implements the declared storage, ordering, banking, or response contract with explicit bounds rather than silently dropping malformed transactions.
## Suitable Applications
Use for local queues, reorder structures, banked stores, and portable memory-backed blocks.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = 32` |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `BANKS` | `parameter int BANKS = 2` |
## Interface Definition
```systemverilog
module memory_bank_adapter #(
parameter int ADDR_WIDTH = 32,
parameter int DATA_WIDTH = 32,
parameter int BANKS = 2
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic request_valid_i,
output logic request_ready_o,
input logic [ ADDR_WIDTH-1:0] request_addr_i,
input logic [ DATA_WIDTH-1:0] request_write_data_i,
input logic [DATA_WIDTH/8-1:0] request_strobe_i,
input logic request_write_i,
output logic response_valid_o,
input logic response_ready_i,
output logic [ DATA_WIDTH-1:0] response_data_o,
output logic [ BANKS-1:0] bank_request_valid_o,
input logic [ BANKS-1:0] bank_request_ready_i,
output logic [ BANKS-1:0][ ADDR_WIDTH-1:0] bank_addr_o,
output logic [ BANKS-1:0][ DATA_WIDTH/BANKS-1:0] bank_write_data_o,
output logic [ BANKS-1:0][DATA_WIDTH/(8*BANKS)-1:0] bank_strobe_o,
output logic [ BANKS-1:0] bank_write_o,
input logic [ BANKS-1:0] bank_response_valid_i,
output logic [ BANKS-1:0] bank_response_ready_o,
input logic [ BANKS-1:0][ DATA_WIDTH/BANKS-1:0] bank_response_data_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `request_valid_i` | `input` | `input logic request_valid_i` |
| `request_ready_o` | `output` | `output logic request_ready_o` |
| `request_addr_i` | `input` | `input logic [ ADDR_WIDTH-1:0] request_addr_i` |
| `request_write_data_i` | `input` | `input logic [ DATA_WIDTH-1:0] request_write_data_i` |
| `request_strobe_i` | `input` | `input logic [DATA_WIDTH/8-1:0] request_strobe_i` |
| `request_write_i` | `input` | `input logic request_write_i` |
| `response_valid_o` | `output` | `output logic response_valid_o` |
| `response_ready_i` | `input` | `input logic response_ready_i` |
| `response_data_o` | `output` | `output logic [ DATA_WIDTH-1:0] response_data_o` |
| `bank_request_valid_o` | `output` | `output logic [ BANKS-1:0] bank_request_valid_o` |
| `bank_request_ready_i` | `input` | `input logic [ BANKS-1:0] bank_request_ready_i` |
| `bank_addr_o` | `output` | `output logic [ BANKS-1:0][ ADDR_WIDTH-1:0] bank_addr_o` |
| `bank_write_data_o` | `output` | `output logic [ BANKS-1:0][ DATA_WIDTH/BANKS-1:0] bank_write_data_o` |
| `bank_strobe_o` | `output` | `output logic [ BANKS-1:0][DATA_WIDTH/(8*BANKS)-1:0] bank_strobe_o` |
| `bank_write_o` | `output` | `output logic [ BANKS-1:0] bank_write_o` |
| `bank_response_valid_i` | `input` | `input logic [ BANKS-1:0] bank_response_valid_i` |
| `bank_response_ready_o` | `output` | `output logic [ BANKS-1:0] bank_response_ready_o` |
| `bank_response_data_i` | `input` | `input logic [ BANKS-1:0][ DATA_WIDTH/BANKS-1:0] bank_response_data_i` |
## Integration and Use
Follow address, depth, outstanding-request, and response-order constraints exactly. Reset state does not imply initialized storage contents unless documented.
```systemverilog
memory_bank_adapter #(
.ADDR_WIDTH(ADDR_WIDTH),
.DATA_WIDTH(DATA_WIDTH),
.BANKS(BANKS)
) u_memory_bank_adapter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.request_valid_i(request_valid_i),
.request_ready_o(request_ready_o),
.request_addr_i(request_addr_i),
.request_write_data_i(request_write_data_i),
.request_strobe_i(request_strobe_i),
.request_write_i(request_write_i),
.response_valid_o(response_valid_o),
.response_ready_i(response_ready_i),
.response_data_o(response_data_o),
.bank_request_valid_o(bank_request_valid_o),
.bank_request_ready_i(bank_request_ready_i),
.bank_addr_o(bank_addr_o),
.bank_write_data_o(bank_write_data_o),
.bank_strobe_o(bank_strobe_o),
.bank_write_o(bank_write_o),
.bank_response_valid_i(bank_response_valid_i),
.bank_response_ready_o(bank_response_ready_o),
.bank_response_data_i(bank_response_data_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/memory/memory_bank_adapter_detail.md
+153
View File
@@ -0,0 +1,153 @@
# memory_bank_adapter_detail
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/memory/data_structures.sv`](../../../rtl/memory/data_structures.sv) |
| Availability | Synthesizable RTL |
## Summary
Banked-memory request splitter and response gatherer.
## Functional Behavior
Banked-memory request splitter and response gatherer. It implements the declared storage, ordering, banking, or response contract with explicit bounds rather than silently dropping malformed transactions.
## Suitable Applications
Use for local queues, reorder structures, banked stores, and portable memory-backed blocks.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = 32` |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `WRITE_USER_WIDTH` | `parameter int WRITE_USER_WIDTH = 1` |
| `READ_USER_WIDTH` | `parameter int READ_USER_WIDTH = 1` |
| `BANKS` | `parameter int BANKS = 2` |
| `BANK_DATA_WIDTH` | `parameter int BANK_DATA_WIDTH = DATA_WIDTH / BANKS` |
| `BANK_BYTES` | `parameter int BANK_BYTES = BANK_DATA_WIDTH / 8` |
## Interface Definition
```systemverilog
module memory_bank_adapter_detail #(
parameter int ADDR_WIDTH = 32,
parameter int DATA_WIDTH = 32,
parameter int WRITE_USER_WIDTH = 1,
parameter int READ_USER_WIDTH = 1,
parameter int BANKS = 2,
parameter int BANK_DATA_WIDTH = DATA_WIDTH / BANKS,
parameter int BANK_BYTES = BANK_DATA_WIDTH / 8
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic request_valid_i,
output logic request_ready_o,
input logic [ ADDR_WIDTH-1:0] request_addr_i,
input logic [ DATA_WIDTH-1:0] request_write_data_i,
input logic [ DATA_WIDTH/8-1:0] request_strobe_i,
input logic [WRITE_USER_WIDTH-1:0] request_user_i,
input logic request_write_i,
output logic response_valid_o,
input logic response_ready_i,
output logic [ DATA_WIDTH-1:0] response_data_o,
output logic [ BANKS-1:0][ READ_USER_WIDTH-1:0] response_user_o,
output logic [ BANKS-1:0] bank_request_valid_o,
input logic [ BANKS-1:0] bank_request_ready_i,
output logic [ BANKS-1:0][ ADDR_WIDTH-1:0] bank_addr_o,
output logic [ BANKS-1:0][ BANK_DATA_WIDTH-1:0] bank_write_data_o,
output logic [ BANKS-1:0][ BANK_BYTES-1:0] bank_strobe_o,
output logic [ BANKS-1:0][WRITE_USER_WIDTH-1:0] bank_write_user_o,
output logic [ BANKS-1:0] bank_write_o,
input logic [ BANKS-1:0] bank_response_valid_i,
output logic [ BANKS-1:0] bank_response_ready_o,
input logic [ BANKS-1:0][ BANK_DATA_WIDTH-1:0] bank_response_data_i,
input logic [ BANKS-1:0][ READ_USER_WIDTH-1:0] bank_response_user_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `request_valid_i` | `input` | `input logic request_valid_i` |
| `request_ready_o` | `output` | `output logic request_ready_o` |
| `request_addr_i` | `input` | `input logic [ ADDR_WIDTH-1:0] request_addr_i` |
| `request_write_data_i` | `input` | `input logic [ DATA_WIDTH-1:0] request_write_data_i` |
| `request_strobe_i` | `input` | `input logic [ DATA_WIDTH/8-1:0] request_strobe_i` |
| `request_user_i` | `input` | `input logic [WRITE_USER_WIDTH-1:0] request_user_i` |
| `request_write_i` | `input` | `input logic request_write_i` |
| `response_valid_o` | `output` | `output logic response_valid_o` |
| `response_ready_i` | `input` | `input logic response_ready_i` |
| `response_data_o` | `output` | `output logic [ DATA_WIDTH-1:0] response_data_o` |
| `response_user_o` | `output` | `output logic [ BANKS-1:0][ READ_USER_WIDTH-1:0] response_user_o` |
| `bank_request_valid_o` | `output` | `output logic [ BANKS-1:0] bank_request_valid_o` |
| `bank_request_ready_i` | `input` | `input logic [ BANKS-1:0] bank_request_ready_i` |
| `bank_addr_o` | `output` | `output logic [ BANKS-1:0][ ADDR_WIDTH-1:0] bank_addr_o` |
| `bank_write_data_o` | `output` | `output logic [ BANKS-1:0][ BANK_DATA_WIDTH-1:0] bank_write_data_o` |
| `bank_strobe_o` | `output` | `output logic [ BANKS-1:0][ BANK_BYTES-1:0] bank_strobe_o` |
| `bank_write_user_o` | `output` | `output logic [ BANKS-1:0][WRITE_USER_WIDTH-1:0] bank_write_user_o` |
| `bank_write_o` | `output` | `output logic [ BANKS-1:0] bank_write_o` |
| `bank_response_valid_i` | `input` | `input logic [ BANKS-1:0] bank_response_valid_i` |
| `bank_response_ready_o` | `output` | `output logic [ BANKS-1:0] bank_response_ready_o` |
| `bank_response_data_i` | `input` | `input logic [ BANKS-1:0][ BANK_DATA_WIDTH-1:0] bank_response_data_i` |
| `bank_response_user_i` | `input` | `input logic [ BANKS-1:0][ READ_USER_WIDTH-1:0] bank_response_user_i` |
## Integration and Use
Follow address, depth, outstanding-request, and response-order constraints exactly. Reset state does not imply initialized storage contents unless documented.
```systemverilog
memory_bank_adapter_detail #(
.ADDR_WIDTH(ADDR_WIDTH),
.DATA_WIDTH(DATA_WIDTH),
.WRITE_USER_WIDTH(WRITE_USER_WIDTH),
.READ_USER_WIDTH(READ_USER_WIDTH),
.BANKS(BANKS),
.BANK_DATA_WIDTH(BANK_DATA_WIDTH),
.BANK_BYTES(BANK_BYTES)
) u_memory_bank_adapter_detail (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.request_valid_i(request_valid_i),
.request_ready_o(request_ready_o),
.request_addr_i(request_addr_i),
.request_write_data_i(request_write_data_i),
.request_strobe_i(request_strobe_i),
.request_user_i(request_user_i),
.request_write_i(request_write_i),
.response_valid_o(response_valid_o),
.response_ready_i(response_ready_i),
.response_data_o(response_data_o),
.response_user_o(response_user_o),
.bank_request_valid_o(bank_request_valid_o),
.bank_request_ready_i(bank_request_ready_i),
.bank_addr_o(bank_addr_o),
.bank_write_data_o(bank_write_data_o),
.bank_strobe_o(bank_strobe_o),
.bank_write_user_o(bank_write_user_o),
.bank_write_o(bank_write_o),
.bank_response_valid_i(bank_response_valid_i),
.bank_response_ready_o(bank_response_ready_o),
.bank_response_data_i(bank_response_data_i),
.bank_response_user_i(bank_response_user_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/memory/sync_memory.md
+84
View File
@@ -0,0 +1,84 @@
# sync_memory
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/memory/sync_memory.sv`](../../../rtl/memory/sync_memory.sv) |
| Availability | Synthesizable RTL |
## Summary
Portable synchronous memory model with positive-logic controls.
## Functional Behavior
Portable synchronous memory model with positive-logic controls. It implements the declared storage, ordering, banking, or response contract with explicit bounds rather than silently dropping malformed transactions.
## Suitable Applications
Use for local queues, reorder structures, banked stores, and portable memory-backed blocks.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `DEPTH` | `parameter int DEPTH = 64` |
| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = (DEPTH > 1) ? $clog2(DEPTH) : 1` |
## Interface Definition
```systemverilog
module sync_memory #(
parameter int DATA_WIDTH = 32,
parameter int DEPTH = 64,
parameter int ADDR_WIDTH = (DEPTH > 1) ? $clog2(DEPTH) : 1
) (
input logic clk_i,
input logic write_enable_i,
input logic read_enable_i,
input logic [ADDR_WIDTH-1:0] addr_i,
input logic [DATA_WIDTH-1:0] write_data_i,
output logic [DATA_WIDTH-1:0] read_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `write_enable_i` | `input` | `input logic write_enable_i` |
| `read_enable_i` | `input` | `input logic read_enable_i` |
| `addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] addr_i` |
| `write_data_i` | `input` | `input logic [DATA_WIDTH-1:0] write_data_i` |
| `read_data_o` | `output` | `output logic [DATA_WIDTH-1:0] read_data_o` |
## Integration and Use
Follow address, depth, outstanding-request, and response-order constraints exactly. Reset state does not imply initialized storage contents unless documented.
```systemverilog
sync_memory #(
.DATA_WIDTH(DATA_WIDTH),
.DEPTH(DEPTH),
.ADDR_WIDTH(ADDR_WIDTH)
) u_sync_memory (
.clk_i(clk_i),
.write_enable_i(write_enable_i),
.read_enable_i(read_enable_i),
.addr_i(addr_i),
.write_data_i(write_data_i),
.read_data_o(read_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/memory/tag_order_queue.md
+132
View File
@@ -0,0 +1,132 @@
# tag_order_queue
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/memory/data_structures.sv`](../../../rtl/memory/data_structures.sv) |
| Availability | Synthesizable RTL |
## Summary
Shared-pool queue preserving FIFO order within each tag.
## Functional Behavior
Shared-pool queue preserving FIFO order within each tag. It implements the declared storage, ordering, banking, or response contract with explicit bounds rather than silently dropping malformed transactions.
## Suitable Applications
Use for local queues, reorder structures, banked stores, and portable memory-backed blocks.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `TAG_WIDTH` | `parameter int TAG_WIDTH = 2` |
| `CAPACITY` | `parameter int CAPACITY = 8` |
| `COMPARE_PORTS` | `parameter int COMPARE_PORTS = 1` |
| `REUSE_POPPED_SLOT` | `parameter bit REUSE_POPPED_SLOT = 1'b1` |
| `NODE_WIDTH` | `parameter int NODE_WIDTH = (CAPACITY > 1) ? $clog2(CAPACITY) : 1` |
## Interface Definition
```systemverilog
module tag_order_queue #(
parameter int DATA_WIDTH = 32,
parameter int TAG_WIDTH = 2,
parameter int CAPACITY = 8,
parameter int COMPARE_PORTS = 1,
parameter bit REUSE_POPPED_SLOT = 1'b1,
parameter int NODE_WIDTH = (CAPACITY > 1) ? $clog2(CAPACITY) : 1
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic write_valid_i,
output logic write_ready_o,
input logic [ TAG_WIDTH-1:0] write_tag_i,
input logic [ DATA_WIDTH-1:0] write_data_i,
input logic read_request_i,
input logic [ TAG_WIDTH-1:0] read_tag_i,
input logic read_take_i,
output logic read_ready_o,
output logic read_found_o,
output logic [ DATA_WIDTH-1:0] read_data_o,
input logic [COMPARE_PORTS-1:0][DATA_WIDTH-1:0] compare_data_i,
input logic [COMPARE_PORTS-1:0][DATA_WIDTH-1:0] compare_mask_i,
input logic [COMPARE_PORTS-1:0] compare_valid_i,
output logic [COMPARE_PORTS-1:0] compare_found_o,
output logic full_o,
output logic empty_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `write_valid_i` | `input` | `input logic write_valid_i` |
| `write_ready_o` | `output` | `output logic write_ready_o` |
| `write_tag_i` | `input` | `input logic [ TAG_WIDTH-1:0] write_tag_i` |
| `write_data_i` | `input` | `input logic [ DATA_WIDTH-1:0] write_data_i` |
| `read_request_i` | `input` | `input logic read_request_i` |
| `read_tag_i` | `input` | `input logic [ TAG_WIDTH-1:0] read_tag_i` |
| `read_take_i` | `input` | `input logic read_take_i` |
| `read_ready_o` | `output` | `output logic read_ready_o` |
| `read_found_o` | `output` | `output logic read_found_o` |
| `read_data_o` | `output` | `output logic [ DATA_WIDTH-1:0] read_data_o` |
| `compare_data_i` | `input` | `input logic [COMPARE_PORTS-1:0][DATA_WIDTH-1:0] compare_data_i` |
| `compare_mask_i` | `input` | `input logic [COMPARE_PORTS-1:0][DATA_WIDTH-1:0] compare_mask_i` |
| `compare_valid_i` | `input` | `input logic [COMPARE_PORTS-1:0] compare_valid_i` |
| `compare_found_o` | `output` | `output logic [COMPARE_PORTS-1:0] compare_found_o` |
| `full_o` | `output` | `output logic full_o` |
| `empty_o` | `output` | `output logic empty_o` |
## Integration and Use
Follow address, depth, outstanding-request, and response-order constraints exactly. Reset state does not imply initialized storage contents unless documented.
```systemverilog
tag_order_queue #(
.DATA_WIDTH(DATA_WIDTH),
.TAG_WIDTH(TAG_WIDTH),
.CAPACITY(CAPACITY),
.COMPARE_PORTS(COMPARE_PORTS),
.REUSE_POPPED_SLOT(REUSE_POPPED_SLOT),
.NODE_WIDTH(NODE_WIDTH)
) u_tag_order_queue (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.write_valid_i(write_valid_i),
.write_ready_o(write_ready_o),
.write_tag_i(write_tag_i),
.write_data_i(write_data_i),
.read_request_i(read_request_i),
.read_tag_i(read_tag_i),
.read_take_i(read_take_i),
.read_ready_o(read_ready_o),
.read_found_o(read_found_o),
.read_data_o(read_data_o),
.compare_data_i(compare_data_i),
.compare_mask_i(compare_mask_i),
.compare_valid_i(compare_valid_i),
.compare_found_o(compare_found_o),
.full_o(full_o),
.empty_o(empty_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/model/apb4_master_model.md
+49
View File
@@ -0,0 +1,49 @@
# apb4_master_model
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/model/apb4_master_model.sv`](../../../rtl/model/apb4_master_model.sv) |
| Availability | Simulation/verification model |
## Summary
Simulation APB4 master model.
## Functional Behavior
Simulation APB4 master model. It models the protocol action for simulation and is not a synthesizable protocol endpoint.
## Suitable Applications
Use in a SystemVerilog testbench or directed protocol smoke test.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
module apb4_master_model (
apb4_if.master apb4
);
```
## Integration and Use
Include the required interface/configuration definitions and do not include this model in a silicon file list.
```systemverilog
apb4_master_model u_apb4_master_model (
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/bypass_buffer.md
+81
View File
@@ -0,0 +1,81 @@
# bypass_buffer
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Combinational valid/ready stream pass-through.
## Functional Behavior
Combinational valid/ready stream pass-through. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
module bypass_buffer #(
parameter int DATA_WIDTH = 32
) (
input logic flush_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `flush_i` | `input` | `input logic flush_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
bypass_buffer #(
.DATA_WIDTH(DATA_WIDTH)
) u_bypass_buffer (
.flush_i(flush_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/latest_value_stream.md
+87
View File
@@ -0,0 +1,87 @@
# latest_value_stream
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Valid-only stream adapter retaining the newest pending value.
## Functional Behavior
Valid-only stream adapter retaining the newest pending value. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
module latest_value_stream #(
parameter int DATA_WIDTH = 32
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic in_valid_i,
input logic [DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [DATA_WIDTH-1:0] out_data_o,
output logic busy_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` |
| `busy_o` | `output` | `output logic busy_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
latest_value_stream #(
.DATA_WIDTH(DATA_WIDTH)
) u_latest_value_stream (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.in_valid_i(in_valid_i),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o),
.busy_o(busy_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/memory_response_bridge.md
+111
View File
@@ -0,0 +1,111 @@
# memory_response_bridge
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Response-order bridge between memory and stream interfaces.
## Functional Behavior
Response-order bridge between memory and stream interfaces. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `REQUEST_WIDTH` | `parameter int REQUEST_WIDTH = 32` |
| `RESPONSE_WIDTH` | `parameter int RESPONSE_WIDTH = 32` |
| `RESPONSE_DEPTH` | `parameter int RESPONSE_DEPTH = 2` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(RESPONSE_DEPTH + 1)` |
## Interface Definition
```systemverilog
module memory_response_bridge #(
parameter int REQUEST_WIDTH = 32,
parameter int RESPONSE_WIDTH = 32,
parameter int RESPONSE_DEPTH = 2,
parameter int COUNT_WIDTH = $clog2(RESPONSE_DEPTH + 1)
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic [ REQUEST_WIDTH-1:0] request_i,
input logic request_valid_i,
output logic request_ready_o,
output logic [ REQUEST_WIDTH-1:0] memory_request_o,
output logic memory_request_valid_o,
input logic memory_request_ready_i,
input logic [RESPONSE_WIDTH-1:0] memory_response_i,
input logic memory_response_valid_i,
output logic [RESPONSE_WIDTH-1:0] response_o,
output logic response_valid_o,
input logic response_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `request_i` | `input` | `input logic [ REQUEST_WIDTH-1:0] request_i` |
| `request_valid_i` | `input` | `input logic request_valid_i` |
| `request_ready_o` | `output` | `output logic request_ready_o` |
| `memory_request_o` | `output` | `output logic [ REQUEST_WIDTH-1:0] memory_request_o` |
| `memory_request_valid_o` | `output` | `output logic memory_request_valid_o` |
| `memory_request_ready_i` | `input` | `input logic memory_request_ready_i` |
| `memory_response_i` | `input` | `input logic [RESPONSE_WIDTH-1:0] memory_response_i` |
| `memory_response_valid_i` | `input` | `input logic memory_response_valid_i` |
| `response_o` | `output` | `output logic [RESPONSE_WIDTH-1:0] response_o` |
| `response_valid_o` | `output` | `output logic response_valid_o` |
| `response_ready_i` | `input` | `input logic response_ready_i` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
memory_response_bridge #(
.REQUEST_WIDTH(REQUEST_WIDTH),
.RESPONSE_WIDTH(RESPONSE_WIDTH),
.RESPONSE_DEPTH(RESPONSE_DEPTH),
.COUNT_WIDTH(COUNT_WIDTH)
) u_memory_response_bridge (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.request_i(request_i),
.request_valid_i(request_valid_i),
.request_ready_o(request_ready_o),
.memory_request_o(memory_request_o),
.memory_request_valid_o(memory_request_valid_o),
.memory_request_ready_i(memory_request_ready_i),
.memory_response_i(memory_response_i),
.memory_response_valid_i(memory_response_valid_i),
.response_o(response_o),
.response_valid_o(response_valid_o),
.response_ready_i(response_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/round_robin_arbiter.md
+84
View File
@@ -0,0 +1,84 @@
# round_robin_arbiter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/round_robin_arbiter.sv`](../../../rtl/stream/round_robin_arbiter.sv) |
| Availability | Synthesizable RTL |
## Summary
Fair transfer-driven round-robin arbiter.
## Functional Behavior
Fair transfer-driven round-robin arbiter. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `CLIENTS` | `parameter int CLIENTS = 4` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (CLIENTS > 1) ? $clog2(CLIENTS) : 1` |
## Interface Definition
```systemverilog
module round_robin_arbiter #(
parameter int CLIENTS = 4,
parameter int INDEX_WIDTH = (CLIENTS > 1) ? $clog2(CLIENTS) : 1
) (
input logic clk_i,
input logic rst_n_i,
input logic advance_i,
input logic [ CLIENTS-1:0] request_i,
output logic [ CLIENTS-1:0] grant_o,
output logic [INDEX_WIDTH-1:0] selected_o,
output logic valid_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `advance_i` | `input` | `input logic advance_i` |
| `request_i` | `input` | `input logic [ CLIENTS-1:0] request_i` |
| `grant_o` | `output` | `output logic [ CLIENTS-1:0] grant_o` |
| `selected_o` | `output` | `output logic [INDEX_WIDTH-1:0] selected_o` |
| `valid_o` | `output` | `output logic valid_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
round_robin_arbiter #(
.CLIENTS(CLIENTS),
.INDEX_WIDTH(INDEX_WIDTH)
) u_round_robin_arbiter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.advance_i(advance_i),
.request_i(request_i),
.grant_o(grant_o),
.selected_o(selected_o),
.valid_o(valid_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_buffer.md
+90
View File
@@ -0,0 +1,90 @@
# stream_buffer
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Valid/ready stream wrapper around a spill register.
## Functional Behavior
Valid/ready stream wrapper around a spill register. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `TRANSPARENT` | `parameter bit TRANSPARENT = 1'b0` |
## Interface Definition
```systemverilog
module stream_buffer #(
parameter int DATA_WIDTH = 32,
parameter bit TRANSPARENT = 1'b0
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_buffer #(
.DATA_WIDTH(DATA_WIDTH),
.TRANSPARENT(TRANSPARENT)
) u_stream_buffer (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_collector.md
+84
View File
@@ -0,0 +1,84 @@
# stream_collector
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Collects selected valid/ready inputs into one stream output.
## Functional Behavior
Collects selected valid/ready inputs into one stream output. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `PORTS` | `parameter int PORTS = 4` |
## Interface Definition
```systemverilog
module stream_collector #(
parameter int DATA_WIDTH = 32,
parameter int PORTS = 4
) (
input logic [ PORTS-1:0] in_valid_i,
output logic [ PORTS-1:0] in_ready_o,
input logic [ PORTS-1:0][DATA_WIDTH-1:0] in_data_i,
input logic [ PORTS-1:0] enable_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [PORTS*DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `in_valid_i` | `input` | `input logic [ PORTS-1:0] in_valid_i` |
| `in_ready_o` | `output` | `output logic [ PORTS-1:0] in_ready_o` |
| `in_data_i` | `input` | `input logic [ PORTS-1:0][DATA_WIDTH-1:0] in_data_i` |
| `enable_i` | `input` | `input logic [ PORTS-1:0] enable_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [PORTS*DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_collector #(
.DATA_WIDTH(DATA_WIDTH),
.PORTS(PORTS)
) u_stream_collector (
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.enable_i(enable_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_credit_limiter.md
+99
View File
@@ -0,0 +1,99 @@
# stream_credit_limiter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Limits stream acceptance by available credits.
## Functional Behavior
Limits stream acceptance by available credits. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `MAX_CREDITS` | `parameter int MAX_CREDITS = 4` |
| `CREDIT_WIDTH` | `parameter int CREDIT_WIDTH = $clog2(MAX_CREDITS + 1)` |
## Interface Definition
```systemverilog
module stream_credit_limiter #(
parameter int DATA_WIDTH = 32,
parameter int MAX_CREDITS = 4,
parameter int CREDIT_WIDTH = $clog2(MAX_CREDITS + 1)
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic release_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [ DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [ DATA_WIDTH-1:0] out_data_o,
output logic [CREDIT_WIDTH-1:0] credit_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `release_i` | `input` | `input logic release_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [ DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [ DATA_WIDTH-1:0] out_data_o` |
| `credit_o` | `output` | `output logic [CREDIT_WIDTH-1:0] credit_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_credit_limiter #(
.DATA_WIDTH(DATA_WIDTH),
.MAX_CREDITS(MAX_CREDITS),
.CREDIT_WIDTH(CREDIT_WIDTH)
) u_stream_credit_limiter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.release_i(release_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o),
.credit_o(credit_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_crossbar.md
+108
View File
@@ -0,0 +1,108 @@
# stream_crossbar
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Arbitrates and routes multiple stream inputs to multiple outputs.
## Functional Behavior
Arbitrates and routes multiple stream inputs to multiple outputs. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `INPUTS` | `parameter int INPUTS = 4` |
| `OUTPUTS` | `parameter int OUTPUTS = 4` |
| `FIXED_PRIORITY` | `parameter bit FIXED_PRIORITY = 1'b0` |
| `TARGET_WIDTH` | `parameter int TARGET_WIDTH = (OUTPUTS > 1) ? $clog2(OUTPUTS) : 1` |
| `SOURCE_WIDTH` | `parameter int SOURCE_WIDTH = (INPUTS > 1) ? $clog2(INPUTS) : 1` |
## Interface Definition
```systemverilog
module stream_crossbar #(
parameter int DATA_WIDTH = 32,
parameter int INPUTS = 4,
parameter int OUTPUTS = 4,
parameter bit FIXED_PRIORITY = 1'b0,
parameter int TARGET_WIDTH = (OUTPUTS > 1) ? $clog2(OUTPUTS) : 1,
parameter int SOURCE_WIDTH = (INPUTS > 1) ? $clog2(INPUTS) : 1
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic [ INPUTS-1:0] in_valid_i,
output logic [ INPUTS-1:0] in_ready_o,
input logic [ INPUTS-1:0][ DATA_WIDTH-1:0] in_data_i,
input logic [ INPUTS-1:0][TARGET_WIDTH-1:0] target_i,
output logic [OUTPUTS-1:0] out_valid_o,
input logic [OUTPUTS-1:0] out_ready_i,
output logic [OUTPUTS-1:0][ DATA_WIDTH-1:0] out_data_o,
output logic [OUTPUTS-1:0][SOURCE_WIDTH-1:0] source_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `in_valid_i` | `input` | `input logic [ INPUTS-1:0] in_valid_i` |
| `in_ready_o` | `output` | `output logic [ INPUTS-1:0] in_ready_o` |
| `in_data_i` | `input` | `input logic [ INPUTS-1:0][ DATA_WIDTH-1:0] in_data_i` |
| `target_i` | `input` | `input logic [ INPUTS-1:0][TARGET_WIDTH-1:0] target_i` |
| `out_valid_o` | `output` | `output logic [OUTPUTS-1:0] out_valid_o` |
| `out_ready_i` | `input` | `input logic [OUTPUTS-1:0] out_ready_i` |
| `out_data_o` | `output` | `output logic [OUTPUTS-1:0][ DATA_WIDTH-1:0] out_data_o` |
| `source_o` | `output` | `output logic [OUTPUTS-1:0][SOURCE_WIDTH-1:0] source_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_crossbar #(
.DATA_WIDTH(DATA_WIDTH),
.INPUTS(INPUTS),
.OUTPUTS(OUTPUTS),
.FIXED_PRIORITY(FIXED_PRIORITY),
.TARGET_WIDTH(TARGET_WIDTH),
.SOURCE_WIDTH(SOURCE_WIDTH)
) u_stream_crossbar (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.target_i(target_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o),
.source_o(source_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_delay_injector.md
+99
View File
@@ -0,0 +1,99 @@
# stream_delay_injector
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Controlled stream delay injector for verification and stress.
## Functional Behavior
Controlled stream delay injector for verification and stress. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `FIXED_DELAY` | `parameter int FIXED_DELAY = 1` |
| `RANDOM_DELAY` | `parameter bit RANDOM_DELAY = 1'b0` |
| `RANDOM_SEED` | `parameter logic [15:0] RANDOM_SEED = 16'h1` |
| `RANDOM_POLY` | `parameter logic [15:0] RANDOM_POLY = 16'hB400` |
## Interface Definition
```systemverilog
module stream_delay_injector #(
parameter int DATA_WIDTH = 32,
parameter int FIXED_DELAY = 1,
parameter bit RANDOM_DELAY = 1'b0,
parameter logic [15:0] RANDOM_SEED = 16'h1,
parameter logic [15:0] RANDOM_POLY = 16'hB400
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_delay_injector #(
.DATA_WIDTH(DATA_WIDTH),
.FIXED_DELAY(FIXED_DELAY),
.RANDOM_DELAY(RANDOM_DELAY),
.RANDOM_SEED(RANDOM_SEED),
.RANDOM_POLY(RANDOM_POLY)
) u_stream_delay_injector (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_discard_gate.md
+67
View File
@@ -0,0 +1,67 @@
# stream_discard_gate
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_control.sv`](../../../rtl/stream/stream_control.sv) |
| Availability | Synthesizable RTL |
## Summary
Consumes input transfers while discard is asserted.
## Functional Behavior
Consumes input transfers while discard is asserted. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
This unit has no configurable parameters.
## Interface Definition
```systemverilog
module stream_discard_gate (
input logic in_valid_i,
output logic in_ready_o,
input logic discard_i,
output logic out_valid_o,
input logic out_ready_i
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `discard_i` | `input` | `input logic discard_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_discard_gate u_stream_discard_gate (
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.discard_i(discard_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_elastic_register.md
+87
View File
@@ -0,0 +1,87 @@
# stream_elastic_register
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
One-entry elastic valid/ready register stage.
## Functional Behavior
One-entry elastic valid/ready register stage. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
module stream_elastic_register #(
parameter int DATA_WIDTH = 32
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_elastic_register #(
.DATA_WIDTH(DATA_WIDTH)
) u_stream_elastic_register (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_fair_arbiter.md
+99
View File
@@ -0,0 +1,99 @@
# stream_fair_arbiter
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Fair round-robin arbiter for valid/ready stream inputs.
## Functional Behavior
Fair round-robin arbiter for valid/ready stream inputs. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `PORTS` | `parameter int PORTS = 4` |
| `FIXED_PRIORITY` | `parameter bit FIXED_PRIORITY = 1'b0` |
| `INDEX_WIDTH` | `parameter int INDEX_WIDTH = (PORTS > 1) ? $clog2(PORTS) : 1` |
## Interface Definition
```systemverilog
module stream_fair_arbiter #(
parameter int DATA_WIDTH = 32,
parameter int PORTS = 4,
parameter bit FIXED_PRIORITY = 1'b0,
parameter int INDEX_WIDTH = (PORTS > 1) ? $clog2(PORTS) : 1
) (
input logic clk_i,
input logic rst_n_i,
input logic clear_i,
input logic [ PORTS-1:0] in_valid_i,
output logic [ PORTS-1:0] in_ready_o,
input logic [ PORTS-1:0][DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [ DATA_WIDTH-1:0] out_data_o,
output logic [INDEX_WIDTH-1:0] selected_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `clear_i` | `input` | `input logic clear_i` |
| `in_valid_i` | `input` | `input logic [ PORTS-1:0] in_valid_i` |
| `in_ready_o` | `output` | `output logic [ PORTS-1:0] in_ready_o` |
| `in_data_i` | `input` | `input logic [ PORTS-1:0][DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [ DATA_WIDTH-1:0] out_data_o` |
| `selected_o` | `output` | `output logic [INDEX_WIDTH-1:0] selected_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_fair_arbiter #(
.DATA_WIDTH(DATA_WIDTH),
.PORTS(PORTS),
.FIXED_PRIORITY(FIXED_PRIORITY),
.INDEX_WIDTH(INDEX_WIDTH)
) u_stream_fair_arbiter (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.clear_i(clear_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o),
.selected_o(selected_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_fallthrough_buffer.md
+87
View File
@@ -0,0 +1,87 @@
# stream_fallthrough_buffer
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
One-entry fall-through valid/ready buffer.
## Functional Behavior
One-entry fall-through valid/ready buffer. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
## Interface Definition
```systemverilog
module stream_fallthrough_buffer #(
parameter int DATA_WIDTH = 32
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_fallthrough_buffer #(
.DATA_WIDTH(DATA_WIDTH)
) u_stream_fallthrough_buffer (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_queue.md
+102
View File
@@ -0,0 +1,102 @@
# stream_queue
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) |
| Availability | Synthesizable RTL |
## Summary
Parameterized valid/ready queue with optional fall-through.
## Functional Behavior
Parameterized valid/ready queue with optional fall-through. It follows the repository valid/ready rule: a payload transfers only when both signals are high in the same cycle, and a stalled valid payload remains stable.
## Suitable Applications
Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `DEPTH` | `parameter int DEPTH = 4` |
| `FALL_THROUGH` | `parameter bit FALL_THROUGH = 1'b1` |
| `PTR_WIDTH` | `parameter int PTR_WIDTH = (DEPTH > 1) ? $clog2(DEPTH) : 1` |
| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(DEPTH + 1)` |
## Interface Definition
```systemverilog
module stream_queue #(
parameter int DATA_WIDTH = 32,
parameter int DEPTH = 4,
parameter bit FALL_THROUGH = 1'b1,
parameter int PTR_WIDTH = (DEPTH > 1) ? $clog2(DEPTH) : 1,
parameter int COUNT_WIDTH = $clog2(DEPTH + 1)
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [ DATA_WIDTH-1:0] in_data_i,
output logic out_valid_o,
input logic out_ready_i,
output logic [ DATA_WIDTH-1:0] out_data_o,
output logic [COUNT_WIDTH-1:0] usage_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [ DATA_WIDTH-1:0] in_data_i` |
| `out_valid_o` | `output` | `output logic out_valid_o` |
| `out_ready_i` | `input` | `input logic out_ready_i` |
| `out_data_o` | `output` | `output logic [ DATA_WIDTH-1:0] out_data_o` |
| `usage_o` | `output` | `output logic [COUNT_WIDTH-1:0] usage_o` |
## Integration and Use
Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.
```systemverilog
stream_queue #(
.DATA_WIDTH(DATA_WIDTH),
.DEPTH(DEPTH),
.FALL_THROUGH(FALL_THROUGH),
.PTR_WIDTH(PTR_WIDTH),
.COUNT_WIDTH(COUNT_WIDTH)
) u_stream_queue (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o),
.usage_o(usage_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
docs/reference/stream/stream_replicator.md
+93
View File
@@ -0,0 +1,93 @@
# stream_replicator
| Property | Value |
| --- | --- |
| Kind | `module` |
| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) |
| Availability | Synthesizable RTL |
## Summary
Registered one-item stream distributor with per-target completion.
## Functional Behavior
Captures one input payload and target mask, then presents it to every enabled target exactly once as each target becomes ready. It releases input backpressure only after all selected transfers complete.
## Suitable Applications
Use for multicast command/data distribution with independently stalling consumers.
## Parameters
The declaration below is canonical; retain the RTL-enforced parameter range.
| Parameter | Declaration |
| --- | --- |
| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` |
| `PORTS` | `parameter int PORTS = 4` |
## Interface Definition
```systemverilog
module stream_replicator #(
parameter int DATA_WIDTH = 32,
parameter int PORTS = 4
) (
input logic clk_i,
input logic rst_n_i,
input logic flush_i,
input logic in_valid_i,
output logic in_ready_o,
input logic [DATA_WIDTH-1:0] in_data_i,
input logic [ PORTS-1:0] enable_i,
output logic [ PORTS-1:0] out_valid_o,
input logic [ PORTS-1:0] out_ready_i,
output logic [ PORTS-1:0][DATA_WIDTH-1:0] out_data_o
);
```
### Port Summary
| Signal | Direction | Declaration |
| --- | --- | --- |
| `clk_i` | `input` | `input logic clk_i` |
| `rst_n_i` | `input` | `input logic rst_n_i` |
| `flush_i` | `input` | `input logic flush_i` |
| `in_valid_i` | `input` | `input logic in_valid_i` |
| `in_ready_o` | `output` | `output logic in_ready_o` |
| `in_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` |
| `enable_i` | `input` | `input logic [ PORTS-1:0] enable_i` |
| `out_valid_o` | `output` | `output logic [ PORTS-1:0] out_valid_o` |
| `out_ready_i` | `input` | `input logic [ PORTS-1:0] out_ready_i` |
| `out_data_o` | `output` | `output logic [ PORTS-1:0][DATA_WIDTH-1:0] out_data_o` |
## Integration and Use
The mask is sampled only on input acceptance. `flush_i` aborts a retained item; downstream consumers must obey normal valid/ready semantics.
```systemverilog
stream_replicator #(
.DATA_WIDTH(DATA_WIDTH),
.PORTS(PORTS)
) u_stream_replicator (
.clk_i(clk_i),
.rst_n_i(rst_n_i),
.flush_i(flush_i),
.in_valid_i(in_valid_i),
.in_ready_o(in_ready_o),
.in_data_i(in_data_i),
.enable_i(enable_i),
.out_valid_o(out_valid_o),
.out_ready_i(out_ready_i),
.out_data_o(out_data_o)
);
```
## Dependencies and Verification
The linked RTL source is the implementation authority and contains local assertions for unsupported
parameter combinations. See [`docs/design.md`](../../design.md) for repository-wide CDC, reset,
stream, and storage contracts, and [`docs/verification.md`](../../verification.md) for the
verification matrix.
Loaded 100 of 157 files, more files were not shown because too many files have changed in this diff. Show more