Summary

Hardens the Linux hardware bridge layer (MemMap, AxiMemMap, AxiStreamDma) against thread-lifetime, file-descriptor, and shared-state bugs surfaced by the bug audit. All public API signatures are unchanged; fixes live in implementation + private/internal members. Each bug class is locked down by a source-audit doctest regression so the audited invariant cannot silently regress.

Bugs fixed

Thread ownership (RAII)

• Replace raw std::thread* thread_ = new std::thread(...) + delete with std::unique_ptr<std::thread> in MemMap, AxiMemMap, AxiStreamDma. Eliminates leaks on construction-failure paths and ensures cleanup ordering.

FD_SETSIZE bounds checks (AxiStreamDma)

• Reject fd_ >= FD_SETSIZE synchronously in the ctor (close + throw GeneralError), before the worker thread starts.
• In-loop FD_SETSIZE guards in acceptReq()/acceptFrame() now include the numeric limit and identify likely root causes (post-stop instance vs process fd-table exhaustion).
• runThread() logs and exits the worker cleanly on out-of-range fd instead of throwing across the thread boundary (which would call std::terminate()).

Shared-buffer state race (AxiStreamDma)

• Add static std::mutex sharedBuffersMtx covering openShared / closeShared / zeroCopyDisable and the ctor-time reads/writes of desc_->bCount / desc_->bSize. Also adds explicit #include <mutex>.
• Drop dead #if 0 block.

openShared() error-path stale-fd leak (AxiStreamDma)

• closeShared() leaves entries in sharedBuffers_ after openCount drops to 0 (only fd/bCount/bSize/rawBuff are reset). On error paths after ::open succeeded but a later step (driver version, dmaCheckVersion, dmaMapDma) failed, the original code closed the fd but left ret->fd non-negative — the next caller would re-enter the persistent record and reuse a stale descriptor, returning EBADF on every op.
• Reset ret->fd = -1 (and scrub bCount/bSize/rawBuff in the dmaMapDma failure path) on every error path before throwing. Comments disambiguate ret->fd (shared record field) from AxiStreamDma::fd_ (per-instance member).

openCount accounting (AxiStreamDma)

• AxiStreamDmaShared ctor now initializes openCount = 0 (was 1, double-counting entries seeded by zeroCopyDisable() before any AxiStreamDma user existed).
• openShared() increments openCount on every successful return path (existing-open, zero-copy-disabled fall-through, and freshly opened branch). The new-entry increment is placed after open + dmaMapDma succeed, so a pre-insertion throw cannot leak openCount.
• closeShared() guards ::close(desc->fd) with if (desc->fd != -1) — avoids close(-1) returning EBADF every time the count reaches 0 in the zeroCopyDisable() flow.

stop() idempotence + worker self-exit (AxiStreamDma)

• Now that runThread() can self-exit via the in-loop fd guard (sets threadEn_ = false and returns), the previous if (threadEn_)-gated cleanup would skip thread_->join() and ~unique_ptr<std::thread> on a still-joinable thread would call std::terminate().
• Drive cleanup from per-resource state: thread_->joinable() for the join, desc_ presence for closeShared (with desc_.reset() to prevent double-close), fd_ >= 0 for the ::close. threadEn_ = false is set unconditionally so the worker still receives the stop signal. Function is idempotent across user-stop → dtor and worker self-exit → stop sequences.

Use-after-stop guards (AxiStreamDma::acceptReq / acceptFrame)

• stop() resets desc_ to nullptr and closes fd_; previously acceptReq() dereferenced desc_->bSize at function entry and segfaulted on a post-stop call, and acceptFrame() only checked the fd inside the inner write loop after frame->lock() and buffer iteration had already run.
• Add fail-fast !desc_ || fd_ < 0 entry guards in both methods that throw GeneralError("...stopped or did not finish construction").

Source-audit regression tests added (tests/cpp/protocols/hardware/)

Each test scans the source for the audited invariant (comment-stripped to avoid false positives from explanatory text):

• test_memmap_raw_thread_audit_repro.cpp
• test_axi_memmap_raw_thread_audit_repro.cpp
• test_axi_stream_dma_raw_thread_audit_repro.cpp
• test_axi_stream_dma_fd_setsize_audit_repro.cpp
• test_axi_stream_dma_disabled_block_audit_repro.cpp
• test_axi_stream_dma_shared_static_race_audit_repro.cpp
• test_axi_stream_dma_open_shared_stale_fd_audit_repro.cpp
• test_axi_stream_dma_open_count_audit_repro.cpp
• test_axi_stream_dma_stop_joinable_audit_repro.cpp
• test_axi_stream_dma_use_after_stop_audit_repro.cpp

Documentation

No .rst updates required: the affected API pages (docs/src/api/cpp/hardware/..., docs/src/api/python/rogue/hardware/...) all use doxygenclass/doxygentypedef autogeneration. All header changes are inside //! \cond INTERNAL ... \endcond blocks (excluded by Doxygen) and no public API signatures changed.

Verification

• Lint: ./scripts/run_linters.sh — clean.
• C++ tests: cmake -DROGUE_BUILD_TESTS=ON -B build && cmake --build build && ctest --test-dir build — 19/19 pass (including all 10 new audit repros).
• Python tests: pytest tests/.