From 3b6a925a51c130e2693f45be05a464db3d96013a Mon Sep 17 00:00:00 2001 From: maksyuki Date: Tue, 4 Aug 2026 16:35:53 +0800 Subject: [PATCH] feat: add documentation for new utility components and scripts - 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. --- .github/workflows/rtl.yml | 2 + AGENTS.md | 4 + Makefile | 6 +- README.md | 217 ++++++++- docs/components.md | 6 + docs/datasheet.md | 5 + docs/design.md | 4 + docs/reference/README.md | 21 + docs/reference/base/bit_count.md | 69 +++ docs/reference/base/component_math_pkg.md | 66 +++ docs/reference/base/counting_bloom_filter.md | 114 +++++ docs/reference/base/credit_pool.md | 93 ++++ docs/reference/base/hash_indicator_bank.md | 78 +++ docs/reference/base/index_to_onehot.md | 75 +++ docs/reference/base/interval_ones_mask.md | 72 +++ docs/reference/base/leading_zero_count.md | 72 +++ docs/reference/base/loop_trip_counter.md | 87 ++++ docs/reference/base/onehot_check.md | 69 +++ docs/reference/base/onehot_to_index.md | 72 +++ docs/reference/base/permutation_hash.md | 81 ++++ docs/reference/base/plru_victim_selector.md | 75 +++ docs/reference/base/prefix_ones_mask.md | 69 +++ docs/reference/base/retry_backoff.md | 87 ++++ docs/reference/base/sample_majority_filter.md | 84 ++++ docs/reference/base/secded_decode.md | 78 +++ docs/reference/base/secded_encode.md | 66 +++ docs/reference/base/secded_layout_pkg.md | 63 +++ docs/reference/base/signal_sink.md | 55 +++ docs/reference/base/signal_tap.md | 66 +++ docs/reference/base/stable_level_filter.md | 84 ++++ docs/reference/base/trailing_zero_count.md | 72 +++ docs/reference/bus/address_map.md | 84 ++++ docs/reference/bus/address_range_decoder.md | 102 ++++ docs/reference/bus/address_region.md | 72 +++ docs/reference/bus/address_set_decoder.md | 105 ++++ docs/reference/cdc/async_gray_queue.md | 96 ++++ docs/reference/cdc/async_reqack.md | 93 ++++ docs/reference/cdc/cdc_2phase.md | 94 ++++ docs/reference/cdc/cdc_2phase_dst.md | 87 ++++ docs/reference/cdc/cdc_2phase_src.md | 87 ++++ docs/reference/cdc/cdc_2phase_warm_flush.md | 103 ++++ docs/reference/cdc/cdc_event_bridge.md | 84 ++++ docs/reference/cdc/cdc_event_bridge_ack.md | 84 ++++ docs/reference/cdc/cdc_fifo.md | 97 ++++ docs/reference/cdc/cdc_fifo_dst.md | 93 ++++ docs/reference/cdc/cdc_fifo_src.md | 93 ++++ docs/reference/cdc/cdc_fifo_warm_flush.md | 106 ++++ .../reference/cdc/cdc_remote_clear_request.md | 84 ++++ docs/reference/cdc/cdc_reset_barrier.md | 78 +++ docs/reference/cdc/cdc_sync.md | 75 +++ docs/reference/cdc/cdc_sync_det.md | 78 +++ .../cdc/cdc_warm_flush_controller.md | 94 ++++ docs/reference/cdc/clearable_async_queue.md | 108 +++++ .../reference/cdc/clearable_two_phase_link.md | 105 ++++ docs/reference/cdc/four_phase_mailbox.md | 93 ++++ docs/reference/cdc/isochronous_handshake.md | 76 +++ .../cdc/isochronous_stream_buffer.md | 93 ++++ docs/reference/cdc/synchronized_edge.md | 84 ++++ docs/reference/cdc/test_reset_synchronizer.md | 78 +++ docs/reference/cdc/two_phase_async_queue.md | 96 ++++ docs/reference/clkrst/clk_int_div_simple.md | 96 ++++ docs/reference/clkrst/clk_int_even_div.md | 84 ++++ .../clkrst/clk_int_even_div_static.md | 69 +++ .../clkrst/clk_int_odd_div_static.md | 69 +++ docs/reference/clkrst/peak_delta_counter.md | 102 ++++ docs/reference/clkrst/rs_counter.md | 87 ++++ docs/reference/clkrst/rs_delta_counter.md | 90 ++++ docs/reference/clkrst/rst_sync.md | 69 +++ docs/reference/clock/clock_divider.md | 87 ++++ docs/reference/clock/clock_or_tree.md | 66 +++ docs/reference/clock/safe_clock_mux.md | 67 +++ docs/reference/interface/ahbl_if.md | 104 ++++ docs/reference/interface/apb4_if.md | 110 +++++ docs/reference/interface/apb4_pure_if.md | 96 ++++ docs/reference/interface/axi4_addr_gen.md | 67 +++ docs/reference/interface/axi4_if.md | 214 +++++++++ docs/reference/interface/ram_if.md | 55 +++ docs/reference/interface/ready_valid_if.md | 84 ++++ docs/reference/interface/ribp_if.md | 74 +++ docs/reference/memory/circular_store.md | 117 +++++ docs/reference/memory/memory_bank_adapter.md | 129 +++++ .../memory/memory_bank_adapter_detail.md | 153 ++++++ docs/reference/memory/sync_memory.md | 84 ++++ docs/reference/memory/tag_order_queue.md | 132 +++++ docs/reference/model/apb4_master_model.md | 49 ++ docs/reference/stream/bypass_buffer.md | 81 ++++ docs/reference/stream/latest_value_stream.md | 87 ++++ .../stream/memory_response_bridge.md | 111 +++++ docs/reference/stream/round_robin_arbiter.md | 84 ++++ docs/reference/stream/stream_buffer.md | 90 ++++ docs/reference/stream/stream_collector.md | 84 ++++ .../reference/stream/stream_credit_limiter.md | 99 ++++ docs/reference/stream/stream_crossbar.md | 108 +++++ .../reference/stream/stream_delay_injector.md | 99 ++++ docs/reference/stream/stream_discard_gate.md | 67 +++ .../stream/stream_elastic_register.md | 87 ++++ docs/reference/stream/stream_fair_arbiter.md | 99 ++++ .../stream/stream_fallthrough_buffer.md | 87 ++++ docs/reference/stream/stream_queue.md | 102 ++++ docs/reference/stream/stream_replicator.md | 93 ++++ docs/reference/stream/stream_router.md | 87 ++++ docs/reference/stream/stream_selector.md | 87 ++++ .../stream/stream_shuffle_network.md | 105 ++++ docs/reference/stream/stream_window_guard.md | 93 ++++ docs/reference/tech/clk_an2.md | 61 +++ docs/reference/tech/clk_buf.md | 58 +++ docs/reference/tech/clk_icg.md | 64 +++ docs/reference/tech/clk_icg2.md | 64 +++ docs/reference/tech/clk_mux2.md | 64 +++ docs/reference/tech/clk_n.md | 58 +++ docs/reference/tech/clk_nd2.md | 61 +++ docs/reference/tech/clk_xor2.md | 61 +++ docs/reference/tech/osc_pad_h.md | 66 +++ docs/reference/tech/osc_pad_v.md | 66 +++ docs/reference/tech/tech_pll.md | 74 +++ docs/reference/tech/tech_ram.md | 84 ++++ docs/reference/tech/tech_ram_bm.md | 90 ++++ docs/reference/tech/tech_regfile.md | 84 ++++ docs/reference/tech/tech_regfile_bm.md | 90 ++++ docs/reference/tech/tri_pd_pad_h.md | 67 +++ docs/reference/tech/tri_pd_pad_v.md | 67 +++ docs/reference/tech/tri_pdu_pad_h.md | 67 +++ docs/reference/tech/tri_pdu_pad_v.md | 67 +++ docs/reference/tech/tri_pu_pad_h.md | 67 +++ docs/reference/tech/tri_pu_pad_v.md | 67 +++ docs/reference/utils/bin2gray.md | 66 +++ docs/reference/utils/dff.md | 69 +++ docs/reference/utils/dffer.md | 75 +++ docs/reference/utils/dfferc.md | 78 +++ docs/reference/utils/dffercn.md | 74 +++ docs/reference/utils/dfferh.md | 75 +++ docs/reference/utils/dfferm.md | 77 +++ docs/reference/utils/dffesr.md | 75 +++ docs/reference/utils/dffl.md | 72 +++ docs/reference/utils/dffr.md | 72 +++ docs/reference/utils/dffrc.md | 75 +++ docs/reference/utils/dffrh.md | 72 +++ docs/reference/utils/dffsr.md | 72 +++ docs/reference/utils/edge_det.md | 81 ++++ docs/reference/utils/edge_det_fe.md | 75 +++ docs/reference/utils/edge_det_re.md | 75 +++ docs/reference/utils/edge_det_sync.md | 75 +++ docs/reference/utils/edge_det_sync_fe.md | 72 +++ docs/reference/utils/edge_det_sync_re.md | 72 +++ docs/reference/utils/fifo.md | 96 ++++ docs/reference/utils/gray2bin.md | 66 +++ docs/reference/utils/lfsr_fibonacci.md | 78 +++ docs/reference/utils/lfsr_galois.md | 81 ++++ docs/reference/utils/ndffr.md | 72 +++ docs/reference/utils/regfield.md | 93 ++++ docs/reference/utils/shift_reg.md | 93 ++++ docs/reference/utils/spill_register.md | 90 ++++ docs/reference/utils/stream_fifo.md | 96 ++++ docs/reference/utils/valid_delay_line.md | 84 ++++ docs/reference/utils/xchecker.md | 66 +++ scripts/check_component_docs.sh | 24 + scripts/render_component_docs.py | 451 ++++++++++++++++++ 157 files changed, 12973 insertions(+), 4 deletions(-) create mode 100644 docs/reference/README.md create mode 100644 docs/reference/base/bit_count.md create mode 100644 docs/reference/base/component_math_pkg.md create mode 100644 docs/reference/base/counting_bloom_filter.md create mode 100644 docs/reference/base/credit_pool.md create mode 100644 docs/reference/base/hash_indicator_bank.md create mode 100644 docs/reference/base/index_to_onehot.md create mode 100644 docs/reference/base/interval_ones_mask.md create mode 100644 docs/reference/base/leading_zero_count.md create mode 100644 docs/reference/base/loop_trip_counter.md create mode 100644 docs/reference/base/onehot_check.md create mode 100644 docs/reference/base/onehot_to_index.md create mode 100644 docs/reference/base/permutation_hash.md create mode 100644 docs/reference/base/plru_victim_selector.md create mode 100644 docs/reference/base/prefix_ones_mask.md create mode 100644 docs/reference/base/retry_backoff.md create mode 100644 docs/reference/base/sample_majority_filter.md create mode 100644 docs/reference/base/secded_decode.md create mode 100644 docs/reference/base/secded_encode.md create mode 100644 docs/reference/base/secded_layout_pkg.md create mode 100644 docs/reference/base/signal_sink.md create mode 100644 docs/reference/base/signal_tap.md create mode 100644 docs/reference/base/stable_level_filter.md create mode 100644 docs/reference/base/trailing_zero_count.md create mode 100644 docs/reference/bus/address_map.md create mode 100644 docs/reference/bus/address_range_decoder.md create mode 100644 docs/reference/bus/address_region.md create mode 100644 docs/reference/bus/address_set_decoder.md create mode 100644 docs/reference/cdc/async_gray_queue.md create mode 100644 docs/reference/cdc/async_reqack.md create mode 100644 docs/reference/cdc/cdc_2phase.md create mode 100644 docs/reference/cdc/cdc_2phase_dst.md create mode 100644 docs/reference/cdc/cdc_2phase_src.md create mode 100644 docs/reference/cdc/cdc_2phase_warm_flush.md create mode 100644 docs/reference/cdc/cdc_event_bridge.md create mode 100644 docs/reference/cdc/cdc_event_bridge_ack.md create mode 100644 docs/reference/cdc/cdc_fifo.md create mode 100644 docs/reference/cdc/cdc_fifo_dst.md create mode 100644 docs/reference/cdc/cdc_fifo_src.md create mode 100644 docs/reference/cdc/cdc_fifo_warm_flush.md create mode 100644 docs/reference/cdc/cdc_remote_clear_request.md create mode 100644 docs/reference/cdc/cdc_reset_barrier.md create mode 100644 docs/reference/cdc/cdc_sync.md create mode 100644 docs/reference/cdc/cdc_sync_det.md create mode 100644 docs/reference/cdc/cdc_warm_flush_controller.md create mode 100644 docs/reference/cdc/clearable_async_queue.md create mode 100644 docs/reference/cdc/clearable_two_phase_link.md create mode 100644 docs/reference/cdc/four_phase_mailbox.md create mode 100644 docs/reference/cdc/isochronous_handshake.md create mode 100644 docs/reference/cdc/isochronous_stream_buffer.md create mode 100644 docs/reference/cdc/synchronized_edge.md create mode 100644 docs/reference/cdc/test_reset_synchronizer.md create mode 100644 docs/reference/cdc/two_phase_async_queue.md create mode 100644 docs/reference/clkrst/clk_int_div_simple.md create mode 100644 docs/reference/clkrst/clk_int_even_div.md create mode 100644 docs/reference/clkrst/clk_int_even_div_static.md create mode 100644 docs/reference/clkrst/clk_int_odd_div_static.md create mode 100644 docs/reference/clkrst/peak_delta_counter.md create mode 100644 docs/reference/clkrst/rs_counter.md create mode 100644 docs/reference/clkrst/rs_delta_counter.md create mode 100644 docs/reference/clkrst/rst_sync.md create mode 100644 docs/reference/clock/clock_divider.md create mode 100644 docs/reference/clock/clock_or_tree.md create mode 100644 docs/reference/clock/safe_clock_mux.md create mode 100644 docs/reference/interface/ahbl_if.md create mode 100644 docs/reference/interface/apb4_if.md create mode 100644 docs/reference/interface/apb4_pure_if.md create mode 100644 docs/reference/interface/axi4_addr_gen.md create mode 100644 docs/reference/interface/axi4_if.md create mode 100644 docs/reference/interface/ram_if.md create mode 100644 docs/reference/interface/ready_valid_if.md create mode 100644 docs/reference/interface/ribp_if.md create mode 100644 docs/reference/memory/circular_store.md create mode 100644 docs/reference/memory/memory_bank_adapter.md create mode 100644 docs/reference/memory/memory_bank_adapter_detail.md create mode 100644 docs/reference/memory/sync_memory.md create mode 100644 docs/reference/memory/tag_order_queue.md create mode 100644 docs/reference/model/apb4_master_model.md create mode 100644 docs/reference/stream/bypass_buffer.md create mode 100644 docs/reference/stream/latest_value_stream.md create mode 100644 docs/reference/stream/memory_response_bridge.md create mode 100644 docs/reference/stream/round_robin_arbiter.md create mode 100644 docs/reference/stream/stream_buffer.md create mode 100644 docs/reference/stream/stream_collector.md create mode 100644 docs/reference/stream/stream_credit_limiter.md create mode 100644 docs/reference/stream/stream_crossbar.md create mode 100644 docs/reference/stream/stream_delay_injector.md create mode 100644 docs/reference/stream/stream_discard_gate.md create mode 100644 docs/reference/stream/stream_elastic_register.md create mode 100644 docs/reference/stream/stream_fair_arbiter.md create mode 100644 docs/reference/stream/stream_fallthrough_buffer.md create mode 100644 docs/reference/stream/stream_queue.md create mode 100644 docs/reference/stream/stream_replicator.md create mode 100644 docs/reference/stream/stream_router.md create mode 100644 docs/reference/stream/stream_selector.md create mode 100644 docs/reference/stream/stream_shuffle_network.md create mode 100644 docs/reference/stream/stream_window_guard.md create mode 100644 docs/reference/tech/clk_an2.md create mode 100644 docs/reference/tech/clk_buf.md create mode 100644 docs/reference/tech/clk_icg.md create mode 100644 docs/reference/tech/clk_icg2.md create mode 100644 docs/reference/tech/clk_mux2.md create mode 100644 docs/reference/tech/clk_n.md create mode 100644 docs/reference/tech/clk_nd2.md create mode 100644 docs/reference/tech/clk_xor2.md create mode 100644 docs/reference/tech/osc_pad_h.md create mode 100644 docs/reference/tech/osc_pad_v.md create mode 100644 docs/reference/tech/tech_pll.md create mode 100644 docs/reference/tech/tech_ram.md create mode 100644 docs/reference/tech/tech_ram_bm.md create mode 100644 docs/reference/tech/tech_regfile.md create mode 100644 docs/reference/tech/tech_regfile_bm.md create mode 100644 docs/reference/tech/tri_pd_pad_h.md create mode 100644 docs/reference/tech/tri_pd_pad_v.md create mode 100644 docs/reference/tech/tri_pdu_pad_h.md create mode 100644 docs/reference/tech/tri_pdu_pad_v.md create mode 100644 docs/reference/tech/tri_pu_pad_h.md create mode 100644 docs/reference/tech/tri_pu_pad_v.md create mode 100644 docs/reference/utils/bin2gray.md create mode 100644 docs/reference/utils/dff.md create mode 100644 docs/reference/utils/dffer.md create mode 100644 docs/reference/utils/dfferc.md create mode 100644 docs/reference/utils/dffercn.md create mode 100644 docs/reference/utils/dfferh.md create mode 100644 docs/reference/utils/dfferm.md create mode 100644 docs/reference/utils/dffesr.md create mode 100644 docs/reference/utils/dffl.md create mode 100644 docs/reference/utils/dffr.md create mode 100644 docs/reference/utils/dffrc.md create mode 100644 docs/reference/utils/dffrh.md create mode 100644 docs/reference/utils/dffsr.md create mode 100644 docs/reference/utils/edge_det.md create mode 100644 docs/reference/utils/edge_det_fe.md create mode 100644 docs/reference/utils/edge_det_re.md create mode 100644 docs/reference/utils/edge_det_sync.md create mode 100644 docs/reference/utils/edge_det_sync_fe.md create mode 100644 docs/reference/utils/edge_det_sync_re.md create mode 100644 docs/reference/utils/fifo.md create mode 100644 docs/reference/utils/gray2bin.md create mode 100644 docs/reference/utils/lfsr_fibonacci.md create mode 100644 docs/reference/utils/lfsr_galois.md create mode 100644 docs/reference/utils/ndffr.md create mode 100644 docs/reference/utils/regfield.md create mode 100644 docs/reference/utils/shift_reg.md create mode 100644 docs/reference/utils/spill_register.md create mode 100644 docs/reference/utils/stream_fifo.md create mode 100644 docs/reference/utils/valid_delay_line.md create mode 100644 docs/reference/utils/xchecker.md create mode 100644 scripts/check_component_docs.sh create mode 100644 scripts/render_component_docs.py diff --git a/.github/workflows/rtl.yml b/.github/workflows/rtl.yml index 0bbc14a..05d3ef8 100644 --- a/.github/workflows/rtl.yml +++ b/.github/workflows/rtl.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 6cd77cb..a6d82d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/Makefile b/Makefile index 659af91..d87f0e9 100644 --- a/Makefile +++ b/Makefile @@ -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) diff --git a/README.md b/README.md index 52f5003..ff1d6bc 100644 --- a/README.md +++ b/README.md @@ -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 + +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. | + + diff --git a/docs/components.md b/docs/components.md index 3ef1855..0af5aea 100644 --- a/docs/components.md +++ b/docs/components.md @@ -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 diff --git a/docs/datasheet.md b/docs/datasheet.md index 31324d1..79f059e 100644 --- a/docs/datasheet.md +++ b/docs/datasheet.md @@ -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 diff --git a/docs/design.md b/docs/design.md index 181d6c2..cff0c75 100644 --- a/docs/design.md +++ b/docs/design.md @@ -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 diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000..e324ed8 --- /dev/null +++ b/docs/reference/README.md @@ -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) diff --git a/docs/reference/base/bit_count.md b/docs/reference/base/bit_count.md new file mode 100644 index 0000000..8e5299c --- /dev/null +++ b/docs/reference/base/bit_count.md @@ -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. diff --git a/docs/reference/base/component_math_pkg.md b/docs/reference/base/component_math_pkg.md new file mode 100644 index 0000000..234a5cb --- /dev/null +++ b/docs/reference/base/component_math_pkg.md @@ -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. diff --git a/docs/reference/base/counting_bloom_filter.md b/docs/reference/base/counting_bloom_filter.md new file mode 100644 index 0000000..8fe6947 --- /dev/null +++ b/docs/reference/base/counting_bloom_filter.md @@ -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. diff --git a/docs/reference/base/credit_pool.md b/docs/reference/base/credit_pool.md new file mode 100644 index 0000000..afa581a --- /dev/null +++ b/docs/reference/base/credit_pool.md @@ -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. diff --git a/docs/reference/base/hash_indicator_bank.md b/docs/reference/base/hash_indicator_bank.md new file mode 100644 index 0000000..f857190 --- /dev/null +++ b/docs/reference/base/hash_indicator_bank.md @@ -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. diff --git a/docs/reference/base/index_to_onehot.md b/docs/reference/base/index_to_onehot.md new file mode 100644 index 0000000..feee62d --- /dev/null +++ b/docs/reference/base/index_to_onehot.md @@ -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. diff --git a/docs/reference/base/interval_ones_mask.md b/docs/reference/base/interval_ones_mask.md new file mode 100644 index 0000000..29722cc --- /dev/null +++ b/docs/reference/base/interval_ones_mask.md @@ -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. diff --git a/docs/reference/base/leading_zero_count.md b/docs/reference/base/leading_zero_count.md new file mode 100644 index 0000000..ee6256d --- /dev/null +++ b/docs/reference/base/leading_zero_count.md @@ -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. diff --git a/docs/reference/base/loop_trip_counter.md b/docs/reference/base/loop_trip_counter.md new file mode 100644 index 0000000..289abea --- /dev/null +++ b/docs/reference/base/loop_trip_counter.md @@ -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. diff --git a/docs/reference/base/onehot_check.md b/docs/reference/base/onehot_check.md new file mode 100644 index 0000000..ddc96c9 --- /dev/null +++ b/docs/reference/base/onehot_check.md @@ -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. diff --git a/docs/reference/base/onehot_to_index.md b/docs/reference/base/onehot_to_index.md new file mode 100644 index 0000000..1c7977f --- /dev/null +++ b/docs/reference/base/onehot_to_index.md @@ -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. diff --git a/docs/reference/base/permutation_hash.md b/docs/reference/base/permutation_hash.md new file mode 100644 index 0000000..065bfca --- /dev/null +++ b/docs/reference/base/permutation_hash.md @@ -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. diff --git a/docs/reference/base/plru_victim_selector.md b/docs/reference/base/plru_victim_selector.md new file mode 100644 index 0000000..522f5f0 --- /dev/null +++ b/docs/reference/base/plru_victim_selector.md @@ -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. diff --git a/docs/reference/base/prefix_ones_mask.md b/docs/reference/base/prefix_ones_mask.md new file mode 100644 index 0000000..7978f9f --- /dev/null +++ b/docs/reference/base/prefix_ones_mask.md @@ -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. diff --git a/docs/reference/base/retry_backoff.md b/docs/reference/base/retry_backoff.md new file mode 100644 index 0000000..b2f5799 --- /dev/null +++ b/docs/reference/base/retry_backoff.md @@ -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. diff --git a/docs/reference/base/sample_majority_filter.md b/docs/reference/base/sample_majority_filter.md new file mode 100644 index 0000000..abe511b --- /dev/null +++ b/docs/reference/base/sample_majority_filter.md @@ -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. diff --git a/docs/reference/base/secded_decode.md b/docs/reference/base/secded_decode.md new file mode 100644 index 0000000..225aac2 --- /dev/null +++ b/docs/reference/base/secded_decode.md @@ -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. diff --git a/docs/reference/base/secded_encode.md b/docs/reference/base/secded_encode.md new file mode 100644 index 0000000..069ce45 --- /dev/null +++ b/docs/reference/base/secded_encode.md @@ -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. diff --git a/docs/reference/base/secded_layout_pkg.md b/docs/reference/base/secded_layout_pkg.md new file mode 100644 index 0000000..19673d9 --- /dev/null +++ b/docs/reference/base/secded_layout_pkg.md @@ -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. diff --git a/docs/reference/base/signal_sink.md b/docs/reference/base/signal_sink.md new file mode 100644 index 0000000..0e832e8 --- /dev/null +++ b/docs/reference/base/signal_sink.md @@ -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. diff --git a/docs/reference/base/signal_tap.md b/docs/reference/base/signal_tap.md new file mode 100644 index 0000000..2cf6c11 --- /dev/null +++ b/docs/reference/base/signal_tap.md @@ -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. diff --git a/docs/reference/base/stable_level_filter.md b/docs/reference/base/stable_level_filter.md new file mode 100644 index 0000000..7d5ff60 --- /dev/null +++ b/docs/reference/base/stable_level_filter.md @@ -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. diff --git a/docs/reference/base/trailing_zero_count.md b/docs/reference/base/trailing_zero_count.md new file mode 100644 index 0000000..3628aa7 --- /dev/null +++ b/docs/reference/base/trailing_zero_count.md @@ -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. diff --git a/docs/reference/bus/address_map.md b/docs/reference/bus/address_map.md new file mode 100644 index 0000000..c9d1831 --- /dev/null +++ b/docs/reference/bus/address_map.md @@ -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. diff --git a/docs/reference/bus/address_range_decoder.md b/docs/reference/bus/address_range_decoder.md new file mode 100644 index 0000000..bba9fcd --- /dev/null +++ b/docs/reference/bus/address_range_decoder.md @@ -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. diff --git a/docs/reference/bus/address_region.md b/docs/reference/bus/address_region.md new file mode 100644 index 0000000..928a71b --- /dev/null +++ b/docs/reference/bus/address_region.md @@ -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. diff --git a/docs/reference/bus/address_set_decoder.md b/docs/reference/bus/address_set_decoder.md new file mode 100644 index 0000000..9c5654e --- /dev/null +++ b/docs/reference/bus/address_set_decoder.md @@ -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. diff --git a/docs/reference/cdc/async_gray_queue.md b/docs/reference/cdc/async_gray_queue.md new file mode 100644 index 0000000..89cbd7f --- /dev/null +++ b/docs/reference/cdc/async_gray_queue.md @@ -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. diff --git a/docs/reference/cdc/async_reqack.md b/docs/reference/cdc/async_reqack.md new file mode 100644 index 0000000..3442912 --- /dev/null +++ b/docs/reference/cdc/async_reqack.md @@ -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. diff --git a/docs/reference/cdc/cdc_2phase.md b/docs/reference/cdc/cdc_2phase.md new file mode 100644 index 0000000..254b4ae --- /dev/null +++ b/docs/reference/cdc/cdc_2phase.md @@ -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. diff --git a/docs/reference/cdc/cdc_2phase_dst.md b/docs/reference/cdc/cdc_2phase_dst.md new file mode 100644 index 0000000..3529d8a --- /dev/null +++ b/docs/reference/cdc/cdc_2phase_dst.md @@ -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. diff --git a/docs/reference/cdc/cdc_2phase_src.md b/docs/reference/cdc/cdc_2phase_src.md new file mode 100644 index 0000000..76c9f73 --- /dev/null +++ b/docs/reference/cdc/cdc_2phase_src.md @@ -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. diff --git a/docs/reference/cdc/cdc_2phase_warm_flush.md b/docs/reference/cdc/cdc_2phase_warm_flush.md new file mode 100644 index 0000000..93b928a --- /dev/null +++ b/docs/reference/cdc/cdc_2phase_warm_flush.md @@ -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. diff --git a/docs/reference/cdc/cdc_event_bridge.md b/docs/reference/cdc/cdc_event_bridge.md new file mode 100644 index 0000000..19d90a0 --- /dev/null +++ b/docs/reference/cdc/cdc_event_bridge.md @@ -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. diff --git a/docs/reference/cdc/cdc_event_bridge_ack.md b/docs/reference/cdc/cdc_event_bridge_ack.md new file mode 100644 index 0000000..37c9f48 --- /dev/null +++ b/docs/reference/cdc/cdc_event_bridge_ack.md @@ -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. diff --git a/docs/reference/cdc/cdc_fifo.md b/docs/reference/cdc/cdc_fifo.md new file mode 100644 index 0000000..bb24338 --- /dev/null +++ b/docs/reference/cdc/cdc_fifo.md @@ -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. diff --git a/docs/reference/cdc/cdc_fifo_dst.md b/docs/reference/cdc/cdc_fifo_dst.md new file mode 100644 index 0000000..8876f89 --- /dev/null +++ b/docs/reference/cdc/cdc_fifo_dst.md @@ -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. diff --git a/docs/reference/cdc/cdc_fifo_src.md b/docs/reference/cdc/cdc_fifo_src.md new file mode 100644 index 0000000..e49b71b --- /dev/null +++ b/docs/reference/cdc/cdc_fifo_src.md @@ -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. diff --git a/docs/reference/cdc/cdc_fifo_warm_flush.md b/docs/reference/cdc/cdc_fifo_warm_flush.md new file mode 100644 index 0000000..f06a485 --- /dev/null +++ b/docs/reference/cdc/cdc_fifo_warm_flush.md @@ -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. diff --git a/docs/reference/cdc/cdc_remote_clear_request.md b/docs/reference/cdc/cdc_remote_clear_request.md new file mode 100644 index 0000000..4fcf33c --- /dev/null +++ b/docs/reference/cdc/cdc_remote_clear_request.md @@ -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. diff --git a/docs/reference/cdc/cdc_reset_barrier.md b/docs/reference/cdc/cdc_reset_barrier.md new file mode 100644 index 0000000..b1c0e32 --- /dev/null +++ b/docs/reference/cdc/cdc_reset_barrier.md @@ -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. diff --git a/docs/reference/cdc/cdc_sync.md b/docs/reference/cdc/cdc_sync.md new file mode 100644 index 0000000..0756395 --- /dev/null +++ b/docs/reference/cdc/cdc_sync.md @@ -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. diff --git a/docs/reference/cdc/cdc_sync_det.md b/docs/reference/cdc/cdc_sync_det.md new file mode 100644 index 0000000..19e27a8 --- /dev/null +++ b/docs/reference/cdc/cdc_sync_det.md @@ -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. diff --git a/docs/reference/cdc/cdc_warm_flush_controller.md b/docs/reference/cdc/cdc_warm_flush_controller.md new file mode 100644 index 0000000..0792f34 --- /dev/null +++ b/docs/reference/cdc/cdc_warm_flush_controller.md @@ -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. diff --git a/docs/reference/cdc/clearable_async_queue.md b/docs/reference/cdc/clearable_async_queue.md new file mode 100644 index 0000000..39e9d89 --- /dev/null +++ b/docs/reference/cdc/clearable_async_queue.md @@ -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. diff --git a/docs/reference/cdc/clearable_two_phase_link.md b/docs/reference/cdc/clearable_two_phase_link.md new file mode 100644 index 0000000..1f298d3 --- /dev/null +++ b/docs/reference/cdc/clearable_two_phase_link.md @@ -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. diff --git a/docs/reference/cdc/four_phase_mailbox.md b/docs/reference/cdc/four_phase_mailbox.md new file mode 100644 index 0000000..373add6 --- /dev/null +++ b/docs/reference/cdc/four_phase_mailbox.md @@ -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. diff --git a/docs/reference/cdc/isochronous_handshake.md b/docs/reference/cdc/isochronous_handshake.md new file mode 100644 index 0000000..82a8b87 --- /dev/null +++ b/docs/reference/cdc/isochronous_handshake.md @@ -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. diff --git a/docs/reference/cdc/isochronous_stream_buffer.md b/docs/reference/cdc/isochronous_stream_buffer.md new file mode 100644 index 0000000..fcc7967 --- /dev/null +++ b/docs/reference/cdc/isochronous_stream_buffer.md @@ -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. diff --git a/docs/reference/cdc/synchronized_edge.md b/docs/reference/cdc/synchronized_edge.md new file mode 100644 index 0000000..91ff8f0 --- /dev/null +++ b/docs/reference/cdc/synchronized_edge.md @@ -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. diff --git a/docs/reference/cdc/test_reset_synchronizer.md b/docs/reference/cdc/test_reset_synchronizer.md new file mode 100644 index 0000000..ca82b0d --- /dev/null +++ b/docs/reference/cdc/test_reset_synchronizer.md @@ -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. diff --git a/docs/reference/cdc/two_phase_async_queue.md b/docs/reference/cdc/two_phase_async_queue.md new file mode 100644 index 0000000..e174d1e --- /dev/null +++ b/docs/reference/cdc/two_phase_async_queue.md @@ -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. diff --git a/docs/reference/clkrst/clk_int_div_simple.md b/docs/reference/clkrst/clk_int_div_simple.md new file mode 100644 index 0000000..6126d42 --- /dev/null +++ b/docs/reference/clkrst/clk_int_div_simple.md @@ -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. diff --git a/docs/reference/clkrst/clk_int_even_div.md b/docs/reference/clkrst/clk_int_even_div.md new file mode 100644 index 0000000..17187ff --- /dev/null +++ b/docs/reference/clkrst/clk_int_even_div.md @@ -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. diff --git a/docs/reference/clkrst/clk_int_even_div_static.md b/docs/reference/clkrst/clk_int_even_div_static.md new file mode 100644 index 0000000..7ba3a39 --- /dev/null +++ b/docs/reference/clkrst/clk_int_even_div_static.md @@ -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. diff --git a/docs/reference/clkrst/clk_int_odd_div_static.md b/docs/reference/clkrst/clk_int_odd_div_static.md new file mode 100644 index 0000000..f40d849 --- /dev/null +++ b/docs/reference/clkrst/clk_int_odd_div_static.md @@ -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. diff --git a/docs/reference/clkrst/peak_delta_counter.md b/docs/reference/clkrst/peak_delta_counter.md new file mode 100644 index 0000000..e37b973 --- /dev/null +++ b/docs/reference/clkrst/peak_delta_counter.md @@ -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. diff --git a/docs/reference/clkrst/rs_counter.md b/docs/reference/clkrst/rs_counter.md new file mode 100644 index 0000000..fbef014 --- /dev/null +++ b/docs/reference/clkrst/rs_counter.md @@ -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. diff --git a/docs/reference/clkrst/rs_delta_counter.md b/docs/reference/clkrst/rs_delta_counter.md new file mode 100644 index 0000000..71792c3 --- /dev/null +++ b/docs/reference/clkrst/rs_delta_counter.md @@ -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. diff --git a/docs/reference/clkrst/rst_sync.md b/docs/reference/clkrst/rst_sync.md new file mode 100644 index 0000000..4115d0e --- /dev/null +++ b/docs/reference/clkrst/rst_sync.md @@ -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. diff --git a/docs/reference/clock/clock_divider.md b/docs/reference/clock/clock_divider.md new file mode 100644 index 0000000..b8b2a7c --- /dev/null +++ b/docs/reference/clock/clock_divider.md @@ -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. diff --git a/docs/reference/clock/clock_or_tree.md b/docs/reference/clock/clock_or_tree.md new file mode 100644 index 0000000..eb38ad4 --- /dev/null +++ b/docs/reference/clock/clock_or_tree.md @@ -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. diff --git a/docs/reference/clock/safe_clock_mux.md b/docs/reference/clock/safe_clock_mux.md new file mode 100644 index 0000000..90a843e --- /dev/null +++ b/docs/reference/clock/safe_clock_mux.md @@ -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. diff --git a/docs/reference/interface/ahbl_if.md b/docs/reference/interface/ahbl_if.md new file mode 100644 index 0000000..116dde1 --- /dev/null +++ b/docs/reference/interface/ahbl_if.md @@ -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. diff --git a/docs/reference/interface/apb4_if.md b/docs/reference/interface/apb4_if.md new file mode 100644 index 0000000..d300672 --- /dev/null +++ b/docs/reference/interface/apb4_if.md @@ -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. diff --git a/docs/reference/interface/apb4_pure_if.md b/docs/reference/interface/apb4_pure_if.md new file mode 100644 index 0000000..346b7d2 --- /dev/null +++ b/docs/reference/interface/apb4_pure_if.md @@ -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. diff --git a/docs/reference/interface/axi4_addr_gen.md b/docs/reference/interface/axi4_addr_gen.md new file mode 100644 index 0000000..17ebc91 --- /dev/null +++ b/docs/reference/interface/axi4_addr_gen.md @@ -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. diff --git a/docs/reference/interface/axi4_if.md b/docs/reference/interface/axi4_if.md new file mode 100644 index 0000000..82b6da8 --- /dev/null +++ b/docs/reference/interface/axi4_if.md @@ -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. diff --git a/docs/reference/interface/ram_if.md b/docs/reference/interface/ram_if.md new file mode 100644 index 0000000..58a04d8 --- /dev/null +++ b/docs/reference/interface/ram_if.md @@ -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. diff --git a/docs/reference/interface/ready_valid_if.md b/docs/reference/interface/ready_valid_if.md new file mode 100644 index 0000000..e022053 --- /dev/null +++ b/docs/reference/interface/ready_valid_if.md @@ -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. diff --git a/docs/reference/interface/ribp_if.md b/docs/reference/interface/ribp_if.md new file mode 100644 index 0000000..7be3ea0 --- /dev/null +++ b/docs/reference/interface/ribp_if.md @@ -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. diff --git a/docs/reference/memory/circular_store.md b/docs/reference/memory/circular_store.md new file mode 100644 index 0000000..33f60b0 --- /dev/null +++ b/docs/reference/memory/circular_store.md @@ -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. diff --git a/docs/reference/memory/memory_bank_adapter.md b/docs/reference/memory/memory_bank_adapter.md new file mode 100644 index 0000000..f3404ba --- /dev/null +++ b/docs/reference/memory/memory_bank_adapter.md @@ -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. diff --git a/docs/reference/memory/memory_bank_adapter_detail.md b/docs/reference/memory/memory_bank_adapter_detail.md new file mode 100644 index 0000000..698cf9a --- /dev/null +++ b/docs/reference/memory/memory_bank_adapter_detail.md @@ -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. diff --git a/docs/reference/memory/sync_memory.md b/docs/reference/memory/sync_memory.md new file mode 100644 index 0000000..3d1353d --- /dev/null +++ b/docs/reference/memory/sync_memory.md @@ -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. diff --git a/docs/reference/memory/tag_order_queue.md b/docs/reference/memory/tag_order_queue.md new file mode 100644 index 0000000..89e7b01 --- /dev/null +++ b/docs/reference/memory/tag_order_queue.md @@ -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. diff --git a/docs/reference/model/apb4_master_model.md b/docs/reference/model/apb4_master_model.md new file mode 100644 index 0000000..6fb62e1 --- /dev/null +++ b/docs/reference/model/apb4_master_model.md @@ -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. diff --git a/docs/reference/stream/bypass_buffer.md b/docs/reference/stream/bypass_buffer.md new file mode 100644 index 0000000..271fd09 --- /dev/null +++ b/docs/reference/stream/bypass_buffer.md @@ -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. diff --git a/docs/reference/stream/latest_value_stream.md b/docs/reference/stream/latest_value_stream.md new file mode 100644 index 0000000..2f2aafc --- /dev/null +++ b/docs/reference/stream/latest_value_stream.md @@ -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. diff --git a/docs/reference/stream/memory_response_bridge.md b/docs/reference/stream/memory_response_bridge.md new file mode 100644 index 0000000..2fa44c8 --- /dev/null +++ b/docs/reference/stream/memory_response_bridge.md @@ -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. diff --git a/docs/reference/stream/round_robin_arbiter.md b/docs/reference/stream/round_robin_arbiter.md new file mode 100644 index 0000000..e24dc98 --- /dev/null +++ b/docs/reference/stream/round_robin_arbiter.md @@ -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. diff --git a/docs/reference/stream/stream_buffer.md b/docs/reference/stream/stream_buffer.md new file mode 100644 index 0000000..dead7d8 --- /dev/null +++ b/docs/reference/stream/stream_buffer.md @@ -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. diff --git a/docs/reference/stream/stream_collector.md b/docs/reference/stream/stream_collector.md new file mode 100644 index 0000000..0c82988 --- /dev/null +++ b/docs/reference/stream/stream_collector.md @@ -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. diff --git a/docs/reference/stream/stream_credit_limiter.md b/docs/reference/stream/stream_credit_limiter.md new file mode 100644 index 0000000..0c9c6db --- /dev/null +++ b/docs/reference/stream/stream_credit_limiter.md @@ -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. diff --git a/docs/reference/stream/stream_crossbar.md b/docs/reference/stream/stream_crossbar.md new file mode 100644 index 0000000..d279408 --- /dev/null +++ b/docs/reference/stream/stream_crossbar.md @@ -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. diff --git a/docs/reference/stream/stream_delay_injector.md b/docs/reference/stream/stream_delay_injector.md new file mode 100644 index 0000000..31061de --- /dev/null +++ b/docs/reference/stream/stream_delay_injector.md @@ -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. diff --git a/docs/reference/stream/stream_discard_gate.md b/docs/reference/stream/stream_discard_gate.md new file mode 100644 index 0000000..d388d7e --- /dev/null +++ b/docs/reference/stream/stream_discard_gate.md @@ -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. diff --git a/docs/reference/stream/stream_elastic_register.md b/docs/reference/stream/stream_elastic_register.md new file mode 100644 index 0000000..73e8bb0 --- /dev/null +++ b/docs/reference/stream/stream_elastic_register.md @@ -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. diff --git a/docs/reference/stream/stream_fair_arbiter.md b/docs/reference/stream/stream_fair_arbiter.md new file mode 100644 index 0000000..1405c66 --- /dev/null +++ b/docs/reference/stream/stream_fair_arbiter.md @@ -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. diff --git a/docs/reference/stream/stream_fallthrough_buffer.md b/docs/reference/stream/stream_fallthrough_buffer.md new file mode 100644 index 0000000..5528fd2 --- /dev/null +++ b/docs/reference/stream/stream_fallthrough_buffer.md @@ -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. diff --git a/docs/reference/stream/stream_queue.md b/docs/reference/stream/stream_queue.md new file mode 100644 index 0000000..49eb962 --- /dev/null +++ b/docs/reference/stream/stream_queue.md @@ -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. diff --git a/docs/reference/stream/stream_replicator.md b/docs/reference/stream/stream_replicator.md new file mode 100644 index 0000000..ce4fb48 --- /dev/null +++ b/docs/reference/stream/stream_replicator.md @@ -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. diff --git a/docs/reference/stream/stream_router.md b/docs/reference/stream/stream_router.md new file mode 100644 index 0000000..9c315e6 --- /dev/null +++ b/docs/reference/stream/stream_router.md @@ -0,0 +1,87 @@ +# stream_router + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Routes one valid/ready input to a selected output. + +## Functional Behavior + +Routes one valid/ready input to a selected 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` | +| `SELECT_WIDTH` | `parameter int SELECT_WIDTH = (PORTS > 1) ? $clog2(PORTS) : 1` | + +## Interface Definition + +```systemverilog +module stream_router #( + parameter int DATA_WIDTH = 32, + parameter int PORTS = 4, + parameter int SELECT_WIDTH = (PORTS > 1) ? $clog2(PORTS) : 1 +) ( + input logic [SELECT_WIDTH-1:0] select_i, + input logic in_valid_i, + output logic in_ready_o, + input logic [ DATA_WIDTH-1:0] in_data_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 | +| --- | --- | --- | +| `select_i` | `input` | `input logic [SELECT_WIDTH-1:0] select_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 [ 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 + +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_router #( + .DATA_WIDTH(DATA_WIDTH), + .PORTS(PORTS), + .SELECT_WIDTH(SELECT_WIDTH) +) u_stream_router ( + .select_i(select_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. diff --git a/docs/reference/stream/stream_selector.md b/docs/reference/stream/stream_selector.md new file mode 100644 index 0000000..a54dc00 --- /dev/null +++ b/docs/reference/stream/stream_selector.md @@ -0,0 +1,87 @@ +# stream_selector + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/stream/stream_cells.sv`](../../../rtl/stream/stream_cells.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Selects one of several valid/ready inputs. + +## Functional Behavior + +Selects one of several valid/ready 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` | +| `SELECT_WIDTH` | `parameter int SELECT_WIDTH = (PORTS > 1) ? $clog2(PORTS) : 1` | + +## Interface Definition + +```systemverilog +module stream_selector #( + parameter int DATA_WIDTH = 32, + parameter int PORTS = 4, + parameter int SELECT_WIDTH = (PORTS > 1) ? $clog2(PORTS) : 1 +) ( + input logic [SELECT_WIDTH-1:0] select_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 +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `select_i` | `input` | `input logic [SELECT_WIDTH-1:0] select_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` | + +## 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_selector #( + .DATA_WIDTH(DATA_WIDTH), + .PORTS(PORTS), + .SELECT_WIDTH(SELECT_WIDTH) +) u_stream_selector ( + .select_i(select_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. diff --git a/docs/reference/stream/stream_shuffle_network.md b/docs/reference/stream/stream_shuffle_network.md new file mode 100644 index 0000000..f8da22c --- /dev/null +++ b/docs/reference/stream/stream_shuffle_network.md @@ -0,0 +1,105 @@ +# stream_shuffle_network + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/stream/stream_advanced.sv`](../../../rtl/stream/stream_advanced.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Deterministic stream-lane permutation network. + +## Functional Behavior + +Deterministic stream-lane permutation network. 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` | +| `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_shuffle_network #( + parameter int DATA_WIDTH = 32, + parameter int INPUTS = 4, + parameter int OUTPUTS = 4, + 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_shuffle_network #( + .DATA_WIDTH(DATA_WIDTH), + .INPUTS(INPUTS), + .OUTPUTS(OUTPUTS), + .TARGET_WIDTH(TARGET_WIDTH), + .SOURCE_WIDTH(SOURCE_WIDTH) +) u_stream_shuffle_network ( + .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. diff --git a/docs/reference/stream/stream_window_guard.md b/docs/reference/stream/stream_window_guard.md new file mode 100644 index 0000000..8f92260 --- /dev/null +++ b/docs/reference/stream/stream_window_guard.md @@ -0,0 +1,93 @@ +# stream_window_guard + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/stream/stream_control.sv`](../../../rtl/stream/stream_control.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Limits outstanding stream requests with explicit retire accounting. + +## Functional Behavior + +Limits outstanding stream requests with explicit retire accounting. 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 | +| --- | --- | +| `MAX_INFLIGHT` | `parameter int MAX_INFLIGHT = 4` | +| `COUNT_WIDTH` | `parameter int COUNT_WIDTH = $clog2(MAX_INFLIGHT + 1)` | + +## Interface Definition + +```systemverilog +module stream_window_guard #( + parameter int MAX_INFLIGHT = 4, + parameter int COUNT_WIDTH = $clog2(MAX_INFLIGHT + 1) +) ( + input logic clk_i, + input logic rst_n_i, + input logic flush_i, + input logic [COUNT_WIDTH-1:0] limit_i, + input logic submit_valid_i, + output logic submit_ready_o, + output logic forward_valid_o, + input logic forward_ready_i, + input logic retire_i, + output logic [COUNT_WIDTH-1:0] used_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` | +| `limit_i` | `input` | `input logic [COUNT_WIDTH-1:0] limit_i` | +| `submit_valid_i` | `input` | `input logic submit_valid_i` | +| `submit_ready_o` | `output` | `output logic submit_ready_o` | +| `forward_valid_o` | `output` | `output logic forward_valid_o` | +| `forward_ready_i` | `input` | `input logic forward_ready_i` | +| `retire_i` | `input` | `input logic retire_i` | +| `used_o` | `output` | `output logic [COUNT_WIDTH-1:0] used_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_window_guard #( + .MAX_INFLIGHT(MAX_INFLIGHT), + .COUNT_WIDTH(COUNT_WIDTH) +) u_stream_window_guard ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .flush_i(flush_i), + .limit_i(limit_i), + .submit_valid_i(submit_valid_i), + .submit_ready_o(submit_ready_o), + .forward_valid_o(forward_valid_o), + .forward_ready_i(forward_ready_i), + .retire_i(retire_i), + .used_o(used_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. diff --git a/docs/reference/tech/clk_an2.md b/docs/reference/tech/clk_an2.md new file mode 100644 index 0000000..a59aeba --- /dev/null +++ b/docs/reference/tech/clk_an2.md @@ -0,0 +1,61 @@ +# clk_an2 + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral two-input clock AND model. + +## Functional Behavior + +Behavioral two-input clock AND model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_an2 ( + input logic clk1_i, + input logic clk2_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk1_i` | `input` | `input logic clk1_i` | +| `clk2_i` | `input` | `input logic clk2_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_an2 u_clk_an2 ( + .clk1_i(clk1_i), + .clk2_i(clk2_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. diff --git a/docs/reference/tech/clk_buf.md b/docs/reference/tech/clk_buf.md new file mode 100644 index 0000000..ab788f1 --- /dev/null +++ b/docs/reference/tech/clk_buf.md @@ -0,0 +1,58 @@ +# clk_buf + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral clock buffer model. + +## Functional Behavior + +Behavioral clock buffer model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_buf ( + input logic clk_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_buf u_clk_buf ( + .clk_i(clk_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. diff --git a/docs/reference/tech/clk_icg.md b/docs/reference/tech/clk_icg.md new file mode 100644 index 0000000..474cfa9 --- /dev/null +++ b/docs/reference/tech/clk_icg.md @@ -0,0 +1,64 @@ +# clk_icg + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral integrated clock-gate model. + +## Functional Behavior + +Behavioral integrated clock-gate model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_icg ( + input logic clk_i, + input logic en_i, + input logic te_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `en_i` | `input` | `input logic en_i` | +| `te_i` | `input` | `input logic te_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_icg u_clk_icg ( + .clk_i(clk_i), + .en_i(en_i), + .te_i(te_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. diff --git a/docs/reference/tech/clk_icg2.md b/docs/reference/tech/clk_icg2.md new file mode 100644 index 0000000..4415a12 --- /dev/null +++ b/docs/reference/tech/clk_icg2.md @@ -0,0 +1,64 @@ +# clk_icg2 + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral two-input integrated clock-gate model. + +## Functional Behavior + +Behavioral two-input integrated clock-gate model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_icg2 ( + input logic clk_i, + input logic en_i, + input logic te_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `en_i` | `input` | `input logic en_i` | +| `te_i` | `input` | `input logic te_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_icg2 u_clk_icg2 ( + .clk_i(clk_i), + .en_i(en_i), + .te_i(te_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. diff --git a/docs/reference/tech/clk_mux2.md b/docs/reference/tech/clk_mux2.md new file mode 100644 index 0000000..ee633a6 --- /dev/null +++ b/docs/reference/tech/clk_mux2.md @@ -0,0 +1,64 @@ +# clk_mux2 + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral two-input clock mux model. + +## Functional Behavior + +Behavioral two-input clock mux model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_mux2 ( + input logic clk1_i, + input logic clk2_i, + input logic en_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk1_i` | `input` | `input logic clk1_i` | +| `clk2_i` | `input` | `input logic clk2_i` | +| `en_i` | `input` | `input logic en_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_mux2 u_clk_mux2 ( + .clk1_i(clk1_i), + .clk2_i(clk2_i), + .en_i(en_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. diff --git a/docs/reference/tech/clk_n.md b/docs/reference/tech/clk_n.md new file mode 100644 index 0000000..1423581 --- /dev/null +++ b/docs/reference/tech/clk_n.md @@ -0,0 +1,58 @@ +# clk_n + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral clock inverter model. + +## Functional Behavior + +Behavioral clock inverter model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_n ( + input logic clk_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_n u_clk_n ( + .clk_i(clk_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. diff --git a/docs/reference/tech/clk_nd2.md b/docs/reference/tech/clk_nd2.md new file mode 100644 index 0000000..26d4ba0 --- /dev/null +++ b/docs/reference/tech/clk_nd2.md @@ -0,0 +1,61 @@ +# clk_nd2 + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral two-input clock NAND model. + +## Functional Behavior + +Behavioral two-input clock NAND model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_nd2 ( + input logic clk1_i, + input logic clk2_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk1_i` | `input` | `input logic clk1_i` | +| `clk2_i` | `input` | `input logic clk2_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_nd2 u_clk_nd2 ( + .clk1_i(clk1_i), + .clk2_i(clk2_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. diff --git a/docs/reference/tech/clk_xor2.md b/docs/reference/tech/clk_xor2.md new file mode 100644 index 0000000..429f9fd --- /dev/null +++ b/docs/reference/tech/clk_xor2.md @@ -0,0 +1,61 @@ +# clk_xor2 + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/stdcell.sv`](../../../rtl/tech/stdcell.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral two-input clock XOR model. + +## Functional Behavior + +Behavioral two-input clock XOR model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module clk_xor2 ( + input logic clk1_i, + input logic clk2_i, + output logic clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk1_i` | `input` | `input logic clk1_i` | +| `clk2_i` | `input` | `input logic clk2_i` | +| `clk_o` | `output` | `output logic clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +clk_xor2 u_clk_xor2 ( + .clk1_i(clk1_i), + .clk2_i(clk2_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. diff --git a/docs/reference/tech/osc_pad_h.md b/docs/reference/tech/osc_pad_h.md new file mode 100644 index 0000000..4543391 --- /dev/null +++ b/docs/reference/tech/osc_pad_h.md @@ -0,0 +1,66 @@ +# osc_pad_h + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Horizontal oscillator pad abstraction. + +## Functional Behavior + +Horizontal oscillator pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module osc_pad_h ( + input logic ds0_i, // driver strength + input logic ds1_i, // driver strength + input logic en_i, + input logic xin_i, + output logic xout_o, + output logic xc_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `en_i` | `input` | `input logic en_i` | +| `xin_i` | `input` | `input logic xin_i` | +| `xout_o` | `output` | `output logic xout_o` | +| `xc_o` | `output` | `output logic xc_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +osc_pad_h u_osc_pad_h ( + .en_i(en_i), + .xin_i(xin_i), + .xout_o(xout_o), + .xc_o(xc_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. diff --git a/docs/reference/tech/osc_pad_v.md b/docs/reference/tech/osc_pad_v.md new file mode 100644 index 0000000..3bf31cb --- /dev/null +++ b/docs/reference/tech/osc_pad_v.md @@ -0,0 +1,66 @@ +# osc_pad_v + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Vertical oscillator pad abstraction. + +## Functional Behavior + +Vertical oscillator pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module osc_pad_v ( + input logic ds0_i, // driver strength + input logic ds1_i, // driver strength + input logic en_i, + input logic xin_i, + output logic xout_o, + output logic xc_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `en_i` | `input` | `input logic en_i` | +| `xin_i` | `input` | `input logic xin_i` | +| `xout_o` | `output` | `output logic xout_o` | +| `xc_o` | `output` | `output logic xc_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +osc_pad_v u_osc_pad_v ( + .en_i(en_i), + .xin_i(xin_i), + .xout_o(xout_o), + .xc_o(xc_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. diff --git a/docs/reference/tech/tech_pll.md b/docs/reference/tech/tech_pll.md new file mode 100644 index 0000000..2d35212 --- /dev/null +++ b/docs/reference/tech/tech_pll.md @@ -0,0 +1,74 @@ +# tech_pll + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/pll.sv`](../../../rtl/tech/pll.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Technology PLL abstraction. + +## Functional Behavior + +Technology PLL abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tech_pll #( +) ( + input logic fref_i, + input logic [ 5:0] refdiv_i, + input [11:0] fbdiv_i, + input logic [ 2:0] postdiv1_i, + input logic [ 2:0] postdiv2_i, + output logic pll_lock_o, + output logic pll_clk_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `fref_i` | `input` | `input logic fref_i` | +| `refdiv_i` | `input` | `input logic [ 5:0] refdiv_i` | +| `fbdiv_i` | `input` | `input [11:0] fbdiv_i` | +| `postdiv1_i` | `input` | `input logic [ 2:0] postdiv1_i` | +| `postdiv2_i` | `input` | `input logic [ 2:0] postdiv2_i` | +| `pll_lock_o` | `output` | `output logic pll_lock_o` | +| `pll_clk_o` | `output` | `output logic pll_clk_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tech_pll u_tech_pll ( + .fref_i(fref_i), + .refdiv_i(refdiv_i), + .fbdiv_i(fbdiv_i), + .postdiv1_i(postdiv1_i), + .postdiv2_i(postdiv2_i), + .pll_lock_o(pll_lock_o), + .pll_clk_o(pll_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. diff --git a/docs/reference/tech/tech_ram.md b/docs/reference/tech/tech_ram.md new file mode 100644 index 0000000..39df6c1 --- /dev/null +++ b/docs/reference/tech/tech_ram.md @@ -0,0 +1,84 @@ +# tech_ram + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/ram.sv`](../../../rtl/tech/ram.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral single-port technology RAM model. + +## Functional Behavior + +Behavioral single-port technology RAM model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `BIT_WIDTH` | `parameter int BIT_WIDTH = 128` | +| `WORD_DEPTH` | `parameter int WORD_DEPTH = 64` | +| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1` | + +## Interface Definition + +```systemverilog +module tech_ram #( + parameter int BIT_WIDTH = 128, + parameter int WORD_DEPTH = 64, + parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1 +) ( + input logic clk_i, + input logic en_i, + input logic wen_i, + input logic [ADDR_WIDTH-1:0] addr_i, + input logic [ BIT_WIDTH-1:0] dat_i, + output logic [ BIT_WIDTH-1:0] dat_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `en_i` | `input` | `input logic en_i` | +| `wen_i` | `input` | `input logic wen_i` | +| `addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] addr_i` | +| `dat_i` | `input` | `input logic [ BIT_WIDTH-1:0] dat_i` | +| `dat_o` | `output` | `output logic [ BIT_WIDTH-1:0] dat_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tech_ram #( + .BIT_WIDTH(BIT_WIDTH), + .WORD_DEPTH(WORD_DEPTH), + .ADDR_WIDTH(ADDR_WIDTH) +) u_tech_ram ( + .clk_i(clk_i), + .en_i(en_i), + .wen_i(wen_i), + .addr_i(addr_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. diff --git a/docs/reference/tech/tech_ram_bm.md b/docs/reference/tech/tech_ram_bm.md new file mode 100644 index 0000000..f943b2a --- /dev/null +++ b/docs/reference/tech/tech_ram_bm.md @@ -0,0 +1,90 @@ +# tech_ram_bm + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/ram.sv`](../../../rtl/tech/ram.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral byte-masked technology RAM model. + +## Functional Behavior + +Behavioral byte-masked technology RAM model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `BIT_WIDTH` | `parameter int BIT_WIDTH = 128` | +| `WORD_DEPTH` | `parameter int WORD_DEPTH = 64` | +| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1` | +| `BYTE_COUNT` | `parameter int BYTE_COUNT = BIT_WIDTH / 8` | + +## Interface Definition + +```systemverilog +module tech_ram_bm #( + parameter int BIT_WIDTH = 128, + parameter int WORD_DEPTH = 64, + parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1, + parameter int BYTE_COUNT = BIT_WIDTH / 8 +) ( + input logic clk_i, + input logic en_i, + input logic wen_i, + input logic [BYTE_COUNT-1:0] bm_i, + input logic [ADDR_WIDTH-1:0] addr_i, + input logic [ BIT_WIDTH-1:0] dat_i, + output logic [ BIT_WIDTH-1:0] dat_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `en_i` | `input` | `input logic en_i` | +| `wen_i` | `input` | `input logic wen_i` | +| `bm_i` | `input` | `input logic [BYTE_COUNT-1:0] bm_i` | +| `addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] addr_i` | +| `dat_i` | `input` | `input logic [ BIT_WIDTH-1:0] dat_i` | +| `dat_o` | `output` | `output logic [ BIT_WIDTH-1:0] dat_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tech_ram_bm #( + .BIT_WIDTH(BIT_WIDTH), + .WORD_DEPTH(WORD_DEPTH), + .ADDR_WIDTH(ADDR_WIDTH), + .BYTE_COUNT(BYTE_COUNT) +) u_tech_ram_bm ( + .clk_i(clk_i), + .en_i(en_i), + .wen_i(wen_i), + .bm_i(bm_i), + .addr_i(addr_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. diff --git a/docs/reference/tech/tech_regfile.md b/docs/reference/tech/tech_regfile.md new file mode 100644 index 0000000..b209440 --- /dev/null +++ b/docs/reference/tech/tech_regfile.md @@ -0,0 +1,84 @@ +# tech_regfile + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/regfile.sv`](../../../rtl/tech/regfile.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral technology register-file model. + +## Functional Behavior + +Behavioral technology register-file model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `BIT_WIDTH` | `parameter int BIT_WIDTH = 128` | +| `WORD_DEPTH` | `parameter int WORD_DEPTH = 64` | +| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1` | + +## Interface Definition + +```systemverilog +module tech_regfile #( + parameter int BIT_WIDTH = 128, + parameter int WORD_DEPTH = 64, + parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1 +) ( + input logic clk_i, + input logic en_i, + input logic wen_i, + input logic [ADDR_WIDTH-1:0] addr_i, + input logic [ BIT_WIDTH-1:0] dat_i, + output logic [ BIT_WIDTH-1:0] dat_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `en_i` | `input` | `input logic en_i` | +| `wen_i` | `input` | `input logic wen_i` | +| `addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] addr_i` | +| `dat_i` | `input` | `input logic [ BIT_WIDTH-1:0] dat_i` | +| `dat_o` | `output` | `output logic [ BIT_WIDTH-1:0] dat_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tech_regfile #( + .BIT_WIDTH(BIT_WIDTH), + .WORD_DEPTH(WORD_DEPTH), + .ADDR_WIDTH(ADDR_WIDTH) +) u_tech_regfile ( + .clk_i(clk_i), + .en_i(en_i), + .wen_i(wen_i), + .addr_i(addr_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. diff --git a/docs/reference/tech/tech_regfile_bm.md b/docs/reference/tech/tech_regfile_bm.md new file mode 100644 index 0000000..9a0a457 --- /dev/null +++ b/docs/reference/tech/tech_regfile_bm.md @@ -0,0 +1,90 @@ +# tech_regfile_bm + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/regfile.sv`](../../../rtl/tech/regfile.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Behavioral byte-masked technology register-file model. + +## Functional Behavior + +Behavioral byte-masked technology register-file model. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `BIT_WIDTH` | `parameter int BIT_WIDTH = 128` | +| `WORD_DEPTH` | `parameter int WORD_DEPTH = 64` | +| `ADDR_WIDTH` | `parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1` | +| `BYTE_COUNT` | `parameter int BYTE_COUNT = BIT_WIDTH / 8` | + +## Interface Definition + +```systemverilog +module tech_regfile_bm #( + parameter int BIT_WIDTH = 128, + parameter int WORD_DEPTH = 64, + parameter int ADDR_WIDTH = (WORD_DEPTH > 1) ? $clog2(WORD_DEPTH) : 1, + parameter int BYTE_COUNT = BIT_WIDTH / 8 +) ( + input logic clk_i, + input logic en_i, + input logic wen_i, + input logic [BYTE_COUNT-1:0] bm_i, + input logic [ADDR_WIDTH-1:0] addr_i, + input logic [ BIT_WIDTH-1:0] dat_i, + output logic [ BIT_WIDTH-1:0] dat_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `en_i` | `input` | `input logic en_i` | +| `wen_i` | `input` | `input logic wen_i` | +| `bm_i` | `input` | `input logic [BYTE_COUNT-1:0] bm_i` | +| `addr_i` | `input` | `input logic [ADDR_WIDTH-1:0] addr_i` | +| `dat_i` | `input` | `input logic [ BIT_WIDTH-1:0] dat_i` | +| `dat_o` | `output` | `output logic [ BIT_WIDTH-1:0] dat_o` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tech_regfile_bm #( + .BIT_WIDTH(BIT_WIDTH), + .WORD_DEPTH(WORD_DEPTH), + .ADDR_WIDTH(ADDR_WIDTH), + .BYTE_COUNT(BYTE_COUNT) +) u_tech_regfile_bm ( + .clk_i(clk_i), + .en_i(en_i), + .wen_i(wen_i), + .bm_i(bm_i), + .addr_i(addr_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. diff --git a/docs/reference/tech/tri_pd_pad_h.md b/docs/reference/tech/tri_pd_pad_h.md new file mode 100644 index 0000000..4753ea4 --- /dev/null +++ b/docs/reference/tech/tri_pd_pad_h.md @@ -0,0 +1,67 @@ +# tri_pd_pad_h + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Horizontal pull-down pad abstraction. + +## Functional Behavior + +Horizontal pull-down pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tri_pd_pad_h ( + input logic i_i, + input logic oen_i, + input logic ren_i, + output logic c_o, + inout wire pad_io +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `i_i` | `input` | `input logic i_i` | +| `oen_i` | `input` | `input logic oen_i` | +| `ren_i` | `input` | `input logic ren_i` | +| `c_o` | `output` | `output logic c_o` | +| `pad_io` | `inout` | `inout wire pad_io` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tri_pd_pad_h u_tri_pd_pad_h ( + .i_i(i_i), + .oen_i(oen_i), + .ren_i(ren_i), + .c_o(c_o), + .pad_io(pad_io) +); +``` + +## 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. diff --git a/docs/reference/tech/tri_pd_pad_v.md b/docs/reference/tech/tri_pd_pad_v.md new file mode 100644 index 0000000..2545fc5 --- /dev/null +++ b/docs/reference/tech/tri_pd_pad_v.md @@ -0,0 +1,67 @@ +# tri_pd_pad_v + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Vertical pull-down pad abstraction. + +## Functional Behavior + +Vertical pull-down pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tri_pd_pad_v ( + input logic i_i, + input logic oen_i, + input logic ren_i, + output logic c_o, + inout wire pad_io +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `i_i` | `input` | `input logic i_i` | +| `oen_i` | `input` | `input logic oen_i` | +| `ren_i` | `input` | `input logic ren_i` | +| `c_o` | `output` | `output logic c_o` | +| `pad_io` | `inout` | `inout wire pad_io` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tri_pd_pad_v u_tri_pd_pad_v ( + .i_i(i_i), + .oen_i(oen_i), + .ren_i(ren_i), + .c_o(c_o), + .pad_io(pad_io) +); +``` + +## 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. diff --git a/docs/reference/tech/tri_pdu_pad_h.md b/docs/reference/tech/tri_pdu_pad_h.md new file mode 100644 index 0000000..e098c0a --- /dev/null +++ b/docs/reference/tech/tri_pdu_pad_h.md @@ -0,0 +1,67 @@ +# tri_pdu_pad_h + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Horizontal pull-down-up pad abstraction. + +## Functional Behavior + +Horizontal pull-down-up pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tri_pdu_pad_h ( + input logic i_i, + input logic oen_i, + input logic ren_i, + output logic c_o, + inout wire pad_io +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `i_i` | `input` | `input logic i_i` | +| `oen_i` | `input` | `input logic oen_i` | +| `ren_i` | `input` | `input logic ren_i` | +| `c_o` | `output` | `output logic c_o` | +| `pad_io` | `inout` | `inout wire pad_io` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tri_pdu_pad_h u_tri_pdu_pad_h ( + .i_i(i_i), + .oen_i(oen_i), + .ren_i(ren_i), + .c_o(c_o), + .pad_io(pad_io) +); +``` + +## 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. diff --git a/docs/reference/tech/tri_pdu_pad_v.md b/docs/reference/tech/tri_pdu_pad_v.md new file mode 100644 index 0000000..140b97c --- /dev/null +++ b/docs/reference/tech/tri_pdu_pad_v.md @@ -0,0 +1,67 @@ +# tri_pdu_pad_v + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Vertical pull-down-up pad abstraction. + +## Functional Behavior + +Vertical pull-down-up pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tri_pdu_pad_v ( + input logic i_i, + input logic oen_i, + input logic ren_i, + output logic c_o, + inout wire pad_io +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `i_i` | `input` | `input logic i_i` | +| `oen_i` | `input` | `input logic oen_i` | +| `ren_i` | `input` | `input logic ren_i` | +| `c_o` | `output` | `output logic c_o` | +| `pad_io` | `inout` | `inout wire pad_io` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tri_pdu_pad_v u_tri_pdu_pad_v ( + .i_i(i_i), + .oen_i(oen_i), + .ren_i(ren_i), + .c_o(c_o), + .pad_io(pad_io) +); +``` + +## 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. diff --git a/docs/reference/tech/tri_pu_pad_h.md b/docs/reference/tech/tri_pu_pad_h.md new file mode 100644 index 0000000..18330d2 --- /dev/null +++ b/docs/reference/tech/tri_pu_pad_h.md @@ -0,0 +1,67 @@ +# tri_pu_pad_h + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Horizontal pull-up pad abstraction. + +## Functional Behavior + +Horizontal pull-up pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tri_pu_pad_h ( + input logic i_i, + input logic oen_i, + input logic ren_i, + output logic c_o, + inout wire pad_io +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `i_i` | `input` | `input logic i_i` | +| `oen_i` | `input` | `input logic oen_i` | +| `ren_i` | `input` | `input logic ren_i` | +| `c_o` | `output` | `output logic c_o` | +| `pad_io` | `inout` | `inout wire pad_io` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tri_pu_pad_h u_tri_pu_pad_h ( + .i_i(i_i), + .oen_i(oen_i), + .ren_i(ren_i), + .c_o(c_o), + .pad_io(pad_io) +); +``` + +## 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. diff --git a/docs/reference/tech/tri_pu_pad_v.md b/docs/reference/tech/tri_pu_pad_v.md new file mode 100644 index 0000000..d88475f --- /dev/null +++ b/docs/reference/tech/tri_pu_pad_v.md @@ -0,0 +1,67 @@ +# tri_pu_pad_v + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/tech/gpio_pad.sv`](../../../rtl/tech/gpio_pad.sv) | +| Availability | Technology model; replace in an ASIC technology flow | + +## Summary + +Vertical pull-up pad abstraction. + +## Functional Behavior + +Vertical pull-up pad abstraction. It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior. + +## Suitable Applications + +Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration. + +## Parameters + +This unit has no configurable parameters. + +## Interface Definition + +```systemverilog +module tri_pu_pad_v ( + input logic i_i, + input logic oen_i, + input logic ren_i, + output logic c_o, + inout wire pad_io +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `i_i` | `input` | `input logic i_i` | +| `oen_i` | `input` | `input logic oen_i` | +| `ren_i` | `input` | `input logic ren_i` | +| `c_o` | `output` | `output logic c_o` | +| `pad_io` | `inout` | `inout wire pad_io` | + +## Integration and Use + +Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract. + +```systemverilog +tri_pu_pad_v u_tri_pu_pad_v ( + .i_i(i_i), + .oen_i(oen_i), + .ren_i(ren_i), + .c_o(c_o), + .pad_io(pad_io) +); +``` + +## 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. diff --git a/docs/reference/utils/bin2gray.md b/docs/reference/utils/bin2gray.md new file mode 100644 index 0000000..b723813 --- /dev/null +++ b/docs/reference/utils/bin2gray.md @@ -0,0 +1,66 @@ +# bin2gray + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/bin2gray.sv`](../../../rtl/utils/bin2gray.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Combinational binary-to-Gray code converter. + +## Functional Behavior + +Combinational binary-to-Gray code converter. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 bin2gray #( + parameter int DATA_WIDTH = 1 +) ( + input logic [DATA_WIDTH-1:0] bin_i, + output logic [DATA_WIDTH-1:0] gray_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `bin_i` | `input` | `input logic [DATA_WIDTH-1:0] bin_i` | +| `gray_o` | `output` | `output logic [DATA_WIDTH-1:0] gray_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +bin2gray #( + .DATA_WIDTH(DATA_WIDTH) +) u_bin2gray ( + .bin_i(bin_i), + .gray_o(gray_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. diff --git a/docs/reference/utils/dff.md b/docs/reference/utils/dff.md new file mode 100644 index 0000000..d2ed108 --- /dev/null +++ b/docs/reference/utils/dff.md @@ -0,0 +1,69 @@ +# dff + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Plain D flip-flop primitive. + +## Functional Behavior + +Plain D flip-flop primitive. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dff #( + parameter int DATA_WIDTH = 1 +) ( + input logic clk_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` | +| `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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dff #( + .DATA_WIDTH(DATA_WIDTH) +) u_dff ( + .clk_i(clk_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. diff --git a/docs/reference/utils/dffer.md b/docs/reference/utils/dffer.md new file mode 100644 index 0000000..5bd657d --- /dev/null +++ b/docs/reference/utils/dffer.md @@ -0,0 +1,75 @@ +# dffer + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Enabled D flip-flop with asynchronous reset. + +## Functional Behavior + +Enabled D flip-flop with asynchronous reset. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dffer #( + parameter int DATA_WIDTH = 1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic en_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` | +| `en_i` | `input` | `input logic en_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffer #( + .DATA_WIDTH(DATA_WIDTH) +) u_dffer ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .en_i(en_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. diff --git a/docs/reference/utils/dfferc.md b/docs/reference/utils/dfferc.md new file mode 100644 index 0000000..98c37ff --- /dev/null +++ b/docs/reference/utils/dfferc.md @@ -0,0 +1,78 @@ +# dfferc + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Enabled D flip-flop with configurable reset value. + +## Functional Behavior + +Enabled D flip-flop with configurable reset value. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter int DATA_WIDTH = 1` | +| `RESET_VAL` | `parameter logic [DATA_WIDTH-1:0] RESET_VAL = '0` | + +## Interface Definition + +```systemverilog +module dfferc #( + parameter int DATA_WIDTH = 1, + parameter logic [DATA_WIDTH-1:0] RESET_VAL = '0 +) ( + input logic clk_i, + input logic rst_n_i, + input logic en_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` | +| `en_i` | `input` | `input logic en_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dfferc #( + .DATA_WIDTH(DATA_WIDTH), + .RESET_VAL(RESET_VAL) +) u_dfferc ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .en_i(en_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. diff --git a/docs/reference/utils/dffercn.md b/docs/reference/utils/dffercn.md new file mode 100644 index 0000000..fe76dd8 --- /dev/null +++ b/docs/reference/utils/dffercn.md @@ -0,0 +1,74 @@ +# dffercn + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Enabled D flip-flop with active-low configurable reset value. + +## Functional Behavior + +Enabled D flip-flop with active-low configurable reset value. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `REG_TYPE` | `parameter type REG_TYPE = logic` | +| `RESET_VAL` | `parameter REG_TYPE RESET_VAL = '0` | + +## Interface Definition + +```systemverilog +module dffercn #( + parameter type REG_TYPE = logic, + parameter REG_TYPE RESET_VAL = '0 +) ( + input logic clk_i, + input logic rst_n_i, + input logic en_i, + input REG_TYPE dat_i, + output REG_TYPE dat_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` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffercn #( + .REG_TYPE(REG_TYPE), + .RESET_VAL(RESET_VAL) +) u_dffercn ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .en_i(en_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. diff --git a/docs/reference/utils/dfferh.md b/docs/reference/utils/dfferh.md new file mode 100644 index 0000000..8a6954a --- /dev/null +++ b/docs/reference/utils/dfferh.md @@ -0,0 +1,75 @@ +# dfferh + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Enabled D flip-flop with all-one reset value. + +## Functional Behavior + +Enabled D flip-flop with all-one reset value. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dfferh #( + parameter int DATA_WIDTH = 1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic en_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` | +| `en_i` | `input` | `input logic en_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dfferh #( + .DATA_WIDTH(DATA_WIDTH) +) u_dfferh ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .en_i(en_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. diff --git a/docs/reference/utils/dfferm.md b/docs/reference/utils/dfferm.md new file mode 100644 index 0000000..44003d2 --- /dev/null +++ b/docs/reference/utils/dfferm.md @@ -0,0 +1,77 @@ +# dfferm + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Masked-update D flip-flop with reset. + +## Functional Behavior + +Masked-update D flip-flop with reset. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_NUM` | `parameter int DATA_NUM = 2` | +| `DATA_WIDTH` | `parameter int DATA_WIDTH = 1` | +| `INIT_VAL` | `parameter [DATA_WIDTH-1:0] INIT_VAL = '1` | + +## Interface Definition + +```systemverilog +module dfferm #( + parameter int DATA_NUM = 2, + parameter int DATA_WIDTH = 1, + parameter [DATA_WIDTH-1:0] INIT_VAL = '1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic [ DATA_NUM-1:0] en_i, + input logic [DATA_WIDTH-1:0] dat_i [0:DATA_NUM-1], + output logic [DATA_WIDTH-1:0] dat_o [0:DATA_NUM-1] +); +``` + + +### 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 [ DATA_NUM-1:0] en_i` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dfferm #( + .DATA_NUM(DATA_NUM), + .DATA_WIDTH(DATA_WIDTH), + .INIT_VAL(INIT_VAL) +) u_dfferm ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .en_i(en_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. diff --git a/docs/reference/utils/dffesr.md b/docs/reference/utils/dffesr.md new file mode 100644 index 0000000..751226b --- /dev/null +++ b/docs/reference/utils/dffesr.md @@ -0,0 +1,75 @@ +# dffesr + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Enabled D flip-flop with synchronous reset. + +## Functional Behavior + +Enabled D flip-flop with synchronous reset. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dffesr #( + parameter int DATA_WIDTH = 1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic en_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` | +| `en_i` | `input` | `input logic en_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffesr #( + .DATA_WIDTH(DATA_WIDTH) +) u_dffesr ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .en_i(en_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. diff --git a/docs/reference/utils/dffl.md b/docs/reference/utils/dffl.md new file mode 100644 index 0000000..fb43f71 --- /dev/null +++ b/docs/reference/utils/dffl.md @@ -0,0 +1,72 @@ +# dffl + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Level-sensitive latch primitive. + +## Functional Behavior + +Level-sensitive latch primitive. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dffl #( + parameter int DATA_WIDTH = 1 +) ( + input logic clk_i, + input logic en_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` | +| `en_i` | `input` | `input logic en_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffl #( + .DATA_WIDTH(DATA_WIDTH) +) u_dffl ( + .clk_i(clk_i), + .en_i(en_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. diff --git a/docs/reference/utils/dffr.md b/docs/reference/utils/dffr.md new file mode 100644 index 0000000..635e8f4 --- /dev/null +++ b/docs/reference/utils/dffr.md @@ -0,0 +1,72 @@ +# dffr + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +D flip-flop with asynchronous active-low reset. + +## Functional Behavior + +D flip-flop with asynchronous active-low reset. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dffr #( + 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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffr #( + .DATA_WIDTH(DATA_WIDTH) +) u_dffr ( + .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. diff --git a/docs/reference/utils/dffrc.md b/docs/reference/utils/dffrc.md new file mode 100644 index 0000000..9f1efd3 --- /dev/null +++ b/docs/reference/utils/dffrc.md @@ -0,0 +1,75 @@ +# dffrc + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +D flip-flop with configurable reset value. + +## Functional Behavior + +D flip-flop with configurable reset value. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter int DATA_WIDTH = 1` | +| `RESET_VAL` | `parameter logic [DATA_WIDTH-1:0] RESET_VAL = '0` | + +## Interface Definition + +```systemverilog +module dffrc #( + parameter int DATA_WIDTH = 1, + parameter logic [DATA_WIDTH-1:0] RESET_VAL = '0 +) ( + 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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffrc #( + .DATA_WIDTH(DATA_WIDTH), + .RESET_VAL(RESET_VAL) +) u_dffrc ( + .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. diff --git a/docs/reference/utils/dffrh.md b/docs/reference/utils/dffrh.md new file mode 100644 index 0000000..603ef50 --- /dev/null +++ b/docs/reference/utils/dffrh.md @@ -0,0 +1,72 @@ +# dffrh + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +D flip-flop with all-one reset value. + +## Functional Behavior + +D flip-flop with all-one reset value. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dffrh #( + 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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffrh #( + .DATA_WIDTH(DATA_WIDTH) +) u_dffrh ( + .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. diff --git a/docs/reference/utils/dffsr.md b/docs/reference/utils/dffsr.md new file mode 100644 index 0000000..971e990 --- /dev/null +++ b/docs/reference/utils/dffsr.md @@ -0,0 +1,72 @@ +# dffsr + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +D flip-flop with synchronous reset. + +## Functional Behavior + +D flip-flop with synchronous reset. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 dffsr #( + 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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +dffsr #( + .DATA_WIDTH(DATA_WIDTH) +) u_dffsr ( + .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. diff --git a/docs/reference/utils/edge_det.md b/docs/reference/utils/edge_det.md new file mode 100644 index 0000000..ee19fe3 --- /dev/null +++ b/docs/reference/utils/edge_det.md @@ -0,0 +1,81 @@ +# edge_det + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/edge_det.sv`](../../../rtl/utils/edge_det.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Single-bit rising and falling edge detector. + +## Functional Behavior + +Single-bit rising and falling edge detector. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 edge_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_o, + output logic [DATA_WIDTH-1:0] re_o, + output logic [DATA_WIDTH-1:0] fe_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` | +| `re_o` | `output` | `output logic [DATA_WIDTH-1:0] re_o` | +| `fe_o` | `output` | `output logic [DATA_WIDTH-1:0] fe_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +edge_det #( + .STAGE(STAGE), + .DATA_WIDTH(DATA_WIDTH) +) u_edge_det ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .dat_i(dat_i), + .dat_o(dat_o), + .re_o(re_o), + .fe_o(fe_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. diff --git a/docs/reference/utils/edge_det_fe.md b/docs/reference/utils/edge_det_fe.md new file mode 100644 index 0000000..6616d15 --- /dev/null +++ b/docs/reference/utils/edge_det_fe.md @@ -0,0 +1,75 @@ +# edge_det_fe + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/edge_det.sv`](../../../rtl/utils/edge_det.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Single-bit falling-edge detector. + +## Functional Behavior + +Single-bit falling-edge detector. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 edge_det_fe #( + 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] fe_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` | +| `fe_o` | `output` | `output logic [DATA_WIDTH-1:0] fe_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +edge_det_fe #( + .STAGE(STAGE), + .DATA_WIDTH(DATA_WIDTH) +) u_edge_det_fe ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .dat_i(dat_i), + .fe_o(fe_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. diff --git a/docs/reference/utils/edge_det_re.md b/docs/reference/utils/edge_det_re.md new file mode 100644 index 0000000..e576df2 --- /dev/null +++ b/docs/reference/utils/edge_det_re.md @@ -0,0 +1,75 @@ +# edge_det_re + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/edge_det.sv`](../../../rtl/utils/edge_det.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Single-bit rising-edge detector. + +## Functional Behavior + +Single-bit rising-edge detector. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 edge_det_re #( + 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] re_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` | +| `re_o` | `output` | `output logic [DATA_WIDTH-1:0] re_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +edge_det_re #( + .STAGE(STAGE), + .DATA_WIDTH(DATA_WIDTH) +) u_edge_det_re ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .dat_i(dat_i), + .re_o(re_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. diff --git a/docs/reference/utils/edge_det_sync.md b/docs/reference/utils/edge_det_sync.md new file mode 100644 index 0000000..afda995 --- /dev/null +++ b/docs/reference/utils/edge_det_sync.md @@ -0,0 +1,75 @@ +# edge_det_sync + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/edge_det.sv`](../../../rtl/utils/edge_det.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Synchronized single-bit rising and falling edge detector. + +## Functional Behavior + +Synchronized single-bit rising and falling edge detector. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 edge_det_sync #( + 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] re_o, + output logic [DATA_WIDTH-1:0] fe_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` | +| `re_o` | `output` | `output logic [DATA_WIDTH-1:0] re_o` | +| `fe_o` | `output` | `output logic [DATA_WIDTH-1:0] fe_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +edge_det_sync #( + .DATA_WIDTH(DATA_WIDTH) +) u_edge_det_sync ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .dat_i(dat_i), + .re_o(re_o), + .fe_o(fe_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. diff --git a/docs/reference/utils/edge_det_sync_fe.md b/docs/reference/utils/edge_det_sync_fe.md new file mode 100644 index 0000000..c5d2e60 --- /dev/null +++ b/docs/reference/utils/edge_det_sync_fe.md @@ -0,0 +1,72 @@ +# edge_det_sync_fe + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/edge_det.sv`](../../../rtl/utils/edge_det.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Synchronized single-bit falling-edge detector. + +## Functional Behavior + +Synchronized single-bit falling-edge detector. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 edge_det_sync_fe #( + 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] fe_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` | +| `fe_o` | `output` | `output logic [DATA_WIDTH-1:0] fe_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +edge_det_sync_fe #( + .DATA_WIDTH(DATA_WIDTH) +) u_edge_det_sync_fe ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .dat_i(dat_i), + .fe_o(fe_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. diff --git a/docs/reference/utils/edge_det_sync_re.md b/docs/reference/utils/edge_det_sync_re.md new file mode 100644 index 0000000..f27aa45 --- /dev/null +++ b/docs/reference/utils/edge_det_sync_re.md @@ -0,0 +1,72 @@ +# edge_det_sync_re + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/edge_det.sv`](../../../rtl/utils/edge_det.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Synchronized single-bit rising-edge detector. + +## Functional Behavior + +Synchronized single-bit rising-edge detector. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 edge_det_sync_re #( + 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] re_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` | +| `re_o` | `output` | `output logic [DATA_WIDTH-1:0] re_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +edge_det_sync_re #( + .DATA_WIDTH(DATA_WIDTH) +) u_edge_det_sync_re ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .dat_i(dat_i), + .re_o(re_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. diff --git a/docs/reference/utils/fifo.md b/docs/reference/utils/fifo.md new file mode 100644 index 0000000..c4293fa --- /dev/null +++ b/docs/reference/utils/fifo.md @@ -0,0 +1,96 @@ +# fifo + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/fifo.sv`](../../../rtl/utils/fifo.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Power-of-two synchronous FIFO with combinational head read. + +## Functional Behavior + +Power-of-two synchronous FIFO with combinational head read. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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` | +| `LOG_BUFFER_DEPTH` | `parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1` | + +## Interface Definition + +```systemverilog +module fifo #( + parameter int DATA_WIDTH = 32, + parameter int BUFFER_DEPTH = 8, + parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic flush_i, + input logic push_i, + output logic full_o, + input logic [ DATA_WIDTH-1:0] dat_i, + input logic pop_i, + output logic empty_o, + output logic [ DATA_WIDTH-1:0] dat_o, + output logic [LOG_BUFFER_DEPTH:0] cnt_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` | +| `push_i` | `input` | `input logic push_i` | +| `full_o` | `output` | `output logic full_o` | +| `dat_i` | `input` | `input logic [ DATA_WIDTH-1:0] dat_i` | +| `pop_i` | `input` | `input logic pop_i` | +| `empty_o` | `output` | `output logic empty_o` | +| `dat_o` | `output` | `output logic [ DATA_WIDTH-1:0] dat_o` | +| `cnt_o` | `output` | `output logic [LOG_BUFFER_DEPTH:0] cnt_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +fifo #( + .DATA_WIDTH(DATA_WIDTH), + .BUFFER_DEPTH(BUFFER_DEPTH), + .LOG_BUFFER_DEPTH(LOG_BUFFER_DEPTH) +) u_fifo ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .flush_i(flush_i), + .push_i(push_i), + .full_o(full_o), + .dat_i(dat_i), + .pop_i(pop_i), + .empty_o(empty_o), + .dat_o(dat_o), + .cnt_o(cnt_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. diff --git a/docs/reference/utils/gray2bin.md b/docs/reference/utils/gray2bin.md new file mode 100644 index 0000000..fed60c2 --- /dev/null +++ b/docs/reference/utils/gray2bin.md @@ -0,0 +1,66 @@ +# gray2bin + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/gray2bin.sv`](../../../rtl/utils/gray2bin.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Combinational Gray-to-binary code converter. + +## Functional Behavior + +Combinational Gray-to-binary code converter. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 gray2bin #( + parameter int DATA_WIDTH = 1 +) ( + input logic [DATA_WIDTH-1:0] gray_i, + output logic [DATA_WIDTH-1:0] bin_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `gray_i` | `input` | `input logic [DATA_WIDTH-1:0] gray_i` | +| `bin_o` | `output` | `output logic [DATA_WIDTH-1:0] bin_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +gray2bin #( + .DATA_WIDTH(DATA_WIDTH) +) u_gray2bin ( + .gray_i(gray_i), + .bin_o(bin_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. diff --git a/docs/reference/utils/lfsr_fibonacci.md b/docs/reference/utils/lfsr_fibonacci.md new file mode 100644 index 0000000..0ea15fe --- /dev/null +++ b/docs/reference/utils/lfsr_fibonacci.md @@ -0,0 +1,78 @@ +# lfsr_fibonacci + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/lfsr.sv`](../../../rtl/utils/lfsr.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Fibonacci-form pseudo-random linear-feedback shift register. + +## Functional Behavior + +Fibonacci-form pseudo-random linear-feedback shift register. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` | +| `SEED` | `parameter int SEED = 0` | + +## Interface Definition + +```systemverilog +module lfsr_fibonacci #( + parameter int DATA_WIDTH = 32, + parameter int SEED = 0 +) ( + input logic clk_i, + input logic rst_n_i, + input logic wr_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` | +| `wr_i` | `input` | `input logic wr_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +lfsr_fibonacci #( + .DATA_WIDTH(DATA_WIDTH), + .SEED(SEED) +) u_lfsr_fibonacci ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .wr_i(wr_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. diff --git a/docs/reference/utils/lfsr_galois.md b/docs/reference/utils/lfsr_galois.md new file mode 100644 index 0000000..4ca0866 --- /dev/null +++ b/docs/reference/utils/lfsr_galois.md @@ -0,0 +1,81 @@ +# lfsr_galois + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/lfsr.sv`](../../../rtl/utils/lfsr.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Galois-form pseudo-random linear-feedback shift register. + +## Functional Behavior + +Galois-form pseudo-random linear-feedback shift register. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter int DATA_WIDTH = 32` | +| `POLY` | `parameter logic [DATA_WIDTH-1:0] POLY = {{(DATA_WIDTH - 1) {1'b0}}, 1'b1}` | +| `RESET_SEED` | `parameter logic [DATA_WIDTH-1:0] RESET_SEED = {{(DATA_WIDTH - 1) {1'b0}}, 1'b1}` | + +## Interface Definition + +```systemverilog +module lfsr_galois #( + parameter int DATA_WIDTH = 32, + parameter logic [DATA_WIDTH-1:0] POLY = {{(DATA_WIDTH - 1) {1'b0}}, 1'b1}, + parameter logic [DATA_WIDTH-1:0] RESET_SEED = {{(DATA_WIDTH - 1) {1'b0}}, 1'b1} +) ( + input logic clk_i, + input logic rst_n_i, + input logic wr_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` | +| `wr_i` | `input` | `input logic wr_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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +lfsr_galois #( + .DATA_WIDTH(DATA_WIDTH), + .POLY(POLY), + .RESET_SEED(RESET_SEED) +) u_lfsr_galois ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .wr_i(wr_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. diff --git a/docs/reference/utils/ndffr.md b/docs/reference/utils/ndffr.md new file mode 100644 index 0000000..69a4fa0 --- /dev/null +++ b/docs/reference/utils/ndffr.md @@ -0,0 +1,72 @@ +# ndffr + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/register.sv`](../../../rtl/utils/register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Resettable multi-stage synchronizer register chain. + +## Functional Behavior + +Resettable multi-stage synchronizer register chain. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 ndffr #( + 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 + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +ndffr #( + .DATA_WIDTH(DATA_WIDTH) +) u_ndffr ( + .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. diff --git a/docs/reference/utils/regfield.md b/docs/reference/utils/regfield.md new file mode 100644 index 0000000..044b6fd --- /dev/null +++ b/docs/reference/utils/regfield.md @@ -0,0 +1,93 @@ +# regfield + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/regfield.sv`](../../../rtl/utils/regfield.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Masked register-field update primitive. + +## Functional Behavior + +Masked register-field update primitive. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter DATA_WIDTH = 32` | +| `SW_ACS` | `parameter SW_ACS = "rw", // rw, ro, wo, w1c, w1s, w0c, rc` | +| `RST_VAL` | `parameter logic [DATA_WIDTH-1:0] RST_VAL = '0 // Reset value` | + +## Interface Definition + +```systemverilog +module regfield #( + parameter DATA_WIDTH = 32, + parameter SW_ACS = "rw", // rw, ro, wo, w1c, w1s, w0c, rc + parameter logic [DATA_WIDTH-1:0] RST_VAL = '0 // Reset value +) ( + input clk_i, + input rst_n_i, + // from sw, in case of rc, top connects rd pulse to sw_wen_i + input sw_wen_i, + input [DATA_WIDTH-1:0] sw_wdata_i, + // from hw: valid for hrw, hwo + input hw_wen_i, + input [DATA_WIDTH-1:0] hw_wdata_i, + // output to hw and reg rd + output logic data_en_o, + output logic [DATA_WIDTH-1:0] data_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input clk_i` | +| `rst_n_i` | `input` | `input rst_n_i` | +| `sw_wen_i` | `input` | `input sw_wen_i` | +| `sw_wdata_i` | `input` | `input [DATA_WIDTH-1:0] sw_wdata_i` | +| `hw_wen_i` | `input` | `input hw_wen_i` | +| `hw_wdata_i` | `input` | `input [DATA_WIDTH-1:0] hw_wdata_i` | +| `data_en_o` | `output` | `output logic data_en_o` | +| `data_o` | `output` | `output logic [DATA_WIDTH-1:0] data_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +regfield #( + .DATA_WIDTH(DATA_WIDTH), + .SW_ACS(SW_ACS), + .RST_VAL(RST_VAL) +) u_regfield ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .sw_wen_i(sw_wen_i), + .sw_wdata_i(sw_wdata_i), + .hw_wen_i(hw_wen_i), + .hw_wdata_i(hw_wdata_i), + .data_en_o(data_en_o), + .data_o(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. diff --git a/docs/reference/utils/shift_reg.md b/docs/reference/utils/shift_reg.md new file mode 100644 index 0000000..25e0130 --- /dev/null +++ b/docs/reference/utils/shift_reg.md @@ -0,0 +1,93 @@ +# shift_reg + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/shift_reg.sv`](../../../rtl/utils/shift_reg.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Parameterized sequential shift register. + +## Functional Behavior + +Parameterized sequential shift register. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter int DATA_WIDTH = 8` | +| `SHIFT_NUM` | `parameter int SHIFT_NUM = 1` | + +## Interface Definition + +```systemverilog +module shift_reg #( + parameter int DATA_WIDTH = 8, + parameter int SHIFT_NUM = 1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic [ 1:0] type_i, + input logic [ 1:0] dir_i, + input logic ld_en_i, + input logic sft_en_i, + input logic [ SHIFT_NUM-1:0] ser_dat_i, + input logic [DATA_WIDTH-1:0] par_data_i, + output logic [ SHIFT_NUM-1:0] ser_dat_o, + output logic [DATA_WIDTH-1:0] par_data_o +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `rst_n_i` | `input` | `input logic rst_n_i` | +| `type_i` | `input` | `input logic [ 1:0] type_i` | +| `dir_i` | `input` | `input logic [ 1:0] dir_i` | +| `ld_en_i` | `input` | `input logic ld_en_i` | +| `sft_en_i` | `input` | `input logic sft_en_i` | +| `ser_dat_i` | `input` | `input logic [ SHIFT_NUM-1:0] ser_dat_i` | +| `par_data_i` | `input` | `input logic [DATA_WIDTH-1:0] par_data_i` | +| `ser_dat_o` | `output` | `output logic [ SHIFT_NUM-1:0] ser_dat_o` | +| `par_data_o` | `output` | `output logic [DATA_WIDTH-1:0] par_data_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +shift_reg #( + .DATA_WIDTH(DATA_WIDTH), + .SHIFT_NUM(SHIFT_NUM) +) u_shift_reg ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .type_i(type_i), + .dir_i(dir_i), + .ld_en_i(ld_en_i), + .sft_en_i(sft_en_i), + .ser_dat_i(ser_dat_i), + .par_data_i(par_data_i), + .ser_dat_o(ser_dat_o), + .par_data_o(par_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. diff --git a/docs/reference/utils/spill_register.md b/docs/reference/utils/spill_register.md new file mode 100644 index 0000000..bfbf530 --- /dev/null +++ b/docs/reference/utils/spill_register.md @@ -0,0 +1,90 @@ +# spill_register + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/spill_register.sv`](../../../rtl/utils/spill_register.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Two-register spill stage for breaking ready timing paths. + +## Functional Behavior + +Uses a primary register plus spill storage to retain input data during downstream stalls while decoupling the ready path. Optional bypass changes empty-state latency only. + +## Suitable Applications + +Use at stream timing boundaries where combinational ready propagation is too long. + +## 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 // transparent` | + +## Interface Definition + +```systemverilog +module spill_register #( + parameter int DATA_WIDTH = 32, + parameter bit BYPASS = 1'b0 // transparent +) ( + input logic clk_i, + input logic rst_n_i, + input logic flush_i, + input logic valid_i, + output logic ready_o, + input logic [DATA_WIDTH-1:0] data_i, + output logic valid_o, + input logic ready_i, + output logic [DATA_WIDTH-1:0] 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` | +| `valid_i` | `input` | `input logic valid_i` | +| `ready_o` | `output` | `output logic ready_o` | +| `data_i` | `input` | `input logic [DATA_WIDTH-1:0] data_i` | +| `valid_o` | `output` | `output logic valid_o` | +| `ready_i` | `input` | `input logic ready_i` | +| `data_o` | `output` | `output logic [DATA_WIDTH-1:0] data_o` | + +## Integration and Use + +Follow valid/ready stability rules and treat `flush_i` as an abort of retained data. Check bypass timing before using it across a long path. + +```systemverilog +spill_register #( + .DATA_WIDTH(DATA_WIDTH), + .BYPASS(BYPASS) +) u_spill_register ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .flush_i(flush_i), + .valid_i(valid_i), + .ready_o(ready_o), + .data_i(data_i), + .valid_o(valid_o), + .ready_i(ready_i), + .data_o(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. diff --git a/docs/reference/utils/stream_fifo.md b/docs/reference/utils/stream_fifo.md new file mode 100644 index 0000000..fda7822 --- /dev/null +++ b/docs/reference/utils/stream_fifo.md @@ -0,0 +1,96 @@ +# stream_fifo + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/fifo.sv`](../../../rtl/utils/fifo.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Legacy valid/ready wrapper around the synchronous FIFO. + +## Functional Behavior + +Legacy valid/ready wrapper around the synchronous FIFO. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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` | +| `LOG_BUFFER_DEPTH` | `parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1` | + +## Interface Definition + +```systemverilog +module stream_fifo #( + parameter int DATA_WIDTH = 32, + parameter int BUFFER_DEPTH = 8, + parameter int LOG_BUFFER_DEPTH = (BUFFER_DEPTH > 1) ? $clog2(BUFFER_DEPTH) : 1 +) ( + input logic clk_i, + input logic rst_n_i, + input logic flush_i, + output logic full_o, + output logic empty_o, + output logic [LOG_BUFFER_DEPTH:0] cnt_o, + input logic [ DATA_WIDTH-1:0] dat_i, + input logic push_i, + output logic [ DATA_WIDTH-1:0] dat_o, + input logic pop_i +); +``` + + +### 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` | +| `full_o` | `output` | `output logic full_o` | +| `empty_o` | `output` | `output logic empty_o` | +| `cnt_o` | `output` | `output logic [LOG_BUFFER_DEPTH:0] cnt_o` | +| `dat_i` | `input` | `input logic [ DATA_WIDTH-1:0] dat_i` | +| `push_i` | `input` | `input logic push_i` | +| `dat_o` | `output` | `output logic [ DATA_WIDTH-1:0] dat_o` | +| `pop_i` | `input` | `input logic pop_i` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +stream_fifo #( + .DATA_WIDTH(DATA_WIDTH), + .BUFFER_DEPTH(BUFFER_DEPTH), + .LOG_BUFFER_DEPTH(LOG_BUFFER_DEPTH) +) u_stream_fifo ( + .clk_i(clk_i), + .rst_n_i(rst_n_i), + .flush_i(flush_i), + .full_o(full_o), + .empty_o(empty_o), + .cnt_o(cnt_o), + .dat_i(dat_i), + .push_i(push_i), + .dat_o(dat_o), + .pop_i(pop_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. diff --git a/docs/reference/utils/valid_delay_line.md b/docs/reference/utils/valid_delay_line.md new file mode 100644 index 0000000..c0b1848 --- /dev/null +++ b/docs/reference/utils/valid_delay_line.md @@ -0,0 +1,84 @@ +# valid_delay_line + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/valid_delay_line.sv`](../../../rtl/utils/valid_delay_line.sv) | +| Availability | Synthesizable RTL | + +## Summary + +Valid-only parameterized sequential delay line. + +## Functional Behavior + +Valid-only parameterized sequential delay line. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## 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 = 2` | + +## Interface Definition + +```systemverilog +module valid_delay_line #( + parameter int DATA_WIDTH = 32, + parameter int DEPTH = 2 +) ( + 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, + 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_data_i` | `input` | `input logic [DATA_WIDTH-1:0] in_data_i` | +| `out_valid_o` | `output` | `output logic out_valid_o` | +| `out_data_o` | `output` | `output logic [DATA_WIDTH-1:0] out_data_o` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +valid_delay_line #( + .DATA_WIDTH(DATA_WIDTH), + .DEPTH(DEPTH) +) u_valid_delay_line ( + .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_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. diff --git a/docs/reference/utils/xchecker.md b/docs/reference/utils/xchecker.md new file mode 100644 index 0000000..253b16d --- /dev/null +++ b/docs/reference/utils/xchecker.md @@ -0,0 +1,66 @@ +# xchecker + +| Property | Value | +| --- | --- | +| Kind | `module` | +| RTL source | [`rtl/utils/xchecker.sv`](../../../rtl/utils/xchecker.sv) | +| Availability | Simulation/verification model | + +## Summary + +Simulation unknown-value checker. + +## Functional Behavior + +Simulation unknown-value checker. Its exact parameters and ports are reproduced below from the implementation declaration. + +## Suitable Applications + +Use as a small reusable datapath, state, coding, delay, or verification primitive. + +## Parameters + +The declaration below is canonical; retain the RTL-enforced parameter range. + +| Parameter | Declaration | +| --- | --- | +| `DATA_WIDTH` | `parameter DATA_WIDTH = 1` | + +## Interface Definition + +```systemverilog +module xchecker #( + parameter DATA_WIDTH = 1 +) ( + input logic clk_i, + input logic [DATA_WIDTH-1:0] dat_i +); +``` + + +### Port Summary + +| Signal | Direction | Declaration | +| --- | --- | --- | +| `clk_i` | `input` | `input logic clk_i` | +| `dat_i` | `input` | `input logic [DATA_WIDTH-1:0] dat_i` | + +## Integration and Use + +Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary. + +```systemverilog +xchecker #( + .DATA_WIDTH(DATA_WIDTH) +) u_xchecker ( + .clk_i(clk_i), + .dat_i(dat_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. diff --git a/scripts/check_component_docs.sh b/scripts/check_component_docs.sh new file mode 100644 index 0000000..e0cc1c9 --- /dev/null +++ b/scripts/check_component_docs.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +set -euo pipefail + +python3 scripts/render_component_docs.py --check + +for page in docs/reference/*/*.md; do + unit_name=$(basename "${page%.md}") + for heading in "## Summary" "## Functional Behavior" "## Suitable Applications" \ + "## Parameters" "## Interface Definition" "## Integration and Use" \ + "## Dependencies and Verification"; do + rg -Fqx "$heading" "$page" >/dev/null || { + printf 'missing required heading %s in %s\n' "$heading" "$page" >&2 + exit 1 + } + done + rg -Fqx "# ${unit_name}" "$page" >/dev/null || { + printf 'unexpected page title in %s\n' "$page" >&2 + exit 1 + } + rg -F '```systemverilog' "$page" >/dev/null || { + printf 'missing SystemVerilog content in %s\n' "$page" >&2 + exit 1 + } +done diff --git a/scripts/render_component_docs.py b/scripts/render_component_docs.py new file mode 100644 index 0000000..3c59b88 --- /dev/null +++ b/scripts/render_component_docs.py @@ -0,0 +1,451 @@ +#!/usr/bin/env python3 +"""Render checked-in RTL reference pages directly from SystemVerilog declarations.""" + +from __future__ import annotations + +import argparse +import re +from dataclasses import dataclass +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +RTL_ROOT = ROOT / "rtl" +DOC_ROOT = ROOT / "docs" / "reference" +README = ROOT / "README.md" +DECL = re.compile(r"^(module|interface|package)\s+([A-Za-z_][A-Za-z0-9_]*)\b") +PARAMETER = re.compile(r"^\s*parameter\b.*\b([A-Za-z_][A-Za-z0-9_]*)\s*=") +PORT = re.compile(r"^\s*(?:input|output|inout)\s+(?:logic|wire|bit)?\s*(?:\[[^]]+\]\s*)*([A-Za-z_][A-Za-z0-9_]*)\s*,?\s*$") +START = "" +END = "" + + +@dataclass(frozen=True) +class Unit: + kind: str + name: str + source: Path + declaration: str + + +def parse_table(raw: str) -> dict[str, str]: + return dict(line.split("\t", 1) for line in raw.strip().splitlines()) + + +SUMMARIES = parse_table(""" +address_map\tMasked address-map decoder with deterministic lowest-index priority. +address_range_decoder\tInclusive address-range decoder. +address_region\tMasked address-region matcher. +address_set_decoder\tDecoder for a set of independently configured address regions. +ahbl_if\tTyped AHB-Lite interface with master and slave modports. +apb4_if\tClocked APB4 interface with master and slave modports. +apb4_master_model\tSimulation APB4 master model. +apb4_pure_if\tClockless APB4 signal interface with master and slave modports. +async_gray_queue\tGray-pointer asynchronous FIFO wrapper. +async_reqack\tOne-entry four-phase asynchronous data mailbox. +axi4_addr_gen\tAXI4 next-address generator for FIXED, INCR, and legal WRAP bursts. +axi4_if\tTyped AXI4 interface with master and slave modports. +bin2gray\tCombinational binary-to-Gray code converter. +bit_count\tCombinational population-count primitive. +bypass_buffer\tCombinational valid/ready stream pass-through. +cdc_2phase\tTwo-phase asynchronous request/acknowledge transfer. +cdc_2phase_dst\tDestination-side implementation of the two-phase CDC link. +cdc_2phase_src\tSource-side implementation of the two-phase CDC link. +cdc_2phase_warm_flush\tSource-initiated warm-clear wrapper for a two-phase CDC link. +cdc_event_bridge\tPulse/event transport over an asynchronous mailbox. +cdc_event_bridge_ack\tAcknowledged asynchronous event transport. +cdc_fifo\tGray-pointer asynchronous FIFO. +cdc_fifo_dst\tDestination-side implementation of the asynchronous FIFO. +cdc_fifo_src\tSource-side implementation of the asynchronous FIFO. +cdc_fifo_warm_flush\tSource-initiated warm-clear wrapper for an asynchronous FIFO. +cdc_remote_clear_request\tRetained remote-clear request channel. +cdc_reset_barrier\tTwo-domain reset barrier with synchronized release. +cdc_sync\tMulti-flop synchronizer for a control bit or independently encoded vector. +cdc_sync_det\tSynchronized control input with edge detection. +cdc_warm_flush_controller\tAcknowledged isolate-reset-resume controller for CDC warm flush. +circular_store\tSequential circular store with bounded random reads. +clearable_async_queue\tAsynchronous queue with coordinated endpoint clear. +clearable_two_phase_link\tTwo-phase link with coordinated endpoint clear. +clk_an2\tBehavioral two-input clock AND model. +clk_buf\tBehavioral clock buffer model. +clk_icg\tBehavioral integrated clock-gate model. +clk_icg2\tBehavioral two-input integrated clock-gate model. +clk_int_div_simple\tRuntime-programmable integer divider with safe low-phase updates. +clk_int_even_div\tEven clock divider retaining requests until a safe boundary. +clk_int_even_div_static\tStatic even integer clock divider. +clk_int_odd_div_static\tStatic odd integer clock divider. +clk_mux2\tBehavioral two-input clock mux model. +clk_n\tBehavioral clock inverter model. +clk_nd2\tBehavioral two-input clock NAND model. +clk_xor2\tBehavioral two-input clock XOR model. +clock_divider\tRuntime-programmable divider that changes only at an output-low boundary. +clock_or_tree\tOR tree for clocks already proven safe to combine. +component_math_pkg\tCompile-time arithmetic helpers for parameterized components. +counting_bloom_filter\tCounting Bloom filter with explicit counter saturation. +credit_pool\tSaturating available-credit tracker for resource flow control. +dff\tPlain D flip-flop primitive. +dffer\tEnabled D flip-flop with asynchronous reset. +dfferc\tEnabled D flip-flop with configurable reset value. +dffercn\tEnabled D flip-flop with active-low configurable reset value. +dfferh\tEnabled D flip-flop with all-one reset value. +dfferm\tMasked-update D flip-flop with reset. +dffesr\tEnabled D flip-flop with synchronous reset. +dffl\tLevel-sensitive latch primitive. +dffr\tD flip-flop with asynchronous active-low reset. +dffrc\tD flip-flop with configurable reset value. +dffrh\tD flip-flop with all-one reset value. +dffsr\tD flip-flop with synchronous reset. +edge_det\tSingle-bit rising and falling edge detector. +edge_det_fe\tSingle-bit falling-edge detector. +edge_det_re\tSingle-bit rising-edge detector. +edge_det_sync\tSynchronized single-bit rising and falling edge detector. +edge_det_sync_fe\tSynchronized single-bit falling-edge detector. +edge_det_sync_re\tSynchronized single-bit rising-edge detector. +fifo\tPower-of-two synchronous FIFO with combinational head read. +four_phase_mailbox\tPublic wrapper for the four-phase asynchronous mailbox API. +gray2bin\tCombinational Gray-to-binary code converter. +hash_indicator_bank\tMulti-hash indicator-vector generator. +index_to_onehot\tBounded index-to-one-hot decoder. +interval_ones_mask\tInclusive contiguous mask generator between two bit positions. +isochronous_handshake\tHandshake for fixed-ratio, STA-constrained isochronous clocks. +isochronous_stream_buffer\tStream buffer for fixed-ratio, STA-constrained isochronous clocks. +latest_value_stream\tValid-only stream adapter retaining the newest pending value. +leading_zero_count\tCombinational leading-zero counter with all-zero indication. +lfsr_fibonacci\tFibonacci-form pseudo-random linear-feedback shift register. +lfsr_galois\tGalois-form pseudo-random linear-feedback shift register. +loop_trip_counter\tProgrammable terminal-count loop counter. +memory_bank_adapter\tPublic banked-memory request and response adapter. +memory_bank_adapter_detail\tBanked-memory request splitter and response gatherer. +memory_response_bridge\tResponse-order bridge between memory and stream interfaces. +ndffr\tResettable multi-stage synchronizer register chain. +onehot_check\tOne-hot validity checker with optional all-zero acceptance. +onehot_to_index\tOne-hot vector to index converter with validity output. +osc_pad_h\tHorizontal oscillator pad abstraction. +osc_pad_v\tVertical oscillator pad abstraction. +peak_delta_counter\tUp/down counter with retained high-water mark. +permutation_hash\tDeterministic non-cryptographic bit-mixing hash. +plru_victim_selector\tPower-of-two pseudo-LRU cache-way victim selector. +prefix_ones_mask\tLow-order prefix-ones mask generator. +ram_if\tSimple RAM request/response interface with master and slave modports. +ready_valid_if\tTyped ready/valid interface with source, sink, and monitor modports. +regfield\tMasked register-field update primitive. +retry_backoff\tPseudo-random exponential retry-delay controller. +ribp_if\tRIBP request/response interface with response-error signaling. +round_robin_arbiter\tFair transfer-driven round-robin arbiter. +rs_counter\tResettable up/down counter. +rs_delta_counter\tDelta-counting counter. +rst_sync\tAsynchronous-assert, synchronous-release reset synchronizer. +safe_clock_mux\tGlitch-safe handover mux for two continuously running clocks. +sample_majority_filter\tSliding-window N-of-M single-bit sample filter. +secded_decode\tExtended-Hamming SECDED decoder, corrector, and error classifier. +secded_encode\tExtended-Hamming SECDED encoder. +secded_layout_pkg\tShared SECDED codeword-layout helpers. +shift_reg\tParameterized sequential shift register. +signal_sink\tIntentional unused-signal terminator. +signal_tap\tNamed combinational signal pass-through for observability. +spill_register\tTwo-register spill stage for breaking ready timing paths. +stable_level_filter\tConsecutive-sample debounce and stability filter. +stream_buffer\tValid/ready stream wrapper around a spill register. +stream_collector\tCollects selected valid/ready inputs into one stream output. +stream_credit_limiter\tLimits stream acceptance by available credits. +stream_crossbar\tArbitrates and routes multiple stream inputs to multiple outputs. +stream_delay_injector\tControlled stream delay injector for verification and stress. +stream_discard_gate\tConsumes input transfers while discard is asserted. +stream_elastic_register\tOne-entry elastic valid/ready register stage. +stream_fair_arbiter\tFair round-robin arbiter for valid/ready stream inputs. +stream_fallthrough_buffer\tOne-entry fall-through valid/ready buffer. +stream_fifo\tLegacy valid/ready wrapper around the synchronous FIFO. +stream_queue\tParameterized valid/ready queue with optional fall-through. +stream_replicator\tRegistered one-item stream distributor with per-target completion. +stream_router\tRoutes one valid/ready input to a selected output. +stream_selector\tSelects one of several valid/ready inputs. +stream_shuffle_network\tDeterministic stream-lane permutation network. +stream_window_guard\tLimits outstanding stream requests with explicit retire accounting. +sync_memory\tPortable synchronous memory model with positive-logic controls. +synchronized_edge\tSynchronizes a control transition and emits a local edge indication. +tag_order_queue\tShared-pool queue preserving FIFO order within each tag. +tech_pll\tTechnology PLL abstraction. +tech_ram\tBehavioral single-port technology RAM model. +tech_ram_bm\tBehavioral byte-masked technology RAM model. +tech_regfile\tBehavioral technology register-file model. +tech_regfile_bm\tBehavioral byte-masked technology register-file model. +test_reset_synchronizer\tVerification-oriented reset synchronization helper. +trailing_zero_count\tCombinational trailing-zero counter with all-zero indication. +tri_pd_pad_h\tHorizontal pull-down pad abstraction. +tri_pd_pad_v\tVertical pull-down pad abstraction. +tri_pdu_pad_h\tHorizontal pull-down-up pad abstraction. +tri_pdu_pad_v\tVertical pull-down-up pad abstraction. +tri_pu_pad_h\tHorizontal pull-up pad abstraction. +tri_pu_pad_v\tVertical pull-up pad abstraction. +two_phase_async_queue\tQueue API built from two-phase asynchronous transfers. +valid_delay_line\tValid-only parameterized sequential delay line. +xchecker\tSimulation unknown-value checker. +""") + + +DETAILS = { + "credit_pool": ("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.", "Use for bounded request windows, queue slots, buffer credits, and response throttling.", "Do not issue unpaired gives or takes. `clear_i` is synchronous; choose `EMPTY_ON_RESET` to match resource ownership after reset."), + "loop_trip_counter": ("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.", "Use for bounded loops, beat scheduling, table traversal, and phase sequencing.", "A nonzero step must reach the limit exactly. This is not an arbitrary modulo counter; skipping the terminal value is an error."), + "stable_level_filter": ("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.", "Use for debounced controls, lock indications, slow GPIO state, and reset-status qualification.", "Synchronize an asynchronous source first. Disabling the filter clears accumulated evidence; `STABLE_CYCLES=1` accepts every enabled sample."), + "sample_majority_filter": ("Retains the most recent enabled samples and asserts when their population count reaches `ASSERT_THRESHOLD`; the default is strict majority.", "Use for noisy status pins, repeated sensor samples, redundant indications, and temporal voting.", "This is a population filter, not a synchronizer or consecutive-stability filter. Choose the threshold deliberately."), + "retry_backoff": ("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.", "Use for contention retries, shared-resource collision recovery, and congestion backoff.", "Gate attempts with `ready_o`. A failure during an active wait replaces the delay, while success cancels it."), + "async_reqack": ("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.", "Use for low-throughput asynchronous control or data mailboxes.", "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."), + "cdc_reset_barrier": ("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.", "Use when two collaborating domains need a coordinated reset release before starting a CDC protocol.", "It does not transfer data or replace reset-domain signoff. Both clocks must run for reset release to complete."), + "spill_register": ("Uses a primary register plus spill storage to retain input data during downstream stalls while decoupling the ready path. Optional bypass changes empty-state latency only.", "Use at stream timing boundaries where combinational ready propagation is too long.", "Follow valid/ready stability rules and treat `flush_i` as an abort of retained data. Check bypass timing before using it across a long path."), + "stream_replicator": ("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.", "Use for multicast command/data distribution with independently stalling consumers.", "The mask is sampled only on input acceptance. `flush_i` aborts a retained item; downstream consumers must obey normal valid/ready semantics."), + "secded_decode": ("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.", "Use on protected memory reads and protected interconnect payloads.", "Treat decoded data as invalid when `uncorrectable_o` is high and use exactly the matching encoder geometry."), + "secded_encode": ("Places data in the shared SECDED layout, generates Hamming parity positions, and appends overall parity for single-error correction and double-error detection.", "Use before writing protected memories or sending protected link data.", "Pair only with `secded_decode` built from the same parameters and layout package."), +} + + +def discover() -> list[Unit]: + units: list[Unit] = [] + for source in sorted(RTL_ROOT.rglob("*.sv")): + lines = source.read_text(encoding="utf-8").splitlines() + for index, line in enumerate(lines): + match = DECL.match(line) + if match is None: + continue + kind, name = match.groups() + terminator = "endpackage" if kind == "package" else "endinterface" if kind == "interface" else ");" + declaration = [line] + for next_line in lines[index + 1:]: + declaration.append(next_line) + if next_line.strip() == terminator: + break + else: + raise RuntimeError(f"unclosed declaration: {source}:{index + 1}") + units.append(Unit(kind, name, source.relative_to(ROOT), "\n".join(declaration))) + return units + + +def category(unit: Unit) -> str: + return unit.source.parent.name + + +def availability(unit: Unit) -> str: + if category(unit) == "tech": + return "Technology model; replace in an ASIC technology flow" + if category(unit) == "model" or unit.name == "xchecker": + return "Simulation/verification model" + if unit.name.startswith("test_"): + return "Verification-oriented helper" + return "Synthesizable RTL" if unit.kind == "module" else "SystemVerilog integration API" + + +def generic_detail(unit: Unit) -> tuple[str, str, str]: + group = category(unit) + summary = SUMMARIES[unit.name] + if group == "cdc": + return (f"{summary} 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.", "Use for reset release, asynchronous control/data transfer, asynchronous queues, event notification, and CDC recovery.", "Never use a simple synchronizer for arbitrary multi-bit data. Keep both endpoint clocks running after reset release and obey all ready/busy outputs.") + if group == "stream": + return (f"{summary} 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.", "Use for elastic pipelines, stream routing, arbitration, backpressure, and response handling.", "Observe vector sizing, selection encoding, and flush semantics in the declaration. Do not modify a valid payload while its corresponding ready is low.") + if group == "interface": + return (f"{summary} It groups protocol signals and constrains endpoint direction with the declared modports; it does not implement protocol state or drive behavior itself.", "Use to connect compatible SystemVerilog RTL or class-based verification components without duplicating a port bundle.", "Connect the correct modport for each role. The connected logic remains responsible for all protocol timing and reset behavior.") + if group == "clock" or group == "clkrst": + return (f"{summary} It implements the declared clock/reset behavior but does not replace physical clock-tree, reset-domain, or STA signoff.", "Use in controlled clock/reset infrastructure with explicit physical-design ownership.", "Respect all clock-running and configuration-stability assumptions. Do not use generic logic as a substitute for a safe clock-control cell.") + if group == "tech": + return (f"{summary} It supplies portable functional behavior or a backend substitution hook, not characterized silicon timing or power behavior.", "Use for simulation, generic synthesis, FPGA prototyping, and technology-independent elaboration.", "Replace it through the target technology flow before ASIC tape-out. Treat its active-low controls and backend macros as part of the integration contract.") + if group == "bus": + return (f"{summary} It classifies the presented address using the configured decode rule and returns the documented selection/match result combinationally.", "Use for memory maps, peripheral selection, firewall regions, and target routing.", "Check overlaps and priority deliberately. Decode does not by itself complete or validate a bus transaction.") + if group == "memory": + return (f"{summary} It implements the declared storage, ordering, banking, or response contract with explicit bounds rather than silently dropping malformed transactions.", "Use for local queues, reorder structures, banked stores, and portable memory-backed blocks.", "Follow address, depth, outstanding-request, and response-order constraints exactly. Reset state does not imply initialized storage contents unless documented.") + if group == "utils": + return (f"{summary} Its exact parameters and ports are reproduced below from the implementation declaration.", "Use as a small reusable datapath, state, coding, delay, or verification primitive.", "Keep parameter values within RTL assertions and add required clocking, reset, or CDC protection at the caller boundary.") + if group == "base": + return (f"{summary} It is a self-contained base primitive with the behavior and parameter checks implemented in the linked RTL source.", "Use as a structured building block for control, encoding, ECC, hashing, masking, replacement, or observability logic.", "Honor validity/error outputs and parameter constraints. Combinational cells do not provide timing isolation or CDC protection.") + if group == "model": + return (f"{summary} It models the protocol action for simulation and is not a synthesizable protocol endpoint.", "Use in a SystemVerilog testbench or directed protocol smoke test.", "Include the required interface/configuration definitions and do not include this model in a silicon file list.") + raise RuntimeError(f"unhandled category: {group}") + + +def page_path(unit: Unit) -> Path: + return DOC_ROOT / category(unit) / f"{unit.name}.md" + + +def signature(unit: Unit) -> str: + """Return only the declaration header when an interface has an internal body.""" + if unit.kind != "interface": + return unit.declaration + lines = [] + for line in unit.declaration.splitlines(): + lines.append(line) + if line.strip().endswith(");"): + break + return "\n".join(lines) + + +def names(pattern: re.Pattern[str], text: str) -> list[str]: + result = [] + for line in text.splitlines(): + match = pattern.match(line) + if match is not None: + result.append(match.group(1)) + return result + + +def markdown_table(headers: tuple[str, ...], rows: list[tuple[str, ...]]) -> str: + if not rows: + return "" + header = "| " + " | ".join(headers) + " |" + separator = "| " + " | ".join("---" for _ in headers) + " |" + body = ["| " + " | ".join(row) + " |" for row in rows] + return "\n".join([header, separator, *body]) + + +def parameter_table(unit: Unit) -> str: + rows = [] + for line in signature(unit).splitlines(): + match = PARAMETER.match(line) + if match is not None: + rows.append((f"`{match.group(1)}`", f"`{line.strip().rstrip(',')}`")) + return markdown_table(("Parameter", "Declaration"), rows) + + +def port_table(unit: Unit) -> str: + rows = [] + for line in signature(unit).splitlines(): + match = PORT.match(line) + if match is not None: + direction = line.strip().split(None, 1)[0] + rows.append((f"`{match.group(1)}`", f"`{direction}`", f"`{line.strip().rstrip(',')}`")) + return markdown_table(("Signal", "Direction", "Declaration"), rows) + + +def use_example(unit: Unit) -> str: + if unit.kind == "package": + return f"```systemverilog\nimport {unit.name}::*;\n// Use exported types, constants, or functions here.\n```" + header = signature(unit) + parameters = names(PARAMETER, header) + parameter_text = "" + if parameters: + parameter_text = " #(\n" + ",\n".join( + f" .{name}({name})" for name in parameters + ) + "\n)" + if unit.kind == "interface": + ports = names(PORT, header) + connection_text = ", ".join(f".{name}({name})" for name in ports) + return f"```systemverilog\n{unit.name}{parameter_text} {unit.name}_i({connection_text});\n// Example: consumer u_consumer (.bus_i({unit.name}_i.slave));\n```" + ports = names(PORT, header) + connection_text = ",\n".join(f" .{name}({name})" for name in ports) + return f"```systemverilog\n{unit.name}{parameter_text} u_{unit.name} (\n{connection_text}\n);\n```" + + +def render_page(unit: Unit) -> str: + detail, scenarios, integration = DETAILS.get(unit.name, generic_detail(unit)) + source_link = f"../../../{unit.source.as_posix()}" + parameter_note = "The declaration below is canonical; retain the RTL-enforced parameter range." if "parameter" in unit.declaration else "This unit has no configurable parameters." + if unit.kind == "package": + parameter_note = "The package declaration below is canonical for exported types, constants, and functions." + parameters = parameter_table(unit) + ports = port_table(unit) + parameter_section = f"{parameter_note}\n\n{parameters}" if parameters else parameter_note + port_section = f"\n\n### Port Summary\n\n{ports}" if ports else "" + return f"""# {unit.name} + +| Property | Value | +| --- | --- | +| Kind | `{unit.kind}` | +| RTL source | [`{unit.source.as_posix()}`]({source_link}) | +| Availability | {availability(unit)} | + +## Summary + +{SUMMARIES[unit.name]} + +## Functional Behavior + +{detail} + +## Suitable Applications + +{scenarios} + +## Parameters + +{parameter_section} + +## Interface Definition + +```systemverilog +{unit.declaration} +``` +{port_section} + +## Integration and Use + +{integration} + +{use_example(unit)} + +## 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. +""" + + +def render_catalog(units: list[Unit]) -> str: + grouped: dict[str, list[Unit]] = {} + for unit in units: + grouped.setdefault(category(unit), []).append(unit) + lines = ["## 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.", ""] + for group in sorted(grouped): + lines.extend([f"### `{group}`", "", "| Component | Type | Function summary |", "| --- | --- | --- |"]) + for unit in sorted(grouped[group], key=lambda value: value.name): + target = page_path(unit).relative_to(ROOT).as_posix() + lines.append(f"| [`{unit.name}`]({target}) | `{unit.kind}` | {SUMMARIES[unit.name]} |") + lines.append("") + return "\n".join(lines) + + +def replace_catalog(readme: str, catalog: str) -> str: + start = readme.index(START) + len(START) + end = readme.index(END) + return readme[:start] + "\n\n" + catalog + "\n" + readme[end:] + + +def render_index(units: list[Unit]) -> str: + grouped: dict[str, list[Unit]] = {} + for unit in units: + grouped.setdefault(category(unit), []).append(unit) + lines = ["# 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", ""] + for group in sorted(grouped): + links = ", ".join(f"[`{unit.name}`]({group}/{unit.name}.md)" for unit in sorted(grouped[group], key=lambda value: value.name)) + lines.append(f"- `{group}`: {links}") + return "\n".join(lines) + "\n" + + +def expected_outputs(units: list[Unit]) -> dict[Path, str]: + outputs = {page_path(unit): render_page(unit) for unit in units} + outputs[DOC_ROOT / "README.md"] = render_index(units) + outputs[README] = replace_catalog(README.read_text(encoding="utf-8"), render_catalog(units)) + return outputs + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--check", action="store_true", help="report stale generated pages instead of rewriting them") + args = parser.parse_args() + units = discover() + if len(units) != 147: + raise RuntimeError(f"expected 147 declarations, found {len(units)}") + missing = sorted(set(unit.name for unit in units) - set(SUMMARIES)) + extras = sorted(set(SUMMARIES) - set(unit.name for unit in units)) + if missing or extras: + raise RuntimeError(f"summary coverage mismatch: missing={missing}, stale={extras}") + outputs = expected_outputs(units) + if args.check: + stale = [str(path.relative_to(ROOT)) for path, text in outputs.items() if not path.is_file() or path.read_text(encoding="utf-8") != text] + if stale: + raise SystemExit("component reference is stale:\n" + "\n".join(stale)) + return + for path, text in outputs.items(): + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + + +if __name__ == "__main__": + main()