[ru551n]

Problem

A verification component (VC) is used by many testbenches, often with several instances in each, and lives in a folder of its own. A relative file name given to exec_file or import_module_from_file resolves against tb_path of whichever testbench is running, and only after test_runner_setup, while a VC process usually starts at time 0. A VC therefore can't find its model by a relative file name, and the user guide doesn't say what to do instead.

The class example in "Independent models of component instances" also calls import_module_from_file(join(tb_path(runner_cfg), "accumulator.py"), ...) inside a component, which has no runner_cfg.

Changes

All in docs/user_guide.rst:

• New section "Verification components with a Python model" (python_bridge:verification_components) under "Sessions", between "Independent models of component instances" and "Caveats". It describes:
  • The pattern: the model is a Python package next to the VC (my_vc/python/my_vc_model/__init__.py), imported by module name. Mutable state lives on one model object per instance. Each instance makes its own session with new_session(my_vc'instance_name) in the statement part of the process.
  • A Python Model class and a VHDL my_vc that imports and creates the model at time 0, without test_runner_setup.
  • A run.py snippet that prepends the VC's Python folder to PYTHONPATH, and pip install -e as an alternative.
  • Things to keep in mind: module and class level state is shared by all instances even with a session per instance, module names are global, errors are reported on the session's logger named after the instance path (with an example), and a model given as a file needs an absolute path.
• The class example in "Independent models of component instances" now uses the component's model_file generic, import_module_from_file(model_file, "accumulator", session), and links to the new section.

Verification

I built a test project outside the repo. It has the my_vc VC and the my_vc_model package copied from the new section, checked by a script to be identical to the docs. It also has a testbench with two instances (gain 1 and gain 10) and a run.py that sets PYTHONPATH as the docs show. I started run.py from a different folder than the testbench.

• GHDL 6.0.0 (mcode, ucrt64) on Windows 11, CPython 3.14.2, VUnit 5.0.0.dev13: passes.
  • With x1 driven 1 then 3 and x2 driven 2 then 4, y1 = 4 and y2 = 60.
  • The testbench waits 1 ns before calling test_runner_setup. At that point it checks that my_vc_model is in sys.modules and that two model objects exist. So both are imported and created at time 0.
  • The bridge library was built with MinGW-w64 gcc 13.2.0 (MSYS2), since a development checkout has no prebuilt DLLs.
• Error message: I made one instance temporarily call a misspelled method. The failure was reported on python_bridge:python:tb_vc(tb):vc2@my_vc(python), which matches the logger name in the docs. The example now shows that exact call and traceback.
• Docs: python -m sphinx -b html docs docs/_build (Sphinx 9.1.0) builds without warnings.
• Repository tests: run the way CI runs them, with the same GHDL, Python and VUnit.
  • python -m pytest tests/test_python_bridge.py: 70 passed, 15 skipped.
  • python tests/run.py -p 4: 108 of 108 passed. The output path has to be short on Windows. With a long one, 23 tb_python_pkg_bridge tests fail because GHDL can't open vunit_results, as the path goes over the 260-character limit.
  • python examples/embedded_python/run.py -p 4 --without-attributes .optional_deps --without-attributes .expected_failure: 18 of 18 passed.

Not verified:

• NVC: not installed on this machine.
• Questa, Riviera-PRO/Active-HDL: not available.
• Other GHDL backends (llvm, gcc), Linux and macOS: not run.

🤖 Generated with Claude Code

[ru551n]

Superseded by #15, which turns this pattern into an API: new_python_object/get_python_object import a class by module name and give each object a session and identity of its own. The parts that still apply moved to #15: making the model importable (package layout, PYTHONPATH in the run script, pip install -e) and the fix to the class example that used runner_cfg inside a component.