Skip to content

[CameraInterface] Add camera_ipc: shared host-memory pool that readers can only read - #1522

Closed
farbod-nv wants to merge 8 commits into
fm/camera_capturefrom
fm/camera_capture_m0_host_pool
Closed

farbod-nv wants to merge 8 commits into
fm/camera_capturefrom
fm/camera_capture_m0_host_pool

Conversation

@farbod-nv

@farbod-nv farbod-nv commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Description

Second pull request of the camera interface. It is stacked on #1521 (camera_core), whose branch is this one's base, so the diff shows only this step.

It adds camera_ipc with HostPool: one stream's slots in shared host memory. This is how frames in host memory reach other processes without a copy. camera_core (the previous pull request) decides which slot holds which frame; this is the memory behind the slots. src/core/camera_ipc/README.md describes it.

  • One sealed memory file per pool. The pool is a single anonymous file in memory (memfd_create) with the slots a page-aligned stride apart. A stream hands a reader one descriptor, each process maps the pool once, and both sides derive the layout from the slot count and slot size that the stream's description carries.
  • The owner writes, readers only read. The process that creates the pool maps it writable and then seals it, so a process that is sent the descriptor cannot map it writable, write to it or resize it. One reader with a bug cannot corrupt frames for the others, and cannot make the owner fault by shrinking the file under it.
  • HostPoolView is the reader's side: a read-only mapping made from the descriptor it was sent. It refuses a descriptor that holds less than the pool needs, which would otherwise fault on first access.
  • UniqueFd owns one file descriptor and closes it.

Why an anonymous sealed file and not named shared memory (shm_open): there is no name to collide with another instance and nothing left in /dev/shm after a crash, the memory is freed when the last process holding it goes away, and only a process that was handed the descriptor can map it.

Linux only (memfd_create and file seals), so the module and its tests are added under CMAKE_SYSTEM_NAME STREQUAL "Linux".

Type of change

  • New feature (non-breaking change which adds functionality)

Testing

  • tests/cpp/core/camera_ipc/test_host_pool.cpp (Catch2, 5 cases, tagged unit): a view sees what the owner writes, including later writes; slots start on page boundaries and do not overlap when the slot size is not a whole number of pages; a process holding the pool's descriptor cannot map it writable, write to it or resize it; a view outlives the pool and can be moved; empty pools, slots out of range, and descriptors that are invalid or too small for the claimed slot count or size are rejected. Run with ctest -L camera_ipc.
  • Built with the project warning set promoted to errors. The tests also pass under AddressSanitizer with UBSan, and under ThreadSanitizer.
  • Ubuntu 22.04 x86_64, GCC 11.4, Linux 6.8.
  • clang-format-14 reports no changes; SKIP=check-copyright-year pre-commit run --all-files passes.

Checklist

  • I have read and understood the contribution guidelines
  • I have run the linter and formatter with SKIP=check-copyright-year pre-commit run --all-files
  • I have made corresponding changes to the documentation (a README in the module; user documentation comes with the plugin executable)
  • I have added tests that prove my fix/feature works (or explained why not)
  • I have signed off all my commits (git commit -s) per the DCO

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The change adds a Linux-only camera_ipc library. HostPool creates shared-memory slots and exposes writable spans and descriptors. HostPoolView maps supplied descriptors as read-only spans. UniqueFd manages descriptor ownership. The added tests cover shared visibility, access restrictions, view lifetime and move behavior, and invalid inputs.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant HostPool
  participant Caller
  participant HostPoolView
  HostPool->>Caller: Expose slot descriptors
  Caller->>HostPoolView: Supply descriptors and slot size
  HostPoolView->>HostPoolView: Map slots read-only
  HostPoolView->>Caller: Expose read-only slot spans
Loading
Merge Risk: Minimal · previous review 869d8

This adds a new Linux-only shared-memory pool library with tests and does not change existing behavior. No concrete merge-blocking risk was found.

Security architecture risk: Minimal · up to 869d8

The inspected change preserves writable owner access while restricting descriptor recipients to read-only, fixed-size shared slots. No material security, ownership, or failure-containment regression was established within this library’s documented scope.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — A handed-out descriptor grants access to its entire slot, including later contents, rather than to one immutable frame. Sharing all slot descriptors exposes the pool’s contents to that recipient; frame-level authorization and reuse policy must therefore be supplied by consumers.

Trust Boundaries and Controls

  • observed — For HostPool-produced descriptors, F_SEAL_SHRINK, F_SEAL_GROW, F_SEAL_FUTURE_WRITE, and F_SEAL_SEAL establish the reader integrity boundary while preserving the owner’s existing writable mapping. HostPoolView itself checks only current size and mapping success; its documented scope is descriptors from a HostPool, not arbitrary untrusted files.

Resilience and Maintainability Implications

  • observed — Pool construction completes sealing before callers can obtain descriptors. A sealing error unwinds the pool and releases its resources, preserving the access-control guarantee rather than returning partially protected storage.

Hardening Proposals

  • proposed — When adding descriptor transport, explicitly define trusted-producer, fork-inheritance, and slot-reuse assumptions. If arbitrary senders are supported, validate required seals before mapping rather than treating a one-time size check as protection against subsequent shrink.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: adding the Linux-only camera_ipc component with a shared host-memory pool (HostPool) whose read-only mapping (HostPoolView) limits readers to reading. The changeset ad…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title names the main change: adding the Linux-only camera_ipc component with a shared host-memory pool (HostPool) whose read-only mapping (HostPoolView) limits readers to reading. The changeset adds HostPool, HostPoolView, UniqueFd, the CMake wiring, and the tests that match this description. The title does not mention UniqueFd or the Linux-only gating, but it does not need to cover every detail.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 32bec85 and 869d876.

Files selected for processing: 9

  • src/core/CMakeLists.txt
  • src/core/camera_ipc/CMakeLists.txt
  • src/core/camera_ipc/cpp/CMakeLists.txt
  • src/core/camera_ipc/cpp/host_pool.cpp
  • src/core/camera_ipc/cpp/inc/camera_ipc/host_pool.hpp
  • src/core/camera_ipc/cpp/inc/camera_ipc/unique_fd.hpp
  • tests/cpp/core/CMakeLists.txt
  • tests/cpp/core/camera_ipc/CMakeLists.txt
  • tests/cpp/core/camera_ipc/test_host_pool.cpp

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

farbod-nv and others added 8 commits November 13, 2026 16:28
… capture plugin

First step of the unified camera capture plugin (milestone M0). camera_core
tracks which pool slots hold which frame sets and who may still read them.
It uses the standard library only and never touches slot memory, so it
builds and is tested on every platform.

- A group is one or more hardware-synchronised streams published as one
  frame set.
- A reader subscribes with a window (frame sets kept for it at a time) and
  a delivery order, newest or in order.
- A subscription is accepted only when the pool covers it:
  slots >= ring history + sum of reader windows + backend reserve.
- A backend either takes a free slot and writes it, or hands over a slot
  the camera SDK filled and is told the moment nobody holds it any more.
- Every frame event carries its timeline, the group's generation and the
  number of frame sets the reader skipped.

Tests: tests/cpp/core/camera_core (Catch2), run with `ctest -L camera_core`.

Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
Co-Authored-By: Claude <noreply@anthropic.com>
…format

H.264 and H.265 are codecs, so they do not belong in PixelFormat. A stream
description now has a Codec (NONE for pixels) next to its PixelFormat, and
is_encoded() reads the codec.

Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Two more places where the stream description and the publisher were too
coarse for real cameras:

- A stream had a single stride. NV12 has two planes, and on Jetson each
  plane has its own offset and stride, so a stream now lists its planes.
  add_group rejects a pixel stream without a size or without one stride
  per plane of its format, and an encoded stream that lists planes.
- Counters were totals over every group. They are now kept per group, so
  a tool can tell which camera drops frames.

Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
Co-Authored-By: Claude <noreply@anthropic.com>
…ory kind

The README explains the terms (stream, group, frame set, window, order,
lease, generation), the two ways a backend gets a slot, and the pool
budget, so a reviewer does not need anything outside the repository.

MemoryKind listed kinds that nothing implements yet. It now has HOST
only; each further kind is added together with its pool.

Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Core tests carry the unit tag, which becomes the CTest label that
`ctest -L unit` selects.

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
The tests start threads. Without the link, std::thread fails at run time
on C libraries that keep threads in a separate library.

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
add_group now checks that every plane of a pixel stream lies inside the
slot (row length against stride, last row against the slot size) and that
a pool can hold one frame set on top of the backend's reserve. publish
refuses an image larger than its slot.

EventSink::send_event is noexcept: it runs on the capture path with the
publisher's lock held, and a throwing sink would have left a slot held.

A group with a slot-free callback hands out its slots with claim_slot
only, so a slot cannot be taken again before its callback has run.

Adds agent notes for the module.

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
HostPool is one stream's slots in shared host memory: a single anonymous
memory file with the slots a page-aligned stride apart. The owner maps it
writable and then seals it, so a process that is sent the descriptor can
map it for reading only and cannot resize it. HostPoolView is that
reader's mapping; both sides derive the layout from the slot count and
slot size. UniqueFd owns a file descriptor.

An anonymous sealed file is used rather than named shared memory: there
is no name to collide or to clean up after a crash, and only a process
that was handed the descriptor can map it.

Linux only, so the module and its tests are added under a platform check.

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Farbod Motlagh <fmotlagh@nvidia.com>
@farbod-nv
farbod-nv force-pushed the fm/camera_capture_m0_host_pool branch from d9498aa to 0bd42c2 Compare November 14, 2026 00:34
@farbod-nv

Copy link
Copy Markdown
Contributor Author

Folded into #1521. The first milestone of the camera interface is now four pull requests instead of twelve: #1521, #1528, #1530 and #1534.

This branch was successfully deployed

1 active deployment
dev — 0bd42c22 Deployed Nov 14, 2026 by farbod-nv via publish-wheel #6936
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants