Add cocotb testbench for validating generated bus decoder RTL across APB3, APB4, and AXI4-Lite interfaces (#9)

* Initial plan

* Add cocotb test infrastructure and testbenches for APB3, APB4, and AXI4-Lite

Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

* Add integration tests, examples, and documentation for cocotb testbenches

Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

* Address code review feedback: use relative imports and update installation docs

Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

* Add implementation summary document

Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

* Merge cocotb dependencies into test group

Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

* Add optional cocotb simulation workflow with Icarus Verilog

Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: arnavsacheti <36746504+arnavsacheti@users.noreply.github.com>

tests/README.md

@@ -1,19 +1,27 @@
-# Unit tests
+# Tests
 
-The bus decoder exporter now ships with a small unit test suite built around
-`pytest`. The tests exercise the Python implementation directly and use the
-[`systemrdl-compiler`](https://github.com/SystemRDL/systemrdl-compiler)
+The bus decoder exporter includes comprehensive test suites to validate both the
+Python implementation and the generated SystemVerilog RTL.
+
+## Unit Tests
+
+The unit test suite is built around `pytest` and exercises the Python implementation
+directly using the [`systemrdl-compiler`](https://github.com/SystemRDL/systemrdl-compiler)
 package to elaborate inline SystemRDL snippets.
 
-## Install dependencies
+### Install dependencies
 
 Create an isolated environment if desired and install the minimal requirements:
 
 ```bash
-python -m pip install -r tests/requirements.txt
+# Using uv (recommended)
+uv sync --group test
+
+# Or using pip
+python -m pip install -e . parameterized pytest pytest-cov pytest-xdist
 ```
 
-## Running the suite
+### Running the suite
 
 Invoke `pytest` from the repository root (or the `tests` directory) and point it
 at the unit tests:
@@ -25,3 +33,55 @@ pytest tests/unit
 Pytest will automatically discover tests that follow the `test_*.py` naming
 pattern and can make use of the `compile_rdl` fixture defined in
 `tests/unit/conftest.py` to compile inline SystemRDL sources.
+
+## Cocotb Integration Tests
+
+The cocotb test suite validates the functionality of generated SystemVerilog RTL
+through simulation. These tests generate bus decoders for different CPU interfaces
+(APB3, APB4, AXI4-Lite) and verify that read/write operations work correctly.
+
+### Install dependencies
+
+```bash
+# Install with cocotb support using uv (recommended)
+uv sync --group test
+
+# Or using pip
+python -m pip install -e . parameterized pytest pytest-cov pytest-xdist cocotb cocotb-bus
+
+# Install HDL simulator (choose one)
+apt-get install iverilog  # Icarus Verilog
+apt-get install verilator # Verilator
+```
+
+### Running the tests
+
+#### Integration tests (no simulator required)
+
+These tests validate code generation without requiring an HDL simulator:
+
+```bash
+pytest tests/cocotb/testbenches/test_integration.py -v
+```
+
+#### Example code generation
+
+Run examples to see generated code for different configurations:
+
+```bash
+python tests/cocotb/examples.py
+```
+
+#### Full simulation tests (requires simulator)
+
+To run the full cocotb simulation tests:
+
+```bash
+# Run all cocotb simulation tests
+pytest tests/cocotb/testbenches/test_*_runner.py -v
+
+# Run specific interface tests
+pytest tests/cocotb/testbenches/test_apb4_runner.py -v
+```
+
+For more information about cocotb tests, see [`tests/cocotb/README.md`](cocotb/README.md).