From b692a039dd648c7b032785ab1a04ae486aa0363d Mon Sep 17 00:00:00 2001 From: Simon Birkholz Date: Fri, 11 Sep 2026 10:55:24 +0200 Subject: [PATCH 1/2] fix(cuda): make the device-buffer path work against the shipped binding CudaImageData could not hand out a device cube at all in 3.6.0.0rc1. Three defects, all in this wrapper; the native SDK and the binding are correct. - _view() called cuvis_il.cuvis_cuda_view_ptr, which no cuvis-il build exports, so to_torch() and __cuda_array_interface__ both raised AttributeError on a perfectly good device buffer. SWIG already converts the void* field to an int, so the pointer is read from the struct directly and no binding helper can go missing again. - make_ipc() called cuvis_il.cuvis_cuda_descriptor_bytes, absent the same way. The descriptor is now serialized here, to the same 184-byte layout cuvis_ipc already parses; a test pins the two copies of that layout together. - __del__ and the DLPack capsule deleter freed with cuvis_cuda_mem_free(handle), but the C API declares cuvis_cuda_mem_free(CUVIS_CUDA_MEM*), like cuvis_cuda_ipc_handle_free. Every call raised TypeError out of the binding: ignored in __del__, invisible in the deleter, so no device buffer was ever returned to the SDK's pool and a long-running consumer exhausted the card. The handle is boxed now, and the ipc free is corrected the same way. Verified against SDK 3.6.0 on an RTX 4070: to_torch() is bit-identical to the host cube, and 40 read-and-drop cycles now grow device memory by 0 MiB. make_ipc(legacy) produces a 184-byte descriptor that round-trips through cuvis_ipc's own parser with the right backend, size and geometry; the cross-process import itself is not covered, since it needs cuda-python. Why this shipped: nothing ever executed the path. test_cuda.py covers capability reporting and the enable/disable toggle, and CudaImageData appeared only in test_handle_lifecycle with a deliberately invalid argument. CI cannot close that gap, since it runs in the cuvis_pyil container on a GPU-less runner. So the new tests lead with checks that need no device: a static assertion that cube_utils references no absent cuvis_il symbol, which fails on main and names both missing functions, and the descriptor layout. The device tests skip with an actionable reason, including when the SDK is processing on the host, which since 3.6.0 is what a cuvis.init that did not ask for the GPU leaves you with. --- CHANGELOG.md | 8 ++ cuvis/cube_utils.py | 80 +++++++++++-- tests/test_cuda_image_data.py | 212 ++++++++++++++++++++++++++++++++++ 3 files changed, 293 insertions(+), 7 deletions(-) create mode 100644 tests/test_cuda_image_data.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 2368c8d..8dc13ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -113,6 +113,14 @@ Pre-releases (`b*`, `rc*`) are not listed. - `cuvis.AcquisitionContext.capture` - `to_internal=True` raised `TypeError` instead of queueing the measurement, because it passed a Python `0` where SWIG requires a null pointer. - `cuvis.Calibration`, `cuvis.AcquisitionContext`, `cuvis.ProcessingContext`, `cuvis.SessionFile`, `cuvis.Measurement`, `cuvis.Viewer`, `cuvis.Worker`, `cuvis.CubeExporter`, `cuvis.EnviExporter`, `cuvis.TiffExporter`, `cuvis.ViewExporter` - `__del__` raised `TypeError` after a failed construction, because it freed a handle that was still `None`. - `cuvis.Worker.get_next_result_async` - a timeout returned a `cuvis.Worker.WorkerResult` built from handles the SDK never filled in; it now raises `cuvis.cuvis_aux.SDKException`. +- `cuvis.CudaImageData.to_torch`, `cuvis.CudaImageData.__cuda_array_interface__` - raised `AttributeError` on every call, because `_view` used `cuvis_il.cuvis_cuda_view_ptr`, which no `cuvis-il` build exports. + The device pointer is now read from the `cuvis_cuda_mem_view_t` field directly, so no binding helper is involved and none can go missing. +- `cuvis.CudaImageData.make_ipc`, `cuvis.CudaImageData.export_payload` - raised `AttributeError`, because they used `cuvis_il.cuvis_cuda_descriptor_bytes`, which no `cuvis-il` build exports. + The descriptor is now serialized in Python to the same 184-byte layout `cuvis_ipc` parses. +- `cuvis.CudaImageData.__del__`, `cuvis.CudaImageData.to_torch` - device buffers were never released: both freed through `cuvis_cuda_mem_free(handle)`, but the C API declares `cuvis_cuda_mem_free(CUVIS_CUDA_MEM*)`, so every call raised `TypeError` out of the binding. + In `__del__` that surfaced only as an ignored exception, and in the DLPack capsule deleter not at all, so a long-running consumer exhausted the card. The handle is now boxed, and `cuvis_cuda_ipc_handle_free` is corrected the same way. +- `tests/test_cuda_image_data.py` - behavior tests for the device-buffer path, which nothing previously executed: a static check that `cube_utils` references no absent `cuvis_il` symbol, the descriptor's wire layout and its agreement with `cuvis_ipc`, the free calling convention, and, on a machine with a CUDA device, that the zero-copy tensor equals the host cube and that repeated read-and-drop cycles return their memory. + The static and layout checks need no device, which matters because CI has none and therefore never ran this code. ## [3.5.3.2] - 2026-08-19 diff --git a/cuvis/cube_utils.py b/cuvis/cube_utils.py index 0203195..ccbdcc8 100644 --- a/cuvis/cube_utils.py +++ b/cuvis/cube_utils.py @@ -3,6 +3,7 @@ from ._cuvis_il import cuvis_il import numpy as np import operator +import struct from .cuvis_aux import SDKException from .cuvis_types import DataFormat from . import cuda @@ -422,6 +423,57 @@ def apply(self, other): del _op, _reflected, _method +# Wire format of cuvis_cuda_ipc_descriptor_t, mirroring the offsets cuvis_ipc parses. Kept +# here rather than imported from cuvis_ipc, which is the consumer half and lives outside this +# package precisely so a consumer process need not be able to import cuvis. +_IPC_HEAD = struct.Struct( + " bytes: + """Serialise a cuvis_cuda_ipc_descriptor_t to its transportable form. + + Done field by field rather than as one memcpy of the struct: SWIG exposes the scalars + directly and the two blobs only as `unsigned char *`, so there is no way to hand the whole + struct out as bytes from Python. The layout is fixed by the C header and asserted below. + """ + + def blob(pointer, length): + """`length` bytes out of an unsigned char array, padded to the fixed field width.""" + if length > _IPC_BLOB_MAX: + raise ValueError("blob length {} exceeds {}".format(length, _IPC_BLOB_MAX)) + taken = bytes( + cuvis_il.p_unsigned_char_getitem(pointer, i) for i in range(length) + ) + return taken.ljust(_IPC_BLOB_MAX, bytes(1)) + + out = bytearray(_IPC_DESC_LEN) + _IPC_HEAD.pack_into( + out, + 0, + int(desc.backend), + int(desc.device_ordinal), + int(desc.handle_type), + int(desc.blob_len), + int(desc.size), + int(desc.alloc_size), + int(desc.offset), + int(desc.exporter_pid), + ) + out[_IPC_BLOB_OFF : _IPC_BLOB_OFF + _IPC_BLOB_MAX] = blob(desc.blob, desc.blob_len) + struct.pack_into(" bytes: @@ -576,7 +640,9 @@ def __del__(self): # Not wrapped in try/except: a device buffer that fails to free is a VRAM leak, # and swallowing it here would hide the leak as well as the reason for it. if self._ipc_handle is not None: - cuvis_il.cuvis_cuda_ipc_handle_free(self._ipc_handle) + box = cuvis_il.new_p_int() + cuvis_il.p_int_assign(box, int(self._ipc_handle)) + cuvis_il.cuvis_cuda_ipc_handle_free(box) self._ipc_handle = None - cuvis_il.cuvis_cuda_mem_free(self._handle) + self._free(self._handle) self._handle = None diff --git a/tests/test_cuda_image_data.py b/tests/test_cuda_image_data.py new file mode 100644 index 0000000..fd09e42 --- /dev/null +++ b/tests/test_cuda_image_data.py @@ -0,0 +1,212 @@ +"""Tests for the CudaImageData device-buffer path. + +The device tests need two things: a CUDA device the SDK accepts, and an SDK actually +processing on it. Since 3.6.0 the latter is not the default -- a process whose `cuvis.init` +did not ask for it processes on the host, and then no cube is backed by device memory -- so +point CUVIS_SETTINGS at a directory whose `cuvis.settings` carries +`force_gpu_mode="cuda"` before running these:: + + python -c "import cuvis; cuvis.SdkSettings(force_gpu_mode='cuda').save('/tmp/cuvis-gpu')" + CUVIS_SETTINGS=/tmp/cuvis-gpu python -m pytest tests/test_cuda_image_data.py + +They skip otherwise, which CI always is: it runs in the cuvis_pyil container on a GPU-less +runner. That is precisely how a release went out calling two cuvis_il functions that do not +exist, so the tests that matter most here are the ones needing no device at all. +""" + +import ast +import struct +from pathlib import Path + +import pytest + +import cuvis +from cuvis import cuda +from cuvis._cuvis_il import cuvis_il +from cuvis.cube_utils import _descriptor_bytes + +_HAS_DEVICE = cuda.capabilities().same_process +requires_device = pytest.mark.skipif( + not _HAS_DEVICE, reason="needs a CUDA device the SDK accepts" +) + + +def _binding_names(module_path): + """Every `cuvis_il.` this module reaches for, found without importing it.""" + tree = ast.parse(Path(module_path).read_text(encoding="utf-8")) + return { + node.attr + for node in ast.walk(tree) + if isinstance(node, ast.Attribute) + and isinstance(node.value, ast.Name) + and node.value.id == "cuvis_il" + } + + +def test_every_binding_symbol_the_cuda_path_uses_exists(): + """Test cube_utils calls no cuvis_il function the installed binding lacks. + + Nothing on a GPU-less runner ever executes the device path, so a missing symbol there + surfaces only as an AttributeError in a user's process. This catches it at any commit. + """ + used = _binding_names(cuvis.cube_utils.__file__) + missing = sorted(name for name in used if not hasattr(cuvis_il, name)) + assert not missing, f"cube_utils references absent cuvis_il symbols: {missing}" + + +def test_free_passes_the_handle_the_way_the_c_api_takes_it(): + """Test cuvis_cuda_mem_free is called with CUVIS_CUDA_MEM*, not the handle by value. + + The C API declares `cuvis_cuda_mem_free(CUVIS_CUDA_MEM* i_mem)`, like + `cuvis_cuda_ipc_handle_free`. Passing the int raises TypeError out of the binding, and the + buffer is then never returned to the SDK's pool. + """ + with pytest.raises(TypeError): + cuvis_il.cuvis_cuda_mem_free(0) # the shape that silently leaked + + box = cuvis_il.new_p_int() + cuvis_il.p_int_assign(box, 0) + cuvis_il.cuvis_cuda_mem_free(box) # freeing a null handle is a no-op, not an error + + +# --- the IPC descriptor, which needs no device to serialise ------------------------------- +def test_descriptor_serialises_to_the_locked_wire_layout(): + """Test _descriptor_bytes emits the 184-byte layout cuvis_ipc parses, blobs included.""" + desc = cuvis_il.cuvis_cuda_ipc_descriptor_t() + desc.backend = 2 + desc.device_ordinal = 1 + desc.handle_type = 3 + desc.blob_len = 4 + desc.size = 65880000 + desc.alloc_size = 67108864 + desc.offset = 128 + desc.exporter_pid = 4321 + desc.ptr_blob_len = 2 + for index, value in enumerate((0xDE, 0xAD, 0xBE, 0xEF)): + cuvis_il.p_unsigned_char_setitem(desc.blob, index, value) + for index, value in enumerate((0x01, 0x02)): + cuvis_il.p_unsigned_char_setitem(desc.ptr_blob, index, value) + + raw = _descriptor_bytes(desc) + + assert len(raw) == 184 + head = struct.unpack_from(" 0 + assert size == host.nbytes + assert ordinal >= 0 + + +@requires_device +def test_to_torch_is_the_same_cube_on_the_device(device_cube): + """Test the zero-copy tensor holds exactly what the host path would have produced.""" + torch = pytest.importorskip("torch") + cimg, host = device_cube + tensor = cimg.to_torch() + assert tensor.is_cuda + assert tuple(tensor.shape) == host.shape + assert torch.equal(tensor.cpu(), torch.from_numpy(host)) + + +@requires_device +def test_cuda_array_interface_reports_the_buffer(device_cube): + """Test the fallback interop path answers instead of raising from the binding.""" + cimg, host = device_cube + with pytest.warns(UserWarning, match="lifecycle"): + interface = cimg.__cuda_array_interface__ + assert interface["shape"] == host.shape + assert interface["data"][0] > 0 + + +@requires_device +def test_device_buffers_are_returned_to_the_sdk(test_session_file, raw_context): + """Test repeated read-and-drop cycles do not accumulate device memory. + + A free that raises leaves every cube's buffer outstanding, which is invisible until a + long run exhausts the card. The SDK pools the buffers, so this asserts a plateau rather + than a return to the starting value. + """ + torch = pytest.importorskip("torch") + cuda.enable() + try: + _device_cube(raw_context, test_session_file).to_torch() + torch.cuda.synchronize() + settled = torch.cuda.mem_get_info()[0] + for _ in range(20): + held = _device_cube(raw_context, test_session_file).to_torch() + del held + torch.cuda.synchronize() + free_now = torch.cuda.mem_get_info()[0] + finally: + cuda.disable() + lost_mib = (settled - free_now) / 2**20 + assert lost_mib < 256, ( + f"{lost_mib:.0f} MiB of device memory not returned over 20 cycles" + ) From 9ea1b2c8a70145814d91fe558b0c0c9549597666 Mon Sep 17 00:00:00 2001 From: Simon Birkholz Date: Fri, 11 Sep 2026 10:58:44 +0200 Subject: [PATCH 2/2] test(cuda): skip the free-convention test where the library exports no CUDA CI runs against a CPU-only libcuvis.so that exports none of the cuvis_cuda_* functions, so calling one raises RuntimeError from the binding's own guard rather than the TypeError the test is about. Gated on binding.available, the same way test_cuda.py gates its device-function tests. The static symbol test is deliberately not gated and passed on that runner: SWIG defines the Python attribute either way, so it still catches a wrapper calling a function the binding never declared. --- tests/test_cuda_image_data.py | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/tests/test_cuda_image_data.py b/tests/test_cuda_image_data.py index fd09e42..efc4947 100644 --- a/tests/test_cuda_image_data.py +++ b/tests/test_cuda_image_data.py @@ -21,13 +21,19 @@ import pytest import cuvis -from cuvis import cuda +from cuvis import binding, cuda from cuvis._cuvis_il import cuvis_il from cuvis.cube_utils import _descriptor_bytes -_HAS_DEVICE = cuda.capabilities().same_process +# Two different denials: the loaded library may not export the CUDA functions at all (the +# CPU-only build CI runs against), and the device may not support them. The first makes even +# calling into the binding raise, so it gates separately from the device tests below. +_HAS_CUDA_EXPORTS = binding.available("cuvis_cuda_mem_free") +requires_cuda_exports = pytest.mark.skipif( + not _HAS_CUDA_EXPORTS, reason="loaded cuvis library exports no CUDA functions" +) requires_device = pytest.mark.skipif( - not _HAS_DEVICE, reason="needs a CUDA device the SDK accepts" + not cuda.capabilities().same_process, reason="needs a CUDA device the SDK accepts" ) @@ -54,6 +60,7 @@ def test_every_binding_symbol_the_cuda_path_uses_exists(): assert not missing, f"cube_utils references absent cuvis_il symbols: {missing}" +@requires_cuda_exports def test_free_passes_the_handle_the_way_the_c_api_takes_it(): """Test cuvis_cuda_mem_free is called with CUVIS_CUDA_MEM*, not the handle by value.