diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt index 9cc4772373..8018cea070 100644 --- a/src/core/CMakeLists.txt +++ b/src/core/CMakeLists.txt @@ -19,6 +19,15 @@ add_subdirectory(oxr_utils) # Build Plugin Manager add_subdirectory(plugin_manager) +# Camera interface: which pool slot holds which frame, and who may still read it +# (standard library only) +add_subdirectory(camera_core) + +# Camera interface: shared memory and the socket between processes +if(CMAKE_SYSTEM_NAME STREQUAL "Linux") + add_subdirectory(camera_ipc) +endif() + # Build OXR library (depends on oxr_utils for types) add_subdirectory(oxr) diff --git a/src/core/camera_core/AGENTS.md b/src/core/camera_core/AGENTS.md new file mode 100644 index 0000000000..4ac71f223a --- /dev/null +++ b/src/core/camera_core/AGENTS.md @@ -0,0 +1,20 @@ + + +# Agent notes — `camera_core` + +**CRITICAL (non-optional):** Before editing this package, complete the mandatory **`AGENTS.md` preflight** in [`../../../AGENTS.md`](../../../AGENTS.md) (read every applicable `AGENTS.md` on your paths, not just this file). + +Read [`README.md`](README.md) for the terms (stream, group, window, order, lease) before changing behaviour. + +- **Standard library only.** No slot memory, sockets, logging or platform headers here; that keeps the module building and tested on every platform. Memory and connections live in `camera_ipc`. +- **One type or field per concept.** A codec is not a pixel format, each plane has its own layout, counters are per group. Do not give a field a second meaning, and do not carry a type over from other code without modelling it for this interface. +- **Nothing ahead of its user.** A memory kind, pixel format or flag is added in the change that brings the pool or backend that needs it. +- **One lock per group.** A camera must never wait for another camera's readers, so nothing takes two groups' locks, and the registry lock is held only to look a group up. +- **`EventSink::send_event` runs on the capture path with its group's lock held.** It is `noexcept` and must not block or call back into the publisher. Callbacks to a backend (`SlotFreeCallback`) run outside the lock. +- **Reject bad input where it enters, with one check.** `problem_with` is the description check for both sides of a connection: `add_group` uses it for what a backend declares and the reader for what it was sent. Add a rule there, not in one of its callers. Sizes from another process are compared with subtraction and division, never summed. +- **Nothing is held for a newest-order reader that is not asking.** A lease taken when a frame set is published is old by the time a busy reader comes for it, and blocks the newer ones. Only `request_newest` and a release that follows it lease for such a reader. +- **Reserve, tell, activate.** `subscribe` sends nothing; the reader is told what it subscribed to, then `activate` starts delivery. Do not send from `subscribe`. +- **Publish, lease and release are three facts.** Ready, held and done (see the README) are not folded into one flag, and a reader going away is not treated as proof that its work on a slot has finished for any memory other than host memory. diff --git a/src/core/camera_core/CMakeLists.txt b/src/core/camera_core/CMakeLists.txt new file mode 100644 index 0000000000..8ce91de360 --- /dev/null +++ b/src/core/camera_core/CMakeLists.txt @@ -0,0 +1,6 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +add_subdirectory(cpp) diff --git a/src/core/camera_core/README.md b/src/core/camera_core/README.md new file mode 100644 index 0000000000..90719f5355 --- /dev/null +++ b/src/core/camera_core/README.md @@ -0,0 +1,132 @@ + + +# Camera interface: core + +The camera interface is the one place Isaac Capture applications get camera frames from. Each +camera is owned by one process, which keeps its frames in fixed pools of shared buffers; viewers, +encoders and recorders in other processes read those buffers in place. + +This module is the part with no memory and no sockets in it: it decides which pool slot holds +which frame set and who may still read it. It uses the standard library only. The shared memory +behind the slots and the connection to other processes live in [`camera_ipc`](../camera_ipc). + +## Terms + +- **Stream**: one sensor's images, or one encoded video stream. It has a pool of **slots**; a + slot holds one image, or one access unit when the stream is encoded. +- **Group**: one or more streams captured together, such as a stereo pair or a triggered rig. + A group publishes one **frame set** at a time: one image per stream, under one sequence number. +- **Window**: how many frame sets are kept for a reader at a time, unread and held together. +- **Order**: `NEWEST` hands the reader the newest frame set there is each time it asks, and skips + the rest (a viewer, a live encoder). `IN_ORDER` sends every frame set in sequence (a recorder). + The default is `NEWEST` for a window of one and `IN_ORDER` otherwise. +- **Lease**: a reader's hold on a frame set. Its slots are not reused until the reader releases + it or goes away. +- **Session**: one run of a group, from the plugin starting to publish it until that plugin + ends, named by a random `session_id` in the group's description. +- **Sequence**: a frame set's place among the group's captures in the session. It is the same + for every reader, so a reader that skips sees a gap, and with the session id it names a + capture for good. +- **Generation**: counts restarts of the camera within the session, so a reader can tell a + restart from a skip. A restart does not reset the sequence. + +## How frames move + +A backend gets a slot in one of two ways, then publishes: + +```cpp +// The backend writes the image itself. +auto slot = publisher.acquire_slot(group, stream); // nothing: every slot is in use, drop the frame +// ... write the pixels into that slot ... +publisher.publish(group, images, timeline); + +// The camera SDK owns the buffers and picked one. +publisher.claim_slot(group, stream, slot_the_sdk_filled); +publisher.publish(group, images, timeline); +``` + +For the second way, `set_slot_free_callback` tells the backend the moment a slot is held by +nobody, so the buffer can go back to the SDK. A group uses one way or the other: once it has +that callback, its slots are handed out with `claim_slot` only. + +A reader subscribes with a window and an order, receives `FrameEvent`s through an `EventSink`, +and returns each one with `release`. Events carry slot indices, the frame set's timeline and the +number of frame sets the reader skipped. A slow reader skips; it never slows capture or another +reader, and no call blocks on a reader. Each group has its own lock, so one camera never waits +while another camera's events are being sent. + +A subscription starts in two steps: `subscribe` reserves it, which counts it in the pool's +budget, and `activate` starts delivery. In between, whoever serves the reader tells it what it +subscribed to, so that answer always comes before the first frame set. + +## When a frame set is held for a reader + +An in-order reader is sent each frame set as it is published, while its window has room. It +starts, the moment its delivery is activated, with what the ring kept: nothing published +between its reservation and its activation waits for the next publish. + +A newest-order reader is sent one only when it asks, with `request_newest`: the newest frame set +there is at that moment, or the next one published if it already has the newest. Nothing is +held for a reader that is not asking. Holding a frame set ahead of time, the moment it is +published, would hand a reader that was busy for a second a frame that is a second old, and +keep every newer one from it. + +The request names the last frame set the reader took. That lets a reader give back a frame +set it did not use (it had stopped waiting when the frame set arrived) and ask again: it gets +the same one back if nothing newer exists, and the newer one otherwise. + +## A camera SDK that owns its buffers + +Some capture stacks are given their buffers up front and pick the one they fill, and stop +capturing when they run out. They map onto the second way like this: + +- every buffer the SDK was given is a slot, and the group is added with a **backend reserve** + equal to the number of buffers the SDK needs in hand to keep capturing; +- when the SDK hands a filled buffer over, the backend calls `claim_slot` for it, and + `publish` once the images of the group are there. An image whose partner does not arrive + in time is given up with `abandon_slot` and goes straight back to the SDK; +- the slot-free callback returns a buffer to the SDK the moment the ring and every reader + have let go of it. + +Because the budget below counts the reserve, readers can never take so many buffers that the +SDK is left short. A consumer that works on the buffers in place, such as an encoder, is a +reader like any other: it holds a buffer until it has finished consuming it. + +## What publishing, holding and releasing mean + +Three different things are true of a slot at different times, and they are kept apart: + +- **Ready**: `publish` says the image is complete. A backend publishes a slot only when + everything that writes it has finished. +- **Held**: a lease says a reader may read the slot. It is not reused or rewritten while any + lease or the ring refers to it, across a camera restart as well. +- **Done**: `release` says everything the reader started on the slot has finished. For host + memory that is the moment it stops reading. + +When a reader goes away its leases are taken back at once. That is right for host memory: a +reader that is gone reads nothing, and one that closed its connection while still reading +gets changing pixels, never memory that is gone. It is not evidence that work a reader handed +to a GPU or a hardware encoder has finished, so a pool kind where such work can outlive the +connection has to bring its own rule for these slots before it is added. + +## Pool budget + +A slot is in use while the ring of recent frame sets or any lease refers to it, so a subscription +is accepted only when the pool can cover it: + +```text +slots >= ring history + sum of reader windows + backend reserve +``` + +Ring history is one frame set, or the largest window among in-order readers. The backend reserve +is the number of slots the backend needs for itself: one to write ahead, more for an SDK that +keeps several captures in flight. A subscription that does not fit is refused with a message that +gives these numbers. + +## Tests + +`tests/cpp/core/camera_core`, run with `ctest -L camera_core`. They are tagged `unit`, so +`ctest -L unit` runs them too. diff --git a/src/core/camera_core/cpp/CMakeLists.txt b/src/core/camera_core/cpp/CMakeLists.txt new file mode 100644 index 0000000000..b4a243b0de --- /dev/null +++ b/src/core/camera_core/cpp/CMakeLists.txt @@ -0,0 +1,17 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +# Camera interface core: which pool slots hold which frame sets and who may still read them. +# Standard library only, so it builds and is tested on every platform. +add_library(camera_core STATIC + description.cpp + publisher.cpp +) + +target_include_directories(camera_core INTERFACE + $ +) + +add_library(camera::camera_core ALIAS camera_core) diff --git a/src/core/camera_core/cpp/description.cpp b/src/core/camera_core/cpp/description.cpp new file mode 100644 index 0000000000..e0dd93e417 --- /dev/null +++ b/src/core/camera_core/cpp/description.cpp @@ -0,0 +1,101 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_core/types.hpp" + +#include + +namespace core::camera +{ + +namespace +{ + +// Whether every plane of a pixel stream lies inside its slot. Written with subtractions and a +// division: the numbers may come from another process, and a sum of them could wrap. +bool planes_fit(const StreamDescription& stream) +{ + for (std::uint32_t i = 0; i < stream.plane_count; ++i) + { + const PlaneSize size = plane_size_of(stream.pixel_format, stream.width, stream.height, i); + const std::uint64_t offset = stream.planes[i].offset_bytes; + const std::uint64_t stride = stream.planes[i].stride_bytes; + if (size.rows == 0 || size.row_bytes == 0 || stride < size.row_bytes) + { + return false; + } + // offset + stride * (rows - 1) + row_bytes <= slot_bytes + if (offset > stream.slot_bytes || size.row_bytes > stream.slot_bytes - offset || + size.rows - 1 > (stream.slot_bytes - offset - size.row_bytes) / stride) + { + return false; + } + } + return true; +} + +} // namespace + +std::string problem_with(const GroupDescription& group) +{ + if (group.id.empty()) + { + return "a camera group needs an id"; + } + const std::string group_name = "camera group '" + group.id + "'"; + if (group.streams.empty() || group.streams.size() > MAX_STREAMS_PER_GROUP) + { + return group_name + " needs between 1 and " + std::to_string(MAX_STREAMS_PER_GROUP) + " streams"; + } + for (std::size_t i = 0; i < group.streams.size(); ++i) + { + const StreamDescription& stream = group.streams[i]; + if (stream.id.empty()) + { + return group_name + " has a stream without an id"; + } + const std::string name = "camera stream '" + stream.id + "'"; + for (std::size_t other = 0; other < i; ++other) + { + if (group.streams[other].id == stream.id) + { + return group_name + " has two streams called '" + stream.id + "'"; + } + } + if (stream.slot_count == 0 || stream.slot_count > MAX_SLOTS_PER_STREAM) + { + return name + " needs between 1 and " + std::to_string(MAX_SLOTS_PER_STREAM) + " slots"; + } + if (stream.slot_bytes == 0 || stream.slot_bytes > MAX_SLOT_BYTES) + { + return name + " needs a slot size between 1 and " + std::to_string(MAX_SLOT_BYTES) + " bytes"; + } + if (!std::isfinite(stream.frame_rate) || stream.frame_rate < 0.0) + { + return name + " needs a frame rate that is a number, 0 when it is not known"; + } + if (stream.is_encoded()) + { + if (stream.plane_count != 0) + { + return name + " is encoded video, which has no planes"; + } + continue; + } + if (stream.width == 0 || stream.height == 0) + { + return name + " needs a width and a height"; + } + if (stream.plane_count > MAX_PLANES_PER_IMAGE || stream.plane_count != plane_count_of(stream.pixel_format)) + { + return name + " does not describe every plane of its pixel format"; + } + if (!planes_fit(stream)) + { + return name + " has a plane whose rows are shorter than its width needs or do not lie inside the slot"; + } + } + return {}; +} + +} // namespace core::camera diff --git a/src/core/camera_core/cpp/inc/camera_core/publisher.hpp b/src/core/camera_core/cpp/inc/camera_core/publisher.hpp new file mode 100644 index 0000000000..64da354ae4 --- /dev/null +++ b/src/core/camera_core/cpp/inc/camera_core/publisher.hpp @@ -0,0 +1,261 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include "types.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +using GroupId = std::uint32_t; +using SubscriptionId = std::uint32_t; // 0 is never a valid subscription + +/** + * @brief Where a reader's frame events go: a socket connection or an in-process queue. + */ +class EventSink +{ +public: + virtual ~EventSink() = default; + + /** + * @brief Hand one event to the reader. Called with the group's lock held, on the capture + * path or on the thread that released or asked for a frame set, so it must not block, + * throw or call back into the publisher. Calls for one subscription never overlap. + * @return false when the event could not be handed over; the reader then gets a later one. + */ + virtual bool send_event(SubscriptionId subscription, const FrameEvent& event) noexcept = 0; +}; + +// Counters of one group since it was added. +struct PublisherStats +{ + std::uint64_t published = 0; // frame sets published + std::uint64_t events_sent = 0; + std::uint64_t send_failures = 0; + std::uint64_t no_free_slot = 0; // acquire_slot calls that found every slot in use +}; + +struct SubscribeResult +{ + SubscriptionId id = 0; + std::string error; // why the subscription was refused, when id is 0 + + explicit operator bool() const + { + return id != 0; + } +}; + +/** + * @brief Tracks which pool slots hold which frame sets and who may still read them. + * + * A group keeps a short ring of recent frame sets; a reader's window is how many are kept for + * it at a time, unread and held together. A subscription is accepted only when + * slots >= ring history + sum of reader windows + backend reserve. A frame set is held for a + * newest-order reader when the reader asks, so it is the newest at that moment; an in-order + * reader is sent each one as it is published. Events carry slot indices; slot memory is never + * touched here. Thread-safe; no call blocks on a reader, and each group has its own lock, so + * one camera never waits for another camera's readers. + */ +class Publisher +{ +public: + using Clock = std::function; + using SlotFreeCallback = std::function; + + /** + * @param clock Host monotonic time in nanoseconds; defaults to std::chrono::steady_clock. + */ + explicit Publisher(Clock clock = {}); + + // ---- backend side ---------------------------------------------------------------------- + + /** + * @brief Declare a group and the size of its pools. + * @param backend_reserve Slots the backend needs beyond the ring and the readers: one to + * write ahead, more for an SDK that keeps several captures in flight in its own queue. + * @throws std::invalid_argument if the description is not usable. + */ + GroupId add_group(const GroupDescription& description, std::uint32_t backend_reserve = 1); + + /** + * @brief Take a free slot to write the next image into. + * @return The slot, or nothing when every slot is in use (the frame should be dropped). + * @throws std::logic_error for a group that has a slot-free callback: its backend owns the + * pool and names slots with claim_slot. + */ + std::optional acquire_slot(GroupId group, std::size_t stream); + + /** + * @brief Mark a slot the SDK chose and filled, for a pool the SDK owns. + * @throws std::invalid_argument if the slot is still held by the ring or a reader. + */ + void claim_slot(GroupId group, std::size_t stream, std::uint32_t slot); + + /** + * @brief Give back a slot taken with acquire_slot or claim_slot without publishing it. + */ + void abandon_slot(GroupId group, std::size_t stream, std::uint32_t slot); + + /** + * @brief Be told when a published slot is no longer held by the ring or any reader, so a + * buffer the SDK owns can go back to it at once. Called outside the group's lock, on + * the thread whose call released the last hold. A group with this callback hands out its + * slots with claim_slot only, so a slot cannot be taken again before its callback has run. + */ + void set_slot_free_callback(GroupId group, SlotFreeCallback callback); + + /** + * @brief Publish one frame set. images[i] belongs to stream i and names a slot taken with + * acquire_slot or claim_slot. + * @param timeline capture_ns and sdk_ready_ns from the backend; the rest is filled in here. + * @return The frame set's sequence number. + * @throws std::invalid_argument if the images do not match the group or do not fit its slots. + */ + std::uint64_t publish(GroupId group, std::span images, const FrameTimeline& timeline); + + /** + * @brief Tell readers the camera restarted: the generation changes and the ring is emptied. + * Frame sets readers already hold stay valid, and their slots unused, until released. + */ + void restart_group(GroupId group); + + // ---- reader side ----------------------------------------------------------------------- + + /** + * @brief Reserve a subscription. It counts in the pool's budget from here on, and nothing + * is sent to the sink before activate(), so the reader can be told what it subscribed to + * first. The sink must outlive the subscription. + * @return The subscription, or the reason it does not fit the pool. + */ + SubscribeResult subscribe(EventSink& sink, GroupId group, const ReaderOptions& options); + + /** + * @brief Start delivery. An in-order reader is sent what the ring kept, at once, and then + * every frame set as it is published; a newest-order reader is sent one each time it asks + * with request_newest(). + */ + void activate(SubscriptionId subscription); + + /** + * @brief A newest-order reader asks for a frame set: the newest one after `after_sequence`, + * held for it now if there is one and its window has room, and otherwise as soon as both + * are true. A reader has one request open at a time; asking again replaces it. + * @param after_sequence The sequence of the last frame set the reader took; 0 for none. + * @return false for a subscription that is not active or not newest-order. + */ + bool request_newest(SubscriptionId subscription, std::uint64_t after_sequence); + + /** + * @brief Return a frame set. What the reader is waiting for, if it now has room, is sent at + * once. + */ + void release(SubscriptionId subscription, std::uint64_t lease_id); + + /** + * @brief End a subscription and take back every frame set it still holds. + */ + void unsubscribe(SubscriptionId subscription); + + // ---- description ----------------------------------------------------------------------- + + std::size_t group_count() const; + GroupDescription group_description(GroupId group) const; + std::optional find_group(std::string_view id) const; + std::uint32_t generation(GroupId group) const; + PublisherStats stats(GroupId group) const; + +private: + struct FrameSet + { + std::uint64_t sequence = 0; + std::uint32_t generation = 0; + FrameTimeline timeline; + std::array images; + }; + + struct Subscription + { + std::uint32_t window = 1; + DeliveryOrder order = DeliveryOrder::NEWEST; + EventSink* sink = nullptr; + bool active = false; // nothing is sent before activate() + bool wanted = false; // newest order: the reader asked and has not been answered + // The reader is next sent a frame set after this sequence: the last one it was sent + // when in order, the last one it says it took when newest. + std::uint64_t cursor = 0; + bool started = false; // the cursor names a frame set the reader had, so skips count from it + std::map leases; // sent and not yet released + }; + + struct Slot + { + std::uint32_t holds = 0; // the ring and every reader lease that names this slot + bool writing = false; // taken by the backend and not yet published + }; + + // One camera. Everything that changes after add_group is guarded by `mutex`; one group's + // lock is never held while another's is taken. + struct Group + { + GroupDescription description; // fixed once the group is added + std::uint32_t reserve = 1; + std::uint32_t slot_count = 0; // the smallest pool of the group + + mutable std::mutex mutex; + std::uint32_t generation = 0; + std::uint64_t sequence = 0; + std::uint64_t next_lease = 1; + std::vector> slots; // per stream + std::deque ring; + std::map subscriptions; // in the order they were made + std::shared_ptr on_free; + PublisherStats stats; + }; + + struct FreedSlot + { + std::shared_ptr callback; + std::size_t stream = 0; + std::uint32_t slot = 0; + }; + + Group& group_at(GroupId group) const; + Group* group_of(SubscriptionId subscription) const; + static Slot& slot_at(Group& group, std::size_t stream, std::uint32_t slot); + static std::size_t history_of(const Group& group); + static void hold(Group& group, const FrameSet& set); + static void unhold(Group& group, const FrameSet& set, std::vector& freed); + static void trim_ring(Group& group, std::vector& freed); + void deliver(Group& group, SubscriptionId id, Subscription& subscription, std::vector& freed) const; + static void notify(const std::vector& freed); + + Clock m_clock; + + // Which groups exist and which group a subscription belongs to: read on every call, changed + // only when a group is added or a reader comes or goes. Held only to look a group up, never + // together with a group's lock. + mutable std::shared_mutex m_registry; + std::vector> m_groups; // never removed, so a group's address is stable + std::map m_subscription_groups; + SubscriptionId m_next_subscription = 1; +}; + +} // namespace core::camera diff --git a/src/core/camera_core/cpp/inc/camera_core/types.hpp b/src/core/camera_core/cpp/inc/camera_core/types.hpp new file mode 100644 index 0000000000..e69f902eb8 --- /dev/null +++ b/src/core/camera_core/cpp/inc/camera_core/types.hpp @@ -0,0 +1,190 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include +#include +#include +#include +#include + +namespace core::camera +{ + +// A group publishes one image per stream, all captured together. +inline constexpr std::size_t MAX_STREAMS_PER_GROUP = 8; +inline constexpr std::uint32_t MAX_SLOTS_PER_STREAM = 64; + +// Larger than any image or access unit, and small enough that no size worked out from a +// description can wrap. +inline constexpr std::uint64_t MAX_SLOT_BYTES = std::uint64_t{ 1 } << 32; + +// Marks a time that is not known. All times are nanoseconds on the host's monotonic clock. +inline constexpr std::int64_t TIME_UNKNOWN = -1; + +enum class PixelFormat : std::uint32_t +{ + BGRA8 = 1, + RGBA8 = 2, + NV12 = 3, + GRAY8 = 4, +}; + +// NV12 has two planes (luma, then interleaved chroma); the other formats have one. +inline constexpr std::size_t MAX_PLANES_PER_IMAGE = 2; + +constexpr std::uint32_t plane_count_of(PixelFormat format) +{ + return format == PixelFormat::NV12 ? 2 : 1; +} + +// Where one plane of an image sits inside a slot. +struct PlaneLayout +{ + std::uint32_t offset_bytes = 0; + std::uint32_t stride_bytes = 0; // from the start of one row to the start of the next +}; + +// The pixels of one plane: the bytes one row holds, without padding, and the number of rows. +struct PlaneSize +{ + std::uint64_t row_bytes = 0; + std::uint64_t rows = 0; +}; + +constexpr PlaneSize plane_size_of(PixelFormat format, std::uint32_t width, std::uint32_t height, std::uint32_t plane) +{ + const std::uint64_t columns = width; + const std::uint64_t rows = height; + switch (format) + { + case PixelFormat::BGRA8: + case PixelFormat::RGBA8: + return { columns * 4, rows }; + case PixelFormat::GRAY8: + return { columns, rows }; + case PixelFormat::NV12: + // Luma at full size, then one interleaved chroma pair per two by two pixels. + return plane == 0 ? PlaneSize{ columns, rows } : PlaneSize{ (columns + 1) / 2 * 2, (rows + 1) / 2 }; + } + return {}; +} + +// Whether a stream's slots hold pixels or one access unit of encoded video each. +enum class Codec : std::uint32_t +{ + NONE = 0, // pixels, laid out as the stream's pixel format says + H264 = 1, + H265 = 2, +}; + +// Where a stream's slots live, which tells a reader how to map them. The core tracks slots by +// index only and never touches their memory; each further kind is added with its pool. +enum class MemoryKind : std::uint32_t +{ + HOST = 1, // shared host memory +}; + +struct StreamDescription +{ + std::string id; + Codec codec = Codec::NONE; + PixelFormat pixel_format = PixelFormat::BGRA8; // of a pixel stream; unused when the stream is encoded + MemoryKind memory = MemoryKind::HOST; + std::uint32_t width = 0; + std::uint32_t height = 0; + std::uint32_t plane_count = 0; // 0 for an encoded stream + std::array planes; // the same for every slot of the stream + std::uint64_t slot_bytes = 0; // capacity of one slot + std::uint32_t slot_count = 0; + double frame_rate = 0.0; // configured or measured, not the sensor mode's maximum + + constexpr bool is_encoded() const + { + return codec != Codec::NONE; + } +}; + +// One or more hardware-synchronised streams that are published as one frame set. +struct GroupDescription +{ + std::string id; + + // Names one run of the group: the same for every frame set from the moment the plugin + // starts publishing it until that plugin ends. With a frame set's sequence it identifies a + // capture for good. Left 0, Publisher::add_group draws one. + std::uint64_t session_id = 0; + + std::vector streams; +}; + +/** + * @brief Why a group cannot be published or read as described: sizes, the planes its pixel + * format needs, strides and offsets against the slot, slot counts. For both sides of a + * connection: what a backend declares and what a reader was sent. + * @return The reason, or nothing when the description is usable. + */ +std::string problem_with(const GroupDescription& group); + +enum ImageFlag : std::uint32_t +{ + IMAGE_FLAG_KEYFRAME = 1u << 0, // encoded stream: this access unit decodes on its own + IMAGE_FLAG_SDK_WARNING = 1u << 1, // the camera SDK delivered the frame but flagged it as suspect +}; + +struct ImageInfo +{ + std::uint32_t slot = 0; + std::uint32_t flags = 0; // ImageFlag bits + std::uint64_t bytes_used = 0; // encoded stream: size of the access unit + std::uint64_t device_frame_id = 0; // the SDK's own frame number + std::int64_t device_time_ns = TIME_UNKNOWN; // the SDK's own timestamp, in the SDK's clock +}; + +// Where a frame set was at each step, so latency can be read off every frame. +struct FrameTimeline +{ + std::int64_t capture_ns = TIME_UNKNOWN; // sensor capture, when the backend can map it to the host clock + std::int64_t sdk_ready_ns = TIME_UNKNOWN; // the SDK handed the frame to the backend + std::int64_t published_ns = TIME_UNKNOWN; // set by Publisher::publish + std::int64_t sent_ns = TIME_UNKNOWN; // set when the event is handed to a reader +}; + +struct FrameEvent +{ + std::uint64_t lease_id = 0; // this reader's hold on the frame set; return it with Publisher::release + // The frame set's place among the group's captures in this session. The same for every + // reader, so readers see gaps rather than a numbering of their own; a restart does not reset it. + std::uint64_t sequence = 0; + std::uint32_t generation = 0; // restarts of the camera within the session + std::uint32_t skipped = 0; // frame sets this reader did not receive since its previous one + std::uint32_t image_count = 0; + FrameTimeline timeline; + std::array images; // images[i] belongs to stream i +}; + +enum class DeliveryOrder +{ + DEFAULT, // NEWEST for a window of one, IN_ORDER otherwise + NEWEST, // each time the reader asks it gets the newest frame set there is then, and skips older ones + IN_ORDER, // the reader is sent every frame set in sequence while it keeps up +}; + +struct ReaderOptions +{ + std::uint32_t window = 1; // frame sets kept for this reader at a time, unread and held together + DeliveryOrder order = DeliveryOrder::DEFAULT; +}; + +// The order a reader with these options gets: what it asked for, or the default for its window. +constexpr DeliveryOrder resolved_order(const ReaderOptions& options) +{ + if (options.order != DeliveryOrder::DEFAULT) + { + return options.order; + } + return options.window == 1 ? DeliveryOrder::NEWEST : DeliveryOrder::IN_ORDER; +} + +} // namespace core::camera diff --git a/src/core/camera_core/cpp/publisher.cpp b/src/core/camera_core/cpp/publisher.cpp new file mode 100644 index 0000000000..cd6606c437 --- /dev/null +++ b/src/core/camera_core/cpp/publisher.cpp @@ -0,0 +1,544 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_core/publisher.hpp" + +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +namespace +{ + +std::int64_t steady_now_ns() +{ + return std::chrono::duration_cast(std::chrono::steady_clock::now().time_since_epoch()).count(); +} + +// Never 0, which stands for "not chosen yet". +std::uint64_t new_session_id() +{ + std::random_device source; + for (;;) + { + const std::uint64_t id = (std::uint64_t{ source() } << 32) | source(); + if (id != 0) + { + return id; + } + } +} + +} // namespace + +Publisher::Publisher(Clock clock) : m_clock(clock ? std::move(clock) : Clock(steady_now_ns)) +{ +} + +GroupId Publisher::add_group(const GroupDescription& description, std::uint32_t backend_reserve) +{ + if (const std::string problem = problem_with(description); !problem.empty()) + { + throw std::invalid_argument(problem); + } + if (backend_reserve == 0) + { + throw std::invalid_argument("camera group '" + description.id + "' needs a backend reserve of at least 1"); + } + + auto group = std::make_unique(); + group->description = description; + if (group->description.session_id == 0) + { + group->description.session_id = new_session_id(); + } + group->reserve = backend_reserve; + group->slot_count = std::numeric_limits::max(); + for (const StreamDescription& stream : description.streams) + { + group->slot_count = std::min(group->slot_count, stream.slot_count); + group->slots.emplace_back(stream.slot_count); + } + // Before any reader, the ring keeps one frame set and the backend keeps its reserve. + if (group->slot_count <= backend_reserve) + { + throw std::invalid_argument("camera group '" + description.id + "' has pools of " + + std::to_string(group->slot_count) + " slots, too few for one frame set and a " + + "backend reserve of " + std::to_string(backend_reserve)); + } + + const std::unique_lock registry(m_registry); + for (const auto& existing : m_groups) + { + if (existing->description.id == description.id) + { + throw std::invalid_argument("camera group '" + description.id + "' already exists"); + } + } + m_groups.push_back(std::move(group)); + return static_cast(m_groups.size() - 1); +} + +std::optional Publisher::acquire_slot(GroupId group, std::size_t stream) +{ + Group& target = group_at(group); + const std::lock_guard lock(target.mutex); + if (target.on_free) + { + throw std::logic_error("camera group '" + target.description.id + + "' has a slot-free callback, so its backend names slots with claim_slot"); + } + std::vector& slots = target.slots.at(stream); + for (std::uint32_t i = 0; i < slots.size(); ++i) + { + if (slots[i].holds == 0 && !slots[i].writing) + { + slots[i].writing = true; + return i; + } + } + ++target.stats.no_free_slot; + return std::nullopt; +} + +void Publisher::claim_slot(GroupId group, std::size_t stream, std::uint32_t slot) +{ + Group& target = group_at(group); + const std::lock_guard lock(target.mutex); + Slot& state = slot_at(target, stream, slot); + if (state.holds != 0 || state.writing) + { + throw std::invalid_argument("camera slot " + std::to_string(slot) + " is still in use and cannot be claimed"); + } + state.writing = true; +} + +void Publisher::abandon_slot(GroupId group, std::size_t stream, std::uint32_t slot) +{ + Group& target = group_at(group); + const std::lock_guard lock(target.mutex); + Slot& state = slot_at(target, stream, slot); + if (!state.writing) + { + throw std::invalid_argument("camera slot " + std::to_string(slot) + " was not acquired and cannot be abandoned"); + } + state.writing = false; +} + +void Publisher::set_slot_free_callback(GroupId group, SlotFreeCallback callback) +{ + Group& target = group_at(group); + const std::lock_guard lock(target.mutex); + target.on_free = callback ? std::make_shared(std::move(callback)) : nullptr; +} + +std::uint64_t Publisher::publish(GroupId group, std::span images, const FrameTimeline& timeline) +{ + std::vector freed; + std::uint64_t sequence = 0; + Group& target = group_at(group); + { + const std::lock_guard lock(target.mutex); + if (images.size() != target.description.streams.size()) + { + throw std::invalid_argument("camera group '" + target.description.id + "' publishes " + + std::to_string(target.description.streams.size()) + " images per frame set"); + } + for (std::size_t i = 0; i < images.size(); ++i) + { + if (!slot_at(target, i, images[i].slot).writing) + { + throw std::invalid_argument("camera slot " + std::to_string(images[i].slot) + + " was not acquired before it was published"); + } + if (images[i].bytes_used > target.description.streams[i].slot_bytes) + { + throw std::invalid_argument("camera stream '" + target.description.streams[i].id + "' published " + + std::to_string(images[i].bytes_used) + " bytes into a slot of " + + std::to_string(target.description.streams[i].slot_bytes)); + } + } + + FrameSet set; + set.sequence = ++target.sequence; + set.generation = target.generation; + set.timeline = timeline; + set.timeline.published_ns = m_clock(); + for (std::size_t i = 0; i < images.size(); ++i) + { + set.images[i] = images[i]; + slot_at(target, i, images[i].slot).writing = false; // the ring holds it from here + } + hold(target, set); + target.ring.push_back(set); + ++target.stats.published; + sequence = set.sequence; + + trim_ring(target, freed); + for (auto& [id, subscription] : target.subscriptions) + { + deliver(target, id, subscription, freed); + } + } + notify(freed); + return sequence; +} + +void Publisher::restart_group(GroupId group) +{ + std::vector freed; + Group& target = group_at(group); + { + const std::lock_guard lock(target.mutex); + ++target.generation; + while (!target.ring.empty()) + { + unhold(target, target.ring.front(), freed); + target.ring.pop_front(); + } + } + notify(freed); +} + +SubscribeResult Publisher::subscribe(EventSink& sink, GroupId group, const ReaderOptions& options) +{ + SubscribeResult result; + if (options.window == 0) + { + result.error = "a reader's window must be at least 1"; + return result; + } + Group* target = nullptr; + SubscriptionId id = 0; + { + // The subscription is known to the registry before its group can send it an event, so + // a release that follows the very first event finds it. + const std::unique_lock registry(m_registry); + if (group >= m_groups.size()) + { + result.error = "unknown camera group"; + return result; + } + target = m_groups[group].get(); + id = m_next_subscription++; + m_subscription_groups.emplace(id, group); + } + + { + const std::lock_guard lock(target->mutex); + const DeliveryOrder order = resolved_order(options); + + // The ring keeps what in-order readers may still be waiting for; newest-only readers + // need the newest frame set and nothing older. + std::size_t history = order == DeliveryOrder::IN_ORDER ? options.window : 1; + std::size_t windows = options.window; + for (const auto& [other_id, other] : target->subscriptions) + { + if (other.order == DeliveryOrder::IN_ORDER) + { + history = std::max(history, other.window); + } + windows += other.window; + } + const std::size_t needed = history + windows + target->reserve; + if (needed <= target->slot_count) + { + Subscription subscription; + subscription.window = options.window; + subscription.order = order; + subscription.sink = &sink; + target->subscriptions.emplace(id, std::move(subscription)); + result.id = id; + return result; + } + result.error = "subscription does not fit the pool of camera group '" + target->description.id + "': it needs " + + std::to_string(needed) + " slots (" + std::to_string(history) + " ring history, " + + std::to_string(windows) + " for reader windows, " + std::to_string(target->reserve) + + " for the backend) and the pool has " + std::to_string(target->slot_count); + } + const std::unique_lock registry(m_registry); + m_subscription_groups.erase(id); + return result; +} + +void Publisher::activate(SubscriptionId subscription) +{ + Group* target = group_of(subscription); + if (target == nullptr) + { + return; + } + std::vector freed; + { + const std::lock_guard lock(target->mutex); + const auto found = target->subscriptions.find(subscription); + if (found != target->subscriptions.end()) + { + found->second.active = true; + // An in-order reader starts with what the ring kept, which includes a frame set + // published between its reservation and this call. Without this it would get + // that frame set only when the next one is published. + deliver(*target, subscription, found->second, freed); + } + } + notify(freed); +} + +bool Publisher::request_newest(SubscriptionId subscription, std::uint64_t after_sequence) +{ + Group* target = group_of(subscription); + if (target == nullptr) + { + return false; + } + std::vector freed; + { + const std::lock_guard lock(target->mutex); + const auto found = target->subscriptions.find(subscription); + if (found == target->subscriptions.end() || !found->second.active || found->second.order != DeliveryOrder::NEWEST) + { + return false; + } + found->second.wanted = true; + found->second.cursor = after_sequence; + found->second.started = after_sequence != 0; + deliver(*target, subscription, found->second, freed); + } + notify(freed); + return true; +} + +void Publisher::release(SubscriptionId subscription, std::uint64_t lease_id) +{ + Group* target = group_of(subscription); + if (target == nullptr) + { + return; + } + std::vector freed; + { + const std::lock_guard lock(target->mutex); + const auto found = target->subscriptions.find(subscription); + if (found == target->subscriptions.end()) + { + return; + } + const auto lease = found->second.leases.find(lease_id); + if (lease == found->second.leases.end()) + { + return; + } + unhold(*target, lease->second, freed); + found->second.leases.erase(lease); + deliver(*target, subscription, found->second, freed); + } + notify(freed); +} + +void Publisher::unsubscribe(SubscriptionId subscription) +{ + Group* target = group_of(subscription); + if (target == nullptr) + { + return; + } + std::vector freed; + { + // Once this lock is let go, no send_event runs or will start for the subscription. + const std::lock_guard lock(target->mutex); + const auto found = target->subscriptions.find(subscription); + if (found != target->subscriptions.end()) + { + for (const auto& lease : found->second.leases) + { + unhold(*target, lease.second, freed); + } + target->subscriptions.erase(found); + trim_ring(*target, freed); + } + } + { + const std::unique_lock registry(m_registry); + m_subscription_groups.erase(subscription); + } + notify(freed); +} + +std::size_t Publisher::group_count() const +{ + const std::shared_lock registry(m_registry); + return m_groups.size(); +} + +GroupDescription Publisher::group_description(GroupId group) const +{ + return group_at(group).description; +} + +std::optional Publisher::find_group(std::string_view id) const +{ + const std::shared_lock registry(m_registry); + for (std::size_t i = 0; i < m_groups.size(); ++i) + { + if (m_groups[i]->description.id == id) + { + return static_cast(i); + } + } + return std::nullopt; +} + +std::uint32_t Publisher::generation(GroupId group) const +{ + const Group& target = group_at(group); + const std::lock_guard lock(target.mutex); + return target.generation; +} + +PublisherStats Publisher::stats(GroupId group) const +{ + const Group& target = group_at(group); + const std::lock_guard lock(target.mutex); + return target.stats; +} + +Publisher::Group& Publisher::group_at(GroupId group) const +{ + const std::shared_lock registry(m_registry); + if (group >= m_groups.size()) + { + throw std::out_of_range("unknown camera group"); + } + return *m_groups[group]; +} + +Publisher::Group* Publisher::group_of(SubscriptionId subscription) const +{ + const std::shared_lock registry(m_registry); + const auto found = m_subscription_groups.find(subscription); + return found == m_subscription_groups.end() ? nullptr : m_groups[found->second].get(); +} + +Publisher::Slot& Publisher::slot_at(Group& group, std::size_t stream, std::uint32_t slot) +{ + if (stream >= group.slots.size() || slot >= group.slots[stream].size()) + { + throw std::invalid_argument("camera group '" + group.description.id + "' has no stream " + + std::to_string(stream) + " slot " + std::to_string(slot)); + } + return group.slots[stream][slot]; +} + +std::size_t Publisher::history_of(const Group& group) +{ + std::size_t history = 1; // the newest frame set is always kept + for (const auto& [id, subscription] : group.subscriptions) + { + if (subscription.order == DeliveryOrder::IN_ORDER) + { + history = std::max(history, subscription.window); + } + } + return history; +} + +void Publisher::hold(Group& group, const FrameSet& set) +{ + for (std::size_t i = 0; i < group.slots.size(); ++i) + { + ++slot_at(group, i, set.images[i].slot).holds; + } +} + +void Publisher::unhold(Group& group, const FrameSet& set, std::vector& freed) +{ + for (std::size_t i = 0; i < group.slots.size(); ++i) + { + Slot& slot = slot_at(group, i, set.images[i].slot); + if (--slot.holds == 0 && group.on_free) + { + freed.push_back({ group.on_free, i, set.images[i].slot }); + } + } +} + +void Publisher::trim_ring(Group& group, std::vector& freed) +{ + const std::size_t history = history_of(group); + while (group.ring.size() > history) + { + unhold(group, group.ring.front(), freed); + group.ring.pop_front(); + } +} + +void Publisher::deliver(Group& group, SubscriptionId id, Subscription& subscription, std::vector& freed) const +{ + if (!subscription.active) + { + return; + } + while (subscription.leases.size() < subscription.window) + { + // A newest-order reader is held a frame set only while it asks for one: whatever was + // held ahead of time would be old by the time the reader came for it. + if (subscription.order == DeliveryOrder::NEWEST && !subscription.wanted) + { + return; + } + if (group.ring.empty() || group.ring.back().sequence <= subscription.cursor) + { + return; + } + const FrameSet* target = &group.ring.back(); + if (subscription.order == DeliveryOrder::IN_ORDER) + { + target = &*std::find_if(group.ring.begin(), group.ring.end(), + [&](const FrameSet& set) { return set.sequence > subscription.cursor; }); + } + + FrameEvent event; + event.lease_id = group.next_lease++; + event.sequence = target->sequence; + event.generation = target->generation; + if (subscription.started) + { + const std::uint64_t skipped = target->sequence - subscription.cursor - 1; + event.skipped = + static_cast(std::min(skipped, std::numeric_limits::max())); + } + event.image_count = static_cast(group.slots.size()); + event.images = target->images; + event.timeline = target->timeline; + event.timeline.sent_ns = m_clock(); + + hold(group, *target); + if (!subscription.sink->send_event(id, event)) + { + unhold(group, *target, freed); + ++group.stats.send_failures; + return; + } + ++group.stats.events_sent; + subscription.leases.emplace(event.lease_id, *target); + subscription.cursor = target->sequence; + subscription.started = true; + subscription.wanted = false; + } +} + +void Publisher::notify(const std::vector& freed) +{ + for (const FreedSlot& slot : freed) + { + (*slot.callback)(slot.stream, slot.slot); + } +} + +} // namespace core::camera diff --git a/src/core/camera_ipc/AGENTS.md b/src/core/camera_ipc/AGENTS.md new file mode 100644 index 0000000000..a5ab98ea3f --- /dev/null +++ b/src/core/camera_ipc/AGENTS.md @@ -0,0 +1,20 @@ + + +# Agent notes — `camera_ipc` + +**CRITICAL (non-optional):** Before editing this package, complete the mandatory **`AGENTS.md` preflight** in [`../../../AGENTS.md`](../../../AGENTS.md) (read every applicable `AGENTS.md` on your paths, not just this file). + +Read [`README.md`](README.md) first; it explains why frames cross between processes this way. + +- **Linux only.** The module and its tests are added under `CMAKE_SYSTEM_NAME STREQUAL "Linux"`. Platform calls stay here and out of `camera_core`. +- **Frame memory crosses as a file descriptor on the module's Unix socket.** Do not add a messaging or shared-memory library for it; a new kind of memory is a new pool type behind the same connection. +- **Nothing on the capture path waits for a reader.** Sends do not block; a full queue and a closed peer are statuses, not exceptions. +- **A lock file owns the socket path.** Remove a socket file only while holding it, and never remove anything that is not a socket. +- **A listener takes its path when it is made and accepts only after `listen()`.** Keep the two steps apart: a camera plugin holds its endpoint while it opens its cameras, and until it can answer a reader is refused at once instead of queued. +- **An endpoint belongs to one camera plugin, and listing them only reads the directory.** `default_endpoint_paths()` does not connect, probe, cache or turn file names back into instances. A socket file left by a killed plugin is listed; whoever connects finds out. +- **Readers cannot write.** A pool is sealed before its descriptor leaves the process, and a reader maps it read-only. Do not hand a reader a writable mapping. +- **Derive what both sides can compute.** A pool's layout follows from the slot count and slot size in the stream's description; do not send it separately. +- **Tests need no camera and no GPU.** They carry the `unit` tag; a case that starts a second process carries `integration` instead. diff --git a/src/core/camera_ipc/CMakeLists.txt b/src/core/camera_ipc/CMakeLists.txt new file mode 100644 index 0000000000..8ce91de360 --- /dev/null +++ b/src/core/camera_ipc/CMakeLists.txt @@ -0,0 +1,6 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +add_subdirectory(cpp) diff --git a/src/core/camera_ipc/README.md b/src/core/camera_ipc/README.md new file mode 100644 index 0000000000..96751c6da3 --- /dev/null +++ b/src/core/camera_ipc/README.md @@ -0,0 +1,123 @@ + + +# Camera interface: sharing frames between processes + +The process that owns a camera and the processes that read it are on one machine. This +module is what crosses between them. Linux only. + +[`camera_core`](../camera_core) decides which slot holds which frame; this module provides the +memory behind the slots and the connection that tells a reader which slot to look at. + +## Host pool + +`HostPool` is one stream's slots in host memory: a single anonymous file in memory +(`memfd_create`), with the slots laid out one page-aligned stride apart. The owner maps it +writable, then seals it. A reader is sent the descriptor and maps it with `HostPoolView`, read +only. Both sides derive the layout from the slot count and slot size, which the stream's +description carries. + +```cpp +HostPool pool(stream.slot_count, stream.slot_bytes, "camera.left"); +std::span pixels = pool.slot(index); // the owner writes here + +HostPoolView view(std::move(received_descriptor), stream.slot_count, stream.slot_bytes); +std::span image = view.slot(index); // a reader sees the same bytes +``` + +Both sides map the pool with its pages already in place (`MAP_POPULATE`), so neither the first +frames a camera writes nor the first frames a reader looks at pay for page faults. + +Why an anonymous sealed file and not named shared memory (`shm_open`): + +- **Nothing to clean up.** There is no name to collide with another instance and no file left in + `/dev/shm` after a crash. The memory is freed when the last process that holds it goes away. +- **Readers cannot damage it.** The seals stop any process that receives the descriptor from + mapping it writable, writing to it, or resizing it. One misbehaving reader cannot change what + the others see, and cannot make the owner fault by shrinking the file under it. +- **Access follows the connection.** Only a process that was handed the descriptor can map the + pool. + +## Message socket + +`MessageListener` and `MessageSocket` are the connection: a Unix domain socket of the +sequenced-packet kind (`SOCK_SEQPACKET`). The owner listens on a socket file, each reader +connects, and either side sends messages with file descriptors attached. + +```cpp +MessageListener listener(path); // the owner takes the path +listener.listen(); // and accepts once it can answer +auto reader = listener.accept(timeout); +const int descriptors[] = { pool.descriptor() }; +reader->send(description_bytes, descriptors); + +MessageSocket socket = MessageSocket::connect(path); // a reader +ReceivedMessage message = socket.receive(buffer, timeout); +HostPoolView view(std::move(message.descriptors[0]), slot_count, slot_bytes); +``` + +- **Whole messages.** One `send` is one `receive`, in order, so there is no framing to get wrong. +- **Sending never blocks.** If a reader stops draining its queue the sender gets `WOULD_BLOCK` + and moves on; capture never waits for a reader. +- **A dead peer is seen at once.** When a process exits or crashes the other end reads + `CLOSED`, which is how the frames a crashed reader held are taken back. +- **Owner only.** The socket file is created with mode `0600`. +- **One listener per path.** A lock file next to the socket file (`.lock`) decides who + owns the path, so of two processes that start together exactly one gets it, and a socket + file left by a crashed process is replaced safely. Anything else found at the path is left + alone. The lock file stays behind, empty. +- **The path is taken first, connections come later.** Constructing a listener locks the path + and puts the socket file there; `listen()` starts accepting. In between, a connect is refused + at once (`ECONNREFUSED`) rather than queued. A camera plugin takes its endpoint before it + opens its cameras, so a second copy of it fails early, and listens when it can answer, so no + reader is left waiting on a plugin that is still starting. +- **A connect never waits.** It is made or refused at once. A listener whose owner has stopped + accepting keeps every connection in its queue; when the queue is full a connect is refused + (`EAGAIN`) instead of waiting for that owner, so one stuck plugin cannot hold up a reader + that is looking through the endpoints. + +## Where a plugin listens + +Each camera plugin is a process of its own with an endpoint of its own. A user's endpoints are +socket files in one directory: `$XDG_RUNTIME_DIR/isaaccapture`, or `/tmp/isaaccapture-` +when that variable is not set. A plugin makes the directory for its owner alone and refuses one +that others can enter. + +`default_endpoint_path(instance)` is the socket path of the plugin with that instance name: +`camera-.sock` in that directory. A plugin's instance name is by default the name of +its backend, and a reader that is told the instance gets the same path. +`default_endpoint_directory()` is the directory itself. + +`default_endpoint_paths()` lists the endpoints in that directory, sorted: the socket files with +those names, without the lock files beside them. A reader that was not told which plugin serves +a camera group looks through this list. The call only reads the directory. It does not connect, +so a socket file left by a plugin that was killed is listed too, and the reader finds out when +it connects. A directory that does not exist yet gives an empty list and is not created. + +## Why a socket and shared memory, and not a messaging library + +Three things have to cross between the processes: the frame memory, a small event per frame +set, and the news that a peer has gone. + +Frame memory is named by a file descriptor: a sealed memory file here, and the same holds for +the buffers of hardware capture and codec stacks (DMA-BUF) and for GPU memory that can be +exported. Attaching a descriptor to a message on a Unix socket is the standard way to hand one +to another process, so a socket is needed whatever else is used. Once it is there it also +carries the events and reports dead peers, which leaves a messaging library nothing to do. + +| Considered | Why it is not used | +|---|---| +| iceoryx2 | It moves self-contained data through host memory that it allocates. Frame memory that exists only as a descriptor would still need a socket beside it, and its C++ binding adds a Rust toolchain to the build. | +| CUDA inter-process handles | A way to share one kind of GPU memory, not a way to connect processes: the handle still has to travel over some connection, and host memory and DMA-BUF are not covered. | +| ZeroMQ, gRPC, DDS | They copy the payload or share host memory only, and none of them pass descriptors. | +| PipeWire, GStreamer | The same mechanism underneath, wrapped in a media graph and, for PipeWire, a daemon. A reader here needs neither. | + +## Tests + +`tests/cpp/core/camera_ipc`, run with `ctest -L camera_ipc`. They are tagged `unit`, so +`ctest -L unit` runs them too. + +One case is tagged `integration` instead: a second process is sent a pool over the socket, maps +it, sees the owner's writes and cannot write itself. diff --git a/src/core/camera_ipc/cpp/CMakeLists.txt b/src/core/camera_ipc/cpp/CMakeLists.txt new file mode 100644 index 0000000000..f3ff4e078d --- /dev/null +++ b/src/core/camera_ipc/cpp/CMakeLists.txt @@ -0,0 +1,19 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +# How camera frames and messages cross between processes on one machine: pools of shared host +# memory that readers can only map read-only, and a socket that carries whole messages with +# file descriptors. Linux only. +add_library(camera_ipc STATIC + endpoint_path.cpp + host_pool.cpp + message_socket.cpp +) + +target_include_directories(camera_ipc INTERFACE + $ +) + +add_library(camera::camera_ipc ALIAS camera_ipc) diff --git a/src/core/camera_ipc/cpp/endpoint_path.cpp b/src/core/camera_ipc/cpp/endpoint_path.cpp new file mode 100644 index 0000000000..1bac1b7185 --- /dev/null +++ b/src/core/camera_ipc/cpp/endpoint_path.cpp @@ -0,0 +1,114 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_ipc/endpoint_path.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +namespace +{ + +// An instance name becomes part of a file name, so it is kept to these characters. +bool is_instance_name(std::string_view name) +{ + const auto allowed = [](unsigned char c) { return std::isalnum(c) != 0 || c == '-' || c == '_'; }; + return !name.empty() && std::all_of(name.begin(), name.end(), allowed); +} + +// Whether default_endpoint_path() gives this file name: "camera-.sock". +bool is_endpoint_name(std::string_view name) +{ + constexpr std::string_view prefix = "camera-"; + constexpr std::string_view suffix = ".sock"; + if (name.size() < prefix.size() + suffix.size() || !name.starts_with(prefix) || !name.ends_with(suffix)) + { + return false; + } + name.remove_prefix(prefix.size()); + name.remove_suffix(suffix.size()); + return is_instance_name(name); +} + +} // namespace + +std::string default_endpoint_directory() +{ + const char* runtime_directory = std::getenv("XDG_RUNTIME_DIR"); + return runtime_directory != nullptr && runtime_directory[0] != '\0' ? + std::string(runtime_directory) + "/isaaccapture" : + "/tmp/isaaccapture-" + std::to_string(::geteuid()); +} + +std::string default_endpoint_path(std::string_view instance) +{ + if (!is_instance_name(instance)) + { + throw std::invalid_argument("a camera plugin's instance name is one or more letters, digits, '-' and '_', not '" + + std::string(instance) + "'"); + } + return default_endpoint_directory() + "/camera-" + std::string(instance) + ".sock"; +} + +std::vector default_endpoint_paths() +{ + const std::string directory = default_endpoint_directory(); + std::vector paths; + std::error_code error; + for (std::filesystem::directory_iterator entry(directory, error), end; !error && entry != end; entry.increment(error)) + { + // An entry that cannot be examined, for instance one that went away since it was read, + // counts as not a socket. + std::error_code gone; + if (is_endpoint_name(entry->path().filename().native()) && std::filesystem::is_socket(entry->symlink_status(gone))) + { + paths.push_back(entry->path().native()); + } + } + // No directory means no plugin has run for this user, which is not an error. + if (error && error != std::errc::no_such_file_or_directory) + { + throw std::system_error(error, "listing '" + directory + "'"); + } + std::sort(paths.begin(), paths.end()); + return paths; +} + +void prepare_endpoint_directory(const std::string& endpoint_path) +{ + const std::size_t slash = endpoint_path.rfind('/'); + if (slash == std::string::npos || slash == 0) + { + return; // the current directory or the root: nothing to prepare + } + const std::string directory = endpoint_path.substr(0, slash); + if (::mkdir(directory.c_str(), S_IRWXU) != 0 && errno != EEXIST) + { + throw std::system_error(errno, std::generic_category(), "creating '" + directory + "'"); + } + // A directory somebody else made in a shared place could be used to watch or replace the + // socket file, so only one that is this user's alone will do. + struct stat entry = {}; + if (::lstat(directory.c_str(), &entry) != 0) + { + throw std::system_error(errno, std::generic_category(), "inspecting '" + directory + "'"); + } + if (!S_ISDIR(entry.st_mode) || entry.st_uid != ::geteuid() || (entry.st_mode & (S_IRWXG | S_IRWXO)) != 0) + { + throw std::system_error( + EACCES, std::generic_category(), "'" + directory + "' is not a directory that belongs to this user alone"); + } +} + +} // namespace core::camera diff --git a/src/core/camera_ipc/cpp/host_pool.cpp b/src/core/camera_ipc/cpp/host_pool.cpp new file mode 100644 index 0000000000..cb9ad88a45 --- /dev/null +++ b/src/core/camera_ipc/cpp/host_pool.cpp @@ -0,0 +1,165 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_ipc/host_pool.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include +#include + +// Older C library headers lack this seal although the kernel has it. +#ifndef F_SEAL_FUTURE_WRITE +# define F_SEAL_FUTURE_WRITE 0x0010 +#endif + +namespace core::camera +{ + +namespace +{ + +[[noreturn]] void throw_errno(const std::string& what) +{ + throw std::system_error(errno, std::generic_category(), what); +} + +// Slots start on page boundaries. Both sides derive the layout from the slot size alone. +std::uint64_t slot_stride_for(std::uint64_t slot_bytes) +{ + const auto page = static_cast(::sysconf(_SC_PAGESIZE)); + return (slot_bytes + page - 1) / page * page; +} + +std::uint64_t pool_bytes_for(std::uint32_t slot_count, std::uint64_t slot_stride) +{ + const auto limit = static_cast(std::numeric_limits::max()); + if (slot_count == 0 || slot_stride == 0 || slot_stride > limit / slot_count) + { + throw std::invalid_argument( + "a host pool needs at least one slot of at least one byte, and a size a file can have"); + } + return slot_stride * slot_count; +} + +} // namespace + +HostPool::HostPool(std::uint32_t slot_count, std::uint64_t slot_bytes, const std::string& name) + : m_slot_count(slot_count), m_slot_bytes(slot_bytes), m_slot_stride(slot_stride_for(slot_bytes)) +{ + const std::uint64_t pool_bytes = pool_bytes_for(slot_count, m_slot_stride); + m_fd.reset(::memfd_create(name.c_str(), MFD_CLOEXEC | MFD_ALLOW_SEALING)); + if (!m_fd.valid()) + { + throw_errno("host pool '" + name + "': memfd_create"); + } + if (::ftruncate(m_fd.get(), static_cast(pool_bytes)) != 0) + { + throw_errno("host pool '" + name + "': sizing the pool"); + } + // MAP_POPULATE: the pages exist and are mapped before the first frame is written, so no + // frame pays for them with page faults on the capture path. + void* memory = ::mmap(nullptr, pool_bytes, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_POPULATE, m_fd.get(), 0); + if (memory == MAP_FAILED) + { + throw_errno("host pool '" + name + "': mapping the pool"); + } + // From here on nobody can resize the pool or map it writable; the mapping above stays. + if (::fcntl(m_fd.get(), F_ADD_SEALS, F_SEAL_SHRINK | F_SEAL_GROW | F_SEAL_FUTURE_WRITE | F_SEAL_SEAL) != 0) + { + const int error = errno; + ::munmap(memory, pool_bytes); + throw std::system_error(error, std::generic_category(), "host pool '" + name + "': sealing the pool"); + } + m_memory = static_cast(memory); +} + +HostPool::~HostPool() +{ + ::munmap(m_memory, m_slot_stride * m_slot_count); +} + +std::span HostPool::slot(std::uint32_t index) +{ + if (index >= m_slot_count) + { + throw std::out_of_range("host pool has no slot " + std::to_string(index)); + } + return { m_memory + m_slot_stride * index, m_slot_bytes }; +} + +HostPoolView::HostPoolView(UniqueFd descriptor, std::uint32_t slot_count, std::uint64_t slot_bytes) + : m_slot_count(slot_count), m_slot_bytes(slot_bytes), m_slot_stride(slot_stride_for(slot_bytes)) +{ + const std::uint64_t pool_bytes = pool_bytes_for(slot_count, m_slot_stride); + struct stat info = {}; + if (::fstat(descriptor.get(), &info) != 0) + { + throw_errno("host pool view: inspecting the pool"); + } + // Mapping more than the descriptor holds would fault on first access instead of failing here. + if (static_cast(info.st_size) < pool_bytes) + { + throw std::invalid_argument("host pool view: the descriptor holds less than the pool needs"); + } + // MAP_POPULATE: a reader's first look at each slot does not fault page by page either. + void* memory = ::mmap(nullptr, pool_bytes, PROT_READ, MAP_SHARED | MAP_POPULATE, descriptor.get(), 0); + if (memory == MAP_FAILED) + { + throw_errno("host pool view: mapping the pool"); + } + m_memory = static_cast(memory); +} + +HostPoolView::~HostPoolView() +{ + unmap(); +} + +HostPoolView::HostPoolView(HostPoolView&& other) noexcept + : m_memory(std::exchange(other.m_memory, nullptr)), + m_slot_count(std::exchange(other.m_slot_count, 0)), + m_slot_bytes(other.m_slot_bytes), + m_slot_stride(other.m_slot_stride) +{ +} + +HostPoolView& HostPoolView::operator=(HostPoolView&& other) noexcept +{ + if (this != &other) + { + unmap(); + m_memory = std::exchange(other.m_memory, nullptr); + m_slot_count = std::exchange(other.m_slot_count, 0); + m_slot_bytes = other.m_slot_bytes; + m_slot_stride = other.m_slot_stride; + } + return *this; +} + +std::span HostPoolView::slot(std::uint32_t index) const +{ + if (index >= m_slot_count) + { + throw std::out_of_range("host pool view has no slot " + std::to_string(index)); + } + return { m_memory + m_slot_stride * index, m_slot_bytes }; +} + +void HostPoolView::unmap() +{ + if (m_memory != nullptr) + { + ::munmap(const_cast(m_memory), m_slot_stride * m_slot_count); + m_memory = nullptr; + m_slot_count = 0; + } +} + +} // namespace core::camera diff --git a/src/core/camera_ipc/cpp/inc/camera_ipc/endpoint_path.hpp b/src/core/camera_ipc/cpp/inc/camera_ipc/endpoint_path.hpp new file mode 100644 index 0000000000..4c9b450354 --- /dev/null +++ b/src/core/camera_ipc/cpp/inc/camera_ipc/endpoint_path.hpp @@ -0,0 +1,51 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include +#include +#include + +namespace core::camera +{ + +/** + * @brief This user's endpoint directory: `$XDG_RUNTIME_DIR/isaaccapture`, or + * `/tmp/isaaccapture-` when that variable is not set. The endpoint of every camera plugin + * of the user is a socket file there. + */ +std::string default_endpoint_directory(); + +/** + * @brief Where the camera plugin with this instance name listens when it is not given a path. + * + * `camera-.sock` in default_endpoint_directory(). An endpoint belongs to one camera + * plugin, and a plugin's instance name is by default the name of its backend. + * + * @throws std::invalid_argument for an empty instance name or one with anything but letters, + * digits, '-' and '_'. + */ +std::string default_endpoint_path(std::string_view instance); + +/** + * @brief The socket paths of the camera endpoints in this user's endpoint directory, sorted. + * + * These are the socket files with a name default_endpoint_path() gives; lock files and + * anything else in the directory are left out. Nothing is connected to, so a socket file left + * by a plugin that was killed is listed too, and the caller finds out when it connects. A + * directory that does not exist gives an empty list and is not created. + * + * @throws std::system_error if the directory cannot be read. + */ +std::vector default_endpoint_paths(); + +/** + * @brief Make sure the directory of an endpoint path exists and belongs to this user alone. + * Creates it with mode 0700 when it is missing. + * @throws std::system_error if it cannot be created, or exists and is not a directory this + * user owns with no access for anyone else. + */ +void prepare_endpoint_directory(const std::string& endpoint_path); + +} // namespace core::camera diff --git a/src/core/camera_ipc/cpp/inc/camera_ipc/host_pool.hpp b/src/core/camera_ipc/cpp/inc/camera_ipc/host_pool.hpp new file mode 100644 index 0000000000..54694f1436 --- /dev/null +++ b/src/core/camera_ipc/cpp/inc/camera_ipc/host_pool.hpp @@ -0,0 +1,109 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include "unique_fd.hpp" + +#include +#include +#include +#include + +namespace core::camera +{ + +/** + * @brief A pool of equally sized slots in one block of shared host memory. + * + * The process that creates the pool writes the slots. Any process that is sent the pool's + * descriptor can map it, but only for reading: the memory is sealed against new writable + * mappings, writes and resizing. + */ +class HostPool +{ +public: + /** + * @param name Shows up in /proc for debugging; it does not have to be unique. + * @throws std::invalid_argument for an empty pool. + * @throws std::system_error if the memory cannot be allocated or sealed. + */ + HostPool(std::uint32_t slot_count, std::uint64_t slot_bytes, const std::string& name); + ~HostPool(); + + HostPool(const HostPool&) = delete; + HostPool& operator=(const HostPool&) = delete; + + std::uint32_t slot_count() const + { + return m_slot_count; + } + + std::uint64_t slot_bytes() const + { + return m_slot_bytes; + } + + /** + * @brief The writable memory of one slot. + * @throws std::out_of_range for a slot the pool does not have. + */ + std::span slot(std::uint32_t index); + + /** + * @brief The pool's descriptor, to send to another process. The pool keeps owning it. + */ + int descriptor() const + { + return m_fd.get(); + } + +private: + UniqueFd m_fd; + std::byte* m_memory = nullptr; + std::uint32_t m_slot_count = 0; + std::uint64_t m_slot_bytes = 0; + std::uint64_t m_slot_stride = 0; // from the start of one slot to the start of the next +}; + +/** + * @brief Another process's read-only mapping of a HostPool, made from the descriptor it was sent. + */ +class HostPoolView +{ +public: + /** + * @param descriptor Of the pool. It is closed once the pool is mapped. + * @param slot_count, slot_bytes As the pool was created with. + * @throws std::system_error if the descriptor cannot be mapped. + * @throws std::invalid_argument if the descriptor holds less than the pool needs. + */ + HostPoolView(UniqueFd descriptor, std::uint32_t slot_count, std::uint64_t slot_bytes); + ~HostPoolView(); + + HostPoolView(HostPoolView&& other) noexcept; + HostPoolView& operator=(HostPoolView&& other) noexcept; + HostPoolView(const HostPoolView&) = delete; + HostPoolView& operator=(const HostPoolView&) = delete; + + std::uint32_t slot_count() const + { + return m_slot_count; + } + + /** + * @brief The memory of one slot. + * @throws std::out_of_range for a slot the pool does not have. + */ + std::span slot(std::uint32_t index) const; + +private: + void unmap(); + + const std::byte* m_memory = nullptr; + std::uint32_t m_slot_count = 0; + std::uint64_t m_slot_bytes = 0; + std::uint64_t m_slot_stride = 0; +}; + +} // namespace core::camera diff --git a/src/core/camera_ipc/cpp/inc/camera_ipc/message_socket.hpp b/src/core/camera_ipc/cpp/inc/camera_ipc/message_socket.hpp new file mode 100644 index 0000000000..0e74af78d4 --- /dev/null +++ b/src/core/camera_ipc/cpp/inc/camera_ipc/message_socket.hpp @@ -0,0 +1,147 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include "unique_fd.hpp" + +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +// A message carries at most this many descriptors. +inline constexpr std::size_t MAX_DESCRIPTORS_PER_MESSAGE = 64; + +enum class SendStatus +{ + SENT, + WOULD_BLOCK, // the peer's queue is full; nothing was sent + CLOSED, // the peer is gone +}; + +enum class ReceiveStatus +{ + MESSAGE, + TIMEOUT, + CLOSED, // the peer is gone +}; + +struct ReceivedMessage +{ + ReceiveStatus status = ReceiveStatus::TIMEOUT; + std::size_t bytes = 0; // of the payload, when status is MESSAGE + std::vector descriptors; // the ones that came with the message +}; + +/** + * @brief One end of a connection between two processes on this machine. It carries whole + * messages in order, each with optional file descriptors. + */ +class MessageSocket +{ +public: + /** + * @brief Connect to a MessageListener. It never waits: the connection is made or refused + * at once. + * @throws std::system_error if nothing listens on the path (ECONNREFUSED, or ENOENT when + * there is no socket file), or if the listener's queue of connections is full because its + * owner is not accepting them (EAGAIN). + */ + static MessageSocket connect(const std::string& path); + + explicit MessageSocket(UniqueFd fd); + + /** + * @brief Send one message. Never blocks. + * @throws std::invalid_argument for an empty payload (it would read as a closed connection) + * or more than MAX_DESCRIPTORS_PER_MESSAGE descriptors. + * @throws std::system_error for a failure other than a full queue or a closed peer. + */ + SendStatus send(std::span payload, std::span descriptors = {}); + + /** + * @brief Wait up to `timeout` for one message and copy its payload into `buffer`. + * @throws std::length_error if the message does not fit the buffer. + * @throws std::system_error for a failure other than a closed peer. + */ + ReceivedMessage receive(std::span buffer, std::chrono::milliseconds timeout); + + // For waiting on several sockets at once. + int descriptor() const + { + return m_fd.get(); + } + +private: + UniqueFd m_fd; +}; + +/** + * @brief Accepts connections on a socket file. Only processes of the same user can connect. + * + * Taking the path and accepting connections are two steps: the constructor takes the path and + * listen() starts accepting. In between, a connect to the path is refused at once + * (ECONNREFUSED) rather than queued. So an owner can take its path, get ready, and be reached + * only once it can answer. + * + * A lock file next to the socket file (`.lock`) decides which process owns the path, so + * of two processes that start at the same moment exactly one gets it. The lock file stays + * behind, empty, for the next listener to lock. + */ +class MessageListener +{ +public: + /** + * @brief Take `path`: lock it and put the socket file there, without accepting connections + * yet. A socket file left behind by a process that has gone is replaced; anything else found + * at the path is left alone. + * @throws std::system_error with EADDRINUSE if another process has taken the path, with + * EEXIST if the path holds something that is not a socket, or with the cause if the path + * cannot be locked or bound. + */ + explicit MessageListener(const std::string& path); + + // Removes the socket file. + ~MessageListener(); + + MessageListener(const MessageListener&) = delete; + MessageListener& operator=(const MessageListener&) = delete; + + /** + * @brief Start accepting connections. Calling it again changes nothing. + * @throws std::system_error if the socket cannot listen. + */ + void listen(); + + /** + * @brief Wait up to `timeout` for a connection. + * @return The connection, or nothing on timeout. + * @throws std::system_error if listen() has not been called. + */ + std::optional accept(std::chrono::milliseconds timeout); + + // For waiting on the listener with other descriptors, once listen() has been called. Before + // that a wait returns at once with a hang-up, never with a connection. + int descriptor() const + { + return m_fd.get(); + } + + const std::string& path() const + { + return m_path; + } + +private: + UniqueFd m_lock; // declared first, so it is released after the socket is closed + UniqueFd m_fd; + std::string m_path; +}; + +} // namespace core::camera diff --git a/src/core/camera_ipc/cpp/inc/camera_ipc/unique_fd.hpp b/src/core/camera_ipc/cpp/inc/camera_ipc/unique_fd.hpp new file mode 100644 index 0000000000..387bf46515 --- /dev/null +++ b/src/core/camera_ipc/cpp/inc/camera_ipc/unique_fd.hpp @@ -0,0 +1,73 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include + +namespace core::camera +{ + +// Owns one file descriptor and closes it. +class UniqueFd +{ +public: + UniqueFd() = default; + + explicit UniqueFd(int fd) : m_fd(fd) + { + } + + UniqueFd(UniqueFd&& other) noexcept : m_fd(other.release()) + { + } + + UniqueFd& operator=(UniqueFd&& other) noexcept + { + if (this != &other) + { + reset(other.release()); + } + return *this; + } + + UniqueFd(const UniqueFd&) = delete; + UniqueFd& operator=(const UniqueFd&) = delete; + + ~UniqueFd() + { + reset(); + } + + int get() const + { + return m_fd; + } + + bool valid() const + { + return m_fd >= 0; + } + + // Gives the descriptor up without closing it. + int release() + { + const int fd = m_fd; + m_fd = -1; + return fd; + } + + void reset(int fd = -1) + { + if (m_fd >= 0) + { + ::close(m_fd); + } + m_fd = fd; + } + +private: + int m_fd = -1; +}; + +} // namespace core::camera diff --git a/src/core/camera_ipc/cpp/message_socket.cpp b/src/core/camera_ipc/cpp/message_socket.cpp new file mode 100644 index 0000000000..3ae67099e4 --- /dev/null +++ b/src/core/camera_ipc/cpp/message_socket.cpp @@ -0,0 +1,288 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_ipc/message_socket.hpp" + +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +namespace +{ + +[[noreturn]] void throw_errno(const std::string& what) +{ + throw std::system_error(errno, std::generic_category(), what); +} + +sockaddr_un address_of(const std::string& path) +{ + sockaddr_un address = {}; + address.sun_family = AF_UNIX; + if (path.empty() || path.size() >= sizeof(address.sun_path)) + { + throw std::invalid_argument("socket path '" + path + "' is empty or too long"); + } + std::memcpy(address.sun_path, path.data(), path.size()); + return address; +} + +UniqueFd new_socket(int extra_flags = 0) +{ + UniqueFd fd(::socket(AF_UNIX, SOCK_SEQPACKET | SOCK_CLOEXEC | extra_flags, 0)); + if (!fd.valid()) + { + throw_errno("creating a socket"); + } + return fd; +} + +// Waits until the descriptor is readable. Returns false on timeout. +bool wait_readable(int fd, std::chrono::milliseconds timeout) +{ + using Milliseconds = std::chrono::milliseconds; + const Milliseconds longest(std::numeric_limits::max()); // what poll() can wait + const auto deadline = std::chrono::steady_clock::now() + std::clamp(timeout, Milliseconds::zero(), longest); + pollfd entry = { fd, POLLIN, 0 }; + for (;;) + { + // An interrupted wait resumes with the time that is left, not the whole timeout again. + const auto left = std::chrono::ceil(deadline - std::chrono::steady_clock::now()); + const int ready = ::poll(&entry, 1, static_cast(std::max(left, Milliseconds::zero()).count())); + if (ready > 0) + { + return true; + } + if (ready == 0) + { + return false; + } + if (errno != EINTR) + { + throw_errno("waiting on a socket"); + } + } +} + +} // namespace + +MessageSocket MessageSocket::connect(const std::string& path) +{ + const sockaddr_un address = address_of(path); + // Not blocking: a listener whose owner has stopped accepting fills its queue of connections, + // and a blocking connect to a full queue would wait until that owner runs again. + UniqueFd fd = new_socket(SOCK_NONBLOCK); + if (::connect(fd.get(), reinterpret_cast(&address), sizeof(address)) != 0) + { + throw_errno("connecting to '" + path + "'"); + } + return MessageSocket(std::move(fd)); +} + +MessageSocket::MessageSocket(UniqueFd fd) : m_fd(std::move(fd)) +{ +} + +SendStatus MessageSocket::send(std::span payload, std::span descriptors) +{ + if (payload.empty() || descriptors.size() > MAX_DESCRIPTORS_PER_MESSAGE) + { + throw std::invalid_argument("a message needs a payload and carries at most " + + std::to_string(MAX_DESCRIPTORS_PER_MESSAGE) + " descriptors"); + } + iovec data = { const_cast(payload.data()), payload.size() }; + msghdr message = {}; + message.msg_iov = &data; + message.msg_iovlen = 1; + + alignas(cmsghdr) char control[CMSG_SPACE(sizeof(int) * MAX_DESCRIPTORS_PER_MESSAGE)]; + if (!descriptors.empty()) + { + message.msg_control = control; + message.msg_controllen = CMSG_SPACE(descriptors.size_bytes()); + cmsghdr* header = CMSG_FIRSTHDR(&message); + header->cmsg_level = SOL_SOCKET; + header->cmsg_type = SCM_RIGHTS; + header->cmsg_len = CMSG_LEN(descriptors.size_bytes()); + std::memcpy(CMSG_DATA(header), descriptors.data(), descriptors.size_bytes()); + } + + for (;;) + { + if (::sendmsg(m_fd.get(), &message, MSG_DONTWAIT | MSG_NOSIGNAL) >= 0) + { + return SendStatus::SENT; + } + if (errno == EAGAIN || errno == EWOULDBLOCK) + { + return SendStatus::WOULD_BLOCK; + } + if (errno == EPIPE || errno == ECONNRESET || errno == ENOTCONN) + { + return SendStatus::CLOSED; + } + if (errno != EINTR) + { + throw_errno("sending a message"); + } + } +} + +ReceivedMessage MessageSocket::receive(std::span buffer, std::chrono::milliseconds timeout) +{ + ReceivedMessage result; + if (!wait_readable(m_fd.get(), timeout)) + { + return result; + } + iovec data = { buffer.data(), buffer.size() }; + alignas(cmsghdr) char control[CMSG_SPACE(sizeof(int) * MAX_DESCRIPTORS_PER_MESSAGE)]; + msghdr message = {}; + message.msg_iov = &data; + message.msg_iovlen = 1; + message.msg_control = control; + message.msg_controllen = sizeof(control); + + ssize_t received = 0; + do + { + received = ::recvmsg(m_fd.get(), &message, MSG_DONTWAIT | MSG_CMSG_CLOEXEC); + } while (received < 0 && errno == EINTR); + if (received < 0) + { + if (errno == EAGAIN || errno == EWOULDBLOCK) + { + return result; + } + if (errno == ECONNRESET) + { + result.status = ReceiveStatus::CLOSED; + return result; + } + throw_errno("receiving a message"); + } + + // Take ownership of every descriptor first, so none leaks if the message is rejected below. + for (cmsghdr* header = CMSG_FIRSTHDR(&message); header != nullptr; header = CMSG_NXTHDR(&message, header)) + { + if (header->cmsg_level != SOL_SOCKET || header->cmsg_type != SCM_RIGHTS) + { + continue; + } + const std::size_t count = (header->cmsg_len - CMSG_LEN(0)) / sizeof(int); + for (std::size_t i = 0; i < count; ++i) + { + int fd = -1; + std::memcpy(&fd, CMSG_DATA(header) + i * sizeof(int), sizeof(int)); + result.descriptors.emplace_back(fd); + } + } + // Checked before the empty read below: a cut message can also come back with no bytes. + if ((message.msg_flags & (MSG_TRUNC | MSG_CTRUNC)) != 0) + { + throw std::length_error("received a message larger than the buffer or with too many descriptors"); + } + if (received == 0 && result.descriptors.empty()) + { + result.status = ReceiveStatus::CLOSED; // an orderly shutdown reads as an empty message + return result; + } + result.status = ReceiveStatus::MESSAGE; + result.bytes = static_cast(received); + return result; +} + +MessageListener::MessageListener(const std::string& path) : m_path(path) +{ + const sockaddr_un address = address_of(path); + + // The lock decides who owns the path. The kernel drops it when its holder dies, so a socket + // file found while holding it was left by a process that is gone. + const std::string lock_path = path + ".lock"; + m_lock.reset(::open(lock_path.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, S_IRUSR | S_IWUSR)); + if (!m_lock.valid()) + { + throw_errno("opening '" + lock_path + "'"); + } + if (::flock(m_lock.get(), LOCK_EX | LOCK_NB) != 0) + { + if (errno == EWOULDBLOCK) + { + throw std::system_error(EADDRINUSE, std::generic_category(), "another process has taken '" + path + "'"); + } + throw_errno("locking '" + lock_path + "'"); + } + struct stat entry = {}; + if (::lstat(path.c_str(), &entry) == 0) + { + if (!S_ISSOCK(entry.st_mode)) + { + throw std::system_error(EEXIST, std::generic_category(), "'" + path + "' exists and is not a socket"); + } + ::unlink(path.c_str()); + } + else if (errno != ENOENT) + { + throw_errno("inspecting '" + path + "'"); + } + + // Not blocking: a connection that goes away between the wait and the accept must not stall accept(). + m_fd = new_socket(SOCK_NONBLOCK); + // The socket file is created with the socket's own mode: only this user may connect. + if (::fchmod(m_fd.get(), S_IRUSR | S_IWUSR) != 0) + { + throw_errno("restricting '" + path + "'"); + } + // Bound and not yet listening: the path is taken, and the kernel refuses a connect to it. + if (::bind(m_fd.get(), reinterpret_cast(&address), sizeof(address)) != 0) + { + throw_errno("binding '" + path + "'"); + } +} + +MessageListener::~MessageListener() +{ + ::unlink(m_path.c_str()); +} + +void MessageListener::listen() +{ + if (::listen(m_fd.get(), SOMAXCONN) != 0) + { + throw_errno("listening on '" + m_path + "'"); + } +} + +std::optional MessageListener::accept(std::chrono::milliseconds timeout) +{ + if (!wait_readable(m_fd.get(), timeout)) + { + return std::nullopt; + } + UniqueFd connection(::accept4(m_fd.get(), nullptr, nullptr, SOCK_CLOEXEC)); + if (!connection.valid()) + { + if (errno == EAGAIN || errno == EWOULDBLOCK || errno == ECONNABORTED || errno == EINTR) + { + return std::nullopt; + } + throw_errno("accepting a connection on '" + m_path + "'"); + } + return MessageSocket(std::move(connection)); +} + +} // namespace core::camera diff --git a/tests/cpp/core/CMakeLists.txt b/tests/cpp/core/CMakeLists.txt index 54c6e1e0d5..541201d114 100644 --- a/tests/cpp/core/CMakeLists.txt +++ b/tests/cpp/core/CMakeLists.txt @@ -14,6 +14,12 @@ add_subdirectory(tracker_metadata) add_subdirectory(log_bridge) add_subdirectory(plugin_manager) +add_subdirectory(camera_core) + +if(CMAKE_SYSTEM_NAME STREQUAL "Linux") + add_subdirectory(camera_ipc) +endif() + if(BUILD_OVXR_CAMERA_QUADS) add_subdirectory(ovxr_pip_layer) endif() diff --git a/tests/cpp/core/camera_core/CMakeLists.txt b/tests/cpp/core/camera_core/CMakeLists.txt new file mode 100644 index 0000000000..f74232fd6b --- /dev/null +++ b/tests/cpp/core/camera_core/CMakeLists.txt @@ -0,0 +1,19 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +find_package(Threads REQUIRED) + +add_executable(camera_core_tests + test_publisher.cpp +) + +target_link_libraries(camera_core_tests PRIVATE + camera::camera_core + Catch2::Catch2WithMain + Threads::Threads +) + +message(STATUS "camera_core_tests target enabled with Catch2") +catch_discover_tests(camera_core_tests ADD_TAGS_AS_LABELS) diff --git a/tests/cpp/core/camera_core/test_publisher.cpp b/tests/cpp/core/camera_core/test_publisher.cpp new file mode 100644 index 0000000000..fa19192602 --- /dev/null +++ b/tests/cpp/core/camera_core/test_publisher.cpp @@ -0,0 +1,1015 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace core::camera; + +namespace +{ + +// A reader that keeps every event it is sent. +struct RecordingSink : EventSink +{ + bool send_event(SubscriptionId, const FrameEvent& event) noexcept override + { + if (!accept) + { + return false; + } + events.push_back(event); + return true; + } + + std::vector events; + bool accept = true; +}; + +GroupDescription make_group(std::uint32_t slots, std::size_t streams = 2, const std::string& id = "head") +{ + GroupDescription group; + group.id = id; + for (std::size_t i = 0; i < streams; ++i) + { + StreamDescription stream; + stream.id = id + "/" + std::to_string(i); + stream.width = 640; + stream.height = 400; + stream.plane_count = 1; + stream.planes[0].stride_bytes = 640 * 4; + stream.slot_bytes = 640 * 400 * 4; + stream.slot_count = slots; + stream.frame_rate = 60.0; + group.streams.push_back(stream); + } + return group; +} + +// Publishes one frame set the way a backend does: take a free slot per stream, then publish. +std::uint64_t publish_next(Publisher& publisher, GroupId group, const FrameTimeline& timeline = {}) +{ + const std::size_t streams = publisher.group_description(group).streams.size(); + std::vector images(streams); + for (std::size_t i = 0; i < streams; ++i) + { + const auto slot = publisher.acquire_slot(group, i); + REQUIRE(slot.has_value()); + images[i].slot = *slot; + } + return publisher.publish(group, images, timeline); +} + +// A subscription as the endpoint sets one up: reserved, then, once the reader knows of it, active. +SubscribeResult open(Publisher& publisher, EventSink& sink, GroupId group, const ReaderOptions& options = {}) +{ + const SubscribeResult result = publisher.subscribe(sink, group, options); + if (result) + { + publisher.activate(result.id); + } + return result; +} + +std::vector sequences(const RecordingSink& sink) +{ + std::vector result; + for (const FrameEvent& event : sink.events) + { + result.push_back(event.sequence); + } + return result; +} + +} // namespace + +TEST_CASE("a newest-order reader gets the newest frame set when it asks", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + + // Nothing is held for a reader that has not asked. + publish_next(publisher, group); + publish_next(publisher, group); + REQUIRE(sink.events.empty()); + + REQUIRE(publisher.request_newest(reader.id, 0)); + REQUIRE(sequences(sink) == std::vector{ 2 }); + REQUIRE(sink.events[0].skipped == 0); + REQUIRE(sink.events[0].image_count == 2); + + // It asks again while it still holds frame set 2: the answer waits for room, and is the + // newest frame set there is when the room comes. + REQUIRE(publisher.request_newest(reader.id, 2)); + publish_next(publisher, group); + publish_next(publisher, group); + REQUIRE(sink.events.size() == 1); + + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(sequences(sink) == std::vector{ 2, 4 }); + REQUIRE(sink.events[1].skipped == 1); +} + +TEST_CASE("a newest-order reader that is waiting is sent a frame set as it is published", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + + REQUIRE(publisher.request_newest(reader.id, 0)); + REQUIRE(sink.events.empty()); + publish_next(publisher, group); + REQUIRE(sequences(sink) == std::vector{ 1 }); + + // One request, one frame set. + publisher.release(reader.id, sink.events[0].lease_id); + publish_next(publisher, group); + REQUIRE(sink.events.size() == 1); +} + +TEST_CASE("a reader that paused gets the newest frame set, not the one from when it stopped", + "[unit][camera_core][delivery]") +{ + std::int64_t now = 0; + Publisher publisher([&] { return now; }); + const GroupId group = publisher.add_group(make_group(4, 1)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + + REQUIRE(publisher.request_newest(reader.id, 0)); + publish_next(publisher, group); + publisher.release(reader.id, sink.events[0].lease_id); + + // The reader does something else for five frame periods, holding nothing and asking for + // nothing. Nothing is put aside for it: every slot but the ring's one is free throughout. + for (int i = 0; i < 5; ++i) + { + now += 10; + publish_next(publisher, group); + REQUIRE(sink.events.size() == 1); + std::vector free_slots; + while (const auto slot = publisher.acquire_slot(group, 0)) + { + free_slots.push_back(*slot); + } + REQUIRE(free_slots.size() == 3); + for (const std::uint32_t slot : free_slots) + { + publisher.abandon_slot(group, 0, slot); + } + } + + // When it comes back it is handed the frame set published last, held from this moment. + now += 3; + REQUIRE(publisher.request_newest(reader.id, 1)); + REQUIRE(sequences(sink) == std::vector{ 1, 6 }); + REQUIRE(sink.events[1].skipped == 4); + REQUIRE(sink.events[1].timeline.published_ns == 50); + REQUIRE(sink.events[1].timeline.sent_ns == 53); +} + +TEST_CASE("a frame set given back unseen is sent again while it is still the newest", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + + REQUIRE(publisher.request_newest(reader.id, 0)); + publish_next(publisher, group); + publisher.release(reader.id, sink.events[0].lease_id); + + // The reader asked, gave up waiting, and frame set 2 arrived for it later. It cannot tell + // whether 2 is still the newest, so it gives it back and asks again, naming the last one + // it took. + REQUIRE(publisher.request_newest(reader.id, 1)); + publish_next(publisher, group); + REQUIRE(sequences(sink) == std::vector{ 1, 2 }); + publisher.release(reader.id, sink.events[1].lease_id); + REQUIRE(publisher.request_newest(reader.id, 1)); + REQUIRE(sequences(sink) == std::vector{ 1, 2, 2 }); + REQUIRE(sink.events[2].skipped == 0); + REQUIRE(sink.events[2].lease_id != sink.events[1].lease_id); + + // Had a newer one been published meanwhile, that is the one it gets. + publish_next(publisher, group); + publisher.release(reader.id, sink.events[2].lease_id); + REQUIRE(publisher.request_newest(reader.id, 1)); + REQUIRE(sink.events.back().sequence == 3); + REQUIRE(sink.events.back().skipped == 1); +} + +TEST_CASE("a subscription is sent nothing until it is activated", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink in_order; + RecordingSink newest; + const SubscribeResult ordered = publisher.subscribe(in_order, group, { .window = 2 }); + const SubscribeResult latest = publisher.subscribe(newest, group, { .window = 1 }); + REQUIRE(ordered); + REQUIRE(latest); + + // Reserved: both count in the budget (2 ring history + 3 windows + 1 reserve), neither + // is sent anything, and a request is refused. + for (int i = 0; i < 3; ++i) + { + publish_next(publisher, group); + } + REQUIRE(in_order.events.empty()); + REQUIRE_FALSE(publisher.request_newest(latest.id, 0)); + RecordingSink third; + REQUIRE_FALSE(publisher.subscribe(third, group, { .window = 3 })); + + // Active: the in-order reader starts at once with what the ring kept, which is what was + // published while it was only reserved. It does not have to wait for the next publish. + publisher.activate(ordered.id); + publisher.activate(latest.id); + REQUIRE(sequences(in_order) == std::vector{ 2, 3 }); + REQUIRE(in_order.events[0].skipped == 0); + REQUIRE(newest.events.empty()); + publish_next(publisher, group); + REQUIRE(in_order.events.size() == 2); // its window of two is full + + // Asking is for newest-order readers. + REQUIRE_FALSE(publisher.request_newest(ordered.id, 0)); + REQUIRE(publisher.request_newest(latest.id, 0)); + REQUIRE(sequences(newest) == std::vector{ 4 }); + REQUIRE_FALSE(publisher.request_newest(99, 0)); +} + +TEST_CASE("a larger window gets every frame set in order", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 3 }); + REQUIRE(reader); + + for (int i = 0; i < 4; ++i) + { + publish_next(publisher, group); + } + // Three are out, the fourth waits in the ring until the reader has room. + REQUIRE(sequences(sink) == std::vector{ 1, 2, 3 }); + + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(sequences(sink) == std::vector{ 1, 2, 3, 4 }); + REQUIRE(sink.events[3].skipped == 0); +} + +TEST_CASE("an in-order reader that falls behind is told what it skipped", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 2 }); + REQUIRE(reader); + + for (int i = 0; i < 6; ++i) + { + publish_next(publisher, group); + } + REQUIRE(sequences(sink) == std::vector{ 1, 2 }); + + // The ring kept the last two (5 and 6); 3 and 4 are gone. + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(sequences(sink) == std::vector{ 1, 2, 5 }); + REQUIRE(sink.events[2].skipped == 2); + + publisher.release(reader.id, sink.events[1].lease_id); + REQUIRE(sequences(sink) == std::vector{ 1, 2, 5, 6 }); + REQUIRE(sink.events[3].skipped == 0); +} + +TEST_CASE("newest order with a larger window skips to the newest frame set", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 2, .order = DeliveryOrder::NEWEST }); + REQUIRE(reader); + + // It holds two frame sets at a time and asks for a third. + REQUIRE(publisher.request_newest(reader.id, 0)); + publish_next(publisher, group); + REQUIRE(publisher.request_newest(reader.id, 1)); + publish_next(publisher, group); + REQUIRE(sequences(sink) == std::vector{ 1, 2 }); + REQUIRE(publisher.request_newest(reader.id, 2)); + publish_next(publisher, group); + publish_next(publisher, group); + REQUIRE(sink.events.size() == 2); + + // A viewer that holds one frame and wants the newest must not be handed frame set 3. + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(sequences(sink) == std::vector{ 1, 2, 4 }); + REQUIRE(sink.events[2].skipped == 1); +} + +TEST_CASE("a subscription that does not fit the pool is refused", "[unit][camera_core][budget]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(4)); + RecordingSink first; + RecordingSink second; + + // 1 ring history + 1 window + 1 backend reserve = 3 of 4 slots. + REQUIRE(publisher.subscribe(first, group, { .window = 1 })); + + // An in-order reader with a window of two needs 2 ring history + 3 windows + 1 reserve = 6. + const SubscribeResult refused = publisher.subscribe(second, group, { .window = 2 }); + REQUIRE_FALSE(refused); + REQUIRE_THAT(refused.error, Catch::Matchers::ContainsSubstring("needs 6 slots")); + REQUIRE_THAT(refused.error, Catch::Matchers::ContainsSubstring("pool has 4")); + + // A second newest-only reader needs 1 + 2 + 1 = 4 and fits. + REQUIRE(publisher.subscribe(second, group, { .window = 1 })); + + REQUIRE_FALSE(publisher.subscribe(second, group, { .window = 0 })); + REQUIRE_FALSE(publisher.subscribe(second, 99, { .window = 1 })); +} + +TEST_CASE("the backend reserve counts against the pool", "[unit][camera_core][budget]") +{ + Publisher publisher; + // An SDK that keeps four captures in flight, on a pool of eight. + const GroupId group = publisher.add_group(make_group(8), 4); + RecordingSink sinks[4]; + + // 1 ring history + 3 windows + 4 reserve = 8. + for (int i = 0; i < 3; ++i) + { + REQUIRE(publisher.subscribe(sinks[i], group, { .window = 1 })); + } + const SubscribeResult refused = publisher.subscribe(sinks[3], group, { .window = 1 }); + REQUIRE_FALSE(refused); + REQUIRE_THAT(refused.error, Catch::Matchers::ContainsSubstring("4 for the backend")); +} + +TEST_CASE("a slot is reused only when neither the ring nor a reader holds it", "[unit][camera_core][slots]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(3, 1)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + REQUIRE(publisher.request_newest(reader.id, 0)); + + publish_next(publisher, group); // slot 0: held by the reader + publish_next(publisher, group); // slot 1: held by the ring + REQUIRE(sink.events.size() == 1); + REQUIRE(sink.events[0].images[0].slot == 0); + REQUIRE(publisher.request_newest(reader.id, 1)); // waits for the reader to have room + + const auto third = publisher.acquire_slot(group, 0); + REQUIRE(third == 2u); + REQUIRE_FALSE(publisher.acquire_slot(group, 0).has_value()); + REQUIRE(publisher.stats(group).no_free_slot == 1); + publisher.abandon_slot(group, 0, *third); + + // Releasing frame set 1 frees slot 0 and hands the reader frame set 2. + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(sink.events.size() == 2); + REQUIRE(sink.events[1].images[0].slot == 1); + REQUIRE(publisher.acquire_slot(group, 0) == 0u); +} + +TEST_CASE("the slot-free callback fires when the last holder lets go", "[unit][camera_core][slots]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(4, 1)); + std::vector> freed; + publisher.set_slot_free_callback(group, + [&](std::size_t stream, std::uint32_t slot) + { + // Runs outside the publisher's lock, so calling back in must not deadlock. + (void)publisher.stats(group); + freed.emplace_back(stream, slot); + }); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + REQUIRE(publisher.request_newest(reader.id, 0)); + + // The SDK owns the buffers and picks the slot it filled. + const auto publish_slot = [&](std::uint32_t slot) + { + publisher.claim_slot(group, 0, slot); + ImageInfo image; + image.slot = slot; + publisher.publish(group, { &image, 1 }, {}); + }; + + publish_slot(0); // ring + reader + publish_slot(1); // the ring lets slot 0 go, the reader still has it + REQUIRE(freed.empty()); + REQUIRE_THROWS_AS(publisher.claim_slot(group, 0, 0), std::invalid_argument); + + REQUIRE(publisher.request_newest(reader.id, 1)); + publisher.release(reader.id, sink.events[0].lease_id); // reader moves on to slot 1 + REQUIRE(freed == std::vector>{ { 0, 0 } }); + + publish_slot(2); // the ring lets slot 1 go, the reader still has it + REQUIRE(freed.size() == 1); + publisher.unsubscribe(reader.id); + REQUIRE(freed == std::vector>{ { 0, 0 }, { 0, 1 } }); + + // A slot the backend gives up itself needs no notification. + publisher.claim_slot(group, 0, 0); + publisher.abandon_slot(group, 0, 0); + REQUIRE(freed.size() == 2); +} + +TEST_CASE("unsubscribing returns every frame set the reader held", "[unit][camera_core][slots]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(8, 1)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 3 }); + REQUIRE(reader); + for (int i = 0; i < 3; ++i) + { + publish_next(publisher, group); + } + REQUIRE(sink.events.size() == 3); + + publisher.unsubscribe(reader.id); + // Only the newest frame set stays in the ring: seven of the eight slots are free again. + for (int i = 0; i < 7; ++i) + { + REQUIRE(publisher.acquire_slot(group, 0).has_value()); + } + REQUIRE_FALSE(publisher.acquire_slot(group, 0).has_value()); + + // Releasing after the subscription ended is harmless. + publisher.release(reader.id, sink.events[0].lease_id); +} + +TEST_CASE("a frame set that could not be sent is not counted as held", "[unit][camera_core][delivery]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(3, 1)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + REQUIRE(publisher.request_newest(reader.id, 0)); + + sink.accept = false; + publish_next(publisher, group); + REQUIRE(publisher.stats(group).send_failures == 1); + REQUIRE(sink.events.empty()); + + // The reader is still waiting, so the next frame set is tried too. + sink.accept = true; + publish_next(publisher, group); + REQUIRE(sequences(sink) == std::vector{ 2 }); + REQUIRE(sink.events[0].skipped == 0); + REQUIRE(publisher.stats(group).events_sent == 1); + + // Frame set 1 left the ring and no reader holds it: its slot is free. + REQUIRE(publisher.acquire_slot(group, 0) == 0u); +} + +TEST_CASE("a restart changes the generation and empties the ring", "[unit][camera_core][lifecycle]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(4, 1)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + REQUIRE(publisher.request_newest(reader.id, 0)); + + publish_next(publisher, group); + REQUIRE(sink.events[0].generation == 0); + + publisher.restart_group(group); + REQUIRE(publisher.generation(group) == 1); + + // The frame set the reader holds stays valid, and its slot out of use, until it is given + // back; the sequence keeps counting. + REQUIRE(publisher.acquire_slot(group, 0) == 1u); + publisher.abandon_slot(group, 0, 1); + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(publisher.acquire_slot(group, 0) == 0u); + publisher.abandon_slot(group, 0, 0); + REQUIRE(sink.events.size() == 1); + REQUIRE(publisher.request_newest(reader.id, 1)); + REQUIRE(sink.events.size() == 1); // the ring was emptied: nothing from before the restart + publish_next(publisher, group); + REQUIRE(sink.events.size() == 2); + REQUIRE(sink.events[1].generation == 1); + REQUIRE(sink.events[1].sequence == 2); +} + +TEST_CASE("a group publishes one image per stream", "[unit][camera_core][groups]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(4, 3, "rig")); + REQUIRE(publisher.find_group("rig") == group); + REQUIRE_FALSE(publisher.find_group("head").has_value()); + REQUIRE(publisher.group_count() == 1); + + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + REQUIRE(publisher.request_newest(reader.id, 0)); + + std::vector images(3); + for (std::size_t i = 0; i < 3; ++i) + { + images[i].slot = *publisher.acquire_slot(group, i); + images[i].device_frame_id = 100 + i; + } + images[1].flags = IMAGE_FLAG_KEYFRAME; + images[1].bytes_used = 4096; + images[2].flags = IMAGE_FLAG_SDK_WARNING; + publisher.publish(group, images, {}); + + REQUIRE(sink.events.size() == 1); + const FrameEvent& event = sink.events[0]; + REQUIRE(event.image_count == 3); + REQUIRE(event.images[0].device_frame_id == 100); + REQUIRE(event.images[1].flags == IMAGE_FLAG_KEYFRAME); + REQUIRE(event.images[1].bytes_used == 4096); + REQUIRE(event.images[2].flags == IMAGE_FLAG_SDK_WARNING); +} + +TEST_CASE("an encoded stream is described by its codec, not by a pixel format", "[unit][camera_core][groups]") +{ + GroupDescription description = make_group(4, 1, "head.enc"); + StreamDescription& stream = description.streams[0]; + REQUIRE_FALSE(stream.is_encoded()); + stream.codec = Codec::H265; + stream.plane_count = 0; + stream.slot_bytes = 2 * 1024 * 1024; // room for one access unit + + Publisher publisher; + const GroupId group = publisher.add_group(description); + const StreamDescription stored = publisher.group_description(group).streams[0]; + REQUIRE(stored.is_encoded()); + REQUIRE(stored.codec == Codec::H265); + REQUIRE(stored.slot_bytes == 2 * 1024 * 1024); +} + +TEST_CASE("every frame set carries its timeline", "[unit][camera_core][timeline]") +{ + std::int64_t now = 1000; + Publisher publisher([&] { return now; }); + const GroupId group = publisher.add_group(make_group(4, 1)); + RecordingSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 1 }); + REQUIRE(reader); + REQUIRE(publisher.request_newest(reader.id, 0)); + + FrameTimeline timeline; + timeline.capture_ns = 100; + timeline.sdk_ready_ns = 900; + publish_next(publisher, group, timeline); + REQUIRE(sink.events[0].timeline.capture_ns == 100); + REQUIRE(sink.events[0].timeline.sdk_ready_ns == 900); + REQUIRE(sink.events[0].timeline.published_ns == 1000); + REQUIRE(sink.events[0].timeline.sent_ns == 1000); + + // A frame set that waits for the reader is stamped as sent when it leaves. + REQUIRE(publisher.request_newest(reader.id, 1)); + now = 2000; + publish_next(publisher, group); + now = 2500; + publisher.release(reader.id, sink.events[0].lease_id); + REQUIRE(sink.events[1].timeline.capture_ns == TIME_UNKNOWN); + REQUIRE(sink.events[1].timeline.published_ns == 2000); + REQUIRE(sink.events[1].timeline.sent_ns == 2500); +} + +TEST_CASE("misuse by a backend is rejected", "[unit][camera_core][validation]") +{ + Publisher publisher; + REQUIRE_THROWS_AS(publisher.add_group(make_group(4, 0)), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.add_group(make_group(4, MAX_STREAMS_PER_GROUP + 1)), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.add_group(make_group(0)), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.add_group(make_group(MAX_SLOTS_PER_STREAM + 1)), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.add_group(make_group(4), 0), std::invalid_argument); + + // A pool holds at least one frame set for the ring on top of the backend's reserve. + REQUIRE_THROWS_AS(publisher.add_group(make_group(1)), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.add_group(make_group(4), 4), std::invalid_argument); + REQUIRE_NOTHROW(publisher.add_group(make_group(4, 2, "tight"), 3)); + + // A pixel stream names every plane of its format; an encoded stream has none. + GroupDescription nv12 = make_group(4, 1, "nv12"); + nv12.streams[0].pixel_format = PixelFormat::NV12; + REQUIRE_THROWS_AS(publisher.add_group(nv12), std::invalid_argument); + nv12.streams[0].plane_count = 2; + nv12.streams[0].planes[1] = { .offset_bytes = 640 * 400, .stride_bytes = 640 }; + REQUIRE_NOTHROW(publisher.add_group(nv12)); + GroupDescription encoded_with_planes = make_group(4, 1, "enc"); + encoded_with_planes.streams[0].codec = Codec::H264; + REQUIRE_THROWS_AS(publisher.add_group(encoded_with_planes), std::invalid_argument); + GroupDescription no_size = make_group(4, 1, "empty"); + no_size.streams[0].width = 0; + REQUIRE_THROWS_AS(publisher.add_group(no_size), std::invalid_argument); + + const GroupId group = publisher.add_group(make_group(4)); + REQUIRE_THROWS_AS(publisher.add_group(make_group(4)), std::invalid_argument); // same id + + // Publishing needs one image per stream, each in a slot the backend took first. + std::vector images(2); + REQUIRE_THROWS_AS(publisher.publish(group, images, {}), std::invalid_argument); + images[0].slot = *publisher.acquire_slot(group, 0); + REQUIRE_THROWS_AS(publisher.publish(group, { images.data(), 1 }, {}), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.publish(group, images, {}), std::invalid_argument); // stream 1 not acquired + + // An image cannot be larger than the slot it sits in. + images[1].slot = *publisher.acquire_slot(group, 1); + images[1].bytes_used = publisher.group_description(group).streams[1].slot_bytes + 1; + REQUIRE_THROWS_AS(publisher.publish(group, images, {}), std::invalid_argument); + REQUIRE(publisher.stats(group).published == 0); + images[1].bytes_used = 0; + REQUIRE(publisher.publish(group, images, {}) == 1); // the slots were still the backend's to publish + + REQUIRE_THROWS_AS(publisher.abandon_slot(group, 1, 0), std::invalid_argument); + REQUIRE_THROWS_AS(publisher.acquire_slot(99, 0), std::out_of_range); + REQUIRE_THROWS_AS(publisher.claim_slot(group, 0, 99), std::invalid_argument); +} + +TEST_CASE("a plane that does not lie inside the slot is rejected", "[unit][camera_core][validation]") +{ + Publisher publisher; + const auto with = [](auto&& change) + { + GroupDescription group = make_group(4, 1); + change(group.streams[0]); + return group; + }; + + // A row is as long as the format needs, and the last row ends inside the slot. + REQUIRE_THROWS_AS( + publisher.add_group(with([](StreamDescription& stream) { stream.planes[0].stride_bytes = 640 * 4 - 1; })), + std::invalid_argument); + REQUIRE_THROWS_AS(publisher.add_group(with([](StreamDescription& stream) { stream.planes[0].offset_bytes = 1; })), + std::invalid_argument); + REQUIRE_THROWS_AS( + publisher.add_group(with([](StreamDescription& stream) { stream.slot_bytes -= 1; })), std::invalid_argument); + REQUIRE_THROWS_AS( + publisher.add_group(with([](StreamDescription& stream) { stream.planes[0].stride_bytes = 0xFFFFFFFF; })), + std::invalid_argument); + + // Padding between rows is fine as long as the last row still fits. + const auto padded = [](StreamDescription& stream) + { + stream.planes[0].stride_bytes = 4096; + stream.slot_bytes = 4096 * 399 + 640 * 4; + }; + REQUIRE_NOTHROW(publisher.add_group(with(padded))); + + // NV12 with odd sides: chroma rows cover the rounded-up half, and both planes must fit. + const auto nv12 = [](std::uint64_t slot_bytes) + { + return [slot_bytes](StreamDescription& stream) + { + stream.id = "nv12"; + stream.pixel_format = PixelFormat::NV12; + stream.width = 5; + stream.height = 3; + stream.plane_count = 2; + stream.planes[0] = { .offset_bytes = 0, .stride_bytes = 8 }; + stream.planes[1] = { .offset_bytes = 24, .stride_bytes = 8 }; + stream.slot_bytes = slot_bytes; + }; + }; + REQUIRE_THROWS_AS(publisher.add_group(with(nv12(24 + 8 + 5))), std::invalid_argument); // chroma row needs 6 + GroupDescription odd = with(nv12(24 + 8 + 6)); + odd.id = "odd"; + REQUIRE_NOTHROW(publisher.add_group(odd)); +} + +TEST_CASE("a description is checked without sums that can wrap", "[unit][camera_core][validation]") +{ + const auto with = [](auto&& change) + { + GroupDescription group = make_group(4, 2); + change(group); + return problem_with(group); + }; + REQUIRE(problem_with(make_group(4, 2)).empty()); + + // The largest numbers the fields hold: a product of them would wrap 64 bits. + const std::uint32_t most = std::numeric_limits::max(); + REQUIRE_FALSE(with( + [&](GroupDescription& group) + { + StreamDescription& stream = group.streams[0]; + stream.width = most; + stream.height = most; + stream.planes[0] = { .offset_bytes = most, .stride_bytes = most }; + stream.slot_bytes = MAX_SLOT_BYTES; + }) + .empty()); + REQUIRE_THAT(with([](GroupDescription& group) { group.streams[0].slot_bytes = MAX_SLOT_BYTES + 1; }), + Catch::Matchers::ContainsSubstring("slot size")); + REQUIRE_THAT(with([](GroupDescription& group) { group.streams[1].id = group.streams[0].id; }), + Catch::Matchers::ContainsSubstring("two streams called")); + REQUIRE_THAT( + with([](GroupDescription& group) { group.streams[0].frame_rate = std::numeric_limits::quiet_NaN(); }), + Catch::Matchers::ContainsSubstring("frame rate")); + REQUIRE_THAT(with([](GroupDescription& group) { group.streams[0].frame_rate = -1.0; }), + Catch::Matchers::ContainsSubstring("frame rate")); + REQUIRE_THAT(with([](GroupDescription& group) { group.streams[0].plane_count = MAX_PLANES_PER_IMAGE + 1; }), + Catch::Matchers::ContainsSubstring("plane")); + REQUIRE_THAT(with([](GroupDescription& group) { group.streams[0].id.clear(); }), + Catch::Matchers::ContainsSubstring("without an id")); + REQUIRE_THAT( + with([](GroupDescription& group) { group.id.clear(); }), Catch::Matchers::ContainsSubstring("needs an id")); + + // A frame rate that is not known is described as 0. + REQUIRE(with([](GroupDescription& group) { group.streams[0].frame_rate = 0.0; }).empty()); +} + +TEST_CASE("every group has a session id", "[unit][camera_core][groups]") +{ + Publisher publisher; + const GroupId head = publisher.add_group(make_group(4, 1, "head")); + const GroupId wrist = publisher.add_group(make_group(4, 1, "wrist")); + const std::uint64_t head_session = publisher.group_description(head).session_id; + REQUIRE(head_session != 0); + REQUIRE(publisher.group_description(wrist).session_id != 0); + REQUIRE(publisher.group_description(wrist).session_id != head_session); + + // A restart of the camera is not a new session. + publisher.restart_group(head); + REQUIRE(publisher.group_description(head).session_id == head_session); + + // A backend that has an identity of its own for the run gives it. + GroupDescription named = make_group(4, 1, "named"); + named.session_id = 42; + REQUIRE(publisher.group_description(publisher.add_group(named)).session_id == 42); +} + +TEST_CASE("a group with a slot-free callback hands out slots by claim only", "[unit][camera_core][slots]") +{ + Publisher publisher; + const GroupId group = publisher.add_group(make_group(4, 1)); + REQUIRE(publisher.acquire_slot(group, 0) == 0u); + publisher.abandon_slot(group, 0, 0); + + publisher.set_slot_free_callback(group, [](std::size_t, std::uint32_t) {}); + REQUIRE_THROWS_AS(publisher.acquire_slot(group, 0), std::logic_error); + REQUIRE_NOTHROW(publisher.claim_slot(group, 0, 0)); + + publisher.set_slot_free_callback(group, {}); + REQUIRE(publisher.acquire_slot(group, 0) == 1u); +} + +TEST_CASE("a pool owned by the camera SDK never leaves the SDK short of its reserve", "[unit][camera_core][slots]") +{ + // The shape of a capture stack that is given its buffers up front and picks the one it + // fills: ten per eye, of which the SDK needs four in hand to keep capturing. + constexpr std::uint32_t BUFFERS = 10; + constexpr std::uint32_t RESERVE = 4; + Publisher publisher; + const GroupId group = publisher.add_group(make_group(BUFFERS, 2), RESERVE); + + // What the SDK has to fill, per eye. A buffer goes back the moment nobody holds it. + std::array, 2> with_sdk; + for (std::deque& buffers : with_sdk) + { + for (std::uint32_t buffer = 0; buffer < BUFFERS; ++buffer) + { + buffers.push_back(buffer); + } + } + publisher.set_slot_free_callback( + group, [&](std::size_t stream, std::uint32_t slot) { with_sdk[stream].push_back(slot); }); + + // An encoder that reads every frame set and holds two at a time, and a viewer that wants + // the newest. With the reserve they fit ten buffers; a recorder on top would not. + RecordingSink encoder; + RecordingSink viewer; + RecordingSink recorder; + const SubscribeResult encoding = open(publisher, encoder, group, { .window = 2, .order = DeliveryOrder::IN_ORDER }); + const SubscribeResult viewing = open(publisher, viewer, group, { .window = 1 }); + REQUIRE(encoding); + REQUIRE(viewing); + REQUIRE(publisher.request_newest(viewing.id, 0)); + REQUIRE_FALSE(publisher.subscribe(recorder, group, { .window = 2, .order = DeliveryOrder::IN_ORDER })); + + std::uint32_t state = 12345; + const auto random = [&state] + { + state = state * 1664525u + 1013904223u; + return state >> 16; + }; + std::size_t encoder_released = 0; + std::size_t viewer_released = 0; + for (int frame = 0; frame < 5000; ++frame) + { + // The SDK fills one buffer per eye, and must find its reserve waiting. + std::array images; + for (std::size_t eye = 0; eye < 2; ++eye) + { + REQUIRE(with_sdk[eye].size() >= RESERVE); + images[eye].slot = with_sdk[eye].front(); + with_sdk[eye].pop_front(); + publisher.claim_slot(group, eye, images[eye].slot); + } + if (random() % 16 == 0) + { + // The eyes did not arrive as a pair: both are given up and go straight back. + for (std::size_t eye = 0; eye < 2; ++eye) + { + publisher.abandon_slot(group, eye, images[eye].slot); + with_sdk[eye].push_back(images[eye].slot); + } + continue; + } + publisher.publish(group, images, {}); + + // The encoder is done with a frame set after a frame or two. The viewer keeps up, + // except when it stalls for a while. + while (encoder_released < encoder.events.size() && random() % 3 != 0) + { + publisher.release(encoding.id, encoder.events[encoder_released++].lease_id); + } + if (random() % 50 != 0) + { + while (viewer_released < viewer.events.size()) + { + publisher.release(viewing.id, viewer.events[viewer_released++].lease_id); + } + publisher.request_newest(viewing.id, viewer.events.empty() ? 0 : viewer.events.back().sequence); + } + } + + // Both readers were served throughout, and what either did not get is accounted for. + REQUIRE(publisher.stats(group).published > 4000); + REQUIRE(viewer.events.size() > 1000); + REQUIRE(encoder.events.size() > 1000); + for (std::size_t i = 1; i < encoder.events.size(); ++i) + { + REQUIRE(encoder.events[i].sequence == encoder.events[i - 1].sequence + 1 + encoder.events[i].skipped); + } +} + +TEST_CASE("one camera does not wait for another camera's readers", "[unit][camera_core][threads]") +{ + using namespace std::chrono_literals; + + // A reader whose sink does not come back. A sink must not do this; it stands in for the + // worst a reader of one camera can do to another camera. + struct StuckSink : EventSink + { + bool send_event(SubscriptionId, const FrameEvent&) noexcept override + { + entered = true; + const auto deadline = std::chrono::steady_clock::now() + 5s; + while (!let_go && std::chrono::steady_clock::now() < deadline) + { + std::this_thread::sleep_for(1ms); + } + return true; + } + + std::atomic entered{ false }; + std::atomic let_go{ false }; + }; + + Publisher publisher; + const GroupId head = publisher.add_group(make_group(4, 1, "head")); + const GroupId wrist = publisher.add_group(make_group(4, 1, "wrist")); + StuckSink stuck; + RecordingSink wrist_reader; + const SubscribeResult head_reading = open(publisher, stuck, head); + REQUIRE(head_reading); + REQUIRE(publisher.request_newest(head_reading.id, 0)); + const SubscribeResult wrist_reading = open(publisher, wrist_reader, wrist); + REQUIRE(wrist_reading); + REQUIRE(publisher.request_newest(wrist_reading.id, 0)); + + std::thread head_capture( + [&] + { + ImageInfo image; + image.slot = publisher.acquire_slot(head, 0).value_or(0); + publisher.publish(head, { &image, 1 }, {}); + }); + while (!stuck.entered) + { + std::this_thread::sleep_for(1ms); + } + + // The head camera is inside its reader's sink. The wrist camera publishes all the same, + // and readers can still come, go and ask what there is. + const auto before = std::chrono::steady_clock::now(); + REQUIRE(publish_next(publisher, wrist) == 1); + REQUIRE(wrist_reader.events.size() == 1); + publisher.release(wrist_reading.id, wrist_reader.events[0].lease_id); + REQUIRE(publisher.find_group("wrist") == wrist); + REQUIRE(publisher.stats(wrist).events_sent == 1); + RecordingSink late; + const SubscribeResult joined = publisher.subscribe(late, wrist, {}); + REQUIRE(joined); + publisher.unsubscribe(joined.id); + REQUIRE(std::chrono::steady_clock::now() - before < 2s); + REQUIRE_FALSE(stuck.let_go); + + stuck.let_go = true; + head_capture.join(); + REQUIRE(publisher.stats(head).events_sent == 1); +} + +TEST_CASE("capture and a reader on different threads keep every frame set in order", "[unit][camera_core][threads]") +{ + // A reader as the endpoint will drive it: events arrive on the capture thread, the + // reader's own thread takes them and releases. + struct QueueSink : EventSink + { + bool send_event(SubscriptionId, const FrameEvent& event) noexcept override + { + { + std::lock_guard lock(mutex); + queue.push_back(event); + } + ready.notify_one(); + return true; + } + + std::mutex mutex; + std::condition_variable ready; + std::deque queue; + }; + + constexpr std::uint64_t FRAME_SETS = 2000; + Publisher publisher; + const GroupId group = publisher.add_group(make_group(16)); + QueueSink sink; + const SubscribeResult reader = open(publisher, sink, group, { .window = 4 }); + REQUIRE(reader); + + std::atomic received{ 0 }; + std::atomic out_of_order{ 0 }; + std::thread consumer( + [&] + { + std::uint64_t last = 0; + while (last < FRAME_SETS) + { + FrameEvent event; + { + std::unique_lock lock(sink.mutex); + sink.ready.wait(lock, [&] { return !sink.queue.empty(); }); + event = sink.queue.front(); + sink.queue.pop_front(); + } + out_of_order += event.sequence <= last ? 1 : 0; + last = event.sequence; + ++received; + publisher.release(reader.id, event.lease_id); + } + }); + + std::uint64_t dropped = 0; + for (std::uint64_t i = 0; i < FRAME_SETS; ++i) + { + std::vector images(2); + const auto left = publisher.acquire_slot(group, 0); + const auto right = publisher.acquire_slot(group, 1); + if (!left || !right) + { + // Cannot happen while the budget holds: a free slot is always left for the backend. + ++dropped; + continue; + } + images[0].slot = *left; + images[1].slot = *right; + publisher.publish(group, images, {}); + } + consumer.join(); + + REQUIRE(dropped == 0); + REQUIRE(out_of_order == 0); + REQUIRE(received > 0); + REQUIRE(publisher.stats(group).published == FRAME_SETS); +} diff --git a/tests/cpp/core/camera_ipc/CMakeLists.txt b/tests/cpp/core/camera_ipc/CMakeLists.txt new file mode 100644 index 0000000000..20a10da0d7 --- /dev/null +++ b/tests/cpp/core/camera_ipc/CMakeLists.txt @@ -0,0 +1,21 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +find_package(Threads REQUIRED) + +add_executable(camera_ipc_tests + test_endpoint_path.cpp + test_host_pool.cpp + test_message_socket.cpp +) + +target_link_libraries(camera_ipc_tests PRIVATE + camera::camera_ipc + Catch2::Catch2WithMain + Threads::Threads +) + +message(STATUS "camera_ipc_tests target enabled with Catch2") +catch_discover_tests(camera_ipc_tests ADD_TAGS_AS_LABELS) diff --git a/tests/cpp/core/camera_ipc/test_endpoint_path.cpp b/tests/cpp/core/camera_ipc/test_endpoint_path.cpp new file mode 100644 index 0000000000..2c3ae163eb --- /dev/null +++ b/tests/cpp/core/camera_ipc/test_endpoint_path.cpp @@ -0,0 +1,187 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace core::camera; + +namespace +{ + +// Sets an environment variable for one test and puts back what was there. +class ScopedEnvironment +{ +public: + ScopedEnvironment(const char* name, const char* value) : m_name(name) + { + if (const char* previous = std::getenv(name)) + { + m_previous = previous; + } + if (value != nullptr) + { + ::setenv(name, value, 1); + } + else + { + ::unsetenv(name); + } + } + + ~ScopedEnvironment() + { + if (m_previous) + { + ::setenv(m_name, m_previous->c_str(), 1); + } + else + { + ::unsetenv(m_name); + } + } + +private: + const char* m_name; + std::optional m_previous; +}; + +class TemporaryDirectory +{ +public: + TemporaryDirectory() + { + std::string pattern = (std::filesystem::temp_directory_path() / "camera_path_XXXXXX").string(); + REQUIRE(::mkdtemp(pattern.data()) != nullptr); + path = pattern; + } + + ~TemporaryDirectory() + { + std::error_code ignored; + std::filesystem::remove_all(path, ignored); + } + + std::filesystem::path path; +}; + +// What a process that was killed leaves behind: a socket file with nothing behind it. +void leave_socket_file(const std::filesystem::path& path) +{ + sockaddr_un address = {}; + address.sun_family = AF_UNIX; + REQUIRE(path.native().size() < sizeof(address.sun_path)); + std::memcpy(address.sun_path, path.c_str(), path.native().size()); + const UniqueFd dead(::socket(AF_UNIX, SOCK_SEQPACKET, 0)); + REQUIRE(::bind(dead.get(), reinterpret_cast(&address), sizeof(address)) == 0); +} + +} // namespace + +TEST_CASE("an endpoint is in the user's endpoint directory", "[unit][camera_ipc][endpoint_path]") +{ + { + const ScopedEnvironment runtime("XDG_RUNTIME_DIR", "/run/user/1234"); + REQUIRE(default_endpoint_directory() == "/run/user/1234/isaaccapture"); + REQUIRE(default_endpoint_path("wrist_2") == "/run/user/1234/isaaccapture/camera-wrist_2.sock"); + } + { + const ScopedEnvironment runtime("XDG_RUNTIME_DIR", nullptr); + const std::string user = std::to_string(::geteuid()); + REQUIRE(default_endpoint_directory() == "/tmp/isaaccapture-" + user); + REQUIRE(default_endpoint_path("b") == "/tmp/isaaccapture-" + user + "/camera-b.sock"); + } + // An instance name becomes part of a file name, so it cannot carry a path, and every + // endpoint has one. + REQUIRE_THROWS_AS(default_endpoint_path("../other"), std::invalid_argument); + REQUIRE_THROWS_AS(default_endpoint_path("a b"), std::invalid_argument); + REQUIRE_THROWS_AS(default_endpoint_path(""), std::invalid_argument); +} + +TEST_CASE("an endpoint's directory is made for its owner alone", "[unit][camera_ipc][endpoint_path]") +{ + TemporaryDirectory directory; + const std::filesystem::path made = directory.path / "isaaccapture"; + const std::string endpoint = (made / "camera-a.sock").string(); + + prepare_endpoint_directory(endpoint); + REQUIRE(std::filesystem::is_directory(made)); + REQUIRE(std::filesystem::status(made).permissions() == std::filesystem::perms::owner_all); + prepare_endpoint_directory(endpoint); // already there and fine + + // One that others can enter is refused rather than used. + REQUIRE(::chmod(made.c_str(), 0755) == 0); + REQUIRE_THROWS_AS(prepare_endpoint_directory(endpoint), std::system_error); + + // So is something that is not a directory, and a directory that cannot be made. + std::filesystem::remove(made); + REQUIRE(::symlink(directory.path.c_str(), made.c_str()) == 0); + REQUIRE_THROWS_AS(prepare_endpoint_directory(endpoint), std::system_error); + REQUIRE_THROWS_AS(prepare_endpoint_directory((directory.path / "missing" / "deeper" / "camera-a.sock").string()), + std::system_error); + + // A bare file name is in the current directory, which is left as it is. + REQUIRE_NOTHROW(prepare_endpoint_directory("camera-a.sock")); +} + +TEST_CASE("the camera endpoints of this user are listed", "[unit][camera_ipc][endpoint_path]") +{ + TemporaryDirectory directory; + const ScopedEnvironment runtime("XDG_RUNTIME_DIR", directory.path.c_str()); + const std::filesystem::path endpoints = directory.path / "isaaccapture"; + + // No plugin has run for this user: nothing is listed, and looking does not make the directory. + REQUIRE(default_endpoint_paths().empty()); + REQUIRE_FALSE(std::filesystem::exists(endpoints)); + + prepare_endpoint_directory(default_endpoint_path("wrist_2")); + REQUIRE(default_endpoint_paths().empty()); + + // Two plugins that are running, one that has its endpoint and does not listen yet, and one + // that was killed. Whether anything answers behind a socket file is for the caller to find out. + MessageListener wrist(default_endpoint_path("wrist_2")); + wrist.listen(); + MessageListener chest(default_endpoint_path("chest")); + chest.listen(); + const MessageListener starting(default_endpoint_path("synthetic")); + leave_socket_file(default_endpoint_path("gone")); + + // What else is in the directory: the listeners' lock files, a file that is not a socket, a + // link to a socket under an endpoint's name, and sockets whose names no camera endpoint has. + REQUIRE(std::filesystem::is_regular_file(default_endpoint_path("wrist_2") + ".lock")); + std::ofstream(endpoints / "camera-file.sock") << "not a socket"; + std::filesystem::create_symlink(default_endpoint_path("gone"), endpoints / "camera-link.sock"); + for (const char* name : + { "viewer-1.sock", "camera-1.lock", "camera_2.sock", "camera.sock", "camera-.sock", "camera-a.b.sock" }) + { + leave_socket_file(endpoints / name); + } + + const std::vector sorted = { default_endpoint_path("chest"), default_endpoint_path("gone"), + default_endpoint_path("synthetic"), default_endpoint_path("wrist_2") }; + REQUIRE(default_endpoint_paths() == sorted); +} + +TEST_CASE("an endpoint directory that cannot be read is an error", "[unit][camera_ipc][endpoint_path]") +{ + TemporaryDirectory directory; + const ScopedEnvironment runtime("XDG_RUNTIME_DIR", directory.path.c_str()); + std::ofstream(directory.path / "isaaccapture") << "not a directory"; + REQUIRE_THROWS_AS(default_endpoint_paths(), std::system_error); +} diff --git a/tests/cpp/core/camera_ipc/test_host_pool.cpp b/tests/cpp/core/camera_ipc/test_host_pool.cpp new file mode 100644 index 0000000000..1b2587912c --- /dev/null +++ b/tests/cpp/core/camera_ipc/test_host_pool.cpp @@ -0,0 +1,161 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace core::camera; + +namespace +{ + +// Not a whole number of pages, so slots are padded apart. +constexpr std::uint64_t SLOT_BYTES = 5000; + +// What another process ends up with after the pool's descriptor was sent to it. +UniqueFd duplicate_descriptor(const HostPool& pool) +{ + UniqueFd result(::fcntl(pool.descriptor(), F_DUPFD_CLOEXEC, 0)); + REQUIRE(result.valid()); + return result; +} + +} // namespace + +TEST_CASE("a view sees what the owner writes", "[unit][camera_ipc][host_pool]") +{ + HostPool pool(3, SLOT_BYTES, "camera_ipc_test"); + REQUIRE(pool.slot_count() == 3); + REQUIRE(pool.slot_bytes() == SLOT_BYTES); + + const HostPoolView view(duplicate_descriptor(pool), 3, SLOT_BYTES); + REQUIRE(view.slot_count() == 3); + + // Slots start zeroed and are separate from each other. + const auto is_zero = [](std::byte value) { return value == std::byte{ 0 }; }; + REQUIRE(std::all_of(view.slot(0).begin(), view.slot(0).end(), is_zero)); + + std::fill(pool.slot(1).begin(), pool.slot(1).end(), std::byte{ 0x5a }); + REQUIRE(view.slot(1).size() == SLOT_BYTES); + REQUIRE(view.slot(1).front() == std::byte{ 0x5a }); + REQUIRE(view.slot(1).back() == std::byte{ 0x5a }); + REQUIRE(std::all_of(view.slot(0).begin(), view.slot(0).end(), is_zero)); + REQUIRE(std::all_of(view.slot(2).begin(), view.slot(2).end(), is_zero)); + + // The mapping is live: a later write shows up without mapping again. + pool.slot(2)[100] = std::byte{ 0x11 }; + REQUIRE(view.slot(2)[100] == std::byte{ 0x11 }); +} + +TEST_CASE("slots start on page boundaries", "[unit][camera_ipc][host_pool]") +{ + HostPool pool(2, SLOT_BYTES, "camera_ipc_test"); + const auto page = static_cast(::sysconf(_SC_PAGESIZE)); + REQUIRE(reinterpret_cast(pool.slot(0).data()) % page == 0); + REQUIRE(reinterpret_cast(pool.slot(1).data()) % page == 0); + REQUIRE(pool.slot(1).data() >= pool.slot(0).data() + SLOT_BYTES); +} + +TEST_CASE("writing and reading a pool for the first time causes no page faults", "[unit][camera_ipc][host_pool]") +{ +#if defined(__SANITIZE_ADDRESS__) || defined(__SANITIZE_THREAD__) + SKIP("a sanitizer's shadow memory faults on first touch whatever the pool does"); +#else + constexpr std::uint32_t SLOTS = 8; + constexpr std::uint64_t BYTES = 2 * 1024 * 1024; + const auto page = static_cast(::sysconf(_SC_PAGESIZE)); + const auto faults = [] + { + rusage usage = {}; + REQUIRE(::getrusage(RUSAGE_SELF, &usage) == 0); + return usage.ru_minflt + usage.ru_majflt; + }; + + HostPool pool(SLOTS, BYTES, "camera_ipc_test"); + HostPoolView view(duplicate_descriptor(pool), SLOTS, BYTES); + + // Touch every page of every slot: write as the owner, then read as a reader would. + const long before = faults(); + unsigned sum = 0; + for (std::uint32_t slot = 0; slot < SLOTS; ++slot) + { + for (std::size_t offset = 0; offset < BYTES; offset += page) + { + pool.slot(slot)[offset] = std::byte{ 1 }; + sum += std::to_integer(view.slot(slot)[offset]); + } + } + const long caused = faults() - before; + REQUIRE(sum == SLOTS * (BYTES / page)); + + // The pool has thousands of pages; without them mapped up front, each would fault twice. + REQUIRE(caused < 32); +#endif +} + +TEST_CASE("a process that is sent the pool cannot write to it or resize it", "[unit][camera_ipc][host_pool]") +{ + HostPool pool(1, SLOT_BYTES, "camera_ipc_test"); + const UniqueFd received = duplicate_descriptor(pool); + + void* writable = ::mmap(nullptr, SLOT_BYTES, PROT_READ | PROT_WRITE, MAP_SHARED, received.get(), 0); + REQUIRE(writable == MAP_FAILED); + REQUIRE(errno == EPERM); + + const char byte = 1; + REQUIRE(::write(received.get(), &byte, 1) == -1); + REQUIRE(::ftruncate(received.get(), 16) == -1); + REQUIRE(::ftruncate(received.get(), static_cast(16 * SLOT_BYTES)) == -1); + + // The owner still can. + pool.slot(0)[0] = std::byte{ 0x7f }; + const HostPoolView view(duplicate_descriptor(pool), 1, SLOT_BYTES); + REQUIRE(view.slot(0)[0] == std::byte{ 0x7f }); +} + +TEST_CASE("a view outlives the pool and can be moved", "[unit][camera_ipc][host_pool]") +{ + std::vector views; + { + HostPool pool(2, SLOT_BYTES, "camera_ipc_test"); + pool.slot(1)[7] = std::byte{ 0x42 }; + views.emplace_back(duplicate_descriptor(pool), 2, SLOT_BYTES); + } + // The memory lives as long as anything maps it. + HostPoolView moved = std::move(views.front()); + REQUIRE(views.front().slot_count() == 0); + REQUIRE(moved.slot_count() == 2); + REQUIRE(moved.slot(1)[7] == std::byte{ 0x42 }); +} + +TEST_CASE("misuse of a host pool is rejected", "[unit][camera_ipc][host_pool]") +{ + REQUIRE_THROWS_AS(HostPool(0, SLOT_BYTES, "camera_ipc_test"), std::invalid_argument); + REQUIRE_THROWS_AS(HostPool(1, 0, "camera_ipc_test"), std::invalid_argument); + + HostPool pool(2, SLOT_BYTES, "camera_ipc_test"); + REQUIRE_THROWS_AS(pool.slot(2), std::out_of_range); + + const HostPoolView view(duplicate_descriptor(pool), 2, SLOT_BYTES); + REQUIRE_THROWS_AS(view.slot(2), std::out_of_range); + + // A descriptor that holds less than the pool claims would fault on access, so it is refused. + REQUIRE_THROWS_AS(HostPoolView(duplicate_descriptor(pool), 3, SLOT_BYTES), std::invalid_argument); + REQUIRE_THROWS_AS(HostPoolView(duplicate_descriptor(pool), 2, 4 * SLOT_BYTES), std::invalid_argument); + REQUIRE_THROWS_AS(HostPoolView(duplicate_descriptor(pool), 0, SLOT_BYTES), std::invalid_argument); + + REQUIRE_THROWS_AS(HostPoolView(UniqueFd(-1), 2, SLOT_BYTES), std::system_error); +} diff --git a/tests/cpp/core/camera_ipc/test_message_socket.cpp b/tests/cpp/core/camera_ipc/test_message_socket.cpp new file mode 100644 index 0000000000..122ee97f2a --- /dev/null +++ b/tests/cpp/core/camera_ipc/test_message_socket.cpp @@ -0,0 +1,470 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace core::camera; +using namespace std::chrono_literals; + +namespace +{ + +// A directory for socket files that is removed with everything in it. +class TemporaryDirectory +{ +public: + TemporaryDirectory() + { + std::string pattern = (std::filesystem::temp_directory_path() / "camera_ipc_XXXXXX").string(); + REQUIRE(::mkdtemp(pattern.data()) != nullptr); + m_path = pattern; + } + + ~TemporaryDirectory() + { + std::error_code ignored; + std::filesystem::remove_all(m_path, ignored); + } + + std::string socket_path() const + { + return (m_path / "endpoint.sock").string(); + } + +private: + std::filesystem::path m_path; +}; + +std::span bytes_of(std::string_view text) +{ + return std::as_bytes(std::span(text.data(), text.size())); +} + +std::string text_of(std::span bytes, std::size_t count) +{ + return { reinterpret_cast(bytes.data()), count }; +} + +// The error code a call fails with, or 0 if it does not throw a std::system_error. +template +int error_of(Call&& call) +{ + try + { + call(); + } + catch (const std::system_error& error) + { + return error.code().value(); + } + return 0; +} + +struct Connection +{ + TemporaryDirectory directory; + MessageListener listener{ directory.socket_path() }; + MessageSocket client = connect(); + MessageSocket server = accept(); + + MessageSocket connect() + { + listener.listen(); + return MessageSocket::connect(directory.socket_path()); + } + + MessageSocket accept() + { + auto accepted = listener.accept(1s); + REQUIRE(accepted.has_value()); + return std::move(*accepted); + } +}; + +} // namespace + +TEST_CASE("messages arrive whole and in order", "[unit][camera_ipc][socket]") +{ + Connection connection; + REQUIRE(connection.client.send(bytes_of("first")) == SendStatus::SENT); + REQUIRE(connection.client.send(bytes_of("second message")) == SendStatus::SENT); + + std::array buffer; + ReceivedMessage received = connection.server.receive(buffer, 1s); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(text_of(buffer, received.bytes) == "first"); + REQUIRE(received.descriptors.empty()); + + received = connection.server.receive(buffer, 1s); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(text_of(buffer, received.bytes) == "second message"); + + // And the other way. + REQUIRE(connection.server.send(bytes_of("reply")) == SendStatus::SENT); + received = connection.client.receive(buffer, 1s); + REQUIRE(text_of(buffer, received.bytes) == "reply"); +} + +TEST_CASE("descriptors travel with a message", "[unit][camera_ipc][socket]") +{ + Connection connection; + HostPool left(2, 4096, "camera_ipc_test_left"); + HostPool right(2, 4096, "camera_ipc_test_right"); + left.slot(1)[5] = std::byte{ 0x33 }; + right.slot(0)[9] = std::byte{ 0x44 }; + + const std::array descriptors = { left.descriptor(), right.descriptor() }; + REQUIRE(connection.server.send(bytes_of("pools"), descriptors) == SendStatus::SENT); + + std::array buffer; + ReceivedMessage received = connection.client.receive(buffer, 1s); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(text_of(buffer, received.bytes) == "pools"); + REQUIRE(received.descriptors.size() == 2); + + // The receiver's descriptors are its own, arrive in order and map the same memory. + REQUIRE(received.descriptors[0].get() != left.descriptor()); + REQUIRE(received.descriptors[1].get() != right.descriptor()); + const HostPoolView left_view(std::move(received.descriptors[0]), 2, 4096); + const HostPoolView right_view(std::move(received.descriptors[1]), 2, 4096); + REQUIRE(left_view.slot(1)[5] == std::byte{ 0x33 }); + REQUIRE(right_view.slot(0)[9] == std::byte{ 0x44 }); +} + +TEST_CASE("send never blocks when the peer does not read", "[unit][camera_ipc][socket]") +{ + Connection connection; + const std::vector payload(1024, std::byte{ 1 }); + + SendStatus status = SendStatus::SENT; + int sent = 0; + while (status == SendStatus::SENT && sent < 1'000'000) + { + status = connection.client.send(payload); + sent += status == SendStatus::SENT ? 1 : 0; + } + REQUIRE(status == SendStatus::WOULD_BLOCK); + REQUIRE(sent > 0); + + // Room appears as soon as the peer reads. + std::array buffer; + REQUIRE(connection.server.receive(buffer, 1s).status == ReceiveStatus::MESSAGE); + REQUIRE(connection.client.send(payload) == SendStatus::SENT); +} + +TEST_CASE("a closed peer is reported, not thrown", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + MessageListener listener(directory.socket_path()); + listener.listen(); + std::optional server; + { + MessageSocket client = MessageSocket::connect(directory.socket_path()); + server = listener.accept(1s); + REQUIRE(server.has_value()); + REQUIRE(client.send(bytes_of("last words")) == SendStatus::SENT); + } + + // What was sent before the peer closed is still delivered. + std::array buffer; + ReceivedMessage received = server->receive(buffer, 1s); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(text_of(buffer, received.bytes) == "last words"); + + REQUIRE(server->receive(buffer, 1s).status == ReceiveStatus::CLOSED); + REQUIRE(server->send(bytes_of("anyone?")) == SendStatus::CLOSED); +} + +TEST_CASE("receive and accept time out when nothing arrives", "[unit][camera_ipc][socket]") +{ + Connection connection; + std::array buffer; + REQUIRE(connection.server.receive(buffer, 10ms).status == ReceiveStatus::TIMEOUT); + REQUIRE(connection.server.receive(buffer, 0ms).status == ReceiveStatus::TIMEOUT); + REQUIRE_FALSE(connection.listener.accept(10ms).has_value()); +} + +TEST_CASE("a listener takes its path before it listens", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + MessageListener listener(path); + REQUIRE(std::filesystem::is_socket(path)); + + // The path is this listener's from construction on: another one is turned away. + REQUIRE(error_of([&path] { MessageListener second(path); }) == EADDRINUSE); + + // Nothing is accepted yet, so a connect is refused at once rather than left waiting. + const auto asked = std::chrono::steady_clock::now(); + REQUIRE(error_of([&path] { MessageSocket::connect(path); }) == ECONNREFUSED); + REQUIRE(std::chrono::steady_clock::now() - asked < 1s); + REQUIRE_THROWS_AS(listener.accept(0ms), std::system_error); + + listener.listen(); + MessageSocket client = MessageSocket::connect(path); + // Listening again is harmless: the connection made before it is still there to accept. + listener.listen(); + REQUIRE(listener.accept(1s).has_value()); +} + +TEST_CASE("a connect never waits, also for a listener that has stopped accepting", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + MessageListener listener(path); + listener.listen(); + + // Nobody accepts, so every connection stays in the listener's queue, also after its client + // has gone. Once the queue is full the next connect is refused instead of left waiting. + int refused = 0; + for (int attempt = 0; attempt < 200000 && refused == 0; ++attempt) + { + refused = error_of([&path] { MessageSocket::connect(path); }); + } + REQUIRE(refused == EAGAIN); + + // The listener is unharmed: what is queued can still be accepted. + REQUIRE(listener.accept(1s).has_value()); +} + +TEST_CASE("a listener replaces a stale socket file but not a live one", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + { + MessageListener live(path); + live.listen(); + try + { + MessageListener second(path); + FAIL("a second listener took over a live endpoint"); + } + catch (const std::system_error& error) + { + REQUIRE(error.code().value() == EADDRINUSE); + } + // The live listener still works after the refused attempt. + MessageSocket client = MessageSocket::connect(path); + REQUIRE(live.accept(1s).has_value()); + } + REQUIRE_FALSE(std::filesystem::exists(path)); // a listener removes its file + + // A process that died without cleaning up leaves the file behind. + { + sockaddr_un address = {}; + address.sun_family = AF_UNIX; + std::memcpy(address.sun_path, path.data(), path.size()); + const UniqueFd dead(::socket(AF_UNIX, SOCK_SEQPACKET, 0)); + REQUIRE(::bind(dead.get(), reinterpret_cast(&address), sizeof(address)) == 0); + } + REQUIRE(std::filesystem::exists(path)); + MessageListener replacement(path); + replacement.listen(); + MessageSocket client = MessageSocket::connect(path); + REQUIRE(replacement.accept(1s).has_value()); +} + +TEST_CASE("the lock decides who owns the path, not the socket file", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + { + MessageListener live(path); + // Even with the socket file gone, the path still belongs to the live listener. + REQUIRE(std::filesystem::remove(path)); + REQUIRE_THROWS_AS(MessageListener(path), std::system_error); + // A refused attempt does not loosen the owner's lock, even from the same process. + REQUIRE_THROWS_AS(MessageListener(path), std::system_error); + REQUIRE_FALSE(std::filesystem::exists(path)); + } + // The lock file stays for the next listener, which takes the path over. + REQUIRE(std::filesystem::exists(path + ".lock")); + MessageListener next(path); + next.listen(); + MessageSocket client = MessageSocket::connect(path); + REQUIRE(next.accept(1s).has_value()); +} + +TEST_CASE("of listeners that start at the same moment exactly one wins", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + + std::array, 8> contenders; + std::atomic start{ false }; + std::vector threads; + for (auto& contender : contenders) + { + threads.emplace_back( + [&contender, &start, &path] + { + while (!start.load()) + { + std::this_thread::yield(); + } + try + { + contender = std::make_unique(path); + } + catch (const std::system_error&) + { + // Lost to another contender. + } + }); + } + start = true; + for (auto& thread : threads) + { + thread.join(); + } + + const auto has_the_path = [](const std::unique_ptr& contender) { return contender != nullptr; }; + REQUIRE(std::count_if(contenders.begin(), contenders.end(), has_the_path) == 1); + + // The winner owns the socket file: a client reaches it. + MessageListener& winner = **std::find_if(contenders.begin(), contenders.end(), has_the_path); + winner.listen(); + MessageSocket client = MessageSocket::connect(path); + REQUIRE(winner.accept(1s).has_value()); +} + +TEST_CASE("a path that holds something other than a socket is left alone", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + std::ofstream(path) << "not a socket"; + + try + { + MessageListener listener(path); + FAIL("a listener replaced a file that is not a socket"); + } + catch (const std::system_error& error) + { + REQUIRE(error.code().value() == EEXIST); + } + REQUIRE(std::filesystem::is_regular_file(path)); + REQUIRE(std::filesystem::file_size(path) == 12); +} + +TEST_CASE("only the owner can connect to a listener", "[unit][camera_ipc][socket]") +{ + TemporaryDirectory directory; + const MessageListener listener(directory.socket_path()); + + const std::filesystem::file_status status = std::filesystem::status(directory.socket_path()); + REQUIRE(std::filesystem::is_socket(status)); + REQUIRE(status.permissions() == (std::filesystem::perms::owner_read | std::filesystem::perms::owner_write)); +} + +TEST_CASE("another process maps a pool it is sent and can only read it", "[integration][camera_ipc]") +{ + TemporaryDirectory directory; + const std::string path = directory.socket_path(); + constexpr std::uint32_t SLOTS = 4; + constexpr std::uint64_t SLOT_BYTES = 5000; + MessageListener listener(path); + listener.listen(); + HostPool pool(SLOTS, SLOT_BYTES, "camera_ipc_test"); + std::fill(pool.slot(2).begin(), pool.slot(2).end(), std::byte{ 0x6b }); + + // The reader's side, in a process of its own. It reports what it found as its exit code; + // nothing in it touches the test framework. + const pid_t child = ::fork(); + REQUIRE(child >= 0); + if (child == 0) + { + int result = 1; + try + { + MessageSocket socket = MessageSocket::connect(path); + std::array buffer; + ReceivedMessage received = socket.receive(buffer, 5s); + if (received.status == ReceiveStatus::MESSAGE && received.descriptors.size() == 1) + { + const int descriptor = received.descriptors[0].get(); + const bool writable = + ::mmap(nullptr, SLOT_BYTES, PROT_READ | PROT_WRITE, MAP_SHARED, descriptor, 0) != MAP_FAILED; + const HostPoolView view(std::move(received.descriptors[0]), SLOTS, SLOT_BYTES); + const bool filled = view.slot(2).front() == std::byte{ 0x6b } && view.slot(2).back() == std::byte{ 0x6b }; + // Tell the owner it is mapped, then wait for the owner to write once more. + socket.send(bytes_of("mapped")); + const bool told = socket.receive(buffer, 5s).status == ReceiveStatus::MESSAGE; + const bool live = view.slot(0)[10] == std::byte{ 0x2a }; + result = (!writable && filled && told && live) ? 0 : 2; + } + } + catch (...) + { + result = 3; + } + ::_exit(result); + } + + std::optional reader = listener.accept(5s); + REQUIRE(reader.has_value()); + const std::array descriptors = { pool.descriptor() }; + REQUIRE(reader->send(bytes_of("pool"), descriptors) == SendStatus::SENT); + std::array buffer; + REQUIRE(reader->receive(buffer, 5s).status == ReceiveStatus::MESSAGE); + // A write after the other process mapped the pool shows up there without mapping again. + pool.slot(0)[10] = std::byte{ 0x2a }; + REQUIRE(reader->send(bytes_of("written")) == SendStatus::SENT); + + int status = 0; + REQUIRE(::waitpid(child, &status, 0) == child); + REQUIRE(WIFEXITED(status)); + REQUIRE(WEXITSTATUS(status) == 0); + // The other process is gone, and this end is told. + REQUIRE(reader->receive(buffer, 5s).status == ReceiveStatus::CLOSED); +} + +TEST_CASE("misuse of a message socket is rejected", "[unit][camera_ipc][socket]") +{ + Connection connection; + REQUIRE_THROWS_AS(connection.client.send({}), std::invalid_argument); + + const std::vector too_many(MAX_DESCRIPTORS_PER_MESSAGE + 1, 0); + REQUIRE_THROWS_AS(connection.client.send(bytes_of("x"), too_many), std::invalid_argument); + + // A message that does not fit the receiver's buffer is an error, not a silent cut. + REQUIRE(connection.client.send(bytes_of("sixteen bytes!!!")) == SendStatus::SENT); + std::array small; + REQUIRE_THROWS_AS(connection.server.receive(small, 1s), std::length_error); + // Also with no room at all, which must not read as a closed connection. + REQUIRE(connection.client.send(bytes_of("x")) == SendStatus::SENT); + REQUIRE_THROWS_AS(connection.server.receive({}, 1s), std::length_error); + + TemporaryDirectory directory; + REQUIRE_THROWS_AS(MessageSocket::connect(directory.socket_path()), std::system_error); + REQUIRE_THROWS_AS(MessageSocket::connect(std::string(200, 'a')), std::invalid_argument); + REQUIRE_THROWS_AS(MessageListener(""), std::invalid_argument); +}