RTL Design Sherpa

Learning Hardware Design Through Practice

A progressive learning framework for RTL development using open-source tools

Documentation Index - Complete guide to all documentation, organized by type

Project Mission

RTL Design Sherpa guides you through digital hardware design with hands-on learning from first principles.

We start with fundamental building blocks (adders, multipliers, FIFOs), progress to protocol-specific modules (AXI, DMA engines), and culminate in complete FPGA-ready systems. Every module is both educational and production-quality - meeting real timing and resource constraints.

What makes RTL Design Sherpa different:

From scratch: Python generators → SystemVerilog → synthesis. No black boxes, every design decision explained.
Safety net for exploration: Comprehensive test suites at every level (unit, integration, formal) let you experiment with confidence. Try different optimizations - the tests catch regressions.
Performance-driven: Multiple implementations of key modules, with measured area/speed tradeoffs. SimPy models predict behavior before writing RTL.
Industry practices: Open-source tools (cocotb, Verilator, Yosys) demonstrating verification methodologies used in production.
Complete transparency: Build systems, Makefiles, debugging sessions - all the "hidden knowledge" made visible.

Whether you're learning your first Verilog module or optimizing a high-speed interconnect, RTL Design Sherpa provides the detailed explanations, working examples, and verification infrastructure to build understanding from the ground up.

Learning Path

Guided progression from primitives to systems. Each level links to the corresponding section in Browse by Class below — every entry is a real link (works on mobile and desktop alike).

Level 1 — Common Building Blocks + Math Library · ~230 modules · counters, FIFOs, arbiters, data integrity, clock utilities (common) + integer and floating-point math (math)
Level 2 — AMBA Protocol Infrastructure · 155 modules · AXI4 · AXI5 · AXI4-Lite · APB · APB5 · AXIS4 · AXIS5 · Monitors + MonBus · Shared observation
Level 3 — Production Components · STREAM · RAPIDS · Bridge · Converters · APB xbar · Retro legacy · Memory controllers
Level 4 — FPGA Projects on Nexys A7 · timing_characterization · cdc_counter_display · ddr2-characterization · rapids_beats

Visual diagram (Mermaid — desktop browsers only)

graph TD
    L1[Level 1: Common Building Blocks<br/>~224 modules] --> L2[Level 2: AMBA Protocol Infrastructure<br/>155 modules]
    L2 --> L4[Level 3: Production Components<br/>10+ components]
    L4 --> L5[Level 4: Complete FPGA Projects]

    L1 -.- L1D[Counters, FIFOs, Arbiters<br/>Math, Floating-Point, Data Integrity]
    L2 -.- L2D[AXI4, AXI5, AXI4-Lite, APB, APB5<br/>AXIS4, AXIS5, Shared monitor/observation]
    L4 -.- L4D[STREAM, RAPIDS, Bridge, Converters<br/>Retro Legacy Blocks, Memory controllers]
    L5 -.- L5D[timing_characterization, cdc_counter_display<br/>ddr2-characterization]

    click L1 "rtl/common/" "Common Building Blocks"
    click L2 "rtl/amba/" "AMBA Protocol Infrastructure"
    click L4 "projects/components/" "Production Components"
    click L5 "projects/fpga-systems/NexysA7/" "FPGA Projects"

Browse by Class

Fast lookup. Each row is a class of things; the deep-dive link goes to its index/spec. For a guided tour through the levels, see Progressive Learning Approach further down.

Counts are approximate as of 2026-06-24; subsystem READMEs are authoritative.

1. Common Building Blocks — `rtl/common/`

Reusable primitives, technology-agnostic. ~230 modules across rtl/common/ and rtl/math/ (math modules were split out of common into their own library). Click any class name for its overview (when to use, picking guide, members table); click RTL for source.

Class (overview)	~Count	RTL	Examples
Counters	5	`rtl/common/` (`counter_*.sv`)	`counter_bin`, `counter_bin_load`, `counter_load_clear`, `counter_ring`, `counter_freq_invariant`. The CDC-pointer counters (`counter_bingray`, `counter_johnson`) moved to `rtl/cdc/`.
Arbiters	5	`rtl/common/` (`arbiter_*.sv`)	`arbiter_round_robin`, `arbiter_round_robin_weighted`, PWM variants
FIFOs	2	`rtl/common/` (`fifo_*.sv`)	`fifo_sync`, `fifo_control`. The async FIFOs live in `rtl/cdc/`.
Shift / LFSR	6	`rtl/common/` (`shifter_*.sv`)	Fibonacci LFSR, Galois LFSR, universal shifters
Math — integer arithmetic	40+	`rtl/math/` (`math_adder_`, `math_mult_`, `math_div_*`)	Han-Carlson prefix adders (16/22/32/44/48/72-bit), Dadda 4:2 compressor mults (8/11/24-bit), leading-zero count, parity
Math — floating point	120+	`rtl/math/` (`math_float_*`)	BF16, FP16, FP32, FP8 (E4M3/E5M2): adder, multiplier, FMA, recip, divide, sqrt; cross-format converters
Data integrity	7	`rtl/common/` (`dataint_*.sv`)	`dataint_crc` (300+ standards), `dataint_ecc_hamming` (SECDED), `dataint_parity`
Clock utilities	3	`rtl/common/` (`clock_*.sv`)	`clock_divider`, `clock_gate_ctrl`, `clock_pulse`
Encoders / decoders	3	`rtl/common/` (`{encoder,decoder}*.sv`)	priority encoder, address decoder
Reset	1	`rtl/common/reset_sync.sv`	async-assert / sync-deassert reset bridge

Deep dive: docs/markdown/rtl-common/index.md (per-module specs) · rtl/common/CLAUDE.md

2. AMBA Protocols — `rtl/amba/`

Production-ready AXI/APB/AXIS infrastructure with built-in monitor + observation. 155 modules across 8 protocol dirs + 48 shared. Click any protocol name for its overview (features, modules, picking guide); click RTL for source.

Protocol (overview)	Modules	RTL	Notes
AXI4	16	`rtl/amba/axi4/`	masters/slaves, RD/WR, `_mon` + `_cg` variants
AXI5	16	`rtl/amba/axi5/`	AXI5 extensions
AXI4-Lite	16	`rtl/amba/axil4/`	Dedicated `axil4_*_mon.sv` (not the legacy `IS_AXI=0`)
APB	9	`rtl/amba/apb4/`	masters, slaves, slave_cdc + `_cg`
APB5	9	`rtl/amba/apb5/`	APB5 extensions
AXI-Stream (AXIS4)	4	`rtl/amba/axis4/`	master / slave
AXI-Stream (AXIS5)	4	`rtl/amba/axis5/`	AXIS5 extensions
Shared infrastructure	48	`rtl/amba/shared/`	monitor core, monbus, observation, sdpram, CDC, arbiters
GAXI generic	8	`rtl/amba/gaxi/`	sync/async FIFOs and skid buffers
Packages	8	`rtl/amba/includes/`	shared `.svh`/types

Deep dive: docs/markdown/rtl-amba/index.md (full shared/ inventory by role) · rtl/amba/CLAUDE.md · docs/markdown/rtl-amba/index.md

3. Clock Domain Crossing (CDC) — Cross-cutting

Read the CDC class overview → (picking guide, what NOT to do, on-board demo)

Everything that crosses a clock domain now lives in one place, rtl/cdc/. It used to be scattered across rtl/common/ and rtl/amba/shared/; if you find a doc still saying that, it is stale.

Module	Where	Use
`cdc_synchronizer.sv`	`rtl/cdc/`	Plain N-flop bit synchronizer
`cdc_2_phase_handshake.sv`	`rtl/cdc/`	2-phase req/ack data CDC
`cdc_4_phase_handshake.sv`	`rtl/cdc/`	4-phase req/ack data CDC
`cdc_open_loop.sv`	`rtl/cdc/`	Fire-and-forget pulse CDC
`bin2gray.sv` / `gray2bin.sv`	`rtl/cdc/`	Gray-code conversion for pointer CDC
`johnson2bin.sv`	`rtl/cdc/`	Johnson-code decode, for non-power-of-2 FIFO depths
`counter_bingray.sv` / `counter_johnson.sv`	`rtl/cdc/`	Dual-encoding counters for FIFO pointers
`fifo_async.sv`	`rtl/cdc/`	Async FIFO for word-width CDC
`gaxi_fifo_async.sv`, `gaxi_skid_buffer_async.sv`	`rtl/cdc/`	AXI-shaped async FIFO + skid
`reset_sync.sv`	`rtl/common/`	Async-assert / sync-deassert reset CDC
`apb4_slave_cdc.sv` (and `apb5_slave_cdc.sv`)	`rtl/amba/apb4/` / `rtl/amba/apb5/`	APB slave with CDC built in

FPGA demo: projects/fpga-systems/NexysA7/cdc_counter_display/ — multi-clock counter CDC running on real hardware.

4. Component Projects — `projects/components/`

Production-shaped reusable IP. Each has its own README + dv/ + dv/tbclasses/.

Project	Status	Domain	Where
STREAM	Ready	Tutorial DMA + scatter-gather; kick-burst multi-channel start + optional 2-D/transpose addressing	`projects/components/dma-ip/stream/`
RAPIDS	In progress	Advanced DMA with network interfaces (RAPID AXI Programmable In-band Descriptor System)	`projects/components/dma-ip/rapids/`
Bridge	Ready	AXI protocol bridges + RDL-generated cfg	`projects/components/fabric-gen-ip/bridge/`
Converters	Ready	UART↔AXIL, protocol conversion	`projects/components/utility-ip/converters/`
APB Crossbar	Ready	M×N APB interconnect	`projects/components/fabric-gen-ip/apbx-xbar/`
Memory controllers	In progress	DDR2 / LPDDR2 controller	`projects/components/mem-ctrl-ip/`
Retro legacy blocks	Ready	HPET, PIC, PIT, RTC, UART, GPIO	`projects/components/retro_legacy_blocks/`
Delta	Planned	Network-on-Chip mesh	`projects/components/noc-ip/delta/`
HIVE	Planned	Distributed RISC-V control	`projects/components/compute-eng-ip/hive/`
Misc	—	Mixed building blocks	`projects/components/utility-ip/misc/`

5. FPGA Projects — `projects/fpga-systems/NexysA7/` (Digilent Nexys A7-100T)

Things that actually run on hardware. Each project ships its own README and Vivado flow.

Project	Goal	Where
timing_characterization	FUB delay characterization. STA-only `bitstream-sweep` is the headline path; on-board MMCM sweep is an optional gut-check (see `README_FPGA.md` §5)	`projects/asic-trials/timing_characterization/`
cdc_counter_display	Live demo of multi-clock counter CDC on the board	`projects/fpga-systems/NexysA7/cdc_counter_display/`
ddr2-characterization	DDR2 / LPDDR2 memory controller (pumice) bring-up and characterization on Nexys A7	`projects/fpga-systems/NexysA7/pumice/ddr2-characterization/` (RTL: `projects/components/mem-ctrl-ip/pumice-ddr2-lpddr2/`)
boards	Board files / pinouts / constraints	`projects/fpga-systems/boards/`

CDC Counter Display — a counter in a fast clock domain driving a display in a slow one, demonstrating the crossing the rtl/amba/cdc/ modules implement:

Clock Domain A (Fast)    Clock Domain B (Slow)
    Counter      →  CDC  →    Display
   @ 100MHz         Sync      @ 10MHz

6. Verification

What	Where
AMBA protocol tests	`val/amba/`
Common-library tests	`val/common/`
Project tests (CocoTB + pytest, Pattern B)	under `projects/components/` — each `*/dv/tests/`
Project-specific TBs	under `projects/components/` — each `*/dv/tbclasses/`
Shared TB framework	`bin/TBClasses/`
BFMs / scoreboards (external package)	`cocotb-framework` on PyPI — source: RTLDesignSherpa-DV — `pip install cocotb-framework`
Verification architecture rules	`GLOBAL_REQUIREMENTS.md` (Category 2), `docs/user-guides/VERIFICATION_ARCHITECTURE_GUIDE.md`

7. Tools

Tool	Purpose	Where
RTL generators	Codegen for math circuits + floating-point modules	`bin/rtl_generators/`
`md_to_docx.py`	Markdown → DOCX/PDF with corporate styles	`bin/md_to_docx.py`
`audit_signal_naming_conflicts.py`	Detect AXI-factory pattern collisions before TB write	`bin/audit_signal_naming_conflicts.py` (guide)
`vivado_timing_failures.py`	Per-violation Vivado timing parser	`bin/vivado_timing_failures.py`
Misc scripts	Build/regen helpers, codemaps, doc generators	bin/ · tools/ · scripts/

8. Documentation hub

docs/DOCUMENTATION_INDEX.md — full doc index
docs/markdown/rtl-common/index.md — per-module specs (common library)
docs/markdown/rtl-amba/index.md — per-module specs (AMBA)
docs/markdown/projects/index.md — project documentation index
GLOBAL_REQUIREMENTS.md — mandatory requirements across the whole repo
CLAUDE.md — guidance for AI assistants working in this repo

Progressive Learning Approach

Level 1: Common Building Blocks (Foundation)

Location: rtl/common/ | Documentation: Full Index | AI Guide

Learn fundamental RTL design patterns through 224 reusable modules:

Integer Arithmetic (44+ modules)

Counters: Binary, Gray code, Johnson, Ring, Load/Clear variants
Adders: Han-Carlson prefix adders (16/22/32/44/48/72-bit), Brent-Kung
Multipliers: Dadda 4:2 compressor trees (8/11/24-bit)
Math: Leading zeros, bit reversal, parity, CRC

Floating-Point (120+ modules)

BF16: Adder, multiplier, FMA, reciprocal, division, square root
FP16 (IEEE 754): Complete arithmetic suite
FP32 (IEEE 754): Adder, multiplier, FMA
FP8 (E4M3/E5M2): ML-optimized formats
Converters: Cross-format conversion (FP32↔FP16↔BF16↔FP8)

Data Structures

FIFOs: Synchronous, asynchronous, dual-clock domain
Shift Registers: LFSR (Fibonacci/Galois), universal shifters
Memory: CAM (Content Addressable Memory), buffers

Control Logic

Arbiters: Round-robin (simple, weighted, PWM), priority encoders
Encoders/Decoders: Priority encoding, address decoding
Clock Management: Dividers, gate control, pulse generation
Reset: Synchronizers, CDC utilities

Data Integrity

CRC Engines: Generic CRC supporting 300+ standards
ECC: Hamming code (SECDED), parity checkers

Example Module: counter_bin.sv

// Simple binary counter - foundation for timers, state machines
module counter_bin #(
    parameter WIDTH = 8
) (
    input  logic             i_clk,
    input  logic             i_rst_n,
    input  logic             i_enable,
    output logic [WIDTH-1:0] o_count
);

Tests: val/common/ - Every module has comprehensive CocoTB tests

Level 2: AMBA Protocol Infrastructure

Location: rtl/amba/ | Documentation: Full Index | AI Guide

Apply common building blocks to implement industry-standard protocols (124 modules):

APB (Advanced Peripheral Bus)

APB Masters - Command/response interfaces with FIFO buffering
APB Slaves - Register interfaces with address decoding
APB Bridges - Protocol conversion, CDC

Example: APB register slave demonstrates parameter-driven design

apb4_slave #(
    .ADDR_WIDTH(12),
    .DATA_WIDTH(32)
) u_apb4_slave (
    .pclk, .presetn, .paddr, .psel, .penable, .pwrite,
    .pwdata, .pready, .prdata, .pslverr
);

AXI4 Full Protocol

AXI4 Masters - Read/write with dual skid buffers
AXI4 Slaves - Response generation, address decoding
AXI4 Infrastructure - FIFOs, skid buffers, arbiters
Monitoring - Protocol compliance checkers

AXI4-Lite (Simplified Register Interface)

AXI4-Lite Masters - Register-optimized masters
AXI4-Lite Slaves - Configuration registers
Converters - Protocol and width conversion (APB, AXI-Lite, AXI4)

AXI4-Stream (High-Throughput Data)

Stream Masters/Slaves - Streaming interfaces
Flow Control - Backpressure, buffering
Sideband Support - TID, TDEST, TUSER, TSTRB

Shared Infrastructure

GAXI Buffers - Generic skid buffers, FIFOs, CDC
Monitors - Transaction monitoring, performance analysis
Arbiters - Advanced arbitration for monitor buses

Tests: val/amba/ - Protocol compliance and integration tests

Level 3: Production Components

Location: projects/components/ | Documentation: Component Index

Build complete, production-ready peripherals for FPGA deployment (10+ components):

DMA Engines

Component	Status	Description
STREAM	Ready	Tutorial DMA with 8 channels, scatter-gather, APB config
RAPIDS	In Progress	Advanced DMA with alignment fixup, network TX/RX, credit flow

Interconnect and Bridges

Component	Status	Description
APB Crossbar	Ready	Parametric M×N APB interconnect with round-robin arbitration
Bridge	Ready	AXI4 protocol bridges, width converters, CDC
Converters	Ready	UART-to-AXI4-Lite, protocol conversion bridges

Retro Legacy Blocks

Status: Production Ready | Location: projects/components/retro_legacy_blocks/

Collection of 9 legacy/retro peripherals with full APB interfaces:

Peripheral	Description
HPET	High Precision Event Timer (2/3/8 timers, 64-bit)
GPIO	General Purpose I/O with interrupts
UART 16550	Full 16550-compatible UART
8259 PIC	Programmable Interrupt Controller
8254 PIT	Programmable Interval Timer
RTC	Real-Time Clock
SMBUS	System Management Bus controller
PM/ACPI	Power Management / ACPI support
IOAPIC	I/O Advanced PIC

Documentation: PRD

Future Components

Component	Status	Description
Delta	Planned	4×4 Network-on-Chip mesh with virtual channels
HIVE	Planned	Distributed RISC-V control (VexRiscv + 16 SERV monitors)

Level 4: Complete FPGA Projects (Future)

Planned: Full SoC designs combining all levels:

Simple SoC: APB HPET + Memory + UART
DMA System: RAPIDS DMA + Multi-bank memory
Communication Hub: Ethernet MAC + DMA + Buffers
Processing Subsystem: Custom accelerators + Interconnect

Verification Methodology

CocoTB-Based Testing

Every module demonstrates professional verification practices:

Test Structure:

# Reusable testbench class (in bin/TBClasses/)
class ModuleTB(TBBase):
    def __init__(self, dut):
        super().__init__(dut)
        self.setup_drivers()
        self.setup_monitors()
        self.setup_scoreboards()

    async def setup_clocks_and_reset(self):
        """Standard clock and reset initialization"""

    async def write_register(self, addr, data):
        """Protocol-specific register write"""

# Test suite (organized by level)
class ModuleBasicTests:
    async def test_register_access(self): ...
    async def run_all_basic_tests(self): ...

class ModuleMediumTests:
    async def test_complex_scenario(self): ...
    async def run_all_medium_tests(self): ...

class ModuleFullTests:
    async def test_stress(self): ...
    async def run_all_full_tests(self): ...

Test Hierarchy:

Basic Tests - Register access, reset behavior, simple operations
Medium Tests - Complex features, multi-component interactions
Full Tests - Stress testing, CDC, edge cases

Test Configuration (conftest.py):

Auto-creates logs directory
Registers pytest markers (basic, medium, full)
Preserves all logs
Parametrized test fixtures

Running Tests:

# Run all tests for a module
pytest val/common/test_counter_bin.py -v

# Run specific test level
pytest val/amba/ -v -m basic      # Basic tests only
pytest val/amba/ -v -m medium     # Medium tests only
pytest val/amba/ -v -m full       # Full tests only

# Run component tests (example: Retro Legacy Blocks HPET)
pytest projects/components/retro_legacy_blocks/dv/tests/test_apb4_hpet.py -v

Technology Stack

Core Tools (All Open-Source)

Simulation and Analysis

Verilator - High-performance RTL simulator
- Supports SystemVerilog
- VCD/FST waveform generation
- Fast execution for large designs
GTKWave - Waveform viewer
- Pre-configured signal groups
- Professional visualization
Verible - SystemVerilog tools
- Linting and style checking
- Code formatting
- Parsing and analysis

Verification Framework

CocoTB - Python-based testbench framework
- Intuitive Python test writing
- Full SystemVerilog integration
- Extensive protocol libraries
pytest - Test runner and framework
- Test discovery and execution
- Parametrized testing
- Rich reporting
Custom VIP - Verification IP for protocols
- APB, AXI4, AXI4-Lite, AXI-Stream drivers/monitors
- Scoreboards and coverage collectors

Register Generation

PeakRDL - SystemRDL tools
- Register file generation from specifications
- APB4, AXI4-Lite interface generation
- C header generation
- Documentation generation

Development and Automation

Python 3.8+ - Scripting and automation
- Code generation (math circuits, register files)
- Analysis tools (dependency, UML)
- Documentation generation (Wavedrom)
Make - Build automation
Git - Version control with CI/CD integration

Repository Structure

rtldesignsherpa/
├── rtl/                          # RTL source code (~390 modules)
│   ├── common/                   # ~57 building blocks (counters, FIFOs, arbiters, etc.)
│   ├── math/                     # ~170 arithmetic modules (integer + FP; split out of common)
│   ├── amba/                     # ~160 AMBA protocol modules
│   │   ├── apb/                 # APB protocol
│   │   ├── axi4/                # AXI4 full protocol
│   │   ├── axil4/               # AXI4-Lite
│   │   ├── axis4/               # AXI4-Stream
│   │   ├── axi5/                # AMBA5 components
│   │   ├── apb5/                # APB5 protocol
│   │   ├── axis5/               # AXIS5 protocol
│   │   ├── gaxi/                # Generic AXI infrastructure
│   │   ├── cdc/                 # Clock domain crossing
│   │   ├── monitor/             # Transaction monitors + MonBus groups
│   │   └── shared/              # Shared observation utilities
│
├── projects/                     # Component projects (10+)
│   ├── components/
│   │   ├── dma-ip/stream/         # STREAM DMA engine
│   │   ├── dma-ip/rapids/         # RAPIDS DMA engine
│   │   ├── bridge/              # Protocol bridges
│   │   ├── converters/          # Width/protocol converters
│   │   ├── apbx_xbar/            # APB crossbar
│   │   ├── mem-ctrl-ip/  # pumice DDR2/LPDDR2 controller
│   │   ├── retro_legacy_blocks/ # Legacy peripherals (HPET, RTC, PIT, ...)
│   │   ├── delta/               # AXIS crossbar generator
│   │   ├── hive/                # RISC-V control (planned)
│   └── NexysA7/                 # FPGA projects
│
├── val/                          # Validation/Test suites
│   ├── common/                  # Common module tests
│   └── amba/                    # AMBA protocol tests
│
├── bin/                          # Tools and automation
│   ├── CocoTBFramework/         # Testbench infrastructure (200+ files)
│   ├── rtl_generators/          # RTL code generators
│   │   ├── bf16/                # BF16 floating-point generators
│   │   ├── ieee754/             # IEEE 754 FP generators
│   │   └── verilog/             # Generic RTL generators
│   ├── md_to_docx.py            # Documentation generator
│   └── update_doc_headers.py    # Header management
│
├── docs/                         # Documentation
│   ├── markdown/                # Technical documentation
│   │   ├── rtl-common/           # Common library docs
│   │   ├── rtl-amba/             # AMBA library docs
│   │   ├── CocoTBFramework/     # Framework docs
│   │   └── projects/            # Component docs
│   └── DOCUMENTATION_INDEX.md   # Master doc index
│
├── CLAUDE.md                     # Repository AI guide
└── README.md → docs/markdown/overview.md  # This file (symlink)

Getting Started

Installation

1. Install Prerequisites:

# Ubuntu/Debian
sudo apt update
sudo apt install -y verilator gtkwave python3 python3-pip git make

# Fedora/RHEL
sudo dnf install -y verilator gtkwave python3 python3-pip git make

# macOS (via Homebrew)
brew install verilator gtkwave python3 git make

2. Install Python Dependencies:

pip3 install cocotb pytest cocotb-test
pip3 install peakrdl peakrdl-regblock  # For register generation

3. Clone Repository:

git clone https://github.com/yourusername/rtldesignsherpa.git
cd rtldesignsherpa

Quick Start Examples

Level 1: Test a Simple Counter

# Run basic counter test
pytest val/common/test_counter_bin.py -v

# View waveforms (after test generates VCD)
gtkwave val/common/local_sim_build/test_counter_bin/dump.vcd

Level 2: Test APB Slave

# Run APB slave tests
pytest val/amba/test_apb4_slave.py -v

# Run only basic tests
pytest val/amba/test_apb4_slave.py -v -m basic

Level 3: Test APB Crossbar

# Run 2-to-4 crossbar test
pytest projects/components/fabric-gen-ip/apbx-xbar/dv/tests/test_apbx_xbar_2to4.py -v

Level 4: Test Retro Legacy Block Component

# Run HPET tests from Retro Legacy Blocks collection
pytest projects/components/retro_legacy_blocks/dv/tests/test_apb4_hpet.py -v

Learning Resources

Documentation by Level

Level 1 - Common Modules:

Common Library PRD - Requirements and specifications
Common CLAUDE Guide - AI-assisted development
Common Tests - Example test patterns

Level 2 - AMBA Protocols:

AMBA Infrastructure PRD - Protocol specifications
AMBA CLAUDE Guide - Implementation patterns
AMBA Tests - Protocol compliance tests

Level 3 - Components:

Component Index - All components
Component Overview - Design patterns
Retro Legacy Blocks - Legacy peripheral collection
HPET Specification - Complete HPET guide

External References

Standards:

AMBA Specifications - ARM protocols
SystemRDL 2.0 - Register specification

Tools:

CocoTB Documentation - Verification framework
Verilator Manual - Simulator guide
PeakRDL Docs - Register generation

Books Referenced:

Advanced FPGA Design by Steve Kilts
Synthesis of Arithmetic Circuits by Deschamps, Bioul, Sutter

Development Workflow

Creating a New Module

1. Design the Module (choose your level):

// rtl/common/my_module.sv (Level 1)
// or
// rtl/amba/my_protocol.sv (Level 2)
module my_module #(
    parameter WIDTH = 8
) (
    input  logic             i_clk,
    input  logic             i_rst_n,
    // ... ports
);

2. Create Testbench:

# bin/TBClasses/{subsystem}/my_module_tb.py
class MyModuleTB(TBBase):
    def __init__(self, dut):
        super().__init__(dut)

    async def setup_clocks_and_reset(self):
        # Clock and reset initialization
        pass

# bin/TBClasses/{subsystem}/my_module_tests_basic.py
class MyModuleBasicTests:
    async def test_basic_functionality(self):
        # Test implementation
        pass

3. Create Test Runner:

# val/{subsystem}/test_my_module.py
import cocotb
import pytest
from cocotb_test.simulator import run

from TBClasses.{subsystem}.my_module_tb import MyModuleTB
from TBClasses.{subsystem}.my_module_tests_basic import MyModuleBasicTests

@cocotb.test()
async def my_module_test(dut):
    tb = MyModuleTB(dut)
    await tb.setup_clocks_and_reset()
    tests = MyModuleBasicTests(tb)
    result = await tests.run_all_basic_tests()
    assert result

@pytest.mark.parametrize("width", [8, 16, 32])
def test_my_module(request, width):
    run(verilog_sources=[...], parameters={'WIDTH': width}, ...)

4. Run Tests:

pytest val/{subsystem}/test_my_module.py -v

5. Document:

Add to subsystem PRD.md
Update CLAUDE.md with patterns
Create examples in documentation

Performance and Quality

Test Coverage

Current Status:

Common Library: >95% line coverage, >90% branch coverage
AMBA Protocols: >95% line coverage, 100% protocol compliance
APB HPET: 5/6 configurations at 100% (12 tests each)
Integration: Full system-level verification

Module Counts

224 Common Modules - Counters, FIFOs, arbiters, math, floating-point
124 AMBA Modules - APB, AXI4, AXI4-Lite, AXI-Stream, AMBA5
10+ Production Components - DMA engines, bridges, legacy peripherals
350+ Total RTL Modules - Complete verification infrastructure

Synthesis Results

Modules have been characterized across FPGA technologies:

Category	Fmax Range	Use Cases
Basic Logic	100-800 MHz	Counters, registers, control
Advanced Math	200-600 MHz	DSP, arithmetic operations
Protocol Masters/Slaves	200-500 MHz	APB, AXI interfaces
Integration Examples	100-400 MHz	Multi-module systems
Production Components	100-200 MHz	Complete peripherals

Contributing

We welcome contributions at all levels:

Level 1-2: New building blocks or protocol modules Level 3: Production components Level 4: Complete FPGA projects

Guidelines:

Follow existing module structure and naming
Include comprehensive CocoTB tests (3-level hierarchy)
Document in PRD.md and CLAUDE.md
Achieve >95% test coverage
Provide integration examples

Use Cases

Educational

University Courses: Complete RTL design curriculum
Self-Learning: Progressive path from basics to production
Industry Preparation: Professional verification practices

Professional

IP Development: Starting point for commercial IP
Prototyping: Rapid hardware proof-of-concept
Tool Evaluation: Open-source vs. commercial comparison

Startup/Small Teams

Cost-Effective Development: No expensive EDA licenses
Team Training: Standardized practices and workflows
IP Portfolio: Foundation for valuable hardware assets

Roadmap

Current Focus

STREAM DMA - Tutorial DMA engine complete
Bridge components - AXI4 width converters, CDC bridges complete
Retro Legacy Blocks - 9 peripherals with MAS documentation
RAPIDS DMA - Advanced DMA in progress
Floating-Point - FP32 FMA, additional converters

Near-Term

Delta Network-on-Chip mesh implementation
HIVE distributed RISC-V control
NexysA7 FPGA integration examples

Long-Term

Complete SoC reference designs
PCIe/Ethernet/USB controllers
Formal verification integration
ASIC synthesis flow examples

Project Philosophy

RTL Design Sherpa believes that:

Learning by Doing - Best way to learn hardware design is building real circuits
Progressive Complexity - Start simple, build up systematically
Verification First - Quality comes from comprehensive testing
Open Source - Knowledge should be accessible to everyone
Industry Practices - Teach real-world professional techniques

The journey from a simple counter to a complete DMA engine teaches not just RTL, but the entire hardware development process.

License

[Your License Here]

Contact and Support

GitHub Issues: [Report issues or request features]
Documentation: [Link to docs]
Community: [Link to discussions/forum]

RTL Design Sherpa: Guiding you from first principles to production-ready hardware design.

Name		Name	Last commit message	Last commit date
.claude		.claude
.dvt		.dvt
.github		.github
bin		bin
docs		docs
formal		formal
make		make
projects		projects
reference		reference
rtl		rtl
scripts		scripts
stats		stats
tools		tools
val		val
vault		vault
.aliases		.aliases
.bashrc		.bashrc
.gitignore		.gitignore
.pylintrc		.pylintrc
.sourcery.yaml		.sourcery.yaml
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GLOBAL_REQUIREMENTS.md		GLOBAL_REQUIREMENTS.md
LICENSE		LICENSE
Makefile		Makefile
PRD.md		PRD.md
README.md		README.md
conftest.py		conftest.py
env_python		env_python
extensions.json		extensions.json
pyrightconfig.json		pyrightconfig.json
requirements.txt		requirements.txt
settings.json		settings.json
setup.cfg		setup.cfg
test_environments.toml		test_environments.toml
test_targets.mk		test_targets.mk
tox.ini		tox.ini
verilator.cpp		verilator.cpp
verilog_condensed_lrm.sv		verilog_condensed_lrm.sv

Latest commit

History

Folders and files

Repository files navigation

RTL Design Sherpa

Project Mission

Learning Path

Browse by Class

1. Common Building Blocks — rtl/common/

2. AMBA Protocols — rtl/amba/

3. Clock Domain Crossing (CDC) — Cross-cutting

4. Component Projects — projects/components/

5. FPGA Projects — projects/fpga-systems/NexysA7/ (Digilent Nexys A7-100T)

6. Verification

7. Tools

8. Documentation hub

Progressive Learning Approach

Level 1: Common Building Blocks (Foundation)

Integer Arithmetic (44+ modules)

Floating-Point (120+ modules)

Data Structures

Control Logic

Data Integrity

Level 2: AMBA Protocol Infrastructure

APB (Advanced Peripheral Bus)

AXI4 Full Protocol

AXI4-Lite (Simplified Register Interface)

AXI4-Stream (High-Throughput Data)

Shared Infrastructure

Level 3: Production Components

DMA Engines

Interconnect and Bridges

Retro Legacy Blocks

Future Components

Level 4: Complete FPGA Projects (Future)

Verification Methodology

CocoTB-Based Testing

Technology Stack

Core Tools (All Open-Source)

Simulation and Analysis

Verification Framework

Register Generation

Development and Automation

Repository Structure

Getting Started

Installation

Quick Start Examples

Level 1: Test a Simple Counter

Level 2: Test APB Slave

Level 3: Test APB Crossbar

Level 4: Test Retro Legacy Block Component

Learning Resources

Documentation by Level

External References

Development Workflow

Creating a New Module

Performance and Quality

Test Coverage

Module Counts

Synthesis Results

Contributing

Use Cases

Educational

Professional

Startup/Small Teams

Roadmap

Current Focus

Near-Term

Long-Term

Project Philosophy

License

Contact and Support

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

1. Common Building Blocks — `rtl/common/`

2. AMBA Protocols — `rtl/amba/`

4. Component Projects — `projects/components/`

5. FPGA Projects — `projects/fpga-systems/NexysA7/` (Digilent Nexys A7-100T)