[#1570] Add iceoryx2-dmabuf crate with SCM_RIGHTS fd sidecar and DMA-BUF wrapper

[julienzarka]

[#1570] Add iceoryx2-dmabuf - SCM_RIGHTS fd sidecar and typed DMA-BUF wrapper

Closes #1570.

Summary

Adds a new workspace crate iceoryx2-dmabuf that extends iceoryx2 pub/sub
with out-of-band delivery of kernel-owned file descriptors (DMA-BUF frames
from V4L2 ISP, DRM scanout, Vulkan external memory, or generic memfds).

The crate exposes two clearly scoped APIs:

Layer	Types	Use case
Transport	FdSidecarPublisher / FdSidecarSubscriber	Any OwnedFd (memfd, eventfd, pipe end, DMA-BUF fd) - no CPU-sync semantics
Payload (feature dma-buf)	DmaBufPublisher / DmaBufSubscriber	Real DMA-BUF fds; subscriber gets dma_buf::DmaBuf with safe CPU access via MappedDmaBuf::read/write/readwrite

The transport carries fds via SCM_RIGHTS over a per-service Unix-domain
socket, synchronised to the iceoryx2 sample sequence through an
FdSidecarToken user-header. The payload layer is a newtype over the
transport that delegates every DMA_BUF_IOCTL_SYNC to the audited
dma-buf crate (v0.5, by
@mripard) - this PR does not reimplement the
ioctl surface.

Motivation (from #1570)

iceoryx2's typed SHM pool delivers value-type payloads efficiently but
cannot represent kernel-owned DMA-BUF allocations produced by V4L2 ISP,
DRM scanout, or Vulkan external-memory exports. Those frames are
identified by a file descriptor whose numeric value is meaningless
outside the producing process; cross-process transfer requires
SCM_RIGHTS over a Unix-domain socket. iceoryx2-dmabuf adds a thin
sidecar channel that delivers fds in lockstep with the normal iceoryx2
metadata flow, preserving zero-copy semantics end-to-end.

Changes

iceoryx2 (core)

• Add iceoryx2::port::side_channel::SideChannel trait - a cross-platform
  role marker for out-of-band transports alongside pub/sub. Deliberately
  free of Linux-specific syscall surface so it compiles everywhere.

iceoryx2-dmabuf (new crate)

• FdSidecarPublisher<S, Meta> / FdSidecarSubscriber<S, Meta> - the
  transport layer. Linux-only at runtime; non-Linux targets compile and
  return UnsupportedPlatform.
• DmaBufPublisher<S, Meta> / DmaBufSubscriber<S, Meta> - typed
  newtypes over the transport, feature-gated on dma-buf. Accept a
  &dma_buf::DmaBuf on send; yield a dma_buf::DmaBuf on recv.
• FdSidecarError::DmaBuf(dma_buf::BufferError) - wraps upstream
  BufferError into our non-exhaustive error enum rather than
  re-exporting it.
• Unix-domain socket accept loop with SO_PEERCRED UID check (feature
  peercred), sequence-number correlation via FdSidecarToken in the
  iceoryx2 sample user-header, and a 50 ms timeout on fd delivery.
• Injection helpers (feature test-utils) for error-path tests.

benchmarks/dmabuf (new crate)

• bench_latency - single-publisher/subscriber per-frame latency for
  1080p fd passing (p50/p95/p99).
• bench_throughput - sustained frames-per-second ceiling.
• bench_fanout - slowest-consumer p95 across N subscribers.

Cargo features (all off by default except std)

Feature	Description	Platform
memfd	memfd_create-based helpers for tests and examples	Linux only
peercred	SO_PEERCRED UID verification before fd delivery	Linux only
dma-buf	DmaBufPublisher / DmaBufSubscriber typed layer	Linux only (pulls dma-buf 0.5)
test-utils	Injection APIs for error-path integration tests	Linux only

Commit structure

[#1570] Add SideChannel trait in iceoryx2::port::side_channel    (+85)
[#1570] Add iceoryx2-dmabuf crate with SCM_RIGHTS fd sidecar ... (+7K)
[#1570] Add iceoryx2-dmabuf benchmarks                           (+0.4K)

Each commit compiles, clippies, and tests in isolation (git bisect green).

Test evidence

macOS aarch64 (Darwin 25.4, cargo 1.88):

• cargo fmt --check ✓
• cargo clippy -p iceoryx2-dmabuf --all-features --all-targets -- -D warnings ✓
• cargo clippy -p iceoryx2-dmabuf --no-default-features --target aarch64-apple-darwin -- -D warnings ✓
• cargo test -p iceoryx2-dmabuf --features "dma-buf memfd peercred test-utils" ✓ (Linux-gated tests report 0 run)

Linux aarch64 (Ubuntu 25.10, cargo 1.93):

• cargo fmt --check ✓
• cargo clippy -p iceoryx2-dmabuf --all-features --all-targets -- -D warnings ✓
• cargo clippy -p iceoryx2-dmabuf --no-default-features -- -D warnings ✓
• cargo test -p iceoryx2-dmabuf --features "dma-buf memfd peercred test-utils" ✓ - 28 pass / 0 fail / 2 ignored
• /dev/dma_heap/system present → real DmaBuf heap round-trip passes with
  DMA_BUF_IOCTL_SYNC firing on both publisher and subscriber

Test suite highlights

• tests/dmabuf_roundtrip.rs - in-process memfd roundtrip
• tests/it_fanout.rs - 1 publisher × 3 subscribers × 100 frames
• tests/it_crash_midsend.rs - producer SIGSTOP between sidecar send
  and iceoryx2 send → subscriber gets NoFdInMessage
• tests/it_service_gone.rs, tests/it_socket_gone.rs - recovery paths
• tests/refcount_survival.rs - fd refcount survives N-1 consumer closes
• tests/it_fd_identity.rs - two-process fstat shows same inode
• tests/error_paths.rs - TokenMismatch and NoFdInMessage paths
  (test-utils injection)
• tests/prop_roundtrip.rs - proptest random payload sizes 1 B - 16 MiB
• tests/it_dmabuf_fd_identity.rs - inode preserved across DmaBuf wrap
• tests/it_dmabuf_heap_roundtrip.rs - real /dev/dma_heap/system
  allocation, MappedDmaBuf::read with CPU-sync ioctls, byte-pattern
  verification

Examples

• examples/publish_subscribe_with_fd/{publisher,subscriber}.rs -
  transport layer with memfd payloads.
• examples/publish_subscribe_dmabuf/{publisher,subscriber}.rs -
  payload layer with dma-heap allocation + MappedDmaBuf::read.

Out of scope for this PR

• Multi-plane (YUV420/NV12 with separate Y/UV fd) support - single fd per sample only.
• Async transport - sendmsg/recvmsg are synchronous.
• sync_file / GPU fence propagation - DMA-BUF only.
• Windows DXGI_KEYED_MUTEX handles - Linux only.
• pidfd_getfd(2) alternative transport - future work if benchmarks show benefit.

Checklist

• Issue exists (#1570)
• Branch prefix (iox2-1570-dmabuf-sidecar per CONTRIBUTING)
• Commit prefix [#1570] on every commit
• Eclipse copyright header on every new .rs file
• Release notes added in doc/release-notes/iceoryx2-unreleased.md
• ECA signed
• CI passes locally on aarch64 Linux and Darwin

Questions for maintainers

1. Would you prefer one commit (everything bundled) over the current
   three? The trait + crate + benchmarks split keeps the diff reviewable
   in chunks; happy to squash.
2. Is iceoryx2-dmabuf the right crate name, or should it be e.g.
   iceoryx2-fd-sidecar to reflect that the transport works with
   arbitrary fds and DMA-BUF is one application?
3. Any preference on whether the dma-buf dependency should be a
   default feature or remain opt-in?

Thanks for the review.