Skip to content

Refactor bus wire API to use driver handles #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xross merged 3 commits into from
Jun 22, 2026
+656 −184
Merged

Refactor bus wire API to use driver handles #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9d9bb91
Refactor bus wire API to use driver handles
xross Jun 18, 2026
e30992e
Updated documentation
xross Jun 22, 2026
dc8a082
Fix bus wire name validation and duplicate checks
xross Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 54 additions & 114 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,132 +1,72 @@
:orphan:

Test Support
============
####################################
test_support: XMOS test support tools
####################################

This repo contains helpers for testing XMOS xCORE applictions and includes the following:
:vendor: XMOS
:scope: General Use
:description: Python helpers for testing XMOS xCORE applications and libraries
:category: Testing
:keywords: test, xsim, pyxsim, pytest, coverage
:devices: xcore-200, xcore.ai

- Python wrapper for the xCORE simulator (xsim)
- Python access functions for XE files
- Python code coverage measurement (xcov) for pytest
*******
Summary
*******

Basic usage: Pyxsim
-------------------
``test_support`` provides shared Python infrastructure for XMOS simulation and
testbench code. It includes helpers for running xsim from pytest, interacting
with simulated ports and pins, comparing simulator output, reading XE metadata,
and modelling resolved bus wires in Python testbenches.

Pyxsim provides Python helpers for running xsim-based tests from pytest. A
typical test builds a simulator thread, optionally attaches plugins, and calls
``Pyxsim.run_on_simulator_`` with a tester such as ``ComparisonTester``.
********
Features
********

When pytest output capture is passed via ``capfd``, Pyxsim captures simulator
and simthread output and replays it according to the pytest verbosity level:
* Python wrapper for the xCORE simulator XSI interface.
* Pytest-oriented simulator runners and output comparison helpers.
* Simulator thread support for Python-driven testbench activity.
* Resolved wire model for buses with multiple named drivers.
* Python access helpers for XE files.
* Python code coverage support for xsim traces.

* ``pytest ...`` keeps output compact and reports pass/fail details.
* ``pytest ... -v`` enables verbose tester output, including captured
``OUTPUT:`` lines from the simulator stream.
* ``pytest ... -vv`` also prints the matching ``GOLDEN:`` lines from
``ComparisonTester`` and is useful when diagnosing mismatches.
************
Known issues
************

``ComparisonTester`` supports regular-expression matching, ordered or unordered
comparison, ignored output patterns, and optional suppression of common xsim
multidrive diagnostics.
* None

Resolved bus wires
------------------
****************
Development repo
****************

``Pyxsim.bus`` contains a small resolved-wire model for Python testbenches:
* `test_support <https://www.github.com/xmos/test_support>`_ (https://www.github.com/xmos/test_support)

* ``BusWire`` models one digital bus wire with named drivers, protocol mode,
and pull-up state.
* ``DriveMode.HIGH_Z`` represents a released line driver.
* ``DriveMode.DRIVE_LOW`` and ``DriveMode.DRIVE_HIGH`` represent hard-driven
values.
* When all drivers are high-Z and pull-up is enabled, the wire resolves high.
* If any driver drives low, the resolved value is low unless another driver is
hard-driving high.
* A hard-low and hard-high combination is reported as ``hard_clash`` in the
wire snapshot.
* Hard-drive operations raise ``BusWireHardClash`` immediately if they create a
hard-low versus hard-high conflict. The exception includes the wire name,
resolved value, active low drivers, active high drivers, and the driver/mode
being applied.
**************
Required tools
**************

Example::
* Python 3.12
* XMOS XTC Tools

from Pyxsim.bus import BusMode, BusWire
*********************************
Required libraries (dependencies)
*********************************

sda = BusWire("sda", mode=BusMode.OPEN_DRAIN, pullup_enabled=True)
sda.release("controller")
sda.drive("target", 0)

snapshot = sda.snapshot()
assert snapshot.resolved == 0
assert not snapshot.hard_clash

Use ``release(driver)`` when the testbench is handing ownership of a wire to
another bus participant. Use ``drive(driver, 1)`` only when the protocol phase
really requires a hard high drive. If the wire has a modeled pull-up, released
drivers can still resolve to a high value without being recorded as hard-driving
high.

Basic usage: xcoverage
----------------------

This only suit for xsim.

It requires disassembly and elf file which dumped from binary file (.xe file) by:

* xobjdump --split [.xe].
* xobjdump -S [.xe] -o [output_file_name.dump].
* run the above 2 step by youself or run method from xcov: generate_elf_disasm("/path_to/(name-of-xe).xe", "/path_where_store_elf_and_disasm", "/path_to/(name-of-disasm).dump")

.xe must make with -g flag to enable the gdb bugger otherwise xcoverage won't work!.

It also needs a tracing file from xsim by running:

* xsim --trace-to [output_file_name.txt] [.xe].

``xcov_process``
.......................

This is the main function to be called in your test.
It returns the average coverage and save the data in .xcov file in xcov dir.
.xcov file is necessary for the below "xcov_combine" function.

xcov_process(disasm, trace, xcov_dir).

* @param disam: path to disasm file.
* @param trace: path to trace file.
* @param xcov_dir : path where xcov directory locates.
* @return average coverage of all src file.
* @output generate xcov file for xcov_combine and save in xcov dir.

``xcov_combine``
.......................

see example in examples/code_coverage

``combine_process``
.......................

see example in examples/code_coverage

``Mark the source code as not expected to be hit``
........................................................

Add a comment "//NOCOVER" or "//NOCOVERSTART" and "//NOCOVEREND" beside you source code. It wouldn't be counted in coverage.

see example in test/test_xcoverage

``Excluded File``
........................................................
Passing an excluded_file arg in xcov_process(), eg:

xcov_process(disasm, trace, xcov_dir, excluded_file=["/tests/shared/test_main.xc","/tests/shared/shared.h" ])

Software version and dependencies
.................................

The CHANGELOG contains information about the current and previous versions.
For a list of direct dependencies, look for DEPENDENT_MODULES in test_support/module_build_info.
* ``colorama``

********
Examples
********

* ``examples/pyxsim`` demonstrates a simulator thread interacting with an xCORE application.
* ``examples/code_coverage`` demonstrates xsim trace based coverage processing.

*******
Support
*******

This package is supported by XMOS Ltd. Issues can be raised against the software
at `www.xmos.com/support <https://www.xmos.com/support>`_ or using GitHub
`issues <https://github.com/xmos/test_support/issues>`_.
Loading
Loading