From 4a13f03f7167f2ffe048f7f9bc7a1b8d8d4556c0 Mon Sep 17 00:00:00 2001 From: Gareth Morgan Date: Wed, 18 Nov 2026 17:01:36 -0500 Subject: [PATCH 1/4] camera_streamer: expose slot write generations for copy validation camera_receiver rewrites a CUDA IPC slot ring_depth pictures after announcing it and never waits for a reader, and the replacement notice only arrives after the new write, so a reader could not tell that its copy overlapped a rewrite. The receiver now advances a shared per-slot write-generation marker for every eye before any GPU work touches the slot, waits for each worker's own CUDA stream, and announces that generation only once the write is complete. A failed attempt publishes nothing and keeps its generation. A reader copies into memory it owns, waits for its GPU reads to finish, and keeps the copy only if the marker still equals the notified generation. The example consumer does this and refuses a publisher that does not offer the feature. The marker is a small header-only native helper with a Python binding, shared by Python and C++ readers, in a new ipc_protocol component. Readers that ignore the marker are unchanged and outside the guarantee. Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Gareth Morgan --- .../camera_streamer/camera_receiver/README.md | 24 +- .../camera_receiver/camera_receiver.py | 57 +- .../camera_receiver/cuda_ipc.py | 63 +- .../camera_streamer/camera_receiver/setup.sh | 9 +- .../tests/test_sample_completion.py | 298 ++++++- .../tests/test_slot_marker_publisher.py | 231 ++++++ .../cuda_ipc_consumer/README.md | 9 +- .../cuda_ipc_consumer/consumer.py | 77 +- .../cuda_ipc_consumer/requirements.txt | 2 + .../cuda_ipc_consumer/setup.sh | 11 +- .../cuda_ipc_consumer/tests/conftest.py | 9 + .../tests/test_slot_validation.py | 155 ++++ .../camera_streamer/ipc_protocol/.gitignore | 3 + .../ipc_protocol/CMakeLists.txt | 33 + .../camera_streamer/ipc_protocol/README.md | 81 ++ .../camera_streamer/ipc_protocol/__init__.py | 27 + .../camera_streamer/ipc_protocol/build.sh | 37 + .../inc/ipc_protocol/slot_markers.hpp | 321 ++++++++ .../ipc_protocol/slot_markers_bindings.cpp | 37 + .../ipc_protocol/tests/conftest.py | 8 + .../tests/test_gpu_slot_integrity.py | 730 ++++++++++++++++++ .../ipc_protocol/tests/test_slot_markers.py | 270 +++++++ 22 files changed, 2438 insertions(+), 54 deletions(-) create mode 100644 examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py create mode 100644 examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py create mode 100644 examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py create mode 100644 examples/camera_streamer/ipc_protocol/.gitignore create mode 100644 examples/camera_streamer/ipc_protocol/CMakeLists.txt create mode 100644 examples/camera_streamer/ipc_protocol/README.md create mode 100644 examples/camera_streamer/ipc_protocol/__init__.py create mode 100755 examples/camera_streamer/ipc_protocol/build.sh create mode 100644 examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp create mode 100644 examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp create mode 100644 examples/camera_streamer/ipc_protocol/tests/conftest.py create mode 100644 examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py create mode 100644 examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py diff --git a/examples/camera_streamer/camera_receiver/README.md b/examples/camera_streamer/camera_receiver/README.md index 2d47f3bdac..174848ece7 100644 --- a/examples/camera_streamer/camera_receiver/README.md +++ b/examples/camera_streamer/camera_receiver/README.md @@ -38,10 +38,12 @@ The setup script creates: ```text .venv/ codec/_camera_receiver_codec*.so +../ipc_protocol/_slot_markers*.so ``` -It installs the Python dependencies from `requirements.txt` and builds the -local native decoder from `codec/`. +It installs the Python dependencies from `requirements.txt`, builds the local +native decoder from `codec/` and builds the shared slot marker module from +[`ipc_protocol/`](../ipc_protocol/README.md). ## Run @@ -114,9 +116,15 @@ rotation during that existing output write. HEVC NV12 rotation replaces the normal NVDEC-to-ring device copy with a rotation kernel; RGBA rotation is fused into color conversion, so neither path adds a second full-frame pass. -`ring_depth` controls how many slots each physical IPC stream owns. Frame -notifications include `slot_generation`; consumers can detect if a slot was -overwritten before they consumed it. +`ring_depth` controls how many slots each physical IPC stream owns. The receiver +cycles through them without waiting for consumers, so a slot is rewritten +`ring_depth` pictures after it was announced. It advances the slot's shared +write-generation marker before it touches the pixels and announces that +generation in the frame notice's `slot_generation` once the write is complete. A +consumer copies the pixels, waits for its copy to finish, and accepts the copy +only if the marker still equals the notified generation. Generations skip a value +when a write attempt fails, so a gap is not a lost picture; use the frame +sequence for that. See [`ipc_protocol/`](../ipc_protocol/README.md). ## Downstream consumers @@ -130,8 +138,10 @@ already remapped by the sender, so consumers must not apply the wrist remap agai See the bundled [remap geometry and calibration](../argus_sender/remaps/README.md). Notifications include frame sequence, slot generation, source timing and local -publish timing. Validate frame identity and generation when associating frames -with metadata. The rings are bounded live buffers, not a durable recording queue. +publish timing. A consumer that reads the pixels must validate its copy against +the slot's marker, as described above; one that ignores the marker can receive a +picture that mixes two frames. The rings are bounded live buffers, not a durable +recording queue. ## Latency diff --git a/examples/camera_streamer/camera_receiver/camera_receiver.py b/examples/camera_streamer/camera_receiver/camera_receiver.py index 05b214b818..b0157f1cba 100755 --- a/examples/camera_streamer/camera_receiver/camera_receiver.py +++ b/examples/camera_streamer/camera_receiver/camera_receiver.py @@ -391,9 +391,6 @@ def __init__(self, config: StreamConfig, gpu_id: int) -> None: self.gpu_id = int(gpu_id) self.camera_count = 2 if config.stereo else 1 self.write_index = 0 - self.slot_generations = [ - [0 for _ in range(config.ring_depth)] for _ in range(self.camera_count) - ] self.decoders: list[Optional[NvVideoDecoder]] = [None] * self.camera_count self.executor = ThreadPoolExecutor( max_workers=1, @@ -456,10 +453,6 @@ def shutdown(self) -> None: self.executor.shutdown(wait=True) self.reset_decoders() - def next_generation(self, camera_index: int, slot: int) -> int: - self.slot_generations[camera_index][slot] += 1 - return self.slot_generations[camera_index][slot] - class Avs1TcpReceiver: def __init__( @@ -764,27 +757,40 @@ def _process_stream( self._validate_stream_descriptor(stream, runtime.config) slot = runtime.write_index + # Advance every eye's marker before any GPU work can touch the slot, so a reader's + # final check sees every write that may have overlapped its copy. A failed attempt + # keeps its new generation, which invalidates the slot's earlier notices. + generations = { + sample.camera_index: self._ipc_publisher.begin_write( + runtime.config.ipc_names[sample.camera_index], slot + ) + for sample in stream.samples + } t0 = time.monotonic() receiver_process_submit_mono_ns = time.monotonic_ns() receiver_process_submit_ns, _ = _read_wall_clock_ns() assert self._sample_pool is not None futures: list[Future[bool]] = [ - self._sample_pool.submit( - self._process_sample, runtime, stream, sample, slot - ) + self._sample_pool.submit(self._write_sample, runtime, stream, sample, slot) for sample in stream.samples ] # Finish every eye before a failure can allow slot reuse or decoder reset. wait(futures) - if not all(future.result() for future in futures): + errors = [future.exception() for future in futures] + if any(errors) or not all(future.result() for future in futures): + # Nothing is published. Drain the device so no launched work overlaps the next + # attempt on this slot, then report the first failure. + with cp.cuda.Device(self._gpu_device_id): + cp.cuda.Device().synchronize() + for error in errors: + if error is not None: + raise error return receiver_process_done_mono_ns = time.monotonic_ns() receiver_process_done_ns, _ = _read_wall_clock_ns() - # The native decoder is synchronous. Raw NV12 copies / conversion kernels - # run on CuPy's current stream, so sync before announcing IPC visibility. - with cp.cuda.Device(self._gpu_device_id): - cp.cuda.get_current_stream().synchronize() + # The native decoder is synchronous and every worker waited for its own CUDA stream, + # which carries the raw copies and conversion kernels, so the slot is complete here. timestamp_ns = time.monotonic_ns() receiver_ipc_publish_mono_ns = timestamp_ns @@ -802,7 +808,7 @@ def _process_stream( ) for sample in stream.samples: - generation = runtime.next_generation(sample.camera_index, slot) + generation = generations[sample.camera_index] metadata = self._frame_metadata( bundle=bundle, stream=stream, @@ -835,6 +841,25 @@ def _process_stream( latencies, ) + def _write_sample( + self, + runtime: _StreamRuntime, + stream: Avs1Stream, + sample: Avs1Sample, + slot: int, + ) -> bool: + """Write one eye and wait for this worker's own GPU stream. + + The marker may be announced only after every launch that wrote the slot has completed, + whichever thread ran it, so each worker finishes its stream before returning. + """ + import cupy as cp + + ok = self._process_sample(runtime, stream, sample, slot) + with cp.cuda.Device(self._gpu_device_id): + cp.cuda.get_current_stream().synchronize() + return ok + def _process_sample( self, runtime: _StreamRuntime, diff --git a/examples/camera_streamer/camera_receiver/cuda_ipc.py b/examples/camera_streamer/camera_receiver/cuda_ipc.py index 6d20b5b002..85e6c752d7 100644 --- a/examples/camera_streamer/camera_receiver/cuda_ipc.py +++ b/examples/camera_streamer/camera_receiver/cuda_ipc.py @@ -6,11 +6,15 @@ 1. Publisher -> client: ``hello`` stream catalog, no CUDA handles yet. 2. Client -> publisher: ``subscribe`` with stream names, or omitted/empty for all. -3. Publisher -> client: ``subscribed`` with CUDA IPC handles for selected streams. +3. Publisher -> client: ``subscribed`` with CUDA IPC handles for selected streams + and the shared write-generation markers for their slots. 4. Publisher -> client: ``frame`` notifications for selected streams only. Image bytes stay in same-host CUDA IPC memory. The socket only carries control -messages and per-frame metadata. +messages and per-frame metadata. The receiver advances a slot's marker before it +touches the slot's pixels and announces that generation once the write is +complete, so a reader that finds the marker unchanged after its copy finished +holds a picture that no write overlapped (see ``ipc_protocol``). """ from __future__ import annotations @@ -22,11 +26,15 @@ import queue import signal import socket +import sys import threading from dataclasses import dataclass from pathlib import Path from typing import Any, Optional +# ipc_protocol is a sibling of camera_receiver; import it from the source tree without an install step. +_STREAMER_ROOT = str(Path(__file__).resolve().parents[1]) + logger = logging.getLogger("isaaccapture.camera_streamer.ipc") _CLIENT_SEND_TIMEOUT_S = 2.0 @@ -35,6 +43,15 @@ _SEND_FLAGS = getattr(socket, "MSG_NOSIGNAL", 0) +def _markers_module(): + """The native slot-marker module, imported on first use.""" + if _STREAMER_ROOT not in sys.path: + sys.path.append(_STREAMER_ROOT) + import ipc_protocol + + return ipc_protocol + + @dataclass(frozen=True) class _SlotInfo: slot: int @@ -73,6 +90,8 @@ def __init__( ) -> None: self._socket_path = str(socket_path) self._owner_name = owner_name + self._stream_order: list[str] = [] + self._markers: Any = None self._queue: "queue.Queue[dict[str, Any]]" = queue.Queue(maxsize=queue_size) self._streams: dict[str, _StreamInfo] = {} self._clients: list[_ClientState] = [] @@ -132,6 +151,9 @@ def register_stream( with self._lock: if name in self._streams: raise ValueError(f"CUDA IPC stream {name!r} registered twice") + if self._started: + raise RuntimeError("CUDA IPC streams must be registered before start()") + self._stream_order.append(name) self._streams[name] = _StreamInfo( name=name, width=int(width), @@ -157,8 +179,14 @@ def start(self) -> None: self._ignore_sigpipe() self._stop.clear() try: + if self._stream_order: + self._markers = _markers_module().SlotMarkers.create( + "/camera_receiver_slots", + [len(self._streams[n].slots) for n in self._stream_order], + ) self._open_server() except Exception: + self._close_markers() with self._lock: self._started = False raise @@ -205,6 +233,7 @@ def stop(self) -> None: thread.join(timeout=2.0) self._accept_thread = None self._broadcast_thread = None + self._close_markers() try: if os.path.exists(self._socket_path): os.unlink(self._socket_path) @@ -213,6 +242,22 @@ def stop(self) -> None: "CUDA IPC: failed to unlink %s", self._socket_path, exc_info=True ) + def begin_write(self, stream_name: str, slot: int) -> int: + """Record a write attempt on ``slot`` and return its generation. + + Call before the first GPU operation that may touch the slot, for every stream the + attempt writes. Publish the returned generation only if the attempt succeeds; a failed + attempt is never undone, so earlier notices for the slot stay invalid. + """ + if self._markers is None: + raise RuntimeError("CUDA IPC publisher is not started") + return self._markers.begin_write(self._stream_order.index(stream_name), slot) + + def _close_markers(self) -> None: + markers, self._markers = self._markers, None + if markers is not None: + markers.close() + def publish( self, stream_name: str, @@ -296,6 +341,18 @@ def _stream_with_slots(self, stream: _StreamInfo) -> dict[str, Any]: ] return msg + def _markers_descriptor(self) -> Optional[dict[str, Any]]: + markers = self._markers + if markers is None: + return None + return { + "name": markers.name, + "size": markers.size, + "layout_version": markers.layout_version, + "epoch": markers.epoch, + "stream_indexes": {n: i for i, n in enumerate(self._stream_order)}, + } + def _hello_message(self) -> dict[str, Any]: with self._lock: streams = list(self._streams.values()) @@ -308,6 +365,7 @@ def _hello_message(self) -> dict[str, Any]: "avs1_metadata", "latency_metadata", "slot_generation", + "slot_write_generation", "nv12", ], "owner": self._owner_name, @@ -329,6 +387,7 @@ def _subscribed_message( { "type": "subscribed", "version": 2, + "slot_markers": self._markers_descriptor(), "streams": [ self._stream_with_slots(all_streams[name]) for name in selected_names diff --git a/examples/camera_streamer/camera_receiver/setup.sh b/examples/camera_streamer/camera_receiver/setup.sh index b6a71c7372..462f02b176 100755 --- a/examples/camera_streamer/camera_receiver/setup.sh +++ b/examples/camera_streamer/camera_receiver/setup.sh @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 # -# Create camera_receiver's local Python environment and build its local decoder. +# Create camera_receiver's local Python environment and build its local decoder and slot marker module. set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -69,13 +69,16 @@ export CAMERA_RECEIVER_VENV="$VENV" export CAMERA_RECEIVER_PYTHON="$PYTHON_EXE" if [[ "${CAMERA_RECEIVER_CLEAN_BUILD:-1}" != "0" ]]; then - echo "setup.sh: cleaning codec/build" - rm -rf "${HERE}/codec/build" + echo "setup.sh: cleaning codec/build and ipc_protocol/build" + rm -rf "${HERE}/codec/build" "${HERE}/../ipc_protocol/build" fi echo "setup.sh: building native decoder" "${HERE}/codec/build.sh" +echo "setup.sh: building slot marker module" +IPC_PROTOCOL_PYTHON="$PYTHON_EXE" "${HERE}/../ipc_protocol/build.sh" + echo "setup.sh: verifying receiver config" "$PYTHON_EXE" "${HERE}/camera_receiver.py" \ --config "${HERE}/configs/receiver.yaml" \ diff --git a/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py b/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py index 52b9b8a38c..4b08f67871 100644 --- a/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py +++ b/examples/camera_streamer/camera_receiver/tests/test_sample_completion.py @@ -2,6 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 from concurrent.futures import ThreadPoolExecutor +import logging import sys import threading from types import ModuleType, SimpleNamespace @@ -12,22 +13,95 @@ from camera_receiver import Avs1TcpReceiver +class _Recorder: + """Thread-safe ordered log of what the fake publisher, workers and CUDA did.""" + + def __init__(self): + self.events = [] + self._lock = threading.Lock() + + def add(self, *event): + with self._lock: + self.events.append(event) + + def kinds(self): + return [event[0] for event in self.events] + + +def _fake_cupy(recorder): + """The little of CuPy that the write path touches, recording who synchronizes what.""" + cupy = ModuleType("cupy") + + class Device: + def __init__(self, _id=None): + pass + + def __enter__(self): + return self + + def __exit__(self, *_): + return False + + def synchronize(self): + recorder.add("device_sync", threading.get_ident()) + + class Stream: + def synchronize(self): + recorder.add("stream_sync", threading.get_ident()) + + cupy.cuda = SimpleNamespace(Device=Device, get_current_stream=Stream) + return cupy + + +def _receiver(recorder, *, process_sample, generations=None, stereo=True): + receiver = Avs1TcpReceiver.__new__(Avs1TcpReceiver) + receiver._validate_stream_descriptor = Mock() + receiver._gpu_device_id = 0 + receiver._stats = None + receiver._frame_metadata = Mock(return_value={}) + receiver._receiver_latencies = Mock(return_value={}) + counters = {} + + def begin_write(name, slot): + counters[(name, slot)] = counters.get((name, slot), 0) + 1 + generation = (generations or {}).get(name, 100) + counters[(name, slot)] + recorder.add("begin_write", name, slot, generation) + return generation + + receiver._ipc_publisher = Mock() + receiver._ipc_publisher.begin_write.side_effect = begin_write + receiver._process_sample = process_sample + eyes = 2 if stereo else 1 + runtime = SimpleNamespace( + write_index=0, + config=SimpleNamespace( + name="head", ring_depth=3, ipc_names=["head_left", "head_right"][:eyes] + ), + ) + stream = SimpleNamespace( + samples=tuple(SimpleNamespace(camera_index=i) for i in range(eyes)), + sequence=7, + tsc_delta_ns=0, + ) + return receiver, runtime, stream + + +def _run(receiver, runtime, stream): + with ThreadPoolExecutor(max_workers=2) as sample_pool: + receiver._sample_pool = sample_pool + receiver._process_stream(None, None, stream, runtime) + + @pytest.mark.parametrize("failure_index", [0, 1]) @pytest.mark.parametrize("raises", [False, True]) def test_failed_stereo_bundle_finishes_both_eyes_before_next_operation( monkeypatch, failure_index, raises ): - monkeypatch.setitem(sys.modules, "cupy", ModuleType("cupy")) + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) blocked_eye_started = threading.Event() release_eye = threading.Event() next_operation = threading.Event() - receiver = Avs1TcpReceiver.__new__(Avs1TcpReceiver) - receiver._validate_stream_descriptor = Mock() - receiver._ipc_publisher = Mock() - runtime = SimpleNamespace(write_index=0, config=SimpleNamespace(name="head")) - stream = SimpleNamespace( - samples=tuple(SimpleNamespace(camera_index=i) for i in range(2)) - ) def process_sample(_runtime, _stream, sample, _slot): if sample.camera_index == failure_index: @@ -39,7 +113,7 @@ def process_sample(_runtime, _stream, sample, _slot): raise TimeoutError("test did not release the other eye") return True - receiver._process_sample = process_sample + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) with ( ThreadPoolExecutor(max_workers=2) as sample_pool, ThreadPoolExecutor(max_workers=1) as stream_pool, @@ -64,3 +138,209 @@ def process_sample(_runtime, _stream, sample, _slot): assert runtime.write_index == 0 receiver._ipc_publisher.publish.assert_not_called() + + +def test_every_eye_marker_advances_before_any_sample_starts(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(_runtime, _stream, sample, slot): + recorder.add("process", sample.camera_index, slot) + return True + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + runtime.write_index = 2 + _run(receiver, runtime, stream) + + kinds = recorder.kinds() + assert kinds[:2] == ["begin_write", "begin_write"] + assert [e[1:3] for e in recorder.events[:2]] == [ + ("head_left", 2), + ("head_right", 2), + ] + assert kinds.count("process") == 2 + assert kinds.index("process") > 1 + + +def test_failing_eye_leaves_markers_advanced_and_publishes_nothing(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + receiver, runtime, stream = _receiver( + recorder, process_sample=lambda _r, _s, sample, _slot: sample.camera_index == 0 + ) + _run(receiver, runtime, stream) + + assert recorder.kinds().count("begin_write") == 2 + receiver._ipc_publisher.publish.assert_not_called() + assert runtime.write_index == 0 + assert "device_sync" in recorder.kinds() + # The next attempt on the same slot gets a newer generation than the failed one. + first = [e[3] for e in recorder.events if e[0] == "begin_write"] + recorder.events.clear() + receiver._process_sample = lambda *_: True + _run(receiver, runtime, stream) + second = [e[3] for e in recorder.events if e[0] == "begin_write"] + assert all(b > a for a, b in zip(first, second)) + assert runtime.write_index == 1 + + +def test_exception_in_one_eye_waits_for_the_other_drains_and_reraises(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + other_started = threading.Event() + release_other = threading.Event() + + def process_sample(_runtime, _stream, sample, _slot): + if sample.camera_index == 0: + other_started.wait(timeout=5) + raise RuntimeError("eye 0 exploded") + other_started.set() + assert release_other.wait(timeout=5) + recorder.add("other_eye_done") + return True + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + with ( + ThreadPoolExecutor(max_workers=2) as sample_pool, + ThreadPoolExecutor(max_workers=1) as stream_pool, + ): + receiver._sample_pool = sample_pool + processing = stream_pool.submit( + receiver._process_stream, None, None, stream, runtime + ) + assert other_started.wait(timeout=2) + assert not processing.done() + release_other.set() + with pytest.raises(RuntimeError, match="eye 0 exploded"): + processing.result(timeout=5) + + kinds = recorder.kinds() + assert kinds.index("other_eye_done") < kinds.index("device_sync") + receiver._ipc_publisher.publish.assert_not_called() + + +def test_first_exception_wins_when_both_eyes_raise(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(_runtime, _stream, sample, _slot): + raise RuntimeError(f"eye {sample.camera_index}") + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + with pytest.raises(RuntimeError, match="eye 0"): + _run(receiver, runtime, stream) + assert "device_sync" in recorder.kinds() + + +def test_process_stream_safe_logs_the_reraised_exception(monkeypatch, caplog): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(*_): + raise RuntimeError("decode failed") + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + with ThreadPoolExecutor(max_workers=2) as sample_pool: + receiver._sample_pool = sample_pool + with caplog.at_level(logging.WARNING): + receiver._process_stream_safe(None, None, stream, runtime) + assert any( + "processing failed" in r.getMessage() and "decode failed" in r.getMessage() + for r in caplog.records + ) + receiver._ipc_publisher.publish.assert_not_called() + + +def test_success_publishes_exactly_the_generation_begin_write_returned(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + receiver, runtime, stream = _receiver( + recorder, + process_sample=lambda *_: True, + generations={"head_left": 40, "head_right": 900}, + ) + runtime.write_index = 1 + _run(receiver, runtime, stream) + + assert receiver._ipc_publisher.begin_write.call_count == 2 + published = { + call.args[0]: call.kwargs + for call in receiver._ipc_publisher.publish.call_args_list + } + assert published["head_left"]["slot_generation"] == 41 + assert published["head_right"]["slot_generation"] == 901 + assert all(kw["slot"] == 1 for kw in published.values()) + assert receiver._ipc_publisher.publish.call_count == 2 + assert runtime.write_index == 2 + # A second frame on the same slot is a fresh attempt: exactly one more begin_write per eye. + runtime.write_index = 1 + _run(receiver, runtime, stream) + published = { + call.args[0]: call.kwargs + for call in receiver._ipc_publisher.publish.call_args_list[2:] + } + assert published["head_left"]["slot_generation"] == 42 + assert published["head_right"]["slot_generation"] == 902 + assert receiver._ipc_publisher.begin_write.call_count == 4 + + +def test_mono_stream_begins_one_write(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + receiver, runtime, stream = _receiver( + recorder, process_sample=lambda *_: True, stereo=False + ) + _run(receiver, runtime, stream) + receiver._ipc_publisher.begin_write.assert_called_once_with("head_left", 0) + receiver._ipc_publisher.publish.assert_called_once() + + +def test_each_worker_waits_for_its_own_cuda_stream_after_its_sample(monkeypatch): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + barrier = threading.Barrier(2, timeout=5) + + def process_sample(_runtime, _stream, sample, _slot): + barrier.wait() # force the two eyes onto two different worker threads + recorder.add("process_end", sample.camera_index, threading.get_ident()) + return True + + receiver, runtime, stream = _receiver(recorder, process_sample=process_sample) + _run(receiver, runtime, stream) + + ends = [e for e in recorder.events if e[0] == "process_end"] + assert len({e[2] for e in ends}) == 2 + for _, _, thread in ends: + idx = recorder.events.index(next(e for e in ends if e[2] == thread)) + later = [ + e + for e in recorder.events[idx + 1 :] + if e[0] == "stream_sync" and e[1] == thread + ] + assert later, "worker returned without synchronizing its own stream" + + +@pytest.mark.parametrize("raises", [False, True]) +def test_worker_waits_for_its_stream_even_when_the_sample_fails_softly( + monkeypatch, raises +): + recorder = _Recorder() + monkeypatch.setitem(sys.modules, "cupy", _fake_cupy(recorder)) + + def process_sample(*_): + if raises: + raise RuntimeError("boom") + return False + + receiver, runtime, stream = _receiver( + recorder, process_sample=process_sample, stereo=False + ) + try: + _run(receiver, runtime, stream) + except RuntimeError: + pass + # A soft failure returns False after the work it launched; that work must still be waited on + # before anything is reported. (An exception path is covered by the device-wide drain.) + assert "device_sync" in recorder.kinds() + if not raises: + assert "stream_sync" in recorder.kinds() diff --git a/examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py b/examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py new file mode 100644 index 0000000000..67249ca717 --- /dev/null +++ b/examples/camera_streamer/camera_receiver/tests/test_slot_marker_publisher.py @@ -0,0 +1,231 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""CudaIpcFramePublisher's slot write-generation markers with real CuPy buffers.""" + +import json +from pathlib import Path +import socket +import sys + +import pytest + +cp = pytest.importorskip("cupy", reason="CuPy is not installed") +try: + _GPU_COUNT = cp.cuda.runtime.getDeviceCount() +except Exception as error: # pragma: no cover - depends on the machine + pytest.skip(f"no usable CUDA device: {error}", allow_module_level=True) +if _GPU_COUNT < 1: + pytest.skip("no CUDA device", allow_module_level=True) + +sys.path.insert(0, str(Path(__file__).resolve().parents[2])) + +from cuda_ipc import CudaIpcFramePublisher # noqa: E402 +from ipc_protocol import SlotMarkers # noqa: E402 + +SLOT_COUNTS = {"left": 3, "right": 2} + + +def _register(publisher, counts=None): + for name, slots in (counts or SLOT_COUNTS).items(): + publisher.register_stream( + name, + 4, + 4, + "rgba8", + 0, + [cp.zeros((4, 4, 4), dtype=cp.uint8) for _ in range(slots)], + ) + + +@pytest.fixture +def socket_path(tmp_path): + return str(tmp_path / "ipc.sock") + + +@pytest.fixture +def publisher(socket_path): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + pub.start() + yield pub + pub.stop() + + +class _Client: + def __init__(self, path): + self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.sock.settimeout(5) + self.sock.connect(path) + self.buf = b"" + + def read(self): + while b"\n" not in self.buf: + chunk = self.sock.recv(65536) + assert chunk, "publisher closed the connection" + self.buf += chunk + line, self.buf = self.buf.split(b"\n", 1) + return json.loads(line) + + def subscribe(self): + hello = self.read() + self.sock.sendall(b'{"type":"subscribe","streams":[]}\n') + return hello, self.read() + + def close(self): + self.sock.close() + + +def _connect(path): + client = _Client(path) + try: + return client, *client.subscribe() + except BaseException: + client.close() + raise + + +def test_hello_lists_slot_write_generation(publisher, socket_path): + client, hello, _ = _connect(socket_path) + client.close() + assert "slot_write_generation" in hello["features"] + + +def test_subscribed_carries_an_attachable_descriptor_in_registration_order( + publisher, socket_path +): + client, _, subscribed = _connect(socket_path) + client.close() + info = subscribed["slot_markers"] + assert info["stream_indexes"] == {"left": 0, "right": 1} + reader = SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) + try: + assert reader.stream_count == 2 + assert [reader.slot_count(0), reader.slot_count(1)] == [3, 2] + finally: + reader.close() + + +def test_begin_write_increases_per_stream_and_slot_without_publishing( + publisher, socket_path +): + client, _, subscribed = _connect(socket_path) + info = subscribed["slot_markers"] + reader = SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) + try: + assert [publisher.begin_write("left", 0) for _ in range(3)] == [1, 2, 3] + assert publisher.begin_write("left", 1) == 1 + assert publisher.begin_write("right", 0) == 1 + assert reader.load(0, 0) == 3 + assert reader.load(0, 1) == 1 + assert reader.load(1, 0) == 1 + assert reader.load(1, 1) == 0 + client.sock.settimeout(0.5) + with pytest.raises(socket.timeout): + client.sock.recv(1) + finally: + reader.close() + client.close() + + +def test_failed_attempt_leaves_a_gap_the_next_publish_carries(publisher, socket_path): + client, _, subscribed = _connect(socket_path) + info = subscribed["slot_markers"] + reader = SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) + try: + first = publisher.begin_write("left", 0) + publisher.publish("left", 0, first, 1, 10) + notice = client.read() + assert notice["slot_generation"] == first + assert reader.unchanged(0, 0, notice["slot_generation"]) + + publisher.begin_write("left", 0) # failed attempt, never published + assert not reader.unchanged(0, 0, notice["slot_generation"]) + + last = publisher.begin_write("left", 0) + assert last == first + 2 + publisher.publish("left", 0, last, 2, 20) + later = client.read() + assert later["slot_generation"] == last + assert reader.unchanged(0, 0, later["slot_generation"]) + assert not reader.unchanged(0, 0, notice["slot_generation"]) + finally: + reader.close() + client.close() + + +def test_begin_write_before_start_raises(socket_path): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + with pytest.raises(RuntimeError, match="not started"): + pub.begin_write("left", 0) + + +def test_begin_write_after_stop_raises(socket_path): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + pub.start() + pub.stop() + with pytest.raises(RuntimeError, match="not started"): + pub.begin_write("left", 0) + + +def test_begin_write_unknown_stream_raises(publisher): + with pytest.raises(ValueError): + publisher.begin_write("missing", 0) + + +def test_registering_a_stream_after_start_raises(publisher): + with pytest.raises(RuntimeError, match="before start"): + publisher.register_stream( + "late", 4, 4, "rgba8", 0, [cp.zeros((4, 4, 4), dtype=cp.uint8)] + ) + + +def test_restart_advertises_a_new_region_and_epoch(socket_path): + descriptors = [] + for _ in range(2): + pub = CudaIpcFramePublisher(socket_path=socket_path) + _register(pub) + pub.start() + client, _, subscribed = _connect(socket_path) + client.close() + descriptors.append(subscribed["slot_markers"]) + if len(descriptors) == 1: + pub.stop() + try: + old, new = descriptors + assert new["name"] != old["name"] + assert new["epoch"] != old["epoch"] + with pytest.raises(RuntimeError): + SlotMarkers.attach( + old["name"], old["size"], old["layout_version"], old["epoch"] + ) + with pytest.raises(RuntimeError): + SlotMarkers.attach( + new["name"], new["size"], new["layout_version"], old["epoch"] + ) + SlotMarkers.attach( + new["name"], new["size"], new["layout_version"], new["epoch"] + ).close() + finally: + pub.stop() + + +def test_stop_removes_the_region(publisher, socket_path): + client, _, subscribed = _connect(socket_path) + client.close() + info = subscribed["slot_markers"] + path = Path("/dev/shm") / info["name"].lstrip("/") + assert path.exists() + publisher.stop() + assert not path.exists() + with pytest.raises(RuntimeError): + SlotMarkers.attach( + info["name"], info["size"], info["layout_version"], info["epoch"] + ) diff --git a/examples/camera_streamer/cuda_ipc_consumer/README.md b/examples/camera_streamer/cuda_ipc_consumer/README.md index 9d79f5fffc..b165be6b34 100644 --- a/examples/camera_streamer/cuda_ipc_consumer/README.md +++ b/examples/camera_streamer/cuda_ipc_consumer/README.md @@ -26,7 +26,8 @@ cd ../cuda_ipc_consumer ``` Each directory has its own `.venv`; the consumer does not use the -`camera_receiver` Python environment. +`camera_receiver` Python environment. Both build the shared slot marker module +from [`ipc_protocol/`](../ipc_protocol/README.md). ## Run @@ -49,6 +50,12 @@ Subscribe to only a subset of streams: ./run.sh --streams head.left,head.right --scale 0.35 ``` +The consumer refuses a publisher that does not provide slot write generations. +It checks the slot's marker after each copy has finished and discards a picture +whose slot was rewritten meanwhile, counted as `discarded_frames` in the +one-second stats. Other applications reading the pixels must do the same through +`CudaIpcClient.slot_unchanged`. + For a headless smoke test: ```bash diff --git a/examples/camera_streamer/cuda_ipc_consumer/consumer.py b/examples/camera_streamer/cuda_ipc_consumer/consumer.py index 20fba5e73c..0a08bdcb64 100755 --- a/examples/camera_streamer/cuda_ipc_consumer/consumer.py +++ b/examples/camera_streamer/cuda_ipc_consumer/consumer.py @@ -13,12 +13,17 @@ import select import signal import socket +import sys import time from dataclasses import dataclass +from pathlib import Path from typing import Optional logger = logging.getLogger("isaaccapture.camera_streamer.consumer") +# ipc_protocol is a sibling of cuda_ipc_consumer; import it from the source tree without an install step. +_STREAMER_ROOT = str(Path(__file__).resolve().parents[1]) + @dataclass class IpcSlot: @@ -57,6 +62,8 @@ def __init__(self, socket_path: str, streams: Optional[list[str]] = None) -> Non self.slots: dict[tuple[str, int], IpcSlot] = {} self.stream_order: list[str] = [] self.stream_info: dict[str, dict] = {} + self.markers = None + self._marker_streams: dict[str, int] = {} def connect(self) -> dict: sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) @@ -65,6 +72,11 @@ def connect(self) -> dict: hello = self._read_json_blocking() if hello is None or hello.get("type") != "hello": raise RuntimeError(f"expected hello message, got {hello!r}") + if "slot_write_generation" not in (hello.get("features") or []): + raise RuntimeError( + "the publisher does not provide slot write generations, so a copied " + "picture cannot be validated; update camera_receiver" + ) self._send_json({"type": "subscribe", "streams": self.requested_streams}) subscribed = self._read_json_blocking() if subscribed is None: @@ -73,6 +85,7 @@ def connect(self) -> dict: raise RuntimeError(str(subscribed.get("error", "subscription failed"))) if subscribed.get("type") != "subscribed": raise RuntimeError(f"expected subscribed message, got {subscribed!r}") + self._open_markers(subscribed) self._open_streams(subscribed) sock.setblocking(False) return {"hello": hello, "subscribed": subscribed} @@ -90,6 +103,35 @@ def close(self) -> None: slot.owner.close() self.slots.clear() self.recv_buf.clear() + if self.markers is not None: + self.markers.close() + self.markers = None + + def slot_unchanged(self, stream: str, slot: int, generation: int) -> bool: + """Whether no write has begun on the slot since ``generation`` was announced. + + Accept a copied picture only if this is true after every GPU read of the slot has + completed; checking before the copy only saves work. + """ + return self.markers.unchanged(self._marker_streams[stream], slot, generation) + + def _open_markers(self, subscribed: dict) -> None: + info = subscribed.get("slot_markers") + if not isinstance(info, dict): + raise RuntimeError("the publisher did not offer slot write generations") + if _STREAMER_ROOT not in sys.path: + sys.path.append(_STREAMER_ROOT) + import ipc_protocol + + self.markers = ipc_protocol.SlotMarkers.attach( + str(info["name"]), + int(info["size"]), + int(info["layout_version"]), + int(info["epoch"]), + ) + self._marker_streams = { + str(name): int(index) for name, index in info["stream_indexes"].items() + } def read_messages(self, timeout_s: float = 0.05) -> Optional[list[dict]]: """Return all currently available messages, or None on socket EOF.""" @@ -500,13 +542,12 @@ def on_sigint(_signum, _frame): latest_cpu: dict[str, object] = {} latest_metadata_by_stream: dict[str, dict] = {} - latest_generation_by_slot: dict[tuple[str, int], int] = {} counts: dict[str, int] = dict.fromkeys(client.stream_order, 0) stats_interval = max(1, args.stats_every) last_report = time.monotonic() last_counts = dict(counts) frames_seen = 0 - overwritten = 0 + discarded = 0 csv_file = None csv_writer = None if args.latency_csv: @@ -528,12 +569,6 @@ def on_sigint(_signum, _frame): msg = _annotate_consumer_receive(msg) stream = str(msg["stream"]) slot_id = int(msg["slot"]) - generation = int(msg.get("slot_generation", 0)) - key = (stream, slot_id) - previous = latest_generation_by_slot.get(key) - if previous is not None and generation > previous + 1: - overwritten += generation - previous - 1 - latest_generation_by_slot[key] = generation counts[stream] = counts.get(stream, 0) + 1 frames_seen += 1 latest_msg_by_stream[stream] = msg @@ -555,11 +590,19 @@ def on_sigint(_signum, _frame): if slot is None: print(f"unknown frame slot: {stream}[{slot_id}]", flush=True) continue - updated_display = True if cv2 is not None: - latest_cpu[stream] = _to_bgr_cpu( - slot.array, client.stream_info.get(stream, {}) - ) + generation = int(msg.get("slot_generation", 0)) + if not client.slot_unchanged(stream, slot_id, generation): + discarded += 1 + continue + # The device-to-host copy has finished when this returns; a write that + # began meanwhile has changed the marker, and the copy is discarded. + image = _to_bgr_cpu(slot.array, client.stream_info.get(stream, {})) + if not client.slot_unchanged(stream, slot_id, generation): + discarded += 1 + continue + latest_cpu[stream] = image + updated_display = True if cv2 is None: for msg in sampled_messages: @@ -572,7 +615,11 @@ def on_sigint(_signum, _frame): metadata_text = _format_stream_metadata(msg.get("metadata")) mean_text = "" if args.sample_mean: + generation = int(msg.get("slot_generation", 0)) mean = float(cp.mean(slot.array).get()) + if not client.slot_unchanged(stream, slot_id, generation): + discarded += 1 + continue mean_text = f" mean={mean:.2f}" print( f"{stream}[{slot_id}] gen={msg.get('slot_generation')} " @@ -603,9 +650,9 @@ def on_sigint(_signum, _frame): prev = last_counts.get(name, 0) rates.append(f"{name}: {current - prev} fps") last_counts[name] = current - if overwritten: - rates.append(f"overwritten_slots={overwritten}") - overwritten = 0 + if discarded: + rates.append(f"discarded_frames={discarded}") + discarded = 0 metadata_text = _format_summary_metadata( _latest_metadata(latest_metadata_by_stream, client.stream_order) ) diff --git a/examples/camera_streamer/cuda_ipc_consumer/requirements.txt b/examples/camera_streamer/cuda_ipc_consumer/requirements.txt index 814bee05b9..0c195db77e 100644 --- a/examples/camera_streamer/cuda_ipc_consumer/requirements.txt +++ b/examples/camera_streamer/cuda_ipc_consumer/requirements.txt @@ -4,3 +4,5 @@ numpy>=1.26,<2 cupy-cuda12x>=13.0,<14 opencv-python>=4.9,<4.12 +pybind11>=2.12 +ninja>=1.11 diff --git a/examples/camera_streamer/cuda_ipc_consumer/setup.sh b/examples/camera_streamer/cuda_ipc_consumer/setup.sh index 82e16c5485..d2e14ff875 100755 --- a/examples/camera_streamer/cuda_ipc_consumer/setup.sh +++ b/examples/camera_streamer/cuda_ipc_consumer/setup.sh @@ -41,8 +41,11 @@ else "$PYTHON_EXE" -m pip check fi +echo "setup.sh: building slot marker module" +IPC_PROTOCOL_PYTHON="$PYTHON_EXE" "${HERE}/../ipc_protocol/build.sh" + echo "setup.sh: verifying imports" -"$PYTHON_EXE" - <<'PY' +IPC_PARENT="$(cd "${HERE}/.." && pwd)" "$PYTHON_EXE" - <<'PY' import cupy import cv2 import numpy @@ -50,6 +53,12 @@ import numpy print(f"numpy={numpy.__version__}") print(f"cupy={cupy.__version__}") print(f"opencv={cv2.__version__}") + +import os +import sys + +sys.path.append(os.environ["IPC_PARENT"]) +import ipc_protocol # noqa: E402,F401 PY echo diff --git a/examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py b/examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py new file mode 100644 index 0000000000..e9e346be09 --- /dev/null +++ b/examples/camera_streamer/cuda_ipc_consumer/tests/conftest.py @@ -0,0 +1,9 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from pathlib import Path +import sys + +CONSUMER_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(CONSUMER_ROOT)) +sys.path.insert(0, str(CONSUMER_ROOT.parent)) diff --git a/examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py b/examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py new file mode 100644 index 0000000000..365698b528 --- /dev/null +++ b/examples/camera_streamer/cuda_ipc_consumer/tests/test_slot_validation.py @@ -0,0 +1,155 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""CudaIpcClient's slot write-generation handshake against a fake publisher (no GPU).""" + +import json +import socket +import threading + +import pytest + +from consumer import CudaIpcClient +from ipc_protocol import SlotMarkers + +FEATURES = ["slot_generation", "slot_write_generation"] + + +class _FakePublisher: + def __init__(self, path, hello, subscribed): + self.server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.server.bind(path) + self.server.listen(1) + self.thread = threading.Thread( + target=self._serve, args=(hello, subscribed), daemon=True + ) + self.thread.start() + + def _serve(self, hello, subscribed): + conn, _ = self.server.accept() + with conn: + conn.sendall(json.dumps(hello).encode() + b"\n") + buf = b"" + while b"\n" not in buf: + chunk = conn.recv(4096) + if not chunk: + return + buf += chunk + if subscribed is not None: + conn.sendall(json.dumps(subscribed).encode() + b"\n") + conn.settimeout(2) + try: + conn.recv(1) + except OSError: + pass + + def close(self): + self.server.close() + self.thread.join(timeout=5) + + +@pytest.fixture +def markers(): + region = SlotMarkers.create("/consumer_test", [2, 1]) + yield region + region.close() + + +def _descriptor(region, streams=None): + return { + "name": region.name, + "size": region.size, + "layout_version": region.layout_version, + "epoch": region.epoch, + "stream_indexes": streams or {"left": 0, "right": 1}, + } + + +@pytest.fixture +def client_for(tmp_path, monkeypatch): + created = [] + + def make(hello, subscribed): + path = str(tmp_path / "pub.sock") + publisher = _FakePublisher(path, hello, subscribed) + client = CudaIpcClient(path) + monkeypatch.setattr(client, "_open_streams", lambda _subscribed: None) + created.append((publisher, client)) + return client + + yield make + for publisher, client in created: + client.close() + publisher.close() + + +def _hello(features=FEATURES): + return {"type": "hello", "version": 2, "features": features, "streams": []} + + +def test_refuses_a_hello_without_slot_write_generation(client_for, markers): + client = client_for( + _hello(["slot_generation"]), + {"type": "subscribed", "slot_markers": _descriptor(markers), "streams": []}, + ) + with pytest.raises(RuntimeError, match="slot write generations"): + client.connect() + assert client.markers is None + + +def test_refuses_a_subscribed_without_slot_markers(client_for): + client = client_for(_hello(), {"type": "subscribed", "streams": []}) + with pytest.raises(RuntimeError, match="slot write generations"): + client.connect() + assert client.markers is None + + +def test_refuses_a_subscribed_with_null_slot_markers(client_for): + client = client_for( + _hello(), {"type": "subscribed", "slot_markers": None, "streams": []} + ) + with pytest.raises(RuntimeError, match="slot write generations"): + client.connect() + + +def test_refuses_markers_of_a_stale_epoch(client_for, markers): + descriptor = _descriptor(markers) + descriptor["epoch"] ^= 1 + client = client_for( + _hello(), {"type": "subscribed", "slot_markers": descriptor, "streams": []} + ) + with pytest.raises(RuntimeError): + client.connect() + assert client.markers is None + + +def test_slot_unchanged_follows_the_shared_marker(client_for, markers): + client = client_for( + _hello(), + {"type": "subscribed", "slot_markers": _descriptor(markers), "streams": []}, + ) + client.connect() + generation = markers.begin_write(0, 1) + assert client.slot_unchanged("left", 1, generation) + markers.begin_write(0, 1) + assert not client.slot_unchanged("left", 1, generation) + # Streams map through stream_indexes, not by name order. + other = markers.begin_write(1, 0) + assert client.slot_unchanged("right", 0, other) + assert not client.slot_unchanged("right", 0, other - 1) + with pytest.raises(KeyError): + client.slot_unchanged("missing", 0, 0) + + +def test_close_closes_the_region(client_for, markers): + client = client_for( + _hello(), + {"type": "subscribed", "slot_markers": _descriptor(markers), "streams": []}, + ) + client.connect() + attached = client.markers + assert attached is not None + client.close() + assert client.markers is None + with pytest.raises(RuntimeError, match="closed"): + attached.load(0, 0) + client.close() # idempotent diff --git a/examples/camera_streamer/ipc_protocol/.gitignore b/examples/camera_streamer/ipc_protocol/.gitignore new file mode 100644 index 0000000000..2c1d2a737d --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/.gitignore @@ -0,0 +1,3 @@ +build/ +_slot_markers*.so +__pycache__/ diff --git a/examples/camera_streamer/ipc_protocol/CMakeLists.txt b/examples/camera_streamer/ipc_protocol/CMakeLists.txt new file mode 100644 index 0000000000..f12a7c2d6a --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/CMakeLists.txt @@ -0,0 +1,33 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# CPU-only slot marker module shared by camera_receiver and the CUDA IPC consumers. The .so lands next to +# __init__.py so the package imports without an install step. + +cmake_minimum_required(VERSION 3.20) +project(camera_ipc_protocol LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_POSITION_INDEPENDENT_CODE ON) + +find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module) + +# pybind11 is pip-installed into the active Python environment. +execute_process( + COMMAND ${Python3_EXECUTABLE} -c "import pybind11; print(pybind11.get_cmake_dir())" + OUTPUT_VARIABLE pybind11_DIR + OUTPUT_STRIP_TRAILING_WHITESPACE + RESULT_VARIABLE _pybind11_rc +) +if(NOT _pybind11_rc EQUAL 0) + message(FATAL_ERROR "pybind11 not found. `uv pip install pybind11` into the active venv.") +endif() +find_package(pybind11 REQUIRED CONFIG) + +pybind11_add_module(_slot_markers MODULE slot_markers_bindings.cpp) +target_include_directories(_slot_markers PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/inc) +target_link_libraries(_slot_markers PRIVATE rt) +target_compile_options(_slot_markers PRIVATE -Wall -Wextra) + +set_target_properties(_slot_markers PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) diff --git a/examples/camera_streamer/ipc_protocol/README.md b/examples/camera_streamer/ipc_protocol/README.md new file mode 100644 index 0000000000..3f3102ff22 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/README.md @@ -0,0 +1,81 @@ + + +# CUDA IPC slot write generations + +`camera_receiver` decodes frames into a ring of GPU slots and shares them with +same-host readers over CUDA IPC. It rewrites a slot `ring_depth` pictures after +announcing it and never waits for a reader, and the replacement notice only +arrives after the new write, so a reader cannot learn from the socket that its +copy overlapped a rewrite. This module adds one shared write-generation marker +per slot so the reader can find out after its copy has finished. + +| Role | Process | What it does | +| --- | --- | --- | +| Slot writer | `camera_receiver` | Advances a slot's marker, writes the slot, announces that generation. | +| Slot reader | `cuda_ipc_consumer`, `camera_livekit_bridge`, any application | Copies a notified slot into memory it owns, then checks the marker before using the copy. | + +## Protocol + +- The writer owns one POSIX shared-memory region (`slot_markers.hpp`, mode `0600`, + unpredictable name, fresh epoch per run) holding one 64-bit atomic per + stream and slot. `_slot_markers` is its Python binding; the header is the single + implementation Python and C++ share. +- The marker counts write attempts. The writer increments it, for every stream + the attempt writes, before launching the first GPU operation that may touch the + slot, and keeps the result. A failed attempt publishes nothing and the marker + is never restored, so earlier notices for that slot stay invalid. +- A frame notice's `slot_generation` is the marker value of its completed write. + Generations skip values when attempts fail, so a gap is not a lost picture; the + frame sequence counts those. +- `hello.features` lists `slot_write_generation`, and `subscribed.slot_markers` + carries the region's `name`, `size`, `layout_version`, `epoch` and + `stream_indexes`. A reader that needs intact pictures refuses a publisher + without the feature and maps the region only if its size, layout version and + epoch match. +- Reader: copy the notified slot into memory it owns, wait until every GPU read of + the slot has completed, load the marker, and keep the copy only if it equals the + notified generation. Loading it before the copy only saves work. A reader that + skips the check, or an older reader that ignores `slot_markers`, can still + receive a picture mixing two frames; it is outside this guarantee. + The egocap capture server's GMSL feed reader still decides with a ring-distance + heuristic and does not use the markers yet. + +## Ordering contract + +The writer's `begin_write` is a sequentially consistent `fetch_add` followed by a +sequentially consistent fence on a lock-free 64-bit atomic in shared memory, and +it runs on the CPU before the first CUDA call that can write the slot. The reader's +`load` is a sequentially consistent load after its stream has finished. The +writer announces a generation only after every worker has waited for its own GPU +stream; on failure it drains the device before the next attempt. + +If a write overlapped any part of a read, the write's launch preceded the end of +the read, and the increment preceded the launch, so the reader's load sees the +increment or a later one and the generation differs. A write that begins after +the reader's load cannot change a copy that already finished. The 64-bit counter +cannot repeat within a run, a new run has a new region and epoch, and unsupported +platforms refuse to initialise rather than fall back to non-atomic access. This +holds for a plain copy and for a kernel that reads the slot, provided each has +finished before the load. + +CUDA's memory model treats an unsynchronized read and write of the same bytes as a +data race and does not specify what the reader then observes. This design relies +on the race affecting only the contents of the reader's private copy, which the +marker check discards; CUDA does not document a stronger guarantee for it, so the +check is validated by tests rather than proven from the memory model. A reader +needing a documented guarantee needs the writer to exclude overlapping access +instead of detecting it. + +## Build + +```bash +./build.sh # needs a C++17 compiler, CMake and pybind11 +IPC_PROTOCOL_PYTHON=/path/to/python ./build.sh +``` + +`camera_receiver/setup.sh` and `cuda_ipc_consumer/setup.sh` run it with their own +environment. The module file name carries the interpreter's ABI tag, so each +interpreter builds in its own tree. diff --git a/examples/camera_streamer/ipc_protocol/__init__.py b/examples/camera_streamer/ipc_protocol/__init__.py new file mode 100644 index 0000000000..9d245600b3 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/__init__.py @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Write-attempt markers shared by camera_receiver and its CUDA IPC readers.""" + +from __future__ import annotations + +try: + from ._slot_markers import ( # type: ignore[import-not-found] + LAYOUT_VERSION, + MAX_SLOTS, + MAX_STREAMS, + REGION_SIZE, + SlotMarkers, + ) +except ImportError as e: + raise ImportError( + "camera_streamer slot marker module not built. Run " + "`ipc_protocol/build.sh` from the camera_streamer directory." + ) from e + +__all__ = [ + "LAYOUT_VERSION", + "MAX_SLOTS", + "MAX_STREAMS", + "REGION_SIZE", + "SlotMarkers", +] diff --git a/examples/camera_streamer/ipc_protocol/build.sh b/examples/camera_streamer/ipc_protocol/build.sh new file mode 100755 index 0000000000..824e1c4603 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/build.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# Builds the slot marker module. The .so lands next to __init__.py so the package imports straight from the source +# tree. Needs only a C++17 compiler and pybind11; no CUDA. +set -euo pipefail + +here="$(cd "$(dirname "$0")" && pwd)" +python_exe="${IPC_PROTOCOL_PYTHON:-${CAMERA_RECEIVER_PYTHON:-python3}}" + +if ! command -v "$python_exe" >/dev/null 2>&1 && [[ ! -x "$python_exe" ]]; then + echo "build.sh: no Python at $python_exe" >&2 + echo "build.sh: override with IPC_PROTOCOL_PYTHON=/path/to/python" >&2 + exit 1 +fi + +if ! "$python_exe" -c "import pybind11" 2>/dev/null; then + echo "build.sh: installing pybind11 into the Python environment..." >&2 + "$python_exe" -m pip install pybind11 +fi + +# The module's file name carries the interpreter's ABI tag, so each interpreter builds in its own tree. +build_dir="${here}/build/$("$python_exe" -c 'import sys; print(f"py{sys.version_info[0]}{sys.version_info[1]}")')" + +generator=() +if command -v ninja >/dev/null 2>&1; then + generator=(-G Ninja) +fi + +cmake -S "${here}" -B "${build_dir}" "${generator[@]}" \ + -DCMAKE_BUILD_TYPE=Release \ + -DPython3_EXECUTABLE="$(command -v "$python_exe")" +cmake --build "${build_dir}" --parallel + +echo +echo "build.sh: built → ${here}/_slot_markers*.so" diff --git a/examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp b/examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp new file mode 100644 index 0000000000..c1e73e5dee --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/inc/ipc_protocol/slot_markers.hpp @@ -0,0 +1,321 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +// +// Write-attempt markers for the CUDA IPC pixel slots that camera_receiver (the slot writer) shares with its readers. +// The writer advances a slot's marker before it touches the slot's pixels; a reader loads it again after its copy +// has finished and accepts the copy only if the marker still equals the generation the frame notice named. +// +// The operations are sequentially consistent process-shared atomics. Their ordering against GPU work is the caller's +// duty: advance the marker before launching the first write, and load it only after the GPU reads have completed. +#pragma once + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace camera_ipc +{ + +inline constexpr std::uint32_t kMarkerMagic = 0x314b4d53u; // "SMK1" +inline constexpr std::uint32_t kMarkerLayoutVersion = 1; +inline constexpr std::uint32_t kMaxStreams = 16; +inline constexpr std::uint32_t kMaxSlots = 32; +// A marker never wraps: a writer that reaches this restarts under a new region and epoch instead. +inline constexpr std::uint64_t kMaxGeneration = 1ull << 62; + +static_assert(std::atomic::is_always_lock_free, "slot markers need lock-free 64-bit atomics"); +static_assert(std::atomic::is_always_lock_free, "slot markers need lock-free 32-bit atomics"); + +struct alignas(64) MarkerCell +{ + std::atomic generation; +}; + +struct alignas(64) MarkerHeader +{ + std::uint32_t magic; + std::uint32_t layout_version; + std::uint64_t epoch; + std::uint32_t total_size; + std::uint32_t stream_count; + std::uint32_t slot_count[kMaxStreams]; + std::atomic ready; +}; + +struct MarkerRegion +{ + MarkerHeader header; + MarkerCell cells[kMaxStreams][kMaxSlots]; +}; + +class SlotMarkers +{ +public: + // Creates and initialises the region. The name is unique per call and the object is private to the user. + static SlotMarkers create(const std::string& name_prefix, const std::vector& slot_counts) + { + require_lock_free(); + if (slot_counts.empty() || slot_counts.size() > kMaxStreams) + { + throw std::invalid_argument("slot markers: stream count must be 1.." + std::to_string(kMaxStreams)); + } + for (std::uint32_t count : slot_counts) + { + if (count < 1 || count > kMaxSlots) + { + throw std::invalid_argument("slot markers: slots per stream must be 1.." + std::to_string(kMaxSlots)); + } + } + + std::random_device entropy; + const std::uint64_t epoch = random_u64(entropy); + char suffix[40]; + std::snprintf(suffix, sizeof(suffix), "_%d_%016llx", static_cast(::getpid()), + static_cast(random_u64(entropy))); + const std::string name = name_prefix + suffix; + + const int fd = ::shm_open(name.c_str(), O_CREAT | O_EXCL | O_RDWR, 0600); + if (fd < 0) + { + throw std::runtime_error("slot markers: shm_open(" + name + ") failed: " + std::strerror(errno)); + } + if (::fchmod(fd, 0600) != 0 || ::ftruncate(fd, sizeof(MarkerRegion)) != 0) + { + const std::string what = std::strerror(errno); + ::close(fd); + ::shm_unlink(name.c_str()); + throw std::runtime_error("slot markers: sizing " + name + " failed: " + what); + } + void* mapped = ::mmap(nullptr, sizeof(MarkerRegion), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + ::close(fd); + if (mapped == MAP_FAILED) + { + const std::string what = std::strerror(errno); + ::shm_unlink(name.c_str()); + throw std::runtime_error("slot markers: mmap(" + name + ") failed: " + what); + } + + // The mapping is zero-filled; construct the atomics in place and publish `ready` last. + auto* region = new (mapped) MarkerRegion(); + region->header.magic = kMarkerMagic; + region->header.layout_version = kMarkerLayoutVersion; + region->header.epoch = epoch; + region->header.total_size = static_cast(sizeof(MarkerRegion)); + region->header.stream_count = static_cast(slot_counts.size()); + for (std::size_t i = 0; i < slot_counts.size(); ++i) + { + region->header.slot_count[i] = slot_counts[i]; + } + region->header.ready.store(1); + return SlotMarkers(region, name, true); + } + + // Maps a region a writer advertised. The advertised size, layout version and epoch must all match the object. + static SlotMarkers attach(const std::string& name, std::uint64_t size, std::uint32_t layout_version, std::uint64_t epoch) + { + require_lock_free(); + if (layout_version != kMarkerLayoutVersion || size != sizeof(MarkerRegion)) + { + throw std::runtime_error("slot markers: unsupported layout (version " + std::to_string(layout_version) + + ", size " + std::to_string(size) + ")"); + } + const int fd = ::shm_open(name.c_str(), O_RDWR, 0); + if (fd < 0) + { + throw std::runtime_error("slot markers: shm_open(" + name + ") failed: " + std::strerror(errno)); + } + struct stat info + { + }; + if (::fstat(fd, &info) != 0 || static_cast(info.st_size) != size) + { + ::close(fd); + throw std::runtime_error("slot markers: " + name + " has the wrong size"); + } + void* mapped = ::mmap(nullptr, sizeof(MarkerRegion), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + ::close(fd); + if (mapped == MAP_FAILED) + { + throw std::runtime_error("slot markers: mmap(" + name + ") failed: " + std::strerror(errno)); + } + auto* region = static_cast(mapped); + const MarkerHeader& header = region->header; + bool sane = header.ready.load() == 1 && header.magic == kMarkerMagic && + header.layout_version == kMarkerLayoutVersion && header.epoch == epoch && + header.total_size == sizeof(MarkerRegion) && header.stream_count >= 1 && + header.stream_count <= kMaxStreams; + for (std::uint32_t i = 0; sane && i < header.stream_count; ++i) + { + sane = header.slot_count[i] >= 1 && header.slot_count[i] <= kMaxSlots; + } + if (!sane) + { + ::munmap(mapped, sizeof(MarkerRegion)); + throw std::runtime_error("slot markers: " + name + " is not the advertised region"); + } + return SlotMarkers(region, name, false); + } + + SlotMarkers(const SlotMarkers&) = delete; + SlotMarkers& operator=(const SlotMarkers&) = delete; + SlotMarkers(SlotMarkers&& other) noexcept + : region_(std::exchange(other.region_, nullptr)), name_(std::move(other.name_)), owner_(other.owner_) + { + } + SlotMarkers& operator=(SlotMarkers&& other) noexcept + { + if (this != &other) + { + close(); + region_ = std::exchange(other.region_, nullptr); + name_ = std::move(other.name_); + owner_ = other.owner_; + } + return *this; + } + ~SlotMarkers() + { + close(); + } + + // Unmaps the region; the creator also removes its name so no new reader can attach. + void close() noexcept + { + if (region_ == nullptr) + { + return; + } + ::munmap(region_, sizeof(MarkerRegion)); + region_ = nullptr; + if (owner_) + { + ::shm_unlink(name_.c_str()); + } + } + + const std::string& name() const + { + return name_; + } + static constexpr std::uint64_t region_size() + { + return sizeof(MarkerRegion); + } + std::uint64_t epoch() const + { + return region().header.epoch; + } + std::uint32_t layout_version() const + { + return region().header.layout_version; + } + std::uint32_t stream_count() const + { + return region().header.stream_count; + } + std::uint32_t slot_count(std::uint32_t stream) const + { + check_stream(stream); + return region().header.slot_count[stream]; + } + + // Writer: records a write attempt and returns its generation. Call before the first GPU operation that may touch + // the slot's pixels, and keep the result to publish if the attempt succeeds. Failed attempts are never undone. + std::uint64_t begin_write(std::uint32_t stream, std::uint32_t slot) + { + std::atomic& marker = cell_at(stream, slot).generation; + const std::uint64_t generation = marker.fetch_add(1) + 1; + if (generation >= kMaxGeneration) + { + throw std::runtime_error("slot markers: generation space exhausted; restart under a new region"); + } + // The increment is globally visible before any later launch, including device doorbell writes. + std::atomic_thread_fence(std::memory_order_seq_cst); + return generation; + } + + // Reader: the slot's current generation. Load it only after every GPU read of the slot has completed. + std::uint64_t load(std::uint32_t stream, std::uint32_t slot) const + { + return cell_at(stream, slot).generation.load(); + } + + // Reader: whether no write has begun since `generation` was announced. + bool unchanged(std::uint32_t stream, std::uint32_t slot, std::uint64_t generation) const + { + return load(stream, slot) == generation; + } + +private: + SlotMarkers(MarkerRegion* region, std::string name, bool owner) + : region_(region), name_(std::move(name)), owner_(owner) + { + } + + static void require_lock_free() + { + std::atomic probe64{ 0 }; + std::atomic probe32{ 0 }; + if (!probe64.is_lock_free() || !probe32.is_lock_free()) + { + throw std::runtime_error("slot markers: this platform has no lock-free process-shared atomics"); + } + } + + static std::uint64_t random_u64(std::random_device& entropy) + { + std::uint64_t value = 0; + while (value == 0) + { + value = (static_cast(entropy()) << 32) ^ entropy(); + } + return value; + } + + void check_stream(std::uint32_t stream) const + { + if (stream >= region().header.stream_count) + { + throw std::out_of_range("slot markers: stream index out of range"); + } + } + + MarkerCell& cell_at(std::uint32_t stream, std::uint32_t slot) const + { + check_stream(stream); + if (slot >= region().header.slot_count[stream]) + { + throw std::out_of_range("slot markers: slot index out of range"); + } + return region().cells[stream][slot]; + } + + MarkerRegion& region() const + { + if (region_ == nullptr) + { + throw std::runtime_error("slot markers: the region is closed"); + } + return *region_; + } + + MarkerRegion* region_; + std::string name_; + bool owner_; +}; + +} // namespace camera_ipc diff --git a/examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp b/examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp new file mode 100644 index 0000000000..a43d66b51e --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/slot_markers_bindings.cpp @@ -0,0 +1,37 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +// +// Thin Python binding over the slot markers. The operations live in the header, shared with the C++ readers. + +#include "ipc_protocol/slot_markers.hpp" + +#include +#include + +namespace py = pybind11; +using camera_ipc::SlotMarkers; + +PYBIND11_MODULE(_slot_markers, m) +{ + m.doc() = "Write-attempt markers for camera_receiver's CUDA IPC pixel slots"; + + m.attr("LAYOUT_VERSION") = camera_ipc::kMarkerLayoutVersion; + m.attr("REGION_SIZE") = SlotMarkers::region_size(); + m.attr("MAX_STREAMS") = camera_ipc::kMaxStreams; + m.attr("MAX_SLOTS") = camera_ipc::kMaxSlots; + + py::class_(m, "SlotMarkers") + .def_static("create", &SlotMarkers::create, py::arg("name_prefix"), py::arg("slot_counts")) + .def_static("attach", &SlotMarkers::attach, py::arg("name"), py::arg("size"), py::arg("layout_version"), + py::arg("epoch")) + .def("close", &SlotMarkers::close) + .def_property_readonly("name", &SlotMarkers::name) + .def_property_readonly("size", [](const SlotMarkers&) { return SlotMarkers::region_size(); }) + .def_property_readonly("epoch", &SlotMarkers::epoch) + .def_property_readonly("layout_version", &SlotMarkers::layout_version) + .def_property_readonly("stream_count", &SlotMarkers::stream_count) + .def("slot_count", &SlotMarkers::slot_count, py::arg("stream")) + .def("begin_write", &SlotMarkers::begin_write, py::arg("stream"), py::arg("slot")) + .def("load", &SlotMarkers::load, py::arg("stream"), py::arg("slot")) + .def("unchanged", &SlotMarkers::unchanged, py::arg("stream"), py::arg("slot"), py::arg("generation")); +} diff --git a/examples/camera_streamer/ipc_protocol/tests/conftest.py b/examples/camera_streamer/ipc_protocol/tests/conftest.py new file mode 100644 index 0000000000..5dbf7a9380 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/tests/conftest.py @@ -0,0 +1,8 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from pathlib import Path +import sys + +STREAMER_ROOT = Path(__file__).resolve().parents[2] +sys.path.insert(0, str(STREAMER_ROOT)) diff --git a/examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py b/examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py new file mode 100644 index 0000000000..a5b3a5b1ff --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/tests/test_gpu_slot_integrity.py @@ -0,0 +1,730 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""GPU acceptance tests: an accepted picture always matches its notice's frame identity. + +The writer (``CudaIpcFramePublisher`` plus test kernels) runs in a spawned child process, because +CUDA IPC handles cannot be opened in the exporting process; the test process is the reader +(``CudaIpcClient``). Pixels are a pure function of the frame id, recomputed in numpy here, and +GPU gates (stream host functions) hold a reader's copy in flight while the writer overwrites a +slot. +""" + +from __future__ import annotations + +import collections +import faulthandler +import multiprocessing +import os +import queue +import random +import shutil +import statistics +import sys +import tempfile +import threading +import time +import traceback +from pathlib import Path + +import numpy as np +import pytest + +_HERE = Path(__file__).resolve() +_STREAMER_ROOT = _HERE.parents[2] +_REPO_ROOT = _HERE.parents[4] +for _p in ( + _STREAMER_ROOT, + _STREAMER_ROOT / "camera_receiver", + _STREAMER_ROOT / "cuda_ipc_consumer", +): + if str(_p) not in sys.path: + sys.path.insert(0, str(_p)) + +try: + import cupy as cp + + _GPU_REASON = ( + None if cp.cuda.runtime.getDeviceCount() > 0 else "no CUDA device present" + ) +except Exception as _exc: # noqa: BLE001 - any import/driver failure means skip + cp = None + _GPU_REASON = f"CuPy/CUDA unavailable: {_exc}" + +try: + import ipc_protocol # noqa: F401 + + _MARKER_REASON = None +except ImportError as _exc: + _MARKER_REASON = f"ipc_protocol not built for this interpreter: {_exc}" + +pytestmark = pytest.mark.skipif( + _GPU_REASON is not None or _MARKER_REASON is not None, + reason=_GPU_REASON or _MARKER_REASON or "", +) + +ROWS, COLS = 96, 128 # 128x64 luma rows + 32 chroma rows +BANDS = 4 +CMD_TIMEOUT_S = 90.0 +GATE_TIMEOUT_S = 10.0 + + +def expected_pixels(fid: int, rows: int = ROWS, cols: int = COLS) -> np.ndarray: + """Pixel pattern of frame ``fid``; every row of every plane carries the id.""" + r = np.arange(rows, dtype=np.int64)[:, None] + c = np.arange(cols, dtype=np.int64)[None, :] + return ((fid * 37 + (fid >> 8) * 11 + r * 5 + c) % 251).astype(np.uint8) + + +def expected_box(fid: int) -> np.ndarray: + """What the pair-averaging kernel reader produces for frame ``fid``.""" + v = expected_pixels(fid).astype(np.int32).reshape(ROWS, COLS // 2, 2) + avg = ((v[:, :, 0] + v[:, :, 1] + 1) >> 1).astype(np.uint8) + return np.repeat(avg, 2, axis=1) + + +def timestamp_for(seq: int) -> int: + return 1_000_000_000 + seq * 33_333_333 + + +# --------------------------------------------------------------------------- writer process + + +def _writer_main(cmd_q, rsp_q, cfg) -> None: + """Writer process: publisher plus test write kernels, driven by commands.""" + try: + import cupy as wcp + + from cuda_ipc import CudaIpcFramePublisher + + wcp.cuda.set_allocator( + None + ) # raw cudaMalloc so every slot is its own IPC allocation + write = wcp.ElementwiseKernel( + "int64 fid, int32 W", + "uint8 out", + "int r = i / W; int c = i % W;" + "out = (unsigned char)((fid * 37 + (fid >> 8) * 11 + (long long)r * 5 + c) % 251);", + "test_write_pattern", + ) + stream = wcp.cuda.Stream(non_blocking=True) + pub = CudaIpcFramePublisher(socket_path=cfg["socket"], queue_size=512) + bufs: dict[str, list] = {} + for name, rows, cols, ring in cfg["streams"]: + bufs[name] = [wcp.zeros((rows, cols), dtype=wcp.uint8) for _ in range(ring)] + pub.register_stream(name, cols, rows * 2 // 3, "nv12", 0, bufs[name]) + pub.start() + rsp_q.put(("ok", {"socket": cfg["socket"]})) + except BaseException: # noqa: BLE001 + rsp_q.put(("err", traceback.format_exc())) + return + + def write_slot(name, slot, fid, rows=None): + arr = bufs[name][slot] + view = arr if rows is None else arr[:rows] + with stream: + write(fid, arr.shape[1], view) + stream.synchronize() + + try: + while True: + cmd, args = cmd_q.get() + try: + if cmd == "stop": + break + if cmd == "write_many": + # items: (stream, slot, fid, rows_or_None, publish) + gens = [pub.begin_write(it[0], it[1]) for it in args["items"]] + for it in args["items"]: + write_slot(it[0], it[1], it[2], it[3]) + for it, g in zip(args["items"], gens): + if it[4]: + pub.publish(it[0], it[1], g, it[2], timestamp_for(it[2])) + rsp_q.put(("ok", gens)) + elif cmd == "burst": + name, ring = args["stream"], len(bufs[args["stream"]]) + t0 = time.perf_counter() + for fid in range(args["first"], args["first"] + args["n"]): + slot = fid % ring + g = pub.begin_write(name, slot) + write_slot(name, slot, fid) + pub.publish(name, slot, g, fid, timestamp_for(fid)) + rsp_q.put(("ok", {"elapsed_s": time.perf_counter() - t0})) + elif cmd == "bench": + name, ring = args["stream"], len(bufs[args["stream"]]) + lat = [] + t0 = time.perf_counter() + for fid in range(args["n"]): + t1 = time.perf_counter() + slot = fid % ring + g = pub.begin_write(name, slot) if args["begin"] else 0 + write_slot(name, slot, fid) + pub.publish(name, slot, g, fid, timestamp_for(fid)) + lat.append(time.perf_counter() - t1) + total = time.perf_counter() - t0 + lat.sort() + rsp_q.put( + ( + "ok", + { + "fps": args["n"] / total, + "mean_us": 1e6 * sum(lat) / len(lat), + "p50_us": 1e6 * lat[len(lat) // 2], + "p99_us": 1e6 * lat[int(len(lat) * 0.99)], + }, + ) + ) + else: + rsp_q.put(("err", f"unknown command {cmd}")) + except BaseException: # noqa: BLE001 + rsp_q.put(("err", traceback.format_exc())) + finally: + pub.stop() + + +class Writer: + """Parent-side handle on a writer child process.""" + + def __init__(self, streams, workdir: Path) -> None: + ctx = multiprocessing.get_context("spawn") + self.cmd_q = ctx.Queue() + self.rsp_q = ctx.Queue() + self.socket = str(Path(tempfile.mkdtemp(dir=workdir)) / "s.sock") + self.proc = ctx.Process( + target=_writer_main, + args=(self.cmd_q, self.rsp_q, {"socket": self.socket, "streams": streams}), + daemon=True, + ) + self.proc.start() + self.result("startup") + + def result(self, what: str, timeout: float = CMD_TIMEOUT_S): + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + try: + status, payload = self.rsp_q.get(timeout=0.25) + except queue.Empty: + if not self.proc.is_alive(): + raise RuntimeError(f"writer died during {what}") from None + continue + if status != "ok": + raise RuntimeError(f"writer failed during {what}:\n{payload}") + return payload + raise TimeoutError(f"writer timed out during {what}") + + def poll_result(self): + """Non-blocking: the pending response or None.""" + try: + status, payload = self.rsp_q.get_nowait() + except queue.Empty: + return None + if status != "ok": + raise RuntimeError(f"writer failed:\n{payload}") + return payload + + def send(self, cmd: str, **args) -> None: + self.cmd_q.put((cmd, args)) + + def call(self, cmd: str, **args): + self.send(cmd, **args) + return self.result(cmd) + + def write_many(self, *items): + return self.call("write_many", items=list(items)) + + def close(self) -> None: + try: + if self.proc.is_alive(): + self.cmd_q.put(("stop", {})) + self.proc.join(10) + finally: + if self.proc.is_alive(): + self.proc.terminate() + self.proc.join(5) + if self.proc.is_alive(): + self.proc.kill() + shutil.rmtree(Path(self.socket).parent, ignore_errors=True) + + +# --------------------------------------------------------------------------- reader side + + +class Reader: + """Test-process reader: a CudaIpcClient plus a notice buffer.""" + + def __init__(self, writer: Writer, streams=None) -> None: + from consumer import CudaIpcClient + + self.client = CudaIpcClient(writer.socket, streams) + self.client.connect() + self.notices: collections.deque = collections.deque() + self.stream = cp.cuda.Stream(non_blocking=True) + + def pump(self, timeout_s: float = 0.05) -> None: + msgs = self.client.read_messages(timeout_s) + assert msgs is not None, "publisher closed the socket" + self.notices.extend(m for m in msgs if m.get("type") == "frame") + + def next_notice(self, stream: str | None = None, timeout_s: float = 10.0) -> dict: + deadline = time.monotonic() + timeout_s + while time.monotonic() < deadline: + for i, n in enumerate(self.notices): + if stream is None or n["stream"] == stream: + del self.notices[i] + return n + self.pump(0.05) + raise TimeoutError("no frame notice arrived") + + def expect_no_notice(self, wait_s: float = 0.4) -> None: + end = time.monotonic() + wait_s + while time.monotonic() < end: + self.pump(0.05) + assert not self.notices, f"unexpected notices {list(self.notices)}" + + def array(self, notice: dict): + return self.client.slots[(notice["stream"], notice["slot"])].array + + def unchanged(self, notice: dict) -> bool: + return self.client.slot_unchanged( + notice["stream"], notice["slot"], notice["slot_generation"] + ) + + def copy_picture(self, notice: dict) -> np.ndarray: + """Copy into reader-owned memory on the reader stream and wait for all GPU work.""" + with self.stream: + dst = cp.empty_like(self.array(notice)) + dst[...] = self.array(notice) + self.stream.synchronize() + return cp.asnumpy(dst) + + def read_checked(self, notice: dict) -> tuple[bool, np.ndarray]: + pic = self.copy_picture(notice) + return self.unchanged(notice), pic + + def close(self) -> None: + self.client.close() + + +class Gate: + """Holds a CUDA stream behind a host function until the test opens it.""" + + def __init__(self) -> None: + self.reached = threading.Event() + self.opened = threading.Event() + self.after_ran = threading.Event() + + def _block(self, _arg) -> None: + self.reached.set() + self.opened.wait(GATE_TIMEOUT_S) + + def _after(self, _arg) -> None: + self.after_ran.set() + + def enqueue(self, stream) -> None: + stream.launch_host_func(self._block, None) + + def enqueue_probe(self, stream) -> None: + """Queue a flag behind everything already queued; it stays unset while closed.""" + stream.launch_host_func(self._after, None) + + def wait_reached(self) -> None: + assert self.reached.wait(GATE_TIMEOUT_S), "gate never reached" + + def assert_closed(self, stream) -> None: + time.sleep(0.15) + assert not self.after_ran.is_set(), "work behind a closed gate already ran" + assert not stream.done, "stream finished while its gate was closed" + + def open(self) -> None: + self.opened.set() + + +@pytest.fixture(autouse=True) +def _watchdog(): + faulthandler.dump_traceback_later(240, exit=True) + yield + faulthandler.cancel_dump_traceback_later() + + +@pytest.fixture +def workdir(): + root = _REPO_ROOT / "tmp" + root.mkdir(exist_ok=True) + path = Path(tempfile.mkdtemp(prefix="gpu_slot_", dir=root)) + yield path + shutil.rmtree(path, ignore_errors=True) + + +@pytest.fixture +def make_writer(workdir): + made: list = [] + + def factory(streams): + w = Writer(streams, workdir) + made.append(w) + return w + + yield factory + for w in made: + w.close() + + +@pytest.fixture +def make_reader(): + made: list = [] + + def factory(writer, streams=None): + r = Reader(writer, streams) + made.append(r) + return r + + yield factory + for r in made: + r.close() + + +# --------------------------------------------------------------------------- scenarios + + +def _check_identity(notice: dict, pic: np.ndarray) -> None: + assert notice["timestamp_ns"] == timestamp_for(notice["seq"]) + np.testing.assert_array_equal(pic, expected_pixels(notice["seq"])) + + +def test_baseline_no_overlap(make_writer, make_reader): + ring = 6 + w = make_writer([("cam", ROWS, COLS, ring)]) + r = make_reader(w) + accepted = 0 + for fid in range(1, 2 * ring + 1): # two laps, every slot rewritten + slot = fid % ring + w.write_many(("cam", slot, fid, None, True)) + n = r.next_notice("cam") + assert (n["seq"], n["slot"]) == (fid, slot) + ok, pic = r.read_checked(n) + assert ok + _check_identity(n, pic) + accepted += 1 + assert accepted == 2 * ring + + +def _gated_full_copy(r: Reader, w: Writer, notice, overwrite_fid, check=True): + """Copy ``notice``'s slot behind a gate; overwrite the slot (no notice) while it is held.""" + gate = Gate() + gate.enqueue(r.stream) + with r.stream: + dst = cp.empty_like(r.array(notice)) + dst[...] = r.array(notice) + gate.enqueue_probe(r.stream) + gate.wait_reached() + gate.assert_closed(r.stream) + if overwrite_fid is not None: + w.write_many(("cam", notice["slot"], overwrite_fid, None, False)) + gate.open() + r.stream.synchronize() + assert gate.after_ran.wait(GATE_TIMEOUT_S) + pic = cp.asnumpy(dst) + unchanged = r.unchanged(notice) + return (unchanged if check else True), pic + + +@pytest.mark.parametrize("check", [True, False], ids=["checked", "negative_control"]) +def test_overwrite_before_copy_completes(make_writer, make_reader, check): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + # Control: same gated path with no overwrite is accepted and exact. + w.write_many(("cam", 0, 100, None, True)) + n0 = r.next_notice("cam") + accepted, pic = _gated_full_copy(r, w, n0, None) + assert accepted + _check_identity(n0, pic) + + w.write_many(("cam", 1, 200, None, True)) + n = r.next_notice("cam") + accepted, pic = _gated_full_copy(r, w, n, 201, check=check) + r.expect_no_notice() # B's notice is withheld + np.testing.assert_array_equal(pic, expected_pixels(201)) # the copy holds B + if check: + assert not accepted, "overwritten slot was accepted" + else: + # Negative control: with the marker check off the wrong picture is accepted. + assert accepted + assert not np.array_equal(pic, expected_pixels(n["seq"])) + + +def _banded_reader(r: Reader, w: Writer, notice, overwrite_fid, kernel: bool): + """Read the slot in BANDS row bands; overwrite it between band 2 and 3.""" + gate = Gate() + src = r.array(notice) + band = ROWS // BANDS + box = cp.ElementwiseKernel( + "raw uint8 x", + "uint8 y", + "y = (unsigned char)(((int)x[i] + (int)x[i ^ 1] + 1) >> 1);", + "test_box_pairs", + ) + with r.stream: + dst = cp.empty_like(src) + for b in range(BANDS): + if b == 2: + gate.enqueue(r.stream) + s, d = src[b * band : (b + 1) * band], dst[b * band : (b + 1) * band] + if kernel: + box(s, d) + else: + d[...] = s + gate.enqueue_probe(r.stream) + gate.wait_reached() + gate.assert_closed(r.stream) + if overwrite_fid is not None: + w.write_many(("cam", notice["slot"], overwrite_fid, None, False)) + gate.open() + r.stream.synchronize() + assert gate.after_ran.wait(GATE_TIMEOUT_S) + return cp.asnumpy(dst) + + +@pytest.mark.parametrize("kernel", [False, True], ids=["copy", "box_kernel"]) +@pytest.mark.parametrize("check", [True, False], ids=["checked", "negative_control"]) +def test_genuine_overlap_mixes_frames(make_writer, make_reader, kernel, check): + ref = expected_box if kernel else expected_pixels + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + # Control: kernel/copy path without overlap is exact (validates expected values). + w.write_many(("cam", 0, 10, None, True)) + n0 = r.next_notice("cam") + pic0 = _banded_reader(r, w, n0, None, kernel) + assert r.unchanged(n0) + np.testing.assert_array_equal(pic0, ref(10)) + + w.write_many(("cam", 1, 20, None, True)) + n = r.next_notice("cam") + pic = _banded_reader(r, w, n, 21, kernel) + r.expect_no_notice() + band = ROWS // BANDS + from_a = [ + np.array_equal( + pic[b * band : (b + 1) * band], ref(20)[b * band : (b + 1) * band] + ) + for b in range(BANDS) + ] + from_b = [ + np.array_equal( + pic[b * band : (b + 1) * band], ref(21)[b * band : (b + 1) * band] + ) + for b in range(BANDS) + ] + print(f"\n[overlap kernel={kernel}] bands from A={from_a} from B={from_b}") + assert from_a == [True, True, False, False] + assert from_b == [False, False, True, True] # a real mixture of two frames + assert not np.array_equal(pic, ref(20)) and not np.array_equal(pic, ref(21)) + accepted = r.unchanged(n) if check else True + if check: + assert not accepted + else: + assert accepted # defect reproduced when the check is disabled + + +def test_single_stream_partial_failure_rejects_earlier_notice(make_writer, make_reader): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + w.write_many(("cam", 2, 50, None, True)) + a = r.next_notice("cam") + gens = w.write_many( + ("cam", 2, 51, ROWS // 3, False) + ) # touches rows, never completes + assert gens[0] > a["slot_generation"] + r.expect_no_notice() + ok, pic = r.read_checked(a) + assert not ok + third = ROWS // 3 + assert np.array_equal( + pic[:third], expected_pixels(51)[:third] + ) # the slot really is torn + assert np.array_equal(pic[third:], expected_pixels(50)[third:]) + # A later completed write gets a fresh generation and is accepted; A stays rejected. + w.write_many(("cam", 2, 52, None, True)) + c = r.next_notice("cam") + ok, pic = r.read_checked(c) + assert ok + _check_identity(c, pic) + assert not r.unchanged(a) + assert c["slot_generation"] > gens[0] + + +def test_stereo_pair_one_eye_fails(make_writer, make_reader): + w = make_writer([("left", ROWS, COLS, 3), ("right", ROWS, COLS, 3)]) + r = make_reader(w) + w.write_many(("left", 0, 60, None, True), ("right", 0, 61, None, True)) + a_l, a_r = r.next_notice("left"), r.next_notice("right") + for n in (a_l, a_r): + ok, pic = r.read_checked(n) + assert ok + _check_identity(n, pic) + # One attempt writes both eyes into slot 0: left completes, right fails partway. + w.write_many(("left", 0, 70, None, True), ("right", 0, 71, ROWS // 2, False)) + b_l = r.next_notice("left") + r.expect_no_notice() # no notice for the failed eye + ok, pic = r.read_checked(b_l) + assert ok + _check_identity(b_l, pic) + for old in (a_l, a_r): + ok, _pic = r.read_checked(old) + assert not ok, f"earlier {old['stream']} notice accepted after the attempt" + + +def _process(r: Reader, n: dict, tally: dict) -> None: + pic = r.copy_picture(n) + if not r.unchanged(n): + tally["discarded"] += 1 + return + tally["accepted"] += 1 + tally["accepted_seqs"].append(n["seq"]) + assert n["slot"] == n["seq"] % 3 + assert n["timestamp_ns"] == timestamp_for(n["seq"]) + if not np.array_equal(pic, expected_pixels(n["seq"])): + tally["mismatch"] += 1 + + +def _tally() -> dict: + return dict(accepted=0, discarded=0, mismatch=0, dropped=0, accepted_seqs=[]) + + +def test_burst_with_stalled_reader(make_writer, make_reader): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + n_frames = 240 + # Reader stalled (never reads the socket); writer is unpaced and must not wait. + t0 = time.monotonic() + res = w.call("burst", stream="cam", first=1, n=n_frames) + wall = time.monotonic() - t0 + print( + f"\n[burst] {n_frames} frames, writer {res['elapsed_s']:.3f}s " + f"({n_frames / res['elapsed_s']:.0f} fps) with a stalled reader, wall {wall:.2f}s" + ) + assert res["elapsed_s"] < 30.0 + time.sleep(0.5) # stall + tally = _tally() + seen = 0 + while seen < n_frames: + n = r.next_notice("cam") + seen += 1 + _process(r, n, tally) + print(f"[burst late drain] {tally}") + assert tally["mismatch"] == 0 + assert tally["accepted"] == 3 # only the latest picture of each slot survives + assert sorted(tally["accepted_seqs"]) == [n_frames - 2, n_frames - 1, n_frames] + assert tally["accepted"] + tally["discarded"] == n_frames + + +def test_burst_with_delayed_and_dropped_notices(make_writer, make_reader): + w = make_writer([("cam", ROWS, COLS, 3)]) + r = make_reader(w) + rng = random.Random(1234) + tally = _tally() + n_frames = 900 + w.send("burst", stream="cam", first=1, n=n_frames) + res = None + live = 0 + deadline = time.monotonic() + 60 + while res is None and time.monotonic() < deadline: + r.pump(0.01) + while r.notices and res is None: + n = r.notices.popleft() + live += 1 + roll = rng.random() + if roll < 0.3: + tally["dropped"] += 1 + elif roll < 0.5: + time.sleep(0.003) # delayed past further rewrites + _process(r, n, tally) + else: + _process(r, n, tally) + res = w.poll_result() + if res is None: + res = w.result("burst") + live_accepted = tally["accepted"] + time.sleep(0.5) # stall, then drain the rest late with no drops + while True: + r.pump(0.2) + if not r.notices: + break + while r.notices: + _process(r, r.notices.popleft(), tally) + print( + f"\n[delayed/dropped] writer {res['elapsed_s']:.3f}s; live={live} " + f"live_accepted={live_accepted} total={tally}" + ) + assert tally["mismatch"] == 0 + assert ( + tally["accepted"] > live_accepted + ) # final late drain accepts the newest pictures + assert res["elapsed_s"] < 60.0 + + +# --------------------------------------------------------------------------- measurements + +# Manual measurements, opt-in: SLOT_MARKER_MEASUREMENTS=1 pytest -s -k measure +_measure = pytest.mark.skipif( + os.environ.get("SLOT_MARKER_MEASUREMENTS") != "1", + reason="manual measurement; set SLOT_MARKER_MEASUREMENTS=1 to run", +) + + +@_measure +def test_measure_marker_call_cost(): + from ipc_protocol import SlotMarkers + + m = SlotMarkers.create("/slotit_bench", [1]) + try: + n = 1_000_000 + t = time.perf_counter_ns() + for _ in range(n): + m.begin_write(0, 0) + bw = (time.perf_counter_ns() - t) / n + t = time.perf_counter_ns() + for _ in range(n): + m.load(0, 0) + ld = (time.perf_counter_ns() - t) / n + t = time.perf_counter_ns() + for _ in range(n): + m.unchanged(0, 0, 1) + un = (time.perf_counter_ns() - t) / n + t = time.perf_counter_ns() + for _ in range(n): + pass + base = (time.perf_counter_ns() - t) / n + print( + f"\n[marker ns/call incl. python call overhead] begin_write={bw:.0f} " + f"load={ld:.0f} unchanged={un:.0f} empty-loop={base:.0f}" + ) + assert m.load(0, 0) == n + finally: + m.close() + + +@_measure +@pytest.mark.parametrize( + "rows,cols,n,label", + [(ROWS, COLS, 3000, "128x64 NV12"), (1984 * 3 // 2, 2560, 300, "2560x1984 NV12")], +) +def test_measure_writer_cost_with_and_without_begin_write( + make_writer, make_reader, rows, cols, n, label +): + w = make_writer([("cam", rows, cols, 3)]) + r = make_reader(w) # attached and stalled: never reads + w.call("bench", stream="cam", n=20, begin=True) # warm-up + out = {} + for rep in range(2): + for begin in (False, True): + out[(begin, rep)] = w.call("bench", stream="cam", n=n, begin=begin) + for (begin, rep), v in out.items(): + print( + f"\n[bench {label} begin_write={begin} rep={rep}] {v['fps']:.0f} fps " + f"mean={v['mean_us']:.1f}us p50={v['p50_us']:.1f}us p99={v['p99_us']:.1f}us" + ) + del r + mean_without = statistics.mean(v["mean_us"] for (b, _), v in out.items() if not b) + mean_with = statistics.mean(v["mean_us"] for (b, _), v in out.items() if b) + print( + f"[bench {label}] mean per-frame: without={mean_without:.1f}us with={mean_with:.1f}us" + ) diff --git a/examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py b/examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py new file mode 100644 index 0000000000..c8f2a9de67 --- /dev/null +++ b/examples/camera_streamer/ipc_protocol/tests/test_slot_markers.py @@ -0,0 +1,270 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Slot marker contract, exercised across real processes.""" + +import multiprocessing +import os +from pathlib import Path +import stat + +import pytest + +from ipc_protocol import ( + LAYOUT_VERSION, + MAX_SLOTS, + MAX_STREAMS, + REGION_SIZE, + SlotMarkers, +) + +SHM_DIR = Path("/dev/shm") + + +def _descriptor(markers): + return (markers.name, markers.size, markers.layout_version, markers.epoch) + + +def _increment_worker(descriptor, stream, slot, count, results): + markers = SlotMarkers.attach(*descriptor) + try: + results.put([markers.begin_write(stream, slot) for _ in range(count)]) + finally: + markers.close() + + +def _begin_once(descriptor, stream, slot, out): + markers = SlotMarkers.attach(*descriptor) + out.put(markers.begin_write(stream, slot)) + markers.close() + + +def _load_once(descriptor, stream, slot, out): + markers = SlotMarkers.attach(*descriptor) + out.put(markers.load(stream, slot)) + markers.close() + + +def _attach_outcome(descriptor, out): + try: + SlotMarkers.attach(*descriptor).close() + out.put("attached") + except RuntimeError as error: + out.put(f"refused: {error}") + + +@pytest.fixture +def ctx(): + return multiprocessing.get_context("spawn") + + +@pytest.fixture +def region(): + markers = SlotMarkers.create("/ipc_protocol_test", [3, 2]) + yield markers + markers.close() + + +def test_child_increment_is_observed_by_parent_and_vice_versa(ctx, region): + out = ctx.Queue() + child = ctx.Process(target=_begin_once, args=(_descriptor(region), 0, 1, out)) + child.start() + assert out.get(timeout=30) == 1 + child.join(timeout=30) + assert region.load(0, 1) == 1 + + assert region.begin_write(0, 1) == 2 + child = ctx.Process(target=_load_once, args=(_descriptor(region), 0, 1, out)) + child.start() + assert out.get(timeout=30) == 2 + child.join(timeout=30) + # Other slots and streams are untouched. + assert region.load(0, 0) == 0 + assert region.load(1, 1) == 0 + + +def test_concurrent_processes_get_unique_consecutive_generations(ctx, region): + processes, per_process = 6, 2000 + results = ctx.Queue() + workers = [ + ctx.Process( + target=_increment_worker, + args=(_descriptor(region), 1, 0, per_process, results), + ) + for _ in range(processes) + ] + for worker in workers: + worker.start() + batches = [results.get(timeout=120) for _ in workers] + for worker in workers: + worker.join(timeout=30) + assert worker.exitcode == 0 + returned = [value for batch in batches for value in batch] + assert len(returned) == processes * per_process + assert len(set(returned)) == len(returned) + assert sorted(returned) == list(range(1, processes * per_process + 1)) + for batch in batches: + assert batch == sorted(batch) + assert region.load(1, 0) == processes * per_process + + +def test_attach_accepts_the_advertised_region(region): + attached = SlotMarkers.attach(*_descriptor(region)) + try: + assert attached.stream_count == 2 + assert [attached.slot_count(0), attached.slot_count(1)] == [3, 2] + assert attached.epoch == region.epoch + assert attached.size == REGION_SIZE + assert attached.layout_version == LAYOUT_VERSION + finally: + attached.close() + + +@pytest.mark.parametrize( + "field, mutate", + [ + ("size", lambda d: (d[0], d[1] + 64, d[2], d[3])), + ("smaller size", lambda d: (d[0], d[1] - 64, d[2], d[3])), + ("layout_version", lambda d: (d[0], d[1], d[2] + 1, d[3])), + ("epoch", lambda d: (d[0], d[1], d[2], d[3] ^ 1)), + ("missing name", lambda d: (d[0] + "_absent", d[1], d[2], d[3])), + ], +) +def test_attach_refuses_mismatched_descriptor(region, field, mutate): + with pytest.raises(RuntimeError): + SlotMarkers.attach(*mutate(_descriptor(region))) + + +def test_attach_refuses_wrong_size_object_and_unready_header(): + name = f"ipc_protocol_test_raw_{os.getpid()}" + path = SHM_DIR / name + try: + # Right size but never initialised: the header was never marked ready. + path.write_bytes(b"\0" * REGION_SIZE) + with pytest.raises(RuntimeError, match="not the advertised region"): + SlotMarkers.attach("/" + name, REGION_SIZE, LAYOUT_VERSION, 1) + # Object whose size differs from the advertised one. + path.write_bytes(b"\0" * (REGION_SIZE // 2)) + with pytest.raises(RuntimeError, match="wrong size"): + SlotMarkers.attach("/" + name, REGION_SIZE, LAYOUT_VERSION, 1) + finally: + path.unlink(missing_ok=True) + + +def test_attach_in_a_fresh_process_reports_refusal(ctx, region): + out = ctx.Queue() + bad_epoch = _descriptor(region)[:3] + (region.epoch ^ 1,) + child = ctx.Process(target=_attach_outcome, args=(bad_epoch, out)) + child.start() + assert out.get(timeout=30).startswith("refused") + child.join(timeout=30) + + +@pytest.mark.parametrize("stream, slot", [(2, 0), (0, 3), (1, 2), (99, 0), (0, 99)]) +def test_out_of_range_indexes_raise(region, stream, slot): + with pytest.raises(IndexError): + region.begin_write(stream, slot) + with pytest.raises(IndexError): + region.load(stream, slot) + with pytest.raises(IndexError): + region.unchanged(stream, slot, 0) + # A refused write advanced nothing. + assert all( + region.load(s, k) == 0 for s in range(2) for k in range(region.slot_count(s)) + ) + + +def test_negative_indexes_are_refused(region): + with pytest.raises((IndexError, TypeError, OverflowError)): + region.begin_write(-1, 0) + with pytest.raises((IndexError, TypeError, OverflowError)): + region.begin_write(0, -1) + + +def test_slot_count_out_of_range_raises(region): + with pytest.raises(IndexError): + region.slot_count(2) + + +@pytest.mark.parametrize( + "counts", + [[], [0], [1, 0], [MAX_SLOTS + 1], [1] * (MAX_STREAMS + 1)], +) +def test_create_refuses_bad_stream_or_slot_counts(counts): + with pytest.raises(ValueError): + SlotMarkers.create("/ipc_protocol_test", counts) + + +def test_create_accepts_the_documented_limits(): + markers = SlotMarkers.create("/ipc_protocol_test", [MAX_SLOTS] * MAX_STREAMS) + try: + assert markers.begin_write(MAX_STREAMS - 1, MAX_SLOTS - 1) == 1 + finally: + markers.close() + + +def test_region_object_is_private_and_named_uniquely(): + first = SlotMarkers.create("/ipc_protocol_test", [1]) + second = SlotMarkers.create("/ipc_protocol_test", [1]) + try: + assert first.name != second.name + assert first.epoch != second.epoch + for markers in (first, second): + assert markers.name.startswith("/ipc_protocol_test_") + path = SHM_DIR / markers.name.lstrip("/") + assert stat.S_IMODE(path.stat().st_mode) == 0o600 + assert path.stat().st_size == REGION_SIZE + finally: + first.close() + second.close() + + +def test_creator_close_removes_the_name_and_is_idempotent(region): + descriptor = _descriptor(region) + reader = SlotMarkers.attach(*descriptor) + path = SHM_DIR / region.name.lstrip("/") + assert path.exists() + region.begin_write(0, 0) + region.close() + region.close() + assert not path.exists() + with pytest.raises(RuntimeError): + SlotMarkers.attach(*descriptor) + # An already attached reader keeps its mapping and its last view. + assert reader.load(0, 0) == 1 + reader.close() + reader.close() + + +def test_closed_region_raises_on_use(region): + reader = SlotMarkers.attach(*_descriptor(region)) + reader.close() + for call in ( + lambda: reader.begin_write(0, 0), + lambda: reader.load(0, 0), + lambda: reader.unchanged(0, 0, 0), + lambda: reader.epoch, + lambda: reader.stream_count, + lambda: reader.slot_count(0), + ): + with pytest.raises(RuntimeError, match="closed"): + call() + + +def test_reader_close_does_not_remove_the_name(region): + reader = SlotMarkers.attach(*_descriptor(region)) + reader.close() + again = SlotMarkers.attach(*_descriptor(region)) + again.close() + + +def test_unchanged_tracks_every_write_attempt(region): + generation = region.begin_write(1, 1) + assert region.unchanged(1, 1, generation) + region.begin_write(1, 1) + assert not region.unchanged(1, 1, generation) + + +def test_generation_exhaustion_limit_is_not_exposed(): + pytest.skip( + "kMaxGeneration (2**62) is not exposed by the module and cannot be reached by incrementing; not tested" + ) From 74343f3b2b1caf2f99c2ac437990f25f34958d50 Mon Sep 17 00:00:00 2001 From: Gareth Morgan Date: Wed, 18 Nov 2026 17:14:09 -0500 Subject: [PATCH 2/4] examples/camera_livekit_bridge: validate each copy with the slot write generation The bridge now maps camera_receiver's shared per-slot write-generation markers through the same native helper the receiver uses, and refuses a publisher that does not provide them. After the GPU copy into the encoder input surface has completed it loads the slot's marker and encodes the picture only if the marker still equals the notified generation; otherwise it drops the picture, counts a slot overrun and prints a prominent error. The same check before the copy only saves work. The notification-age check, its flag, statistics and tests are removed, so there is a single integrity decision. Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Gareth Morgan --- examples/camera_livekit_bridge/README.md | 30 +- .../camera_livekit_bridge/bridge/main.cpp | 11 +- .../bridge/stream_worker.cpp | 108 ++--- .../bridge/stream_worker.hpp | 10 +- .../ipc_client/CMakeLists.txt | 14 + .../ipc_client/cuda_ipc_client.cpp | 37 ++ .../inc/ipc_client/cuda_ipc_client.hpp | 24 +- .../tests/python/test_bridge_slot_age.py | 250 ----------- .../tests/python/test_bridge_slot_marker.py | 392 ++++++++++++++++++ .../tests/slot_age/CMakeLists.txt | 13 - .../tests/slot_age/test_slot_age.cpp | 71 ---- .../video_types/inc/video_types/slot_age.hpp | 37 -- 12 files changed, 523 insertions(+), 474 deletions(-) delete mode 100644 examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py create mode 100644 examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py delete mode 100644 examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt delete mode 100644 examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp delete mode 100644 examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp diff --git a/examples/camera_livekit_bridge/README.md b/examples/camera_livekit_bridge/README.md index 6540688247..4ed1cef9cc 100644 --- a/examples/camera_livekit_bridge/README.md +++ b/examples/camera_livekit_bridge/README.md @@ -22,8 +22,8 @@ sequence is the track's `frame_id`, the sensor start time (when the receiver derived one) is the `user_timestamp` in Unix microseconds, and the sensor counter is the 8-byte `user_data`. The newest picture is encoded and older queued ones are skipped. The receiver overwrites a slot without notice once its ring wraps, so after the GPU copy the -bridge checks for a newer notice for the same slot, or as many newer notices as the ring has other slots, and drops the -picture instead of encoding it (counted as `slot overruns`). The session also answers clock-sync requests that +bridge checks the slot's shared write-generation marker and drops the picture instead of encoding it when the receiver +began a write meanwhile (counted as `slot overruns`). The session also answers clock-sync requests that arrive as LiveKit data messages. ## Integration boundary @@ -33,8 +33,8 @@ wiring (`livekit_publisher/` and the session handling in `bridge/`) is temporary behind transport adapters: a layer that carries camera video and application messages over a selectable network transport and owns sessions, admission limits and feedback. Camera buffer ownership and encode and decode responsibilities belong to the camera interface. A replacement must preserve browser delivery, bounded latency and -safe GPU access. Until receiver slots have read leases, the residual risk described under "Reading the receiver's -slots" applies. +safe GPU access. Until the receiver excludes overlapping slot access instead of letting the bridge detect it, the +residual described under "Reading the receiver's slots" applies. | Current path | Intended owner or replacement | Reuse, adapt or retire | Follow-up and landing condition | | --- | --- | --- | --- | @@ -113,15 +113,21 @@ build/probe/camera_ipc_probe --socket /tmp/camera_receiver_avs1_cuda_ipc.sock \ It prints each stream's plane layout, then per frame the slot, generation, stream sequence, session id, sensor start time and a checksum of the first -pixels. Slots are overwritten without notice when the publisher's ring wraps. +pixels. Slots are overwritten without notice when the publisher's ring wraps; the probe does not validate the pixels it +checksums. ## Reading the receiver's slots The receiver rewrites its GPU ring slots in rotation and never waits for a reader: a slot is overwritten without -notice about `ring_depth` frames after it was announced, and the only signal is a later frame notice. A consumer -therefore has to finish with a slot within that window or skip ahead. The bridge follows this: it uses only the -newest notice, starts the GPU copy at once on its own stream, waits for it to complete, and drops (never encodes) -the picture when later notices show the ring may have wrapped; those frames count as slot overruns in the `[stats]` -line. The notices arrive asynchronously, so this check cannot prove a copy was clean: a stall of most of the ring's -window between the notice and the end of the copy can still publish a picture that mixes two frames under the earlier -frame's metadata. Only a read guard in the receiver, which skips slots a reader holds, would remove that case. +notice about `ring_depth` frames after it was announced, and the replacement notice only arrives after the new write. +It therefore advances a shared write-generation marker for the slot before it touches the pixels and announces that +generation in the frame notice once the write is complete. The bridge maps the markers through the same native helper +the receiver uses (`camera_streamer/ipc_protocol`), uses only the newest notice, starts the GPU copy into the encoder +input surface at once on its own stream, waits for it to complete, and then loads the marker. It encodes the picture +only if the marker still equals the notified generation; otherwise it drops it, prints a prominent error (at most every +5 s per stream) and counts a slot overrun in the `[stats]` line. The same check before the copy only saves work. A +publisher that does not provide write generations is refused at connect time. + +CUDA's memory model does not specify what a read that races a write observes, so the check relies on the race only +changing the bridge's private copy, which it discards. See `camera_streamer/ipc_protocol/README.md` for the ordering +contract and what is and is not guaranteed. diff --git a/examples/camera_livekit_bridge/bridge/main.cpp b/examples/camera_livekit_bridge/bridge/main.cpp index 9c7360373b..cd854b1810 100644 --- a/examples/camera_livekit_bridge/bridge/main.cpp +++ b/examples/camera_livekit_bridge/bridge/main.cpp @@ -33,7 +33,7 @@ void usage() { std::cerr << "usage: camera_livekit_bridge --livekit-url URL --livekit-token-file FILE --stream NAME=TRACK[:DIV] [--stream ...]\n" - " [--socket PATH] [--fps N] [--bitrate-mbps N] [--idr-period N] [--max-notice-age-ms N] [--gpu N] [--source-full-range]\n [--timestamp-basis monotonic_us|capture_monotonic_us|capture_unix_us]\n" + " [--socket PATH] [--fps N] [--bitrate-mbps N] [--idr-period N] [--gpu N] [--source-full-range]\n [--timestamp-basis monotonic_us|capture_monotonic_us|capture_unix_us]\n" " NAME is a stream in camera_receiver's IPC catalog; TRACK is the LiveKit track name egocap expects;\n DIV shrinks the picture on the GPU by that integer factor before encoding.\n"; } @@ -91,8 +91,6 @@ int main(int argc, char** argv) defaults.bitrate_bps = static_cast(std::atof(next().c_str()) * 1e6); else if (arg == "--source-full-range") defaults.source_full_range = true; - else if (arg == "--max-notice-age-ms") - defaults.max_notice_age_ms = static_cast(std::atoi(next().c_str())); else if (arg == "--idr-period") defaults.idr_period = static_cast(std::atoi(next().c_str())); else if (arg == "--timestamp-basis") @@ -200,12 +198,9 @@ int main(int argc, char** argv) std::cerr << "[stats] " << workers[i]->config().track << ": " << (frames - last_frames[i]) / seconds << " fps, " << frames << " frames, " << stats.keyframes.load() << " keyframes, " << stats.skipped.load() << " skipped, " << stats.rejected.load() << " rejected, " - << stats.slot_overruns.load() << " slot overruns, " << stats.stale_slot_reads.load() - << " stale slot reads, encode " << mean_ms << " ms mean, bitrate " - << stats.bitrate_bps.load() / 1000 << " kbps (transport target " + << stats.slot_overruns.load() << " slot overruns, encode " << mean_ms + << " ms mean, bitrate " << stats.bitrate_bps.load() / 1000 << " kbps (transport target " << stats.target_bps.load() / 1000 << " kbps, " << stats.rate_changes.load() << " changes)"; - if (const uint64_t unchecked = stats.unchecked_slot_reads.load(); unchecked > 0) - std::cerr << ", " << unchecked << " slot reads without a notice time to check"; const uint64_t ready_samples = stats.capture_to_ready_samples.load(); if (ready_samples > 0) { diff --git a/examples/camera_livekit_bridge/bridge/stream_worker.cpp b/examples/camera_livekit_bridge/bridge/stream_worker.cpp index 77f5cb8f58..f8e5d3ee97 100644 --- a/examples/camera_livekit_bridge/bridge/stream_worker.cpp +++ b/examples/camera_livekit_bridge/bridge/stream_worker.cpp @@ -6,7 +6,6 @@ #include #include #include -#include #include #include @@ -15,7 +14,6 @@ #include #include #include -#include #include #include @@ -27,27 +25,20 @@ namespace constexpr auto kOverwriteReportInterval = std::chrono::seconds(5); -/// The loud error for a picture that may mix two frames. Rate limited per stream; the stats line keeps the totals. -void report_slot_overwrite_risk(const WorkerConfig& config, - const FrameNotice& notice, - std::size_t slot_count, - bool newer_notice, - bool late_copy, - int64_t age_ns, - int64_t deadline_ns, - uint64_t dropped_total) +/// The loud error for a picture whose slot the publisher rewrote after announcing it. Rate limited per stream; the +/// stats line keeps the totals. +void report_slot_overwrite(const WorkerConfig& config, + const FrameNotice& notice, + std::size_t slot_count, + bool during_copy, + uint64_t dropped_total) { - std::cerr << "\n!!!!!!!!!! SLOT OVERWRITE RISK on stream '" << config.stream << "': picture DROPPED !!!!!!!!!!\n" - << " The receiver's ring (" << slot_count << " slots) may have rewritten slot " << notice.slot - << " (generation " << notice.slot_generation << ") while this bridge was still reading it, so the\n" - << " pixels could be a mix of two frames under the first frame's ID and timestamp.\n"; - if (newer_notice) - std::cerr << " Evidence: a newer notice for the same slot, or a full ring of newer notices, arrived.\n"; - if (late_copy) - std::cerr << " Evidence: the copy finished " << static_cast(age_ns) / 1e6 - << " ms after the notice; the ring wraps in " << static_cast(deadline_ns) / 1e6 << " ms at " - << config.fps << " fps.\n"; std::cerr + << "\n!!!!!!!!!! SLOT OVERWRITE DETECTED on stream '" << config.stream << "': picture DROPPED !!!!!!!!!!\n" + << " The receiver began writing slot " << notice.slot << " (generation " << notice.slot_generation + << ") of its " << slot_count << "-slot ring " + << (during_copy ? "while this bridge was copying it" : "before this bridge started copying it") + << ",\n so the pixels could be a mix of two frames under the first frame's ID and timestamp.\n" << " Cause: this consumer is reading too slowly (starved GPU or CPU), or the receiver is delivering frames\n" << " faster than " << config.fps << " fps. Fix the stall; do not trust recordings of this period.\n" << " Pictures dropped for this reason so far: " << dropped_total << " (reported at most every " @@ -166,22 +157,13 @@ struct StreamWorker::Impl const IpcStream& stream = client.streams().front(); bool need_idr = true; - const int64_t deadline_ns = config.max_notice_age_ms != 0 ? - static_cast(config.max_notice_age_ms) * 1'000'000 : - slot_read_deadline_ns(config.fps, stream.slots.size()); auto last_overwrite_report = std::chrono::steady_clock::now() - kOverwriteReportInterval; uint32_t own_frame_id = 0; uint64_t last_session = 0; FrameNotice notice; - std::optional pending; // a newer notice seen while checking the last slot; used next while (running) { - if (pending) - { - notice = std::move(*pending); - pending.reset(); - } - else if (!client.next_frame(notice, std::chrono::milliseconds(200))) + if (!client.next_frame(notice, std::chrono::milliseconds(200))) continue; // Encode the newest picture: anything queued behind it is older, and a late frame is worse than a skipped // one. @@ -192,6 +174,24 @@ struct StreamWorker::Impl ++stats.skipped; } + // A picture whose slot the publisher rewrote is dropped, counted and reported loudly (rate limited). + const auto drop_overwritten = [&](bool during_copy) + { + ++stats.slot_overruns; + const auto now = std::chrono::steady_clock::now(); + if (now - last_overwrite_report >= kOverwriteReportInterval) + { + last_overwrite_report = now; + report_slot_overwrite(config, notice, stream.slots.size(), during_copy, stats.slot_overruns.load()); + } + }; + // Check before spending a copy on a slot that is already being rewritten. This only saves work; the check + // after the copy is the one that decides. + if (!client.slot_unchanged(notice)) + { + drop_overwritten(/*during_copy=*/false); + continue; + } const IpcSlot& slot = client.slot(notice); const auto* base = static_cast(slot.device_ptr); NvencEncoder::Surface surface; @@ -224,51 +224,19 @@ struct StreamWorker::Impl cudaGetErrorString(copy_status)); } - // The publisher overwrites a slot without notice once its ring wraps. The copy must have finished before - // that, and a newer notice for the same slot, or as many newer notices as the ring has other slots, means - // it may not have. Such a picture is dropped, never encoded. + // The copy must have finished before the marker is read: a write that began during it advanced the marker + // first, so an unchanged marker means no write overlapped the copy. A changed one means the picture may + // mix two frames; it is dropped, never encoded. if (cudaStreamSynchronize(copy_stream) != cudaSuccess) { encoder.release(surface); throw std::runtime_error("GPU copy from the IPC slot did not complete"); } + if (!client.slot_unchanged(notice)) { - bool overwritten = false; - std::size_t newer_count = 0; - FrameNotice newer; - while (client.next_frame(newer, std::chrono::milliseconds(0))) - { - ++newer_count; - if (newer.slot == notice.slot && newer.slot_generation > notice.slot_generation) - overwritten = true; - pending = std::move(newer); - } - if (stream.slots.size() > 1 && newer_count + 1 >= stream.slots.size()) - overwritten = true; - // The copy is done. If it finished later than the publisher needs to wrap its ring, the slot may have - // been overwritten during it, whether or not the replacement notice has arrived yet. - const int64_t copy_done_ns = monotonic_ns(); - const SlotAge age = classify_slot_age(notice.timestamp_ns, copy_done_ns, deadline_ns); - if (age == SlotAge::Unknown && deadline_ns > 0) - ++stats.unchecked_slot_reads; - const bool stale = age == SlotAge::Stale; - if (overwritten || stale) - { - encoder.release(surface); - if (overwritten) - ++stats.slot_overruns; - else - ++stats.stale_slot_reads; - const auto now = std::chrono::steady_clock::now(); - if (now - last_overwrite_report >= kOverwriteReportInterval) - { - last_overwrite_report = now; - report_slot_overwrite_risk(config, notice, stream.slots.size(), overwritten, stale, - copy_done_ns - static_cast(notice.timestamp_ns), - deadline_ns, stats.slot_overruns + stats.stale_slot_reads); - } - continue; - } + encoder.release(surface); + drop_overwritten(/*during_copy=*/true); + continue; } const uint64_t session_id = unsigned_field(notice.metadata, "session_id"); diff --git a/examples/camera_livekit_bridge/bridge/stream_worker.hpp b/examples/camera_livekit_bridge/bridge/stream_worker.hpp index 2d9cf6c4e1..8b37696e8d 100644 --- a/examples/camera_livekit_bridge/bridge/stream_worker.hpp +++ b/examples/camera_livekit_bridge/bridge/stream_worker.hpp @@ -26,9 +26,6 @@ struct WorkerConfig uint32_t fps = 30; uint32_t bitrate_bps = 8'000'000; uint32_t idr_period = 30; - /// A read that finishes later than this after its slot's notice is treated as possibly overwritten and dropped. - /// Zero derives it from the ring: the time the publisher needs to wrap it at `fps`. - uint32_t max_notice_age_ms = 0; /// Integer factor the picture is shrunk by on the GPU before encoding (1 keeps the source size). uint32_t scale_div = 1; /// The IPC pictures are full-range (0-255) rather than limited-range (16-235); the encoded stream signals it. The @@ -44,12 +41,9 @@ struct WorkerStats std::atomic skipped{ 0 }; std::atomic keyframes{ 0 }; std::atomic rejected{ 0 }; - /// Pictures dropped because the publisher may have overwritten the IPC slot during the copy. + /// Pictures dropped because the publisher began writing the IPC slot after announcing the picture, either before + /// the copy or while it ran. std::atomic slot_overruns{ 0 }; - /// Pictures dropped because the copy finished too long after the slot's notice for the pixels to be trusted, and - /// pictures whose notice carried no time to check (those are kept). - std::atomic stale_slot_reads{ 0 }; - std::atomic unchecked_slot_reads{ 0 }; std::atomic encode_us_total{ 0 }; /// The bitrate the encoder is configured for now, and how many times congestion feedback changed it. std::atomic bitrate_bps{ 0 }; diff --git a/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt b/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt index 490db23f5c..d39d3bff48 100644 --- a/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt +++ b/examples/camera_livekit_bridge/ipc_client/CMakeLists.txt @@ -1,6 +1,13 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 +# The slot write-generation markers are shared with camera_receiver and its other readers; the header lives with them. +set(CAMERA_IPC_PROTOCOL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../camera_streamer/ipc_protocol" + CACHE PATH "camera_streamer's ipc_protocol directory") +if(NOT EXISTS "${CAMERA_IPC_PROTOCOL_DIR}/inc/ipc_protocol/slot_markers.hpp") + message(FATAL_ERROR "slot_markers.hpp not found under CAMERA_IPC_PROTOCOL_DIR=${CAMERA_IPC_PROTOCOL_DIR}") +endif() + add_library(ipc_client STATIC cuda_ipc_client.cpp) target_include_directories(ipc_client @@ -8,9 +15,16 @@ target_include_directories(ipc_client $ ) +# The client's own sources include the markers header, and so do its consumers through cuda_ipc_client.hpp. +target_include_directories(ipc_client + PUBLIC + $ +) + target_link_libraries(ipc_client PUBLIC nlohmann_json::nlohmann_json + rt PRIVATE CUDA::cudart ) diff --git a/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp b/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp index 0d6c54980f..f8005c051d 100644 --- a/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp +++ b/examples/camera_livekit_bridge/ipc_client/cuda_ipc_client.cpp @@ -6,6 +6,7 @@ #include #include +#include #include #include #include @@ -83,6 +84,8 @@ void CudaIpcClient::close_all() } } m_streams.clear(); + m_markers.reset(); + m_marker_streams.clear(); if (m_fd >= 0) { ::close(m_fd); @@ -166,6 +169,12 @@ void CudaIpcClient::connect() const auto hello = read_message(std::chrono::seconds(5), timed_out); if (timed_out || hello.value("type", "") != "hello") fail("expected a hello message from the IPC publisher"); + // A publisher that does not advance write generations gives no way to tell that a copy overlapped a rewrite. + const auto features = hello.value("features", nlohmann::json::array()); + if (std::find(features.begin(), features.end(), nlohmann::json("slot_write_generation")) == features.end()) + fail( + "the IPC publisher does not provide slot write generations, so a copied picture cannot be validated; " + "update camera_receiver"); send_message({ { "type", "subscribe" }, { "streams", m_requested } }); const auto subscribed = read_message(std::chrono::seconds(5), timed_out); if (timed_out) @@ -174,9 +183,29 @@ void CudaIpcClient::connect() fail("the IPC subscription was refused: " + subscribed.value("error", std::string("no reason given"))); if (subscribed.value("type", "") != "subscribed") fail("expected a subscribed message from the IPC publisher"); + open_markers(subscribed); open_streams(subscribed); } +void CudaIpcClient::open_markers(const nlohmann::json& subscribed) +{ + const auto descriptor = subscribed.find("slot_markers"); + if (descriptor == subscribed.end() || !descriptor->is_object()) + fail("the IPC publisher did not offer slot write generations"); + try + { + m_markers.emplace(camera_ipc::SlotMarkers::attach( + descriptor->at("name").get(), descriptor->at("size").get(), + descriptor->at("layout_version").get(), descriptor->at("epoch").get())); + } + catch (const nlohmann::json::exception& error) + { + fail(std::string("malformed slot write generation descriptor: ") + error.what()); + } + for (const auto& [name, index] : descriptor->at("stream_indexes").items()) + m_marker_streams[name] = index.get(); +} + void CudaIpcClient::open_streams(const nlohmann::json& subscribed) { for (const auto& entry : subscribed.at("streams")) @@ -221,6 +250,14 @@ const IpcSlot& CudaIpcClient::slot(const FrameNotice& notice) const throw std::out_of_range("unknown IPC stream " + notice.stream); } +bool CudaIpcClient::slot_unchanged(const FrameNotice& notice) const +{ + const auto stream = m_marker_streams.find(notice.stream); + if (!m_markers || stream == m_marker_streams.end()) + throw std::out_of_range("unknown IPC stream " + notice.stream); + return m_markers->unchanged(stream->second, static_cast(notice.slot), notice.slot_generation); +} + bool CudaIpcClient::next_frame(FrameNotice& out, std::chrono::milliseconds timeout) { const auto deadline = std::chrono::steady_clock::now() + timeout; diff --git a/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp b/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp index ddd6dc499e..c7213cb30e 100644 --- a/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp +++ b/examples/camera_livekit_bridge/ipc_client/inc/ipc_client/cuda_ipc_client.hpp @@ -3,12 +3,15 @@ #pragma once +#include #include #include #include #include +#include #include +#include #include namespace camera_bridge @@ -34,8 +37,9 @@ struct IpcStream std::vector slots; }; -/// A frame notification: the slot now holds a new picture. The slot is overwritten without notice when the -/// publisher's ring wraps, so a consumer must finish with it before `slot_generation` advances by the ring size. +/// A frame notification: the slot now holds a new picture, written under generation `slot_generation`. The publisher +/// rewrites a slot without notice when its ring wraps; a copy of it is valid only if `slot_unchanged` still holds after +/// the copy has finished. struct FrameNotice { std::string stream; @@ -50,8 +54,9 @@ struct FrameNotice * @brief Client of camera_receiver's CUDA IPC publisher (newline-delimited JSON on a unix socket). * * Protocol: the publisher sends `hello`; the client answers `subscribe` with stream names (all when empty); the - * publisher replies `subscribed` with one CUDA IPC handle per slot, then sends `frame` notices. Pixels never cross - * the socket. Must run in a different process from the publisher. + * publisher replies `subscribed` with one CUDA IPC handle per slot and the shared write-generation markers, then sends + * `frame` notices. Pixels never cross the socket. Must run in a different process from the publisher. A publisher + * without write generations is refused, because a copy from it cannot be validated. */ class CudaIpcClient { @@ -62,7 +67,8 @@ class CudaIpcClient CudaIpcClient(const CudaIpcClient&) = delete; CudaIpcClient& operator=(const CudaIpcClient&) = delete; - /// Connects, subscribes and opens every slot. Throws std::runtime_error with the reason on failure. + /// Connects, subscribes, maps the write-generation markers and opens every slot. Throws std::runtime_error with + /// the reason on failure, including a publisher that does not provide write generations. void connect(); const std::vector& streams() const @@ -73,6 +79,11 @@ class CudaIpcClient /// The slot a frame notice refers to; throws std::out_of_range for an unknown stream or slot. const IpcSlot& slot(const FrameNotice& notice) const; + /// Whether the publisher has begun no write on the notice's slot since it announced the notice's generation. A + /// copy of the slot may be used only if this is true after every GPU read of the slot has completed; checking + /// before the copy only saves work. + bool slot_unchanged(const FrameNotice& notice) const; + /// Waits up to `timeout` for the next frame notice. Returns false on timeout; throws if the publisher went away. bool next_frame(FrameNotice& out, std::chrono::milliseconds timeout); @@ -80,6 +91,7 @@ class CudaIpcClient nlohmann::json read_message(std::chrono::milliseconds timeout, bool& timed_out); void send_message(const nlohmann::json& message); void open_streams(const nlohmann::json& subscribed); + void open_markers(const nlohmann::json& subscribed); void close_all(); std::string m_socket_path; @@ -87,6 +99,8 @@ class CudaIpcClient int m_fd = -1; std::string m_buffer; std::vector m_streams; + std::optional m_markers; + std::unordered_map m_marker_streams; }; } // namespace camera_bridge diff --git a/examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py b/examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py deleted file mode 100644 index c32722c04d..0000000000 --- a/examples/camera_livekit_bridge/tests/python/test_bridge_slot_age.py +++ /dev/null @@ -1,250 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -"""The bridge drops a picture whose notice is older than the ring's wrap time. - -A separate publisher process serves one NV12 stream through the real CUDA IPC -publisher, stamping each notice with ``time.monotonic_ns()`` (fresh) or ten -seconds earlier (stale). The bridge publishes to a local livekit-server; no -subscriber is needed, because the check is on the bridge's own stderr and -``[stats]`` line. - -Run: python3 test_bridge_slot_age.py -v (about 30 s; needs a CUDA device). - -Environment overrides: LIVEKIT_SERVER_BIN, CAMERA_LIVEKIT_BRIDGE_BIN, -CUPY_PYTHON (interpreter with CuPy for the publisher process). Skipped, never -faked, when a prerequisite is missing. -""" - -from __future__ import annotations - -import os -import re -import shutil -import signal -import socket -import sys -import tempfile -import time -import unittest -import uuid -from pathlib import Path - -from test_bridge_pipeline import ( - BRIDGE_BIN, - RECEIVER_DIR, - RECEIVER_PY, - SERVER_BIN, - _cuda_present, - _Proc, - _python_has, - free_port, - make_token, -) - -FPS = 30 -RING = 6 -WIDTH, HEIGHT = 320, 240 -STREAM, TRACK = "cam", "cam_track" -STALE_AGE_NS = 10_000_000_000 -PUBLISHER_IDENTITY = "bridge-pub" -RUN_S = 8.0 -STATS_TIMEOUT_S = 20.0 - -STATS_RE = re.compile( - r"\[stats\] " + TRACK + r": (?P[\d.]+) fps, (?P\d+) frames, " - r"(?P\d+) keyframes, (?P\d+) skipped, " - r"(?P\d+) rejected, (?P\d+) slot overruns, " - r"(?P\d+) stale slot reads," -) - - -def _cupy_python() -> Path: - override = os.environ.get("CUPY_PYTHON") - if override: - return Path(override) - if _python_has(RECEIVER_PY, "cupy"): - return RECEIVER_PY - return Path(sys.executable) - - -def _skip_reason() -> str | None: - if not SERVER_BIN.is_file(): - return f"livekit-server not found ({SERVER_BIN}); set LIVEKIT_SERVER_BIN" - if not BRIDGE_BIN.is_file(): - return f"camera_livekit_bridge not built ({BRIDGE_BIN}); set CAMERA_LIVEKIT_BRIDGE_BIN" - if not _cuda_present(): - return "no CUDA device (nvidia-smi -L lists no GPU)" - if not _python_has(_cupy_python(), "cupy"): - return f"{_cupy_python()} lacks CuPy; set CUPY_PYTHON" - return None - - -def _publisher_main(socket_path: str, mode: str) -> None: - """Child process: serve one stream and announce frames until terminated.""" - import cupy as cp - - sys.path.insert(0, str(RECEIVER_DIR)) - from cuda_ipc import CudaIpcFramePublisher - - publisher = CudaIpcFramePublisher(socket_path=socket_path, owner_name="slot_age") - y_bytes = WIDTH * HEIGHT - layout = { - "planes": [ - { - "name": "y", - "offset": 0, - "width": WIDTH, - "height": HEIGHT, - "pitch": WIDTH, - }, - { - "name": "uv", - "offset": y_bytes, - "width": WIDTH, - "height": HEIGHT // 2, - "pitch": WIDTH, - }, - ] - } - buffers = [ - cp.full((y_bytes * 3 // 2,), 100 + i, dtype=cp.uint8) for i in range(RING) - ] - publisher.register_stream(STREAM, WIDTH, HEIGHT, "nv12", 0, buffers, layout) - cp.cuda.Device(0).synchronize() - publisher.start() - - stopping = False - - def _stop(*_args: object) -> None: - nonlocal stopping - stopping = True - - signal.signal(signal.SIGTERM, _stop) - print("READY", flush=True) - - seq = 0 - while not stopping: - now = time.monotonic_ns() - publisher.publish( - STREAM, - slot=seq % RING, - slot_generation=seq // RING + 1, - seq=seq, - timestamp_ns=now - STALE_AGE_NS if mode == "stale" else now, - metadata={"session_id": 1, "stream_name": STREAM, "stream_sequence": seq}, - ) - seq += 1 - time.sleep(1.0 / FPS) - publisher.stop() - - -@unittest.skipIf(_skip_reason() is not None, _skip_reason() or "") -class BridgeSlotAgeTest(unittest.TestCase): - @classmethod - def setUpClass(cls): - cls._tmp = Path(tempfile.mkdtemp(prefix="bridge_slot_age_")) - cls.addClassCleanup(shutil.rmtree, cls._tmp, ignore_errors=True) - lk_port = free_port(socket.SOCK_STREAM) - cls.url = f"ws://127.0.0.1:{lk_port}" - cls.room = f"slot-age-{uuid.uuid4().hex[:10]}" - server = _Proc( - "livekit", - [ - str(SERVER_BIN), - "--dev", - "--bind", - "127.0.0.1", - "--node-ip", - "127.0.0.1", - "--port", - str(lk_port), - "--rtc.tcp_port", - str(free_port(socket.SOCK_STREAM)), - "--udp-port", - str(free_port(socket.SOCK_DGRAM)), - ], - cls._tmp, - ) - cls.addClassCleanup(server.stop) - server.wait_for("starting LiveKit server", 20) - deadline = time.monotonic() + 20 - while time.monotonic() < deadline: - try: - socket.create_connection(("127.0.0.1", lk_port), timeout=1).close() - break - except OSError: - time.sleep(0.2) - else: - raise AssertionError("livekit-server never accepted connections") - token = cls._tmp / "pub.token" - token.write_text(make_token(cls.room, PUBLISHER_IDENTITY, True)) - cls.token = token - - def _run(self, mode: str) -> str: - """Run publisher + bridge for RUN_S; return the bridge's output.""" - sock = self._tmp / f"{mode}.sock" - publisher = _Proc( - f"publisher_{mode}", - [ - str(_cupy_python()), - str(Path(__file__).resolve()), - "--publisher", - str(sock), - mode, - ], - self._tmp, - ) - self.addCleanup(publisher.stop) - publisher.wait_for("READY", 60) - bridge = _Proc( - f"bridge_{mode}", - [ - str(BRIDGE_BIN), - "--livekit-url", - self.url, - "--livekit-token-file", - str(self.token), - "--socket", - str(sock), - "--fps", - str(FPS), - "--stream", - f"{STREAM}={TRACK}", - ], - self._tmp, - ) - self.addCleanup(bridge.stop) - bridge.wait_for("publishing", 60) - time.sleep(RUN_S) - bridge.wait_for("[stats]", STATS_TIMEOUT_S) - text = bridge.text() - bridge.stop() - return text - - def _stats(self, text: str) -> dict[str, int]: - matches = list(STATS_RE.finditer(text)) - self.assertTrue(matches, f"no [stats] line for {TRACK}:\n{text[-3000:]}") - last = matches[-1] - return {k: int(float(v)) for k, v in last.groupdict().items()} - - def test_stale_notice_is_dropped_loudly(self): - text = self._run("stale") - self.assertIn("SLOT OVERWRITE RISK", text) - stats = self._stats(text) - self.assertGreater(stats["stale"], 0, text[-3000:]) - self.assertEqual(stats["frames"], 0, "a stale picture was published") - - def test_fresh_notice_is_published(self): - text = self._run("fresh") - self.assertNotIn("SLOT OVERWRITE RISK", text) - stats = self._stats(text) - self.assertEqual(stats["stale"], 0, text[-3000:]) - self.assertGreater(stats["frames"], 0, text[-3000:]) - - -if __name__ == "__main__": - if len(sys.argv) == 4 and sys.argv[1] == "--publisher": - _publisher_main(sys.argv[2], sys.argv[3]) - else: - unittest.main() diff --git a/examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py b/examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py new file mode 100644 index 0000000000..aedf35a33f --- /dev/null +++ b/examples/camera_livekit_bridge/tests/python/test_bridge_slot_marker.py @@ -0,0 +1,392 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""The bridge encodes only pictures whose slot write generation is unchanged. + +A separate publisher process serves one NV12 stream through the real CUDA IPC +publisher. Each notice carries the generation returned by ``begin_write``; the +"stale" notices are announced after the same slot's marker has advanced again, +which is what a rewrite that began after the announcement looks like. The +bridge publishes to a local livekit-server; no subscriber is needed, because +the checks are on the bridge's own stderr and ``[stats]`` line. A small relay +between the bridge and the real publisher covers a publisher that lacks the +feature and a damaged marker descriptor. + +Run: python3 test_bridge_slot_marker.py -v (about 60 s; needs a CUDA device). + +Environment overrides: LIVEKIT_SERVER_BIN, CAMERA_LIVEKIT_BRIDGE_BIN, +CUPY_PYTHON (interpreter with CuPy for the publisher process). Skipped, never +faked, when a prerequisite is missing. +""" + +from __future__ import annotations + +import json +import os +import re +import shutil +import signal +import socket +import subprocess +import sys +import tempfile +import threading +import time +import unittest +import uuid +from pathlib import Path + +from test_bridge_pipeline import ( + BRIDGE_BIN, + RECEIVER_DIR, + RECEIVER_PY, + SERVER_BIN, + _cuda_present, + _Proc, + _python_has, + free_port, + make_token, +) + +FPS = 30 +RING = 6 +WIDTH, HEIGHT = 320, 240 +STREAM, TRACK = "cam", "cam_track" +PUBLISHER_IDENTITY = "bridge-pub" +RUN_S = 6.0 +STATS_TIMEOUT_S = 20.0 +EXIT_TIMEOUT_S = 30.0 + +STATS_RE = re.compile( + r"\[stats\] " + TRACK + r": (?P[\d.]+) fps, (?P\d+) frames, " + r"(?P\d+) keyframes, (?P\d+) skipped, " + r"(?P\d+) rejected, (?P\d+) slot overruns," +) + + +def _cupy_python() -> Path: + override = os.environ.get("CUPY_PYTHON") + if override: + return Path(override) + if _python_has(RECEIVER_PY, "cupy"): + return RECEIVER_PY + return Path(sys.executable) + + +def _skip_reason() -> str | None: + if not SERVER_BIN.is_file(): + return f"livekit-server not found ({SERVER_BIN}); set LIVEKIT_SERVER_BIN" + if not BRIDGE_BIN.is_file(): + return f"camera_livekit_bridge not built ({BRIDGE_BIN}); set CAMERA_LIVEKIT_BRIDGE_BIN" + if not _cuda_present(): + return "no CUDA device (nvidia-smi -L lists no GPU)" + if not _python_has(_cupy_python(), "cupy"): + return f"{_cupy_python()} lacks CuPy; set CUPY_PYTHON" + return None + + +def _publisher_main(socket_path: str, mode: str) -> None: + """Child process: serve one stream and announce frames until terminated. + + ``valid`` announces the generation of the write just made. ``stale`` + advances the slot's marker a second time before announcing, so every + notice names a generation the slot has already left. ``mixed`` alternates. + """ + import cupy as cp + + sys.path.insert(0, str(RECEIVER_DIR)) + from cuda_ipc import CudaIpcFramePublisher + + publisher = CudaIpcFramePublisher(socket_path=socket_path, owner_name="slot_marker") + y_bytes = WIDTH * HEIGHT + layout = { + "planes": [ + { + "name": "y", + "offset": 0, + "width": WIDTH, + "height": HEIGHT, + "pitch": WIDTH, + }, + { + "name": "uv", + "offset": y_bytes, + "width": WIDTH, + "height": HEIGHT // 2, + "pitch": WIDTH, + }, + ] + } + buffers = [ + cp.full((y_bytes * 3 // 2,), 100 + i, dtype=cp.uint8) for i in range(RING) + ] + publisher.register_stream(STREAM, WIDTH, HEIGHT, "nv12", 0, buffers, layout) + cp.cuda.Device(0).synchronize() + publisher.start() + + stopping = False + + def _stop(*_args: object) -> None: + nonlocal stopping + stopping = True + + signal.signal(signal.SIGTERM, _stop) + print("READY", flush=True) + + seq = 0 + while not stopping: + slot = seq % RING + generation = publisher.begin_write(STREAM, slot) + if mode == "stale" or (mode == "mixed" and seq % 2 == 1): + publisher.begin_write(STREAM, slot) + publisher.publish( + STREAM, + slot=slot, + slot_generation=generation, + seq=seq, + timestamp_ns=time.monotonic_ns(), + metadata={"session_id": 1, "stream_name": STREAM, "stream_sequence": seq}, + ) + seq += 1 + time.sleep(1.0 / FPS) + publisher.stop() + + +class _Relay: + """Forwards one bridge connection to a real publisher, editing its replies. + + The handshake is ``hello``, ``subscribe``, ``subscribed``; ``edit`` is + applied to the parsed ``subscribed`` message and ``edit_hello`` to the + ``hello``. Either may be None to forward unchanged. + """ + + def __init__(self, path: Path, upstream: Path, edit_hello=None, edit=None): + self.path = path + self._upstream = upstream + self._edit_hello = edit_hello + self._edit = edit + self._server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self._server.bind(str(path)) + self._server.listen(1) + self._thread = threading.Thread(target=self._serve, daemon=True) + self._thread.start() + + @staticmethod + def _line(sock: socket.socket) -> bytes: + data = b"" + while not data.endswith(b"\n"): + chunk = sock.recv(1) + if not chunk: + raise ConnectionError("peer closed") + data += chunk + return data + + def _serve(self) -> None: + try: + down, _ = self._server.accept() + up = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + up.connect(str(self._upstream)) + with down, up: + hello = json.loads(self._line(up)) + if self._edit_hello: + self._edit_hello(hello) + down.sendall(json.dumps(hello).encode() + b"\n") + up.sendall(self._line(down)) + subscribed = json.loads(self._line(up)) + if self._edit: + self._edit(subscribed) + down.sendall(json.dumps(subscribed).encode() + b"\n") + time.sleep(2.0) + except (OSError, ConnectionError, ValueError): + pass + + def close(self) -> None: + self._server.close() + + +@unittest.skipIf(_skip_reason() is not None, _skip_reason() or "") +class BridgeSlotMarkerTest(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls._tmp = Path(tempfile.mkdtemp(prefix="bridge_slot_marker_")) + cls.addClassCleanup(shutil.rmtree, cls._tmp, ignore_errors=True) + lk_port = free_port(socket.SOCK_STREAM) + cls.url = f"ws://127.0.0.1:{lk_port}" + cls.room = f"slot-marker-{uuid.uuid4().hex[:10]}" + server = _Proc( + "livekit", + [ + str(SERVER_BIN), + "--dev", + "--bind", + "127.0.0.1", + "--node-ip", + "127.0.0.1", + "--port", + str(lk_port), + "--rtc.tcp_port", + str(free_port(socket.SOCK_STREAM)), + "--udp-port", + str(free_port(socket.SOCK_DGRAM)), + ], + cls._tmp, + ) + cls.addClassCleanup(server.stop) + server.wait_for("starting LiveKit server", 20) + deadline = time.monotonic() + 20 + while time.monotonic() < deadline: + try: + socket.create_connection(("127.0.0.1", lk_port), timeout=1).close() + break + except OSError: + time.sleep(0.2) + else: + raise AssertionError("livekit-server never accepted connections") + token = cls._tmp / "pub.token" + token.write_text(make_token(cls.room, PUBLISHER_IDENTITY, True)) + cls.token = token + + def _start_publisher(self, mode: str) -> Path: + sock = self._tmp / f"{mode}_{uuid.uuid4().hex[:6]}.sock" + publisher = _Proc( + f"publisher_{mode}", + [str(_cupy_python()), str(Path(__file__).resolve()), "--publisher"] + + [str(sock), mode], + self._tmp, + ) + self.addCleanup(publisher.stop) + publisher.wait_for("READY", 60) + return sock + + def _bridge(self, name: str, sock: Path) -> _Proc: + bridge = _Proc( + name, + [ + str(BRIDGE_BIN), + "--livekit-url", + self.url, + "--livekit-token-file", + str(self.token), + "--socket", + str(sock), + "--fps", + str(FPS), + "--stream", + f"{STREAM}={TRACK}", + ], + self._tmp, + ) + self.addCleanup(bridge.stop) + return bridge + + def _run(self, mode: str) -> str: + """Run publisher + bridge for RUN_S; return the bridge's output.""" + bridge = self._bridge(f"bridge_{mode}", self._start_publisher(mode)) + bridge.wait_for("publishing", 60) + time.sleep(RUN_S) + bridge.wait_for("[stats]", STATS_TIMEOUT_S) + text = bridge.text() + bridge.stop() + return text + + def _stats(self, text: str) -> dict[str, int]: + matches = list(STATS_RE.finditer(text)) + self.assertTrue(matches, f"no [stats] line for {TRACK}:\n{text[-3000:]}") + last = matches[-1] + return {k: int(float(v)) for k, v in last.groupdict().items()} + + def _refused(self, sock: Path, name: str) -> str: + """Run the bridge against ``sock``; it must exit non-zero; return its output.""" + bridge = self._bridge(name, sock) + try: + bridge.proc.wait(timeout=EXIT_TIMEOUT_S) + except subprocess.TimeoutExpired: + self.fail(f"bridge did not exit:\n{bridge.text()[-3000:]}") + self.assertNotEqual(bridge.proc.returncode, 0, bridge.text()[-3000:]) + text = bridge.text() + self.assertNotRegex(text, r"\d+ frames", "the bridge streamed anyway") + return text + + def test_unchanged_marker_is_encoded(self): + text = self._run("valid") + self.assertNotIn("SLOT OVERWRITE", text) + stats = self._stats(text) + self.assertEqual(stats["overruns"], 0, text[-3000:]) + self.assertGreater(stats["frames"], 0, text[-3000:]) + + def test_advanced_marker_is_dropped_loudly(self): + text = self._run("stale") + self.assertIn("SLOT OVERWRITE", text) + stats = self._stats(text) + self.assertGreater(stats["overruns"], 0, text[-3000:]) + self.assertEqual(stats["frames"], 0, "an overwritten picture was encoded") + + def test_only_the_overwritten_pictures_are_dropped(self): + text = self._run("mixed") + self.assertIn("SLOT OVERWRITE", text) + stats = self._stats(text) + self.assertGreater(stats["overruns"], 0, text[-3000:]) + self.assertGreater(stats["frames"], 0, text[-3000:]) + + def test_publisher_without_write_generations_is_refused(self): + upstream = self._start_publisher("valid") + + def drop_feature(hello: dict) -> None: + hello["features"] = [ + f for f in hello["features"] if f != "slot_write_generation" + ] + + relay = _Relay(self._tmp / "nofeature.sock", upstream, edit_hello=drop_feature) + self.addCleanup(relay.close) + text = self._refused(relay.path, "bridge_nofeature") + self.assertIn("does not provide slot write generations", text) + + def test_missing_marker_descriptor_is_refused(self): + upstream = self._start_publisher("valid") + relay = _Relay( + self._tmp / "nodesc.sock", + upstream, + edit=lambda msg: msg.pop("slot_markers", None), + ) + self.addCleanup(relay.close) + text = self._refused(relay.path, "bridge_nodesc") + self.assertIn("did not offer slot write generations", text) + + def test_wrong_epoch_descriptor_is_refused(self): + upstream = self._start_publisher("valid") + + def wrong_epoch(msg: dict) -> None: + msg["slot_markers"]["epoch"] += 1 + + relay = _Relay(self._tmp / "epoch.sock", upstream, edit=wrong_epoch) + self.addCleanup(relay.close) + text = self._refused(relay.path, "bridge_epoch") + self.assertIn("[error]", text) + self.assertIn("not the advertised region", text) + + def test_garbled_descriptors_are_refused(self): + edits = { + "layout": lambda d: d.update(layout_version=d["layout_version"] + 1), + "size": lambda d: d.update(size=d["size"] + 8), + "name": lambda d: d.update(name="/no_such_marker_region"), + "fields": lambda d: d.pop("epoch"), + "type": lambda d: d.update(size="large"), + } + upstream = self._start_publisher("valid") + for label, edit in edits.items(): + with self.subTest(label): + relay = _Relay( + self._tmp / f"garbled_{label}.sock", + upstream, + edit=lambda msg, edit=edit: edit(msg["slot_markers"]), + ) + self.addCleanup(relay.close) + text = self._refused(relay.path, f"bridge_garbled_{label}") + self.assertIn("[error]", text) + + +if __name__ == "__main__": + if len(sys.argv) == 4 and sys.argv[1] == "--publisher": + _publisher_main(sys.argv[2], sys.argv[3]) + else: + unittest.main() diff --git a/examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt b/examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt deleted file mode 100644 index 51a7fbac02..0000000000 --- a/examples/camera_livekit_bridge/tests/slot_age/CMakeLists.txt +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -add_executable(test_slot_age test_slot_age.cpp) - -target_link_libraries(test_slot_age - PRIVATE - camera_livekit_bridge::video_types -) - -target_compile_options(test_slot_age PRIVATE -Wall -Wextra) - -add_test(NAME slot_age COMMAND test_slot_age) diff --git a/examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp b/examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp deleted file mode 100644 index 5adeaf56d0..0000000000 --- a/examples/camera_livekit_bridge/tests/slot_age/test_slot_age.cpp +++ /dev/null @@ -1,71 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -#include - -#include -#include - -namespace -{ - -int g_failures = 0; - -void check(bool condition, const char* what) -{ - if (!condition) - { - std::cerr << "FAILED: " << what << "\n"; - ++g_failures; - } -} - -} // namespace - -int main() -{ - using camera_bridge::classify_slot_age; - using camera_bridge::slot_read_deadline_ns; - using camera_bridge::SlotAge; - - // The publisher wraps a ring of N slots after N - 1 further frames. - check(slot_read_deadline_ns(30, 6) == 5 * 1'000'000'000LL / 30, "6 slots at 30 fps"); - check(slot_read_deadline_ns(30, 6) >= 166'666'666 && slot_read_deadline_ns(30, 6) <= 166'666'667, - "6 slots at 30 fps is about 166.67 ms"); - check(slot_read_deadline_ns(60, 3) == 2 * 1'000'000'000LL / 60, "3 slots at 60 fps"); - check(slot_read_deadline_ns(30, 2) == 1'000'000'000LL / 30, "2 slots is the smallest usable ring"); - check(slot_read_deadline_ns(0, 6) == 0, "fps 0 disables the check"); - check(slot_read_deadline_ns(30, 1) == 0, "a one-slot ring disables the check"); - check(slot_read_deadline_ns(30, 0) == 0, "an empty ring disables the check"); - - const int64_t now = 10'000'000'000; - const int64_t deadline = 166'000'000; - const uint64_t notice = static_cast(now - 100'000'000); - - check(classify_slot_age(notice, now, deadline) == SlotAge::Fresh, "well within the deadline is fresh"); - check(classify_slot_age(static_cast(now), now, deadline) == SlotAge::Fresh, "age 0 is fresh"); - check(classify_slot_age(static_cast(now - deadline), now, deadline) == SlotAge::Fresh, - "exactly at the deadline is fresh"); - check(classify_slot_age(static_cast(now - deadline - 1), now, deadline) == SlotAge::Stale, - "one nanosecond past the deadline is stale"); - check(classify_slot_age(static_cast(now - 5'000'000'000), now, deadline) == SlotAge::Stale, - "long past the deadline is stale"); - - check(classify_slot_age(0, now, deadline) == SlotAge::Unknown, "no notice time is unknown"); - check(classify_slot_age(static_cast(now + 1), now, deadline) == SlotAge::Unknown, - "a notice from the future is unknown"); - check(classify_slot_age(static_cast(now + 5'000'000'000), now, deadline) == SlotAge::Unknown, - "a notice far in the future is unknown"); - check(classify_slot_age(notice, now, 0) == SlotAge::Unknown, "deadline 0 disables the check"); - check(classify_slot_age(notice, now, -1) == SlotAge::Unknown, "a negative deadline disables the check"); - // Even a very old notice is not judged when the check is off. - check(classify_slot_age(1, now, 0) == SlotAge::Unknown, "deadline 0 beats an ancient notice"); - - if (g_failures != 0) - { - std::cerr << g_failures << " check(s) failed\n"; - return 1; - } - std::cout << "slot_age: all checks passed\n"; - return 0; -} diff --git a/examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp b/examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp deleted file mode 100644 index 63deb76c9a..0000000000 --- a/examples/camera_livekit_bridge/video_types/inc/video_types/slot_age.hpp +++ /dev/null @@ -1,37 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -#pragma once - -#include -#include - -namespace camera_bridge -{ - -/// How long after its notice a slot is still safe to read: the time the publisher needs to write the other slots of -/// its ring and come back to this one, at the stream's nominal rate. Zero when the rate or ring is unusable. -inline int64_t slot_read_deadline_ns(uint32_t fps, std::size_t slot_count) -{ - if (fps == 0 || slot_count < 2) - return 0; - return static_cast(slot_count - 1) * 1'000'000'000 / static_cast(fps); -} - -enum class SlotAge -{ - Fresh, ///< the read finished within the deadline - Stale, ///< the read finished after the deadline: the slot may have been overwritten during it - Unknown, ///< the notice has no usable time (missing, or later than now): nothing can be said -}; - -/// Classify a read that finished at `now_ns` (CLOCK_MONOTONIC) of the slot announced at `notice_ns` (the publisher's -/// CLOCK_MONOTONIC on the same host). A deadline of zero disables the check. -inline SlotAge classify_slot_age(uint64_t notice_ns, int64_t now_ns, int64_t deadline_ns) -{ - if (deadline_ns <= 0 || notice_ns == 0 || static_cast(notice_ns) > now_ns) - return SlotAge::Unknown; - return now_ns - static_cast(notice_ns) > deadline_ns ? SlotAge::Stale : SlotAge::Fresh; -} - -} // namespace camera_bridge From bc45a16ce229e5138826d4381e86c5e31782c3ce Mon Sep 17 00:00:00 2001 From: Gareth Morgan Date: Wed, 18 Nov 2026 17:21:38 -0500 Subject: [PATCH 3/4] ipc_protocol: document the marker check as interim protection CUDA treats a read racing a write as undefined behavior, so the check is a stopgap that makes overlaps visible rather than a documented guarantee. The writer-side exclusion that would replace it is follow-up work. Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Gareth Morgan --- .../camera_streamer/ipc_protocol/README.md | 23 +++++++++++++------ 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/examples/camera_streamer/ipc_protocol/README.md b/examples/camera_streamer/ipc_protocol/README.md index 3f3102ff22..0bb8403118 100644 --- a/examples/camera_streamer/ipc_protocol/README.md +++ b/examples/camera_streamer/ipc_protocol/README.md @@ -61,13 +61,22 @@ platforms refuse to initialise rather than fall back to non-atomic access. This holds for a plain copy and for a kernel that reads the slot, provided each has finished before the load. -CUDA's memory model treats an unsynchronized read and write of the same bytes as a -data race and does not specify what the reader then observes. This design relies -on the race affecting only the contents of the reader's private copy, which the -marker check discards; CUDA does not document a stronger guarantee for it, so the -check is validated by tests rather than proven from the memory model. A reader -needing a documented guarantee needs the writer to exclude overlapping access -instead of detecting it. +## Status: interim protection + +CUDA's memory model makes an unsynchronized read and write of the same bytes a +data race with undefined behavior, and CUDA documents no bound on the effect for +a copy or kernel whose source is modified concurrently. This design relies on +the race only changing the reader's private copy, which the marker check +discards. The tests exercise that and the check has never accepted a mismatched +picture in them, but it is not proven from the memory model. + +It is an interim measure: it makes every detected overlap visible and drops the +picture, and it narrows the window a reader can be hurt in, but it is not a +documented guarantee. The proper fix is for the writer to exclude overlapping +access, for example short reader reservations that the writer honours before +reusing a slot; that is planned as follow-up work and would replace the marker +check. Until then, treat a picture that passed the check as very likely intact, +not as proven intact. ## Build From 787b9be501b2f16d6bd5b1967841a30884060ba6 Mon Sep 17 00:00:00 2001 From: Gareth Morgan Date: Wed, 18 Nov 2026 17:21:52 -0500 Subject: [PATCH 4/4] camera_livekit_bridge: document the slot check as interim protection Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Gareth Morgan --- examples/camera_livekit_bridge/README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/examples/camera_livekit_bridge/README.md b/examples/camera_livekit_bridge/README.md index 4ed1cef9cc..b924d69a4f 100644 --- a/examples/camera_livekit_bridge/README.md +++ b/examples/camera_livekit_bridge/README.md @@ -128,6 +128,9 @@ only if the marker still equals the notified generation; otherwise it drops it, 5 s per stream) and counts a slot overrun in the `[stats]` line. The same check before the copy only saves work. A publisher that does not provide write generations is refused at connect time. -CUDA's memory model does not specify what a read that races a write observes, so the check relies on the race only -changing the bridge's private copy, which it discards. See `camera_streamer/ipc_protocol/README.md` for the ordering -contract and what is and is not guaranteed. +This is interim protection, not a documented guarantee. CUDA's memory model makes a read that races a write undefined +behavior, and the check relies on the race only changing the bridge's private copy, which it discards. It makes every +detected overlap visible and narrows the window, but a picture that passed it is very likely intact rather than proven +intact. The proper fix is for the receiver to exclude overlapping access (short reader reservations it honours), planned +as follow-up work that would replace this check. See `camera_streamer/ipc_protocol/README.md` for the ordering +contract.