### Install cocotbext-axi for Development

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Clones the repository and installs the package in development mode using pip. This is suitable for making modifications to the package.

```bash
git clone https://github.com/alexforencich/cocotbext-axi.git
cd cocotbext-axi
pip install -e .
```

--------------------------------

### Install cocotbext-axi Package

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Installs the cocotbext-axi package from PyPI using pip. Requires Python 3.6+ and automatically installs cocotb and cocotb-bus dependencies.

```bash
pip install cocotbext-axi
```

--------------------------------

### Configure AxiStreamSource

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6

This example demonstrates how to create and configure an `AxiStreamSource` for sending data. It includes setting queue occupancy limits and sending a frame.

```python
# Create AXI Stream source
source = AxiStreamSource(bus, clock, reset)

# Configure queue limits
source.queue_occupancy_limit_bytes = 1024
source.queue_occupancy_limit_frames = 16

# Send data
frame = AxiStreamFrame(b"Hello World")
await source.send(frame)
```

--------------------------------

### Install Test Dependencies for cocotbext-axi

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Installs additional Python packages required for running tests, including pytest and cocotb-test.

```bash
pip install pytest cocotb-test
```

--------------------------------

### Install Icarus Verilog Simulator

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Installs the Icarus Verilog simulator on Ubuntu/Debian systems using the apt package manager. This simulator is required for running cocotb testbenches.

```bash
sudo apt install iverilog
```

--------------------------------

### AXI-Lite Master Write and Read Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Demonstrates how to create an AXI-Lite master and perform write and read operations. It uses cocotbext.axi.AxiLiteBus and cocotbext.axi.AxiLiteMaster to interact with the DUT.

```python
import cocotb
from cocotbext.axi import AxiLiteBus, AxiLiteMaster

@cocotb.test()
async def test_axil_master(dut):
    # Create AXI-Lite bus and master
    axil_bus = AxiLiteBus.from_prefix(dut, "s_axil")
    axil_master = AxiLiteMaster(axil_bus, dut.clk, dut.rst)
    
    # Perform write operation
    await axil_master.write(0x1000, b'\x01\x02\x03\x04')
    
    # Perform read operation  
    data = await axil_master.read(0x1000, 4)
    assert data.data == b'\x01\x02\x03\x04'
```

--------------------------------

### AXI-Lite RAM Model Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Illustrates the creation of an AXI-Lite RAM model for simulation. The AxiLiteRam automatically handles transactions from the DUT, simplifying testbench development.

```python
import cocotb
from cocotbext.axi import AxiLiteBus, AxiLiteRam

@cocotb.test()
async def test_axil_ram(dut):
    # Create AXI-Lite RAM model
    axil_bus = AxiLiteBus.from_prefix(dut, "m_axil")
    axil_ram = AxiLiteRam(axil_bus, dut.clk, dut.rst, size=2**16)
    
    # RAM automatically responds to transactions from DUT
    # No explicit interaction required in testbench
```

--------------------------------

### Address Space and Region Setup with Memory Pools

Source: https://deepwiki.com/alexforencich/cocotbext-axi/4

Demonstrates how to create an address space, register memory regions, and set up a pool for dynamic memory allocation. This is useful for defining memory layouts and managing dynamic memory within a simulated hardware environment.

```python
addr_space = AddressSpace(size=2**32)
addr_space.register_region(region, base=0x0000, size=4096)
addr_space.register_region(sparse_region, base=0x10000, size=2**20)

pool = addr_space.create_pool(base=0x100000, size=2**16)
allocated_region = pool.alloc_region(size=1024)
```

--------------------------------

### AXI Full Protocol Test Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Example test for the AXI Full protocol, demonstrating basic read/write operations, data lengths, and address alignments. Verifies protocol compliance.

```python
class TB(Testbench):
    async def _test_read_write(
        self,
        address,
        length,
        data
    ):
        await self.bus.write(address, data)
        read_data = await self.bus.read(address, length)
        assert read_data == data

    @cocotb.test()
    async def test_basic_rw(self):
        await self._test_read_write(0x1000, 4, b"\x01\x02\x03\x04")
        await self._test_read_write(0x1004, 8, b"\x05\x06\x07\x08\x09\x0a\x0b\x0c")
```

--------------------------------

### Configure AxiStreamSink with Backpressure

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6

This snippet shows the setup of an `AxiStreamSink` with backpressure capabilities. It includes configuring queue limits and setting a pause generator for random backpressure before receiving data.

```python
# Create AXI Stream sink with backpressure
sink = AxiStreamSink(bus, clock, reset)
sink.queue_occupancy_limit_frames = 8

# Set pause generator for random backpressure
import random
pause_gen = (random.random() < 0.1 for _ in range(1000))
sink.set_pause_generator(pause_gen)

# Receive data
frame = await sink.recv()
```

--------------------------------

### AXI-Lite Protocol Test Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Example test for the AXI-Lite protocol, focusing on simple transactions. Verifies basic read and write operations for AXI-Lite components.

```python
class TB(Testbench):
    async def _test_read_write(
        self,
        address,
        data
    ):
        await self.bus.write(address, data)
        read_data = await self.bus.read(address)
        assert read_data == data

    @cocotb.test()
    async def test_simple_transaction(self):
        await self._test_read_write(0x1000, b"\xAA")
        await self._test_read_write(0x1004, b"\xBB\xCC")
```

--------------------------------

### AXI Stream Source Send Frame Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/2-getting-started

Shows how to create an AXI Stream source and send a data frame. It utilizes cocotbext.axi.AxiStreamBus, cocotbext.axi.AxiStreamSource, and cocotbext.axi.AxiStreamFrame.

```python
import cocotb
from cocotbext.axi import AxiStreamBus, AxiStreamSource, AxiStreamFrame

@cocotb.test()
async def test_axis_source(dut):
    # Create AXI Stream bus and source
    axis_bus = AxiStreamBus.from_prefix(dut, "s_axis")
    axis_source = AxiStreamSource(axis_bus, dut.clk, dut.rst)
    
    # Send data frame
    test_data = b'\x01\x02\x03\x04\x05\x06\x07\x08'
    test_frame = AxiStreamFrame(test_data)
    await axis_source.send(test_frame)
```

--------------------------------

### AXI Stream Protocol Test Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Example test for the AXI Stream protocol, showcasing source and sink components. Verifies data transfer through the stream.

```python
class TB(Testbench):
    async def _test_stream_transfer(self, data):
        source = AxiStreamSource(self.bus.source)
        sink = AxiStreamSink(self.bus.sink)

        await source.send(data)
        received_data = await sink.recv()
        assert received_data == data

    @cocotb.test()
    async def test_stream_data(self):
        await self._test_stream_transfer(b"\x01\x02\x03\x04\x05")
```

--------------------------------

### Monitor AxiStream Transactions

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6

This example illustrates how to use `AxiStreamMonitor` for passive observation of stream transactions. It continuously receives frames using `recv_nowait` until the queue is empty.

```python
# Create monitor for passive observation
monitor = AxiStreamMonitor(bus, clock, reset)

# Collect all transactions
frames = []
while True:
    try:
        frame = monitor.recv_nowait()
        frames.append(frame)
    except QueueEmpty:
        break
```

--------------------------------

### Testbench Class Structure Example

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Illustrates the common structure of a testbench class (`TB`) used in the test suites. It includes clock and reset management, component instantiation, and stimulus control.

```python
class TB(Testbench):
    def __init__(self, dut):
        super().__init__(dut)
        self.log.info("Initializing testbench")
        # Instantiate protocol components here
        # self.master = AxiMaster(self.bus)
        # self.slave = AxiRam(self.bus)

    async def reset(self):
        self.dut.reset_n.value = 0
        await RisingEdge(self.dut.clk)
        self.dut.reset_n.value = 1
        await RisingEdge(self.dut.clk)
        self.log.info("Reset complete")

    async def run_test(self):
        # Test logic goes here
        pass
```

--------------------------------

### Run Parametrized Test with Pytest

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

This command runs a specific parametrized test case, identified by its file and parameter. For example, running `test_axi` with a data width of 8.

```bash
# Run with specific data width
pytest tests/axi/test_axi.py::test_axi[8]
```

--------------------------------

### Stress Testing with Concurrent Operations

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Example of stress testing using concurrent operations with multiple workers. This verifies system behavior under high load and concurrent access.

```python
async def worker(tb, address_range):
    for _ in range(100):
        # Perform random read/write operations within the range
        addr = random.randrange(*address_range)
        data = os.urandom(random.randint(1, 16))
        await tb.bus.write(addr, data)
        read_data = await tb.bus.read(addr, len(data))
        assert read_data == data

@cocotb.test()
async def test_stress(dut):
    tb = TB(dut)
    await tb.reset()
    tasks = [cocotb.create_task(worker(tb, (0x2000, 0x3000))) for _ in range(4)]
    await cocotb.task.gather(*tasks)
```

--------------------------------

### AXI RAM Model Initialization in Python

Source: https://deepwiki.com/alexforencich/cocotbext-axi/3

Shows how to instantiate and initialize the AxiRam model. It covers creating a RAM of a specified size and initializing it with pre-defined byte data, facilitating memory simulation.

```python
# Create AXI RAM
axi_ram = AxiRam(bus, clock, reset, size=1024*1024)  # 1MB RAM

# RAM with pre-initialized data
initial_data = bytearray(1024)
axi_ram = AxiRam(bus, clock, reset, mem=initial_data)
```

--------------------------------

### Advanced AXI Master Configuration and Write in Python

Source: https://deepwiki.com/alexforencich/cocotbext-axi/3

Illustrates advanced configuration options for the AxiMaster, including custom burst lengths and specifying detailed AXI write transaction parameters. This allows for fine-grained control over data transfers and protocol attributes.

```python
# Master with custom burst configuration
axi_master = AxiMasterWrite(
    bus.write, 
    clock, 
    reset,
    max_burst_len=64  # Custom burst length
)

# Write with specific AXI parameters
await axi_master.write(
    address=0x1000,
    data=data,
    awid=5,                    # Transaction ID
    burst=AxiBurstType.INCR,   # Burst type
    size=3,                    # Burst size (8 bytes)
    prot=AxiProt.NONSECURE,   # Protection attributes
    cache=0b0011              # Cache attributes
)
```

--------------------------------

### Basic AXI Master Usage in Python

Source: https://deepwiki.com/alexforencich/cocotbext-axi/3

Demonstrates the fundamental usage of the AxiMaster class for performing read and write operations. It initializes the master with bus, clock, and reset signals, then executes a write followed by a read transaction.

```python
# Create AXI master
axi_master = AxiMaster(bus, clock, reset)

# Write operation
write_resp = await axi_master.write(address=0x1000, data=b'\x01\x02\x03\x04')

# Read operation  
read_resp = await axi_master.read(address=0x1000, length=4)
```

--------------------------------

### Run All Tests with Pytest

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

This command executes all tests within the project using the pytest framework. It's the primary command for a full test suite run.

```bash
# Run all tests
pytest tests/
```

--------------------------------

### Create Memory Regions - Python

Source: https://deepwiki.com/alexforencich/cocotbext-axi/4

Demonstrates the creation of different types of memory regions: MemoryRegion for dense simulation, SparseMemoryRegion for large address spaces, and PeripheralRegion for simulating external devices.

```python
from cocotbext.axi.address_space import MemoryRegion, SparseMemoryRegion, PeripheralRegion

# Create a memory region with mmap backing
region = MemoryRegion(size=4096)

# Create a sparse memory region for large address spaces
sparse_region = SparseMemoryRegion(size=2**32)

# Create a peripheral region that delegates to a custom object
peripheral = PeripheralRegion(my_peripheral_obj, size=1024)
```

--------------------------------

### Run Specific Test File with Pytest

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

This command executes tests from a particular file, such as `test_axi.py`. It's a more granular approach to running tests.

```bash
pytest tests/axi/test_axi.py
```

--------------------------------

### TestFactory Integration for Parametric Testing

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Shows how to use cocotb's `TestFactory` to generate parametric tests. This allows for comprehensive testing across various configurations and conditions.

```python
from cocotb.triggers import TestFactory

# Assuming TB class and _test_read_write method are defined

factory = TestFactory(TB)
factory.add_option("address", [0x1000, 0x2000])
factory.add_option("length", [4, 8, 16])
factory.add_argument("data", arg_values=[b"\x01\x02\x03\x04", b"\x05\x06\x07\x08\x09\x0a\x0b\x0c"])

factory.generate_tests()

# This will generate tests like:
# test_read_write_address=0x1000_length=4_data=b'\x01\x02\x03\x04'
# test_read_write_address=0x1000_length=8_data=b'\x05\x06\x07\x08\x09\x0a\x0b\x0c'
# ...
```

--------------------------------

### Window Operations for Isolated Memory Access

Source: https://deepwiki.com/alexforencich/cocotbext-axi/4

Illustrates how to create windows for isolated memory access and manage dynamic windows using a window pool. This functionality is key for segmenting memory and controlling access to specific memory regions in simulations.

```python
window1 = region.create_window(offset=0, size=512)
window2 = region.create_window(offset=512, size=512)

window_pool = region.create_window_pool(offset=1024, size=2048)
allocated_window = window_pool.alloc_window(size=256)
```

--------------------------------

### Run Specific Protocol Tests with Pytest

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

These commands allow for running tests specific to certain protocols like AXI, AXIL, or AXIS. This is useful for targeted testing or debugging.

```bash
# Run specific protocol tests  
pytest tests/axi/
pytest tests/axil/
pytest tests/axis/
```

--------------------------------

### Timing Control with cycle_pause()

Source: https://deepwiki.com/alexforencich/cocotbext-axi/5-testing-and-development

Demonstrates the use of `cycle_pause()` for generating realistic bus idle and backpressure conditions. This function creates a repeating pattern for timing control.

```python
async def cycle_pause(clk, pattern):
    for cycle in pattern:
        if cycle == 1:
            await RisingEdge(clk)
        else:
            # Simulate idle or backpressure
            await Timer(10, units='ns') # Example delay

# In a test:
# await cycle_pause(self.dut.clk, [1, 1, 1, 0])
```

--------------------------------

### AXI Slave Components

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6-api-reference

Slave components respond to protocol transactions and model target devices such as memories or peripherals.

```APIDOC
## API Reference - Slave Components

### Memory Model Classes

| Class          | Purpose                       | Protocol Support              |
|----------------|-------------------------------|-------------------------------|
| `AxiRam`       | Full-featured memory model    | Full AXI with burst support   |
| `AxiLiteRam`   | Simple memory model           | AXI-Lite single transactions  |

### Stream Sink Classes

| Class             | Purpose                                 | Key Methods                           |
|-------------------|-----------------------------------------|---------------------------------------|
| `AxiStreamSink`   | Data consumption with backpressure      | `recv()`, `recv_nowait()`, `read()`   |
| `AxiStreamMonitor`| Passive data observation                | `recv()`, `recv_nowait()`, `read()`   |

Sources: cocotbext/axi/axis.py588-730, cocotbext/axi/axis.py732-841
```

--------------------------------

### AXI Master Components

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6-api-reference

Master components initiate protocol transactions and provide the primary user interface for generating traffic. All master classes inherit from `Region` to support address space management.

```APIDOC
## API Reference - Master Components

### AXI Master Classes

| Class             | Purpose                             | Key Methods                                     |
|-------------------|-------------------------------------|-------------------------------------------------|
| `AxiMaster`       | Combined read/write master          | `read()`, `write()`, `init_read()`, `init_write()` |
| `AxiMasterWrite`  | Write-only operations               | `write()`, `init_write()`                       |
| `AxiMasterRead`   | Read-only operations                | `read()`, `init_read()`                         |

### AXI-Lite Master Classes

| Class               | Purpose                             | Key Methods                                     |
|---------------------|-------------------------------------|-------------------------------------------------|
| `AxiLiteMaster`     | Combined read/write master          | `read()`, `write()`, `init_read()`, `init_write()` |
| `AxiLiteMasterWrite`| Write-only operations               | `write()`, `init_write()`                       |
| `AxiLiteMasterRead` | Read-only operations                | `read()`, `init_read()`                         |

### AXI Stream Source Classes

| Class               | Purpose             | Key Methods                           |
|---------------------|---------------------|---------------------------------------|
| `AxiStreamSource`   | Data generation     | `send()`, `send_nowait()`, `write()`  |

Sources: cocotbext/axi/axi_master.py196-636, cocotbext/axi/axi_master.py638-1036, cocotbext/axi/axi_master.py1038-1079, cocotbext/axi/axil_master.py86-344, cocotbext/axi/axil_master.py346-580, cocotbext/axi/axil_master.py582-617, cocotbext/axi/axis.py421-587
```

--------------------------------

### AXI Stream Components API

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6

This section details the classes and methods for handling AXI Stream data flow, including frame representation, bus signaling, and source/sink components with backpressure support.

```APIDOC
## AxiStreamFrame

### Description
The `AxiStreamFrame` class represents a single AXI Stream transaction, containing data and all associated sideband signals.

### Attributes
- **tdata** (bytearray or list) - Main data payload
- **tkeep** (list or None) - Byte enable signals
- **tid** (int, list, or None) - Stream ID
- **tdest** (int, list, or None) - Destination routing
- **tuser** (int, list, or None) - User-defined sideband
- **sim_time_start** (int) - Simulation time when transmission started
- **sim_time_end** (int) - Simulation time when transmission completed
- **tx_complete** (Event or callable) - Completion notification

### Key Methods
- **normalize()**: Ensures all sideband signals match `tdata` length.
- **compact()**: Removes invalid bytes based on `tkeep` and consolidates sideband signals.
- **handle_tx_complete()**: Triggers completion notification.

### Sources
cocotbext/axi/axis.py:37-232

## AxiStreamBus

### Description
The `AxiStreamBus` class provides signal mapping for AXI Stream interfaces, extending the cocotb-bus `Bus` class.

### Required Signals
- **tdata** - Data signal

### Optional Signals
- **tvalid** - Valid signal
- **tready** - Ready signal
- **tlast** - Last signal (end of frame)
- **tkeep** - Byte enable
- **tid** - Stream ID
- **tdest** - Destination
- **tuser** - User sideband

### Sources
cocotbext/axi/axis.py:234-249

## AxiStreamSource

### Description
The `AxiStreamSource` class generates AXI Stream data with support for backpressure and flow control.

### Key Methods
- **send(frame: AxiStreamFrame)**: Queue frame for transmission (blocking).
- **send_nowait(frame: AxiStreamFrame)**: Queue frame for transmission (non-blocking).
- **write(data: bytes)**: Convenience method for sending raw data.
- **write_nowait(data: bytes)**: Non-blocking version of `write()`.
- **full()**: Check if queue is at occupancy limit.
- **idle()**: Check if no active transmission.
- **wait()**: Wait until all queued frames are sent.

### Configuration Properties
- **queue_occupancy_limit_bytes** (int): Maximum bytes in queue (-1 for unlimited).
- **queue_occupancy_limit_frames** (int): Maximum frames in queue (-1 for unlimited).
- **pause** (bool): Pause transmission.

### Sources
cocotbext/axi/axis.py:421-586

## AxiStreamSink

### Description
The `AxiStreamSink` class receives AXI Stream data with backpressure support, combining monitor functionality with flow control.

### Key Methods
- **recv(compact: bool = True)**: Receive frame (blocking).
- **recv_nowait(compact: bool = True)**: Receive frame (non-blocking).
- **read(count: int = -1)**: Read raw bytes from received data.
- **read_nowait(count: int = -1)**: Non-blocking version of `read()`.
- **full()**: Check if receive queue is full.

### Configuration Properties
- **queue_occupancy_limit_bytes** (int): Maximum bytes in receive queue.
- **queue_occupancy_limit_frames** (int): Maximum frames in receive queue.
- **pause** (bool): Pause reception (deassert `tready`).

### Sources
cocotbext/axi/axis.py:732-841

## AxiStreamMonitor

### Description
The `AxiStreamMonitor` class observes AXI Stream transactions without affecting the data flow, useful for verification and debugging.

### Sources
cocotbext/axi/axis.py:843-850
```

--------------------------------

### Data Structure Classes

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6-api-reference

The API provides specialized data structures for representing protocol transactions and frames.

```APIDOC
## API Reference - Data Structure Classes

### Transaction Response Classes

Sources: cocotbext/axi/axi_master.py67-108, cocotbext/axi/axil_master.py55-84, cocotbext/axi/axis.py37-232
```

--------------------------------

### Create Custom Stream Type with define_stream

Source: https://deepwiki.com/alexforencich/cocotbext-axi/6

The `define_stream` function generates custom stream types tailored for specific protocols. It takes signal names, optional signals, and signal width specifications to create `Bus`, `Transaction`, `Source`, `Sink`, and `Monitor` classes.

```python
def define_stream(name, signals, optional_signals=None, valid_signal=None,
                 ready_signal=None, signal_widths=None):
    # ... implementation details ...
    return Bus, Transaction, Source, Sink, Monitor
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.