This directory contains a cocotb-based test framework for testing the LiteX CLIC (Core Local Interrupt Controller) implementation.

test/
├── test_clic_litex.py              # Main pytest test file with all test functions
├── tb_clic_litex.v                 # Testbench wrapper for cocotb
├── Makefile                        # Makefile for running CLIC tests
├── wrappers/
│   ├── generate_clic.py            # LiteX CLIC DUT generator
├── tests/
│   ├── test_clic_litex_basic.py    # Basic interrupt tests
│   ├── test_clic_litex_priority.py # Priority arbitration tests
│   ├── test_clic_litex_csr.py      # CSR access tests
│   ├── test_clic_litex_performance.py # Performance measurement tests
│   └── wb_master.py                # Existing Wishbone master (reused)

The framework tests the following CLIC functionality:

1. Basic Interrupt Handling (test_litex_clic_basic)

   • Single interrupt generation via CSR
   • Interrupt acknowledgment and claiming
   • Interrupt clearing

2. Individual Interrupts (test_litex_clic_interrupt)

   • Parameterized testing of interrupts 0-3
   • Enable/disable functionality
   • Priority configuration

3. Priority Arbitration (test_litex_clic_priority)

   • Multiple simultaneous interrupts
   • Priority-based selection
   • Higher priority preemption

4. CSR Access (test_litex_clic_csr_access)

   • Wishbone CSR register read/write
   • Configuration persistence
   • Address mapping validation

5. Interrupt Latency (test_litex_clic_performance[latency])

   • Measures time from interrupt trigger to active signal
   • Statistical analysis (mean, min, max, std dev)
   • Performance requirement: <100ns average

6. Interrupt Throughput (test_litex_clic_performance[throughput])

   • Measures interrupts processed per second
   • Continuous interrupt generation and acknowledgment
   • Reports throughput and average processing time

7. Priority Switch Time (test_litex_clic_performance[priority_switch])

   • Measures time to switch between different priority interrupts
   • Tests preemption latency
   • Performance requirement: <50ns average

8. Acknowledgment Time (test_litex_clic_performance[acknowledgment])

   • Measures time from claim signal to interrupt clear
   • Tests interrupt completion cycle
   • Performance requirement: <30ns average

# Install required packages
pip install cocotb cocotb-test pytest cocotbext-wishbone

# Generate the CLIC DUT using LiteX
make generate-litex

# Prepare files for testing (generate and copy)
make prepare-litex

make test-all

# Basic interrupt tests
make test-basic

# Individual interrupt tests (parameterized)
make test-interrupt

# Priority arbitration tests
make test-priority

# CSR access tests
make test-csr

# Run all performance tests
make test-performance-all

# Run specific performance tests
make test-performance-latency      # Interrupt latency
make test-performance-throughput   # Interrupt throughput
make test-performance-priority     # Priority switch time
make test-performance-ack         # Acknowledgment time

WAVES=1 make test-basic

python -m pytest test_clic_litex.py::test_litex_clic_basic -v
python -m pytest test_clic_litex.py::test_litex_clic_interrupt[2] -v
python -m pytest test_clic_litex.py::test_litex_clic_performance[latency] -v

The test framework uses LiteX to generate the CLIC DUT:

1. DUT Generation: wrappers/generate_clic.py creates a LiteX SoC with CLIC
2. Testbench Wrapper: tb_clic_litex.v provides cocotb-compatible interface
3. CSR Mapping: Automatically generated in csr_clic.csv
4. Build Output: Generated files stored in build_clic/gateware/

The tests interact with CLIC through Wishbone CSR registers:

• Enable registers: 0xf0c05000 + interrupt_id * 4
• Pending registers: 0xf0c05040 + interrupt_id * 4
• Priority registers: 0xf0c05080 + interrupt_id * 4

Performance tests use cocotb's get_sim_time() for nanosecond-precision timing:

start_time = get_sim_time('ns')
# Trigger interrupt
await write_csr(dut, pending_addr, 1)
# Wait for active signal
while dut.clicInterrupt.value != 1:
    await RisingEdge(dut.clk)
end_time = get_sim_time('ns')
latency = end_time - start_time

Tests can be parameterized via environment variables:

• interrupt_id: Specific interrupt to test (0-15)
• test_mode: Test mode selection (basic/single/priority/csr)
• perf_test: Performance test type (latency/throughput/priority_switch/acknowledgment/all)
• csr_base: Base address for CSR registers (default: 0xf0c05000)
• NO_WAVES: Set to 1 to disable waveform generation

Enable waveform generation for debugging:

WAVES=1 make -f Makefile_clic test-basic

View waveforms with:

• GTKWave: gtkwave tb_clic.vcd

The performance tests provide the following metrics:

• Interrupt Latency: Time from trigger to active signal
• Priority Switch Time: Time to switch between priority levels
• Acknowledgment Time: Time from claim to interrupt clear

• Interrupts per Second: Maximum sustainable interrupt rate
• Average Processing Time: Time per interrupt cycle

All measurements include statistical analysis:

• Mean, minimum, maximum values
• Standard deviation for consistency analysis
• Multiple samples for accuracy (10+ iterations)

# Clean test artifacts
make clean-test

# Clean LiteX build files
make clean-litex

# Clean everything
make clean