VHDL to Python interface: python_pkg on a native bridge for NVC, GHDL and Questa

.github/workflows/push.yml

@@ -165,6 +165,14 @@ jobs:
     - name: '🚧 Run job'
       run: tox -e py${{ matrix.task }} -- --color=yes
 
+#
+# Prebuilt Windows DLLs of the VHDL Python bridge, included in releases
+#
+
+  python-bridge-dlls:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    uses: ./.github/workflows/python_bridge_dlls.yml
+
 #
 # Deploy to PyPI
 #
@@ -177,6 +185,7 @@ jobs:
       - ghdl
       - nvc
       - win
+      - python-bridge-dlls
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     name: '🚀 Deploy'
     steps:
@@ -186,6 +195,12 @@ jobs:
       with:
         submodules: recursive
 
+    - name: '📥 Download Python bridge DLLs'
+      uses: actions/download-artifact@v4
+      with:
+        name: python-bridge-dlls
+        path: vunit/python_bridge/bin
+
     - name: '🐍 Setup Python'
       uses: actions/setup-python@v6
       with:

.github/workflows/python_bridge.yml

@@ -0,0 +1,235 @@
+name: 'python bridge'
+
+# Tests of the VHDL Python integration, add_python(), in the environments
+# push.yml does not provide: CPython from python.org, on Linux
+# (bridge compiled on first use) and Windows (prebuilt MSVC DLLs), and the
+# content of the package.
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+
+#
+# Linux and macOS, bridge compiled on first use
+#
+
+  posix:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # The oldest and newest supported CPython; every GHDL backend, since
+        # the bridge library is loaded differently by the ones that link ahead
+        # of time (llvm, gcc), on the latest release; the NVC release VUnit is
+        # developed against.
+        #
+        # Canaries (allowed to fail): the GHDL nightly builds and NVC built
+        # from its master branch, with Python 3.14, where simulator changes
+        # show up first.
+        include:
+          - { os: ubuntu-24.04, py: '3.10', sim: nvc, nvc: '1.22.1' }
+          - { os: ubuntu-24.04, py: '3.14', sim: nvc, nvc: '1.22.1' }
+          - { os: ubuntu-24.04, py: '3.14', sim: nvc, nvc: master, canary: true }
+          - { os: ubuntu-24.04, py: '3.10', sim: ghdl, backend: mcode, ghdl: latest }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: mcode, ghdl: nightly, canary: true }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: llvm-jit, ghdl: latest }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: llvm-jit, ghdl: nightly, canary: true }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: llvm, ghdl: latest }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: llvm, ghdl: nightly, canary: true }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: gcc, ghdl: latest }
+          - { os: ubuntu-24.04, py: '3.14', sim: ghdl, backend: gcc, ghdl: nightly, canary: true }
+          - { os: macos-15, py: '3.14', sim: nvc, nvc: brew }
+          # macos-15: setup-ghdl has no build for newer macOS versions yet, and only the llvm backend
+          - { os: macos-15, py: '3.14', sim: ghdl, backend: llvm, ghdl: latest }
+    name: '${{ matrix.os }} · Python ${{ matrix.py }} · ${{ matrix.sim }} ${{ matrix.backend }}${{ matrix.ghdl }}${{ matrix.nvc }}'
+    continue-on-error: ${{ matrix.canary || false }}
+    env:
+      VUNIT_SIMULATOR: ${{ matrix.sim }}
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: '🐍 Setup Python'
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.py }}
+
+    - name: '⚙️ Setup NVC'
+      if: matrix.sim == 'nvc' && matrix.nvc != 'brew' && matrix.nvc != 'master'
+      run: |
+        curl -fsSL -o nvc.deb "https://github.com/nickg/nvc/releases/download/r${{ matrix.nvc }}/nvc_${{ matrix.nvc }}-1_amd64_ubuntu-24.04.deb"
+        sudo apt-get install -y ./nvc.deb
+
+    # As in NVC's README
+    - name: '⚙️ Build NVC from its master branch'
+      if: matrix.nvc == 'master'
+      run: |
+        sudo apt-get install -y -qq build-essential automake autoconf flex check llvm-dev pkg-config zlib1g-dev libdw-dev libffi-dev libzstd-dev
+        git clone --depth 1 https://github.com/nickg/nvc.git "$RUNNER_TEMP/nvc"
+        cd "$RUNNER_TEMP/nvc" && ./autogen.sh && mkdir build && cd build && ../configure && make -j"$(nproc)" && sudo make install
+        nvc --version
+
+    - name: '⚙️ Setup NVC with Homebrew'
+      if: matrix.nvc == 'brew'
+      run: brew install nvc
+
+    - name: '⚙️ Setup GHDL'
+      if: matrix.sim == 'ghdl'
+      uses: ghdl/setup-ghdl@main
+      with:
+        version: ${{ matrix.ghdl }}
+        backend: ${{ matrix.backend }}
+
+    # The environment and the output go to the runner's temporary directory,
+    # outside the checkout, so nothing built can end up in the tree. The space
+    # in the path is deliberate: the bridge builds command lines and simulator
+    # options from these paths.
+    - name: '🐍 Install VUnit in a virtual environment'
+      run: |
+        python -m venv "$RUNNER_TEMP/venv with space"
+        echo "$RUNNER_TEMP/venv with space/bin" >> "$GITHUB_PATH"
+        "$RUNNER_TEMP/venv with space/bin/pip" install -e . --progress-bar off
+
+    - name: '🚧 Feature tests'
+      run: python vunit/vhdl/python/run.py -p 4 -o "$RUNNER_TEMP/out dir"
+
+    - name: '🚧 Example'
+      run: python examples/vhdl/embedded_python/run.py -p 4 --without-attributes .optional_deps --without-attributes .expected_failure
+
+#
+# Windows, prebuilt MSVC DLLs
+#
+
+  dlls:
+    uses: ./.github/workflows/python_bridge_dlls.yml
+
+  windows:
+    needs: dlls
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        py: ['3.10', '3.12', '3.14']
+        sim: [nvc, ghdl]
+        bridge: [dll]
+        # No prebuilt DLLs: the library is built with the MinGW gcc of the runner image, the
+        # build Questa/ModelSim always uses on Windows, which has no runner
+        include:
+          - {py: '3.13', sim: nvc, bridge: gcc}
+    name: '🟦 Windows · Python ${{ matrix.py }} · ${{ matrix.sim }} · ${{ matrix.bridge }}'
+    env:
+      VUNIT_SIMULATOR: ${{ matrix.sim }}
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: '📥 Download bridge DLLs'
+      if: matrix.bridge == 'dll'
+      uses: actions/download-artifact@v4
+      with:
+        name: python-bridge-dlls
+        path: vunit/python_bridge/bin
+
+    - name: '⚙️ Put MinGW gcc on PATH'
+      if: matrix.bridge == 'gcc'
+      run: echo "C:/mingw64/bin" >> "$GITHUB_PATH"
+
+    - name: '🐍 Setup Python'
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.py }}
+        architecture: x64
+
+    - name: '⚙️ Setup NVC'
+      if: matrix.sim == 'nvc'
+      shell: pwsh
+      run: |
+        Invoke-WebRequest -Uri https://github.com/nickg/nvc/releases/download/r1.22.1/nvc-1.22.1.msi -OutFile nvc.msi
+        Start-Process msiexec.exe -Wait -ArgumentList '/i', 'nvc.msi', '/qn', '/norestart'
+        $bin = Get-ChildItem -Path 'C:\Program Files*' -Recurse -Filter nvc.exe -ErrorAction SilentlyContinue | Select-Object -First 1
+        $bin.DirectoryName | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+    - name: '⚙️ Setup GHDL'
+      if: matrix.sim == 'ghdl'
+      uses: ghdl/setup-ghdl@main
+      with:
+        backend: mcode
+
+    # Same as on Linux: outside the checkout, with a space in the path
+    - name: '🐍 Install VUnit in a virtual environment'
+      run: |
+        python -m venv "$RUNNER_TEMP/venv with space"
+        echo "$RUNNER_TEMP/venv with space/Scripts" >> "$GITHUB_PATH"
+        "$RUNNER_TEMP/venv with space/Scripts/pip" install -e . --progress-bar off
+
+    # The simulator is accepted as x64, and a 32-bit executable of Windows itself is detected
+    - name: '🔍 64-bit check'
+      run: |
+        python -c "import shutil; from vunit.python_bridge.native_library import pe_machine; \
+          assert pe_machine(shutil.which('${{ matrix.sim }}')) == 0x8664; \
+          assert pe_machine(r'C:\Windows\SysWOW64\cmd.exe') == 0x14C"
+
+    # dll: no MSVC on PATH, the prebuilt DLLs must be used. gcc: the library must be built with gcc.
+    - name: '🚧 Feature tests'
+      run: |
+        ! command -v cl
+        if [ '${{ matrix.bridge }}' = gcc ]; then command -v gcc; fi
+        python vunit/vhdl/python/run.py -p 4 -o "$RUNNER_TEMP/out dir"
+        if [ '${{ matrix.bridge }}' = gcc ]; then
+          find "$RUNNER_TEMP/out dir" -path '*-win_amd64-gcc-*' -name vunit_python_bridge.dll | grep .
+        fi
+
+    - name: '🚧 Example'
+      run: python examples/vhdl/embedded_python/run.py -p 4 --without-attributes .optional_deps --without-attributes .expected_failure
+
+#
+# Packaging, sources and DLLs included, no Linux binaries
+#
+
+  packaging:
+    needs: dlls
+    runs-on: ubuntu-latest
+    name: '📦 Packaging'
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: '📥 Download bridge DLLs'
+      uses: actions/download-artifact@v4
+      with:
+        name: python-bridge-dlls
+        path: vunit/python_bridge/bin
+
+    - name: '🐍 Setup Python'
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.13'
+
+    - name: '📦 Build sdist'
+      run: |
+        pip install -U setuptools wheel --progress-bar off
+        python setup.py sdist
+
+    # The C sources, the five DLLs, no Linux binary
+    - name: '🔍 Check sdist content'
+      run: |
+        tar tzf dist/*.tar.gz > content.txt
+        grep -q 'vunit/python_bridge/native/bridge.h$' content.txt
+        test "$(grep -c 'vunit/python_bridge/bin/vunit_python_bridge-cp3[0-9]*-win_amd64.dll$' content.txt)" = 5
+        ! grep -q '\.so$' content.txt

.github/workflows/python_bridge_dlls.yml

@@ -0,0 +1,63 @@
+name: 'python bridge dlls'
+
+# Builds the prebuilt Windows DLLs of the VHDL Python bridge with MSVC, one per
+# CPython version. Called by python_bridge.yml and by push.yml for releases.
+
+on:
+  workflow_call:
+
+jobs:
+
+  build:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        py: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    name: '🟦 MSVC · bridge DLL · Python ${{ matrix.py }}'
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v4
+
+    - name: '🐍 Setup Python'
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.py }}
+        architecture: x64
+
+    - name: '⚙️ Setup MSVC'
+      uses: ilammy/msvc-dev-cmd@v1
+      with:
+        arch: x64
+
+    - name: '🔨 Build DLL'
+      run: python tools/build_python_bridge.py --output-dir dlls
+
+    - name: '📤 Upload DLL'
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-bridge-dll-${{ matrix.py }}
+        path: dlls/*.dll
+        if-no-files-found: error
+
+  collect:
+    needs: build
+    runs-on: ubuntu-latest
+    name: '📦 Collect bridge DLLs'
+    steps:
+
+    - name: '📥 Download DLLs'
+      uses: actions/download-artifact@v4
+      with:
+        pattern: python-bridge-dll-*
+        merge-multiple: true
+        path: dlls
+
+    - name: '🔍 Check DLLs'
+      run: test "$(ls dlls/*.dll | wc -l)" = 5
+
+    - name: '📤 Upload DLLs'
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-bridge-dlls
+        path: dlls/*.dll

docs/hdl_libraries.rst

@@ -24,6 +24,11 @@ VUnit includes several optional libraries in a group named *VHDL builtins* (see
 Most of the utilities are based on some internal data types providing dynamic arrays and queues (FIFOs).
 See :ref:`data_types_library`.
 
+With :meth:`add_python() <vunit.ui.VUnit.add_python>`, testbenches can also execute Python code and call Python
+functions through :vunit_file:`python <vunit/vhdl/python>` (``context vunit_lib.python_context;``). NVC, GHDL and
+Questa/ModelSim are served by the VUnit Python bridge, Riviera-PRO/Active-HDL by a VHPI application.
+See :ref:`python_bridge`.
+
 Communication
 -------------
 

docs/index.rst

@@ -40,6 +40,7 @@ often"* approach through automation. :ref:`Read more <about>`
    com/user_guide
    verification_components/user_guide
    data_types/user_guide
+   python_bridge/user_guide
 
 .. toctree::
    :caption: Reference

docs/news.d/1220.feature.rst

@@ -0,0 +1,9 @@
+VHDL testbenches can now execute Python code and call Python functions
+directly from the simulator: NumPy reference models, checkers, file access and
+anything else the Python ecosystem offers. The VHDL API is ``python_pkg`` and
+it is enabled with ``add_python()`` after ``add_vhdl_builtins()``. Values of
+all the common VHDL types cross the boundary in both directions, as arguments
+and as results. The API is available on NVC, GHDL and Questa/ModelSim through
+the VUnit Python bridge, and on Riviera-PRO/Active-HDL through a VHPI
+application, both of which ``add_python()`` builds under the output path. See
+:ref:`python_bridge`.

docs/news.d/1221.feature.1.rst

@@ -0,0 +1,3 @@
+Added accessor functions to ``check_pkg`` for inspecting a ``check_result_t``:
+``is_pass``, ``get_checker``, ``get_msg``, ``get_log_level``, ``get_line_num`` and
+``get_file_name``.

docs/news.d/1221.feature.2.rst

@@ -0,0 +1,2 @@
+Added ``run_script_path(runner_cfg)`` to ``run_pkg``, returning the path of the
+VUnit run script that started the simulation.