CocoTB Framework

Reusable CocoTB verification infrastructure for RTL testing. Provides protocol-specific Bus Functional Models (BFMs), transaction scoreboards, and shared utilities for AMBA and other standard interfaces.

Extracted from the RTLDesignSherpa project as a standalone, pip-installable package.

Installation

pip install cocotb-framework

With all optional dependencies:

pip install cocotb-framework[all]

For development:

git clone https://github.com/sean-galloway/RTLDesignSherpa-DV.git
cd RTLDesignSherpa-DV
pip install -e ".[dev,all]"

Package Structure

CocoTBFramework/
├── components/           # Protocol-specific BFMs and drivers
│   ├── ace/             # AXI4-ACE (coherency extensions)
│   ├── axi4/            # AXI4 full protocol
│   ├── axi5/            # AXI5 (AMBA5) protocol
│   ├── axil4/           # AXI4-Lite
│   ├── apb/             # APB protocol
│   ├── apb5/            # APB5 protocol
│   ├── axis4/           # AXI-Stream
│   ├── axis5/           # AXI-Stream v5
│   ├── dfi/             # DDR PHY Interface (DFI) v2.1-v5.x BFMs
│   ├── fifo/            # Generic FIFO
│   ├── gaxi/            # GAXI — validate FIFO-based interfaces on small blocks
│   ├── smbus/           # System Management Bus
│   ├── uart/            # UART serial
│   ├── wavedrom/        # Waveform visualization
│   └── shared/          # Common utilities
└── scoreboards/         # Transaction verification
    ├── base_scoreboard  # Base class for all scoreboards
    ├── apb / gaxi / fifo / axi4 / dfi scoreboards
    └── axi4/            # AXI4-specific scoreboards (dwidth converter)

Protocol BFMs

Each protocol package provides a complete set of verification components: masters (drivers), slaves (responders), monitors (passive observers), and packets (transaction representations).

Note (2026-10-12): RTL Design Sherpa's monitor system is branded Ocelus. The monitor BFM classes in this framework (APBMonitor, GAXIMonitor, AXISMonitor, ...) are the verification companions of that fabric — class names and the MonBus fabric name are unchanged by the brand.

AMBA Protocols

AXI4 (Advanced eXtensible Interface)

Full AXI4 protocol implementation with compliance checking and constrained randomization.

from CocoTBFramework.components.axi4.axi4_interfaces import AXI4MasterRead, AXI4MasterWrite
from CocoTBFramework.components.axi4.axi4_interfaces import AXI4SlaveRead, AXI4SlaveWrite
from CocoTBFramework.components.axi4.axi4_packet import AXI4Packet
from CocoTBFramework.components.axi4.axi4_compliance_checker import AXI4ComplianceChecker
from CocoTBFramework.components.axi4.axi4_sequence import AXI4Sequence, run_axi4_sequence

Key classes:

• AXI4MasterRead / AXI4MasterWrite — Full-duplex master with integrated compliance
• AXI4SlaveRead / AXI4SlaveWrite — Slave responder with configurable timing
• AXI4ComplianceChecker — Protocol violation detection and tracking
• AXI4Sequence / run_axi4_sequence — Directed-random sequence authoring and pipelined execution
• AXI4Packet — Complete transaction representation with field formatting

AXI4-ACE (AXI Coherency Extensions)

AXI4 extended with coherency: ARSNOOP/AWSNOOP on the front side, plus the AC/CR/CD snoop channels and RACK/WACK acknowledges. Implements the cache-ip ACE-shaped port contract (onyx D2 subset).

from CocoTBFramework.components.ace import (
    AXI4ACEMasterRead,
    AXI4ACEMasterWrite,
    AXI4ACESnoopMaster,
    AXI4ACESnoopSlave,
    ACEComplianceChecker,
)

Key classes:

• AXI4ACEMasterRead / AXI4ACEMasterWrite — Coherent front-side masters with auto-pulsed RACK/WACK
• AXI4ACESnoopMaster / AXI4ACESnoopSlave — CCU-side initiator and cache-side responder for AC/CR/CD
• ACEComplianceChecker — Snoop-order and CRRESP validity checker
• ACEPacket / SnoopPacket — Transaction packets including snoop-channel factory methods
• ACETransactionType / SnoopType / CRRESP / CacheState — Coherent transaction and state enumerations

AXI5

AMBA5-generation AXI with extended signals and features. Same class structure as AXI4.

from CocoTBFramework.components.axi5.axi5_interfaces import AXI5MasterRead, AXI5MasterWrite
from CocoTBFramework.components.axi5.axi5_compliance_checker import AXI5ComplianceChecker

AXI4-Lite

Simplified AXI for register-mapped peripherals.

from CocoTBFramework.components.axil4.axil4_interfaces import AXIL4MasterRead, AXIL4MasterWrite
from CocoTBFramework.components.axil4.axil4_compliance_checker import AXIL4ComplianceChecker

APB / APB5 (Advanced Peripheral Bus)

Simple bus protocol for low-bandwidth peripherals.

from CocoTBFramework.components.apb.apb_components import APBMaster, APBSlave, APBMonitor
from CocoTBFramework.components.apb.apb_packet import APBPacket
from CocoTBFramework.components.apb.apb_sequence import APBSequence
from CocoTBFramework.components.apb.apb_factories import create_apb4_monitor, create_apb4_scoreboard

AXI-Stream (AXIS4 / AXIS5)

Unidirectional streaming with handshake.

from CocoTBFramework.components.axis4.axis_master import AXISMaster
from CocoTBFramework.components.axis4.axis_slave import AXISSlave
from CocoTBFramework.components.axis4.axis_monitor import AXISMonitor
from CocoTBFramework.components.axis4.axis_packet import AXISPacket

Generic AXI (GAXI)

Lightweight valid/ready handshake protocol for validating individual FIFO-based interfaces on very small internal blocks. Interfaces can carry data packed into fields within a single bus, or have many discrete signals. Includes built-in coverage hooks and statistics tracking.

from CocoTBFramework.components.gaxi import GAXIMaster, GAXISlave, GAXIMonitor
from CocoTBFramework.components.gaxi import GaxiCoverageHook, register_coverage_hooks
from CocoTBFramework.components.gaxi.gaxi_packet import GAXIPacket
from CocoTBFramework.components.gaxi.gaxi_sequence import GAXISequence

Other Protocols

DFI (DDR PHY Interface)

DFI v2.1-v5.x master (memory controller side) and slave (PHY side) BFMs with per-version behavior classes, JEDEC timing enforcement, and DRAM state modeling.

from CocoTBFramework.components.dfi.dfi_master_mc import DFIMasterMC
from CocoTBFramework.components.dfi.dfi_slave_phy import DFISlavePHY
from CocoTBFramework.components.dfi.dfi_monitor import DFIMonitor

FIFO

Generic FIFO verification with masters, slaves, monitors, and command handling.

from CocoTBFramework.components.fifo.fifo_master import FIFOMaster
from CocoTBFramework.components.fifo.fifo_slave import FIFOSlave
from CocoTBFramework.components.fifo.fifo_monitor import FIFOMonitor

SMBus (System Management Bus)

SMBus/I2C protocol verification with open-drain tristate signal handling and CRC-8 PEC.

from CocoTBFramework.components.smbus.smbus_components import SMBusMaster, SMBusSlave, SMBusMonitor

UART

Serial UART protocol at the bit level.

from CocoTBFramework.components.uart.uart_components import UARTMaster, UARTSlave, UARTMonitor

Shared Utilities

Common infrastructure used across all protocol implementations.

from CocoTBFramework.components.shared.packet import Packet
from CocoTBFramework.components.shared.field_config import FieldConfig, FieldDefinition
from CocoTBFramework.components.shared.memory_model import MemoryModel
from CocoTBFramework.components.shared.flex_randomizer import FlexRandomizer
from CocoTBFramework.components.shared.packet_factory import PacketFactory

Scoreboards

Queue-based transaction verification with protocol-specific comparators and cross-protocol adapters.

from CocoTBFramework.scoreboards.base_scoreboard import BaseScoreboard
from CocoTBFramework.scoreboards.gaxi_scoreboard import GAXIScoreboard
from CocoTBFramework.scoreboards.fifo_scoreboard import FIFOScoreboard
from CocoTBFramework.scoreboards.apb_scoreboard import APBScoreboard
from CocoTBFramework.scoreboards.apb_gaxi_scoreboard import APBGAXIScoreboard

Cross-Protocol Adapters

from CocoTBFramework.scoreboards.apb_gaxi_transformer import APBtoGAXITransformer

The scoreboard system includes transformers and adapters for verifying protocol bridges and converters (APB ↔ GAXI, GAXI ↔ Memory, etc.).

Waveform Visualization

Generate WaveJSON timing diagrams from simulation signals.

from CocoTBFramework.components.wavedrom.wavejson_gen import WaveJSONGenerator
from CocoTBFramework.components.wavedrom.signal_binder import WavedromSignalBinder
from CocoTBFramework.components.wavedrom.constraint_solver import TemporalConstraintSolver  # needs the [wavedrom] extra (OR-Tools)

Dependencies

Required

Optional Extras

pip install cocotb-framework[wavedrom]   # OR-Tools for constraint solving
pip install cocotb-framework[crc]        # CRC computation
pip install cocotb-framework[all]        # All optional dependencies

Development

# Install in development mode
pip install -e ".[dev,all]"

# Lint
ruff check src/

# Build distributable
python -m build

Related Projects

• RTLDesignSherpa — Parent project with 350+ RTL modules, testbenches, and verification infrastructure
• cocotb — Coroutine-based cosimulation framework
• cocotb-bus — Bus driver and monitor base classes

License

MIT License. See LICENSE for details.