APB (APB3/APB4) Protocol Verification IP

📋 Overview

The KVIPS APB VIP is a vendor-neutral SystemVerilog/UVM verification component supporting both APB3 and APB4 protocols in a single compiled image with runtime protocol selection. Ideal for verifying register access interfaces and low-bandwidth peripheral connections.

🔌 Protocol Selection

The APB VIP supports both APB3 and APB4 in a single compiled image. The interface always includes APB4 signals (PPROT, PSTRB), but the mode determines their behavior:

# APB3 mode - legacy compatibility
+APB_PROTOCOL=APB3
# Master forces PSTRB='1, PPROT=0
# APB4-only assertions are disabled

# APB4 mode (default) - full APB4 features
+APB_PROTOCOL=APB4
# PPROT and PSTRB are actively driven
# All APB4 assertions are enabled

🚀 Quick Start

Run Example Tests

Navigate to the APB examples directory and run tests:

cd apb/examples/

# List available tests
make list-tests

# Run smoke test on Questa with APB4
make questa TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB4'

# Run with APB3 mode
make questa TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB3'

# Run on VCS
make vcs TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB4'

# Run on Xcelium
make xcelium TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB4'

# Run on Verilator
make verilator TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB4'

# Full Verilator regression
make regress-verilator

# Run with LSF (if tools require job scheduler)
# source <path-to-lsf>/conf/profile.lsf
make questa USE_LSF=1 TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB4'

📝 Note: SVA assertions are skipped under Verilator.

Available Test Cases

🧪 APB4 RTL-DUT verification

The separate apb/examples/uvm_dut/ flow connects the KVIPS APB4 master to a byte-addressed signal-level RAM DUT. It is an executable integration target, not the APB master/slave loopback demo. The eight DUT tests cover deterministic readback, continuous transfers, PSTRB, PPROT, wait states, the mapped boundary, unmapped PSLVERR, and randomized APB4 traffic.

Run the evidence-gated commercial regressions from the repository root:

make -C apb/examples regress-rtl-questa USE_LSF=1
make -C apb/examples regress-rtl-vcs USE_LSF=1
make -C apb/examples regress-rtl-xcelium USE_LSF=1

The gate requires observed monitor handshakes, expected error behavior, zero protocol/UVM/simulator errors, and zero scoreboard mismatches. GitHub Actions runs the DUT list with Verilator; Verilator remains a CI-only path on the development workstation. The complete test matrix and remaining single-slave boundaries are in the APB4 DUT verification milestone.

📐 Architecture

Component Hierarchy

apb_env
├── apb_agent (master)
│   ├── apb_sequencer
│   ├── apb_master_driver
│   └── apb_monitor
├── apb_agent (slave)
│   ├── apb_sequencer
│   ├── apb_slave_driver
│   └── apb_monitor
├── apb_scoreboard
└── apb_txn_logger (optional)

Directory Structure

kvips/apb/
├── sv/
│   ├── if/
│   │   └── apb_if.sv              # APB interface + clocking blocks
│   ├── assertions/
│   │   └── apb_if_sva.svh         # Protocol assertions (SVA)
│   ├── pkg/
│   │   ├── apb_types_pkg.sv       # Type definitions, enums
│   │   └── apb_uvm_pkg.sv         # UVM package
│   └── uvm/
│       ├── apb_cfg.sv             # Configuration object
│       ├── apb_txn.sv             # Transaction item
│       ├── apb_sequencer.sv       # Sequencer
│       ├── apb_master_driver.sv   # Master driver
│       ├── apb_slave_driver.sv    # Slave driver/responder
│       ├── apb_monitor.sv         # Passive monitor
│       ├── apb_scoreboard.sv      # Data integrity checker
│       ├── apb_agent.sv           # Agent wrapper
│       ├── apb_env.sv             # Environment
│       └── sequences/
│           ├── apb_base_seq.sv
│           ├── apb_single_seq.sv
│           └── apb_burst_seq.sv
├── docs/
│   ├── user_guide.md              # Detailed usage guide
│   ├── integration_guide.md       # Integration instructions
│   ├── supported_features.md      # Feature list & roadmap
│   ├── assertions.md              # Assertion documentation
│   ├── testplan.md                # Test coverage plan
│   ├── directory_structure.md     # File organization
│   └── dut_verification.md        # APB4 RTL-DUT milestone
├── examples/
│   ├── uvm_back2back/             # Self-contained VIP-to-VIP demo
│   └── uvm_dut/                   # APB4 master to RTL-DUT integration
└── README.md                       # Quick reference

⚙️ Configuration

Key Configuration Knobs

class apb_cfg extends uvm_object;
  
  // Protocol Selection
  apb_protocol_t protocol = APB4;  // APB3 or APB4
  
  // Address/Data Configuration
  int unsigned addr_width = 32;
  int unsigned data_width = 32;
  int unsigned nsel = 1;           // Number of PSEL signals
  
  // Master Configuration
  bit drop_psel_between = 1;       // Drop PSEL between transactions
  int unsigned sel_index = 0;      // Which PSEL to drive (0..nsel-1)
  
  // Slave Configuration - Wait States
  bit        allow_wait_states = 1;
  int unsigned min_wait_cycles = 0;  // Minimum PREADY=0 cycles
  int unsigned max_wait_cycles = 5;  // Maximum PREADY=0 cycles
  
  // Slave Configuration - Error Injection
  bit        err_enable = 0;         // Enable PSLVERR injection
  bit [31:0] err_addr_lo = 0;        // Error range start
  bit [31:0] err_addr_hi = 0;        // Error range end
  int unsigned err_pct = 10;         // Error probability %
  
  // APB4-Specific Configuration
  bit        randomize_pprot = 1;    // Random PPROT generation
  bit        randomize_pstrb = 0;    // Random PSTRB (0=full strobes)
  
  // Debug & Coverage
  bit        trace_enable = 0;       // Transaction tracing
  bit        coverage_enable = 1;    // Coverage sampling
  
  // Assertion Control
  bit        assertions_enable = 1;  // Enable SVA checks
  
  // Memory Configuration
  bit [31:0] mem_base = 32'h0000_0000;
  bit [31:0] mem_size = 32'h0001_0000;
  
endclass

Runtime Configuration via Plusargs

# Protocol mode selection
+APB_PROTOCOL=APB3       # APB3 mode
+APB_PROTOCOL=APB4       # APB4 mode (default)

# Debug options
+VIP_TRACE               # Enable transaction tracing
+UVM_VERBOSITY=UVM_HIGH  # Verbose UVM messaging

# Scoreboard options
+KVIPS_APB_SB_WARN_UNINIT  # Warn on reads from uninitialized memory

📊 Supported Features

✅ APB3 Features (Current)

• ✅ Master driver with setup/access phase sequencing
• ✅ Optional drop/continuous PSEL style
• ✅ Slave responder with word-addressed memory model
• ✅ Configurable wait-state insertion (PREADY control)
• ✅ Error injection (PSLVERR) by address range
• ✅ Monitor with transaction reconstruction
• ✅ Scoreboard with expected memory model
• ✅ Read data integrity checking

✅ APB4 Features (APB3 + Enhancements)

• ✅ PPROT signal generation and checking
  • Optional randomization
  • Protocol-aware constraints
• ✅ PSTRB byte-lane strobing
  • Byte-lane masked writes in memory model
  • Optional randomization or full strobes
• ✅ APB4-specific assertions
  • Automatically enabled in APB4 mode
  • Gated off in APB3 mode

✅ Multi-Select Support

• ✅ Vector PSEL[NSEL-1:0] interface support
• ✅ Configurable NSEL parameter
• ✅ Master selects specific sel_index

📋 Limitations & Future Enhancements

Current Limitations

• 📋 Slave memory model is simplified (not a full register model)
• 📋 No negative/bad-driver test modes yet
• 📋 Limited constrained random coverage scenarios

Planned Enhancements

• 📋 Register abstraction layer (RAL) integration
• 📋 Advanced error injection modes
• 📋 Protocol violation tests
• 📋 Formal verification property exports
• 📋 Performance monitoring
• 📋 Multi-master arbitration scenarios

🔍 APB3 vs APB4 Comparison

🔍 Debug Workflow

Recommended Bring-Up Sequence

1. Start with basic APB4 transfers:

   make questa TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB4'
   

   Verifies basic read/write operations with APB4

2. Test APB3 backward compatibility:

   make questa TEST=apb_b2b_smoke_test PLUSARGS='+APB_PROTOCOL=APB3'
   

   Ensures APB3 mode works correctly

3. Enable wait states:

   make questa TEST=apb_wait_state_test PLUSARGS='+APB_PROTOCOL=APB4'
   

   Tests slave PREADY stalling

4. Test byte strobes (APB4 only):

   make questa TEST=apb_strobe_test PLUSARGS='+APB_PROTOCOL=APB4'
   

   Verifies PSTRB byte-lane writes

5. Enable error injection:

   make questa TEST=apb_error_test PLUSARGS='+APB_PROTOCOL=APB4'
   

   Tests PSLVERR error responses

6. Random stress testing:

   make questa TEST=apb_random_stress_test PLUSARGS='+APB_PROTOCOL=APB4'
   

   Runs mixed random transactions

Debug Options

# Verbose UVM messaging
+UVM_VERBOSITY=UVM_HIGH

# Enable transaction tracing
+VIP_TRACE

# Warn on uninitialized memory reads
+KVIPS_APB_SB_WARN_UNINIT

# Waveform dumping
+KVIPS_WAVES

# Protocol mode selection
+APB_PROTOCOL=APB3  # or APB4

📚 Detailed Documentation

For comprehensive information, refer to the following source documents in apb/docs/:

• User Guide - Detailed configuration and usage
• Integration Guide - Step-by-step integration
• Supported Features - Complete feature list
• Assertions - SVA checker documentation
• Testplan - Test coverage mapping
• Directory Structure - File organization
• APB4 DUT verification - Executable DUT test matrix and evidence rules

💡 Integration Example

Minimal Testbench Integration

// 1. Instantiate APB interface
apb_if #(
    .ADDR_W(32),
    .DATA_W(32),
    .NSEL(1)
) apb_if_inst (
    .PCLK(clk),
    .PRESETn(rst_n)
);

// 2. In your UVM environment
class my_env extends uvm_env;
    apb_env apb_env_inst;
    
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        
        // Create APB configuration
        apb_cfg cfg = apb_cfg::type_id::create("cfg");
        cfg.protocol = APB4;
        cfg.allow_wait_states = 1;
        cfg.max_wait_cycles = 3;
        cfg.trace_enable = 1;
        
        // Set virtual interface
        if (!uvm_config_db#(virtual apb_if)::get(this, "", "vif", cfg.vif))
            `uvm_fatal("ENV", "Failed to get APB interface")
        
        // Create environment
        uvm_config_db#(apb_cfg)::set(this, "apb_env_inst", "cfg", cfg);
        apb_env_inst = apb_env::type_id::create("apb_env_inst", this);
    endfunction
endclass

// 3. Start sequences
class my_test extends uvm_test;
    task run_phase(uvm_phase phase);
        apb_single_seq seq;
        phase.raise_objection(this);
        
        // Write to register
        seq = apb_single_seq::type_id::create("seq");
        seq.addr = 32'h1000;
        seq.data = 32'hCAFEBABE;
        seq.is_write = 1;
        seq.strb = 4'hF;  // All bytes (APB4)
        seq.start(env.apb_env_inst.master_agent.sequencer);
        
        // Read back
        seq = apb_single_seq::type_id::create("seq");
        seq.addr = 32'h1000;
        seq.is_write = 0;
        seq.start(env.apb_env_inst.master_agent.sequencer);
        
        phase.drop_objection(this);
    endtask
endclass

🎓 Example Tests

The back-to-back tests are located in kvips/apb/examples/uvm_back2back/. The APB4 RTL-DUT tests are located in kvips/apb/examples/uvm_dut/:

examples/
├── tb/
│   ├── top.sv                  # Top-level testbench
│   └── test_pkg.sv             # Test package
├── tests/
│   ├── apb_base_test.sv
│   ├── apb_b2b_smoke_test.sv
│   ├── apb_wait_state_test.sv
│   ├── apb_error_test.sv
│   ├── apb_strobe_test.sv      # APB4 only
│   └── apb_random_stress_test.sv
└── sim/
    ├── Makefile
    ├── run_questa.sh
    ├── run_vcs.sh
    └── run_xcelium.sh

uvm_dut/
├── tb/dut/apb_ram_slave.sv       # Signal-level APB4 RAM DUT
├── tb/tests/                     # Eight DUT-focused UVM tests
└── sim/                          # Commercial and Verilator runners

🔧 Validated Tool Versions

📞 Support & Resources