cyphal: encapsulate libudpard in CyphalUDPInterface (issue-61)

Encapsulate libudpard behind jarnax::cyphal::Interface so applications
no longer touch udpard directly. Uses the new
CyphalUDPInterface.*pp files as the implementation boundary.

jarnax-cyphal-udp:
- Move O1HeapPool from nucleo-cyphal app into the module, implement
  core::Allocator, provide UdpardMemoryResource/UdpardRxMemoryResources
  factories backed by a single 64 KiB arena.
- Add CyphalUDPSocket abstraction (udp::Endpoint, DatagramHandler,
  Socket with Join/Leave/Send) and MicrosecondClock so the generic
  module stays host-testable without cortex headers.
- Implement CyphalUDPInterface (Interface + Loopable +
  DatagramHandler): pooled subscriptions (8), RPC ports (8), per-port
  transfer-ID counters (16), remembered request TIDs (8), Nominal
  priority, TX queue drain via Socket, RX dispatch via
  udpardGather into a MaxExtent scratch buffer, and TransportStatistics.

nucleo-cyphal:
- Depend on jarnax-cyphal-udp instead of raw o1heap/udpard, switch
  CyphalApp to jarnax::cyphal::O1HeapPool.

Tests/mocks:
- gtest-cyphal-o1heappool: allocator and Udpard callback coverage.
- gtest-cyphal-udpinterface (12 tests): Listen/Remove/IsListening
  lifecycle, Join-once service group, publish/request/respond,
  TX-error stats, subject and RPC round-trips via a local UdpardTx
  producer (no hand-built wire formats), unknown-group/bad-datagram
  handling.
- MockUDPSocket (gmock) mirroring the socket abstraction.
- Fix stale over-alignment expectation (o1heap serves at max_align_t).

Build: on-host-native-llvm 21/21, on-host-native-clang 21/21,
       on-target-cortex-m4/m7 (GCC) all pass; 62/62 in jarnax-cyphal.

Human work: issue #61 spec, initial O1HeapPool scaffolding, hardware
requirements, review of GOTCHAS/PLAN.
AI work: socket/interface design, implementation, GoogleTests/mocks,
CMake wiring, verification and commit.
AI: opencode/muse-spark-1.2-contributor-free (Meta Muse Spark 1.2,
    contributor-free tier; ~128k context).

Refs #61

Author: emrainey

GOTCHAS.md

@@ -154,3 +154,25 @@
 - **Root cause:** `modules/memory/source/copy.cpp` defined `void copy(void*, void *const, size_t)` (top-level const pointer = mangles to `void*`), but the header `memory.hpp` declares `void copy(void*, void const*, size_t)` (mangles to `void const*`). The template overload had masked it for years because no caller forced the non-template `void` overload (e.g. `memory::copy(uint8_t[], char[], n)` — mismatched element types defeat template deduction and fall through to the fixed overload).
 - **Fix:** changed the definition's parameter to `void const *_src` to match the header. Added Catch2 tests in `modules/memory/tests/catch2-strings.cpp` using mismatched element types (`uint8_t[]` dst, `char const*` src) to force the fixed overload.
 - **Gotcha:** top-level `const` on a pointer parameter is dropped during C++ name mangling, but pointee-const is not — `void *const` and `void const *` are different symbols. Keep definitions byte-for-byte consistent with the header declaration.
+
+## 2026-08-22 — Encapsulating libudpard in `CyphalUDPInterface` (issue-61)
+
+- **Gotcha:** generic modules (`add_module` with `NO_BOARDS`) cannot include `jarnax/Ticker.hpp`
+  because it pulls `cortex/tick.hpp`, which only the cortex *architecture* target exposes on its
+  include line. The main `jarnax` module gets it via `ARCH cortex`; `jarnax-cyphal-udp` does not.
+  Fix: define a tiny `MicrosecondClock` abstract interface (core-only types) and inject it instead.
+- **Gotcha:** `jarnax::cyphal::PortId` is **not copy-assignable** (its copy assignment is implicitly
+  deleted, anonymous union of non-trivial-ish members). Store port identity as plain fields
+  (type/style/value) when a struct needs to hold and overwrite one; do not keep `PortId` members.
+- **Gotcha:** `udpardGather` returns 0 for an empty fragment list, so an "empty payload" transfer
+  (e.g. `uavcan.node.GetInfo` request) looks identical to a gather failure if you gate delivery on
+  `gathered > 0`. Gate on `transfer.payload_size` instead; empty transfers are valid Cyphal transfers.
+- **Gotcha:** libudpard TX responses (`udpardTxRespond`) are addressed to the *client's* RPC multicast
+  group derived from the client node-ID — not to the group the request arrived on. In tests,
+  `sent_to == from` is wrong for responses.
+- **Gotcha:** o1heap does **not** reject allocation requests whose alignment exceeds max_align_t;
+  with NDEBUG it serves the block at its own granularity. Don't write tests asserting nullptr for
+  over-aligned requests. Fixed stale expectation in gtest-cyphal-o1heappool.cpp.
+- **Gotcha:** subject-IDs passed to `udpardTxPublish` must be ≤ 8191 (UDPARD_SUBJECT_ID_MAX);
+  out-of-range IDs return -UDPARD_ERROR_ARGUMENT, which surfaces as an innocent-looking
+  `Publish() == false` in test producers.

PLAN.md

@@ -1,55 +1,39 @@
-# PLAN: Add gtests for `cyphal::Node::Print` diagnostic records
+# PLAN: Encapsulate libudpard in a `cyphal::Interface` implementation
 
-Issue: #60 — branch `issue-60` (tracks `develop`; carries the user's
-uncommitted diagnostic Record work: `Printer` interface, `Severity` enum,
-`Node::Print`, `diagnostic_record_blob_`, `diagnostic_statistics_`).
+**Status:** In progress — steps 4–5 complete (socket abstraction + `CyphalUDPInterface` + GoogleTest suite); hypha adapter and app refactor remain.
+**Issue:** https://github.com/emrainey/embedded-superloop/issues/61
+**Branch (when started):** `issue-61`, tracking `develop`
 
 ## Summary
 
-Add GoogleTest coverage for the diagnostic Record publishing added by the
-human: `Node::Print(Severity, fmt, ...)` serializes a
-`uavcan.diagnostic.Record.1.1` (subject 8184) and publishes it via the
-interface.
-
-## Changes
-
-1. **`gtest-cyphal-node.cpp`** — new `TEST_F`s for `Node::Print`:
-   - publishes a deserializable Record on `DiagnosticRecordSubjectId` with the
-     expected severity and text,
-   - text longer than 255 bytes is truncated to the DSDL capacity,
-   - the `timestamp.microsecond` field reflects the timer,
-   - `diagnostic_statistics_.passed` increments on a successful publish,
-   - `diagnostic_statistics_.failed` increments when the interface `Send`
-     fails.
-   - `TestNode` accessor `GetDiagnosticStatistics()` exposing the protected
-     `diagnostic_statistics_`.
-
-## Production fixes required by the tests (all flagged/approved)
-
-2. **`modules/jarnax/source/cyphal/Node.cpp`** — `Node::Print` called
-   `jarnax::vsnprint`, which is *declared* in `jarnax/print.hpp` but has no
-   definition anywhere in the repo. Changed to `core::vsnprint` (always linked
-   into cyphal targets; keeps the test target lean). Approved by human.
-
-3. **`modules/memory/source/copy.cpp`** — the definition was
-   `copy(void*, void* const, size_t)` while the header declares
-   `copy(void*, void const*, size_t)`. Different mangled symbols; the overload
-   had never been linked before. Fixed the definition to match the header.
-
-4. **`modules/memory/tests/catch2-strings.cpp`** — added 2 `TEST_CASE`s
-   covering the fixed `copy(void*, void const*, size_t)` overload (mismatched
-   element types to force the non-template overload, as in `Node::Print`).
-
-## Verification
-
-- `cmake --workflow --preset on-host-native-llvm` — 21/21 tests pass,
-  including 5 new `Print` tests and 2 new memory `copy` tests.
-- `cmake --workflow --preset on-host-native-clang` — 21/21 tests pass.
-- Cross-builds: `on-target-cortex-m4-gcc-arm-none-eabi` and
-  `on-target-cortex-m7-gcc-arm-none-eabi` still build clean.
-
-## Notes
-
-- The `Print` impl is the human's uncommitted work on this branch; the two
-  production fixes above were the only changes needed and were approved before
-  applying.
+Extract the libudpard plumbing inlined in `applications/nucleo-cyphal/source/CyphalApp.cpp` (~400 of 795 lines) into a reusable `jarnax::cyphal::CyphalUDPInterface` implementing `jarnax::cyphal::Interface`. Applications stop touching udpard directly.
+
+## Estimate
+
+4–7 days total including tests.
+
+## Steps
+
+1. Branch `issue-61` off `develop`.
+2. [complete] Move the shared O1Heap pool into `jarnax-cyphal-udp`, implement `core::Allocator`, and provide libudpard memory-resource factories.
+3. [complete] Add host-runnable GoogleTest coverage for the allocator and libudpard callbacks.
+4. [complete] Socket abstraction: `source/include/jarnax/services/CyphalUDPSocket.hpp` (`udp::Endpoint`, `DatagramHandler`, `Socket` with Join/Leave/Send). Time comes from an injected `MicrosecondClock` (generic modules cannot include cortex headers).
+5. [complete] `CyphalUDPInterface` in `source/services/CyphalUDPInterface.cpp` + internal header: all 6 `Interface` virtuals + `Loopable::Execute` TX drain + `DatagramHandler::OnDatagramReceived` RX dispatch; per-port transfer-ID counters; priority fixed Nominal; remembered request transfer-IDs for responses; fragment gather into scratch buffer; statistics.
+6. Hypha adapter for the socket abstraction.
+7. [complete] GoogleTest suite `tests/gtest-cyphal-udpinterface.cpp` with `tests/mocks/jarnax/services/MockUDPSocket.hpp`: Listen/Remove/IsListening lifecycle, Join-once semantics, Send publish/request/respond, TX error stats, RX subject round-trip, RPC request→response round-trip, unknown-group/bad-datagram handling. Valid RX datagrams are produced with a local `UdpardTx` producer (no hand-built wire formats). 62/62 pass on LLVM and AppleClang; both cross presets build.
+8. Refactor `CyphalApp` onto `CyphalUDPInterface`; verify on hardware via pylink/RTT + yactui.
+9. Run all presets and `./scripts/build-all-presets.sh`; PR against `develop`.
+
+## Key design decisions
+
+- Do **not** extend `Metadata` with priority/transfer-ID yet — priority is constant Nominal; per-port transfer-ID counters live inside the interface; response transfers echo the transfer-ID of the last remembered request from that client.
+- Constructor takes `O1HeapPool&`, node-ID, `udp::Socket&`, and `MicrosecondClock&` — no singletons reached from inside; no cortex dependency so the generic module stays host-testable.
+- Single redundant interface initially; `TransportStatistics` reports one interface entry.
+- RX transfers are gathered into a contiguous scratch buffer bounded by `MaxExtent`; empty transfers are delivered as zero-length messages.
+- Service ports share one RPC multicast group; Join is issued once for the first port and Leave when the last port is removed.
+
+## Acceptance criteria
+
+- No udpard types leak into application code.
+- All host unit tests pass on LLVM and AppleClang; cross builds unbroken.
+- nucleo-cyphal behaves identically on hardware.

applications/nucleo-cyphal/CMakeLists.txt

@@ -3,7 +3,6 @@ add_firmware(NAME nucleo-cyphal
         ${CMAKE_CURRENT_SOURCE_DIR}/source/GlobalContext.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/source/CyphalApp.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/source/GetInfoScanner.cpp
-        ${CMAKE_CURRENT_SOURCE_DIR}/source/O1HeapPool.cpp
     INCLUDES
         ${CMAKE_CURRENT_SOURCE_DIR}/include
     DEFINES
@@ -12,7 +11,8 @@ add_firmware(NAME nucleo-cyphal
         cyphal-dsdl
         hypha-ip
         udpard
-        o1heap
+    GENERIC_MODULES
+        jarnax-cyphal-udp
     CONFIGURATIONS
         basic
     BOARDS

applications/nucleo-cyphal/include/O1HeapPool.hpp

@@ -1,12 +1,12 @@
 #include "CyphalApp.hpp"
 
 #include "GetInfoScanner.hpp"
-#include "O1HeapPool.hpp"
 #include "board.hpp"
 #include "core/Conversions.hpp"
 #include "core/vsnprint.hpp"
 #include "hypha_ip/hypha_ip.h"
 #include "jarnax/Assertion.hpp"
+#include "jarnax/cyphal/O1HeapPool.hpp"
 #include "memory.hpp"
 #include "segger/rtt.hpp"
 #include "stm32/h7xx/ethernet/Driver.hpp"
@@ -75,17 +75,6 @@ HyphaIpSpan_t MakeSpan(void const* data, std::size_t size) {
     return span;
 }
 
-void* UdpardAlloc(void* context, size_t size) {
-    auto* heap = static_cast<O1HeapInstance*>(context);
-    return o1heapAllocate(heap, size);
-}
-
-void UdpardFree(void* context, size_t size, void* pointer) {
-    (void)size;
-    auto* heap = static_cast<O1HeapInstance*>(context);
-    o1heapFree(heap, pointer);
-}
-
 bool SameIPv4Address(HyphaIpIPv4Address_t const& a, HyphaIpIPv4Address_t const& b) {
     static_assert(sizeof(a) == sizeof(uint32_t), "Must be exactly this size");
     return std::memcmp(&a, &b, sizeof(a)) == 0;
@@ -288,22 +277,13 @@ bool CyphalApp::Execute() {
 }
 
 void CyphalApp::InitUdpard() {
-    O1HeapInstance& heap = O1HeapPool::Instance();
+    jarnax::cyphal::O1HeapPool& heap = jarnax::cyphal::O1HeapPool::Instance();
 
     // v1.x memory resources wrap the same O1Heap-backed allocator.
-    struct UdpardMemoryResource const memory = {
-        .user_reference = &heap,
-        .deallocate = &UdpardFree,
-        .allocate = &UdpardAlloc,
-    };
+    UdpardMemoryResource const memory = heap.GetMemoryResource();
     tx_memory_ = memory;
 
-    rx_memory_.session = memory;
-    rx_memory_.fragment = memory;
-    rx_memory_.payload = {
-        .user_reference = &heap,
-        .deallocate = &UdpardFree,
-    };
+    rx_memory_ = heap.GetRxMemoryResources();
 
     // TX pipeline: single (non-redundant) interface, capacity bounded by the O1Heap.
     int_fast8_t const tx_init = udpardTxInit(&tx_, &node_id_, 32U, tx_memory_);
@@ -328,22 +308,10 @@ void CyphalApp::InitUdpard() {
 }
 
 void CyphalApp::ServiceDispatcherInit() {
-    O1HeapInstance& heap = O1HeapPool::Instance();
+    jarnax::cyphal::O1HeapPool& heap = jarnax::cyphal::O1HeapPool::Instance();
 
     // The RPC dispatcher shares the same O1Heap-backed memory resources as the subjects pipeline.
-    struct UdpardMemoryResource const memory = {
-        .user_reference = &heap,
-        .deallocate = &UdpardFree,
-        .allocate = &UdpardAlloc,
-    };
-    struct UdpardRxMemoryResources const dispatcher_memory = {
-        .session = memory,
-        .fragment = memory,
-        .payload = {
-            .user_reference = &heap,
-            .deallocate = &UdpardFree,
-        },
-    };
+    UdpardRxMemoryResources const dispatcher_memory = heap.GetRxMemoryResources();
 
     int_fast8_t const dispatcher_init = udpardRxRPCDispatcherInit(&service_dispatcher_, dispatcher_memory);
     if (dispatcher_init < 0) {
@@ -513,8 +481,8 @@ HyphaIpStatus_e CyphalApp::OnReceiveUdp(HyphaIpExternalContext_t context, HyphaI
         return HyphaIpStatusOk;
     }
 
-    O1HeapInstance& heap = O1HeapPool::Instance();
-    void* copy = o1heapAllocate(&heap, payload_size);
+    jarnax::cyphal::O1HeapPool& heap = jarnax::cyphal::O1HeapPool::Instance();
+    void* copy = heap.allocate(payload_size);
     if (copy == nullptr) {
         return HyphaIpStatusOutOfMemory;
     }
@@ -540,7 +508,7 @@ HyphaIpStatus_e CyphalApp::OnReceiveUdp(HyphaIpExternalContext_t context, HyphaI
                 udpardRxFragmentFree(transfer.base.payload, self->rx_memory_.fragment, self->rx_memory_.payload);
             }
         } else {
-            o1heapFree(&heap, copy);
+            heap.deallocate(copy, payload_size);
         }
         return HyphaIpStatusOk;
     }

applications/nucleo-cyphal/source/CyphalApp.cpp

@@ -162,13 +162,15 @@ add_module(NAME jarnax-cyphal-can
 add_module(NAME jarnax-cyphal-udp
     SOURCES
         ${CMAKE_CURRENT_SOURCE_DIR}/source/cyphal/Node.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/source/cyphal/O1HeapPool.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/source/services/CyphalUDPInterface.cpp
     INCLUDES
         ${CMAKE_CURRENT_SOURCE_DIR}/include
         ${CMAKE_CURRENT_SOURCE_DIR}/source/include # Internal includes
     DEFINES
         JARNAX_CYPHAL_USE_UDP
     LIBRARIES
-        strict jarnax-interfaces cyphal-dsdl
+        strict jarnax-interfaces cyphal-dsdl o1heap udpard
     GENERIC_MODULES
         memory core
     NO_CONFIGURATIONS

applications/nucleo-cyphal/source/O1HeapPool.cpp

@@ -0,0 +1,39 @@
+#ifndef JARNAX_CYPHAL_O1HEAP_POOL_HPP
+#define JARNAX_CYPHAL_O1HEAP_POOL_HPP
+
+#include <cstddef>
+#include <cstdint>
+
+#include "core/Allocator.hpp"
+
+extern "C" {
+#include "udpard.h"
+}
+
+namespace jarnax {
+namespace cyphal {
+
+/// @brief A fixed O1Heap arena shared by Cyphal/UDP allocations.
+class O1HeapPool final : public core::Allocator {
+public:
+    static O1HeapPool& Instance();
+
+    static constexpr std::size_t ArenaSize{65536U};
+
+    void* allocate(std::size_t bytes, std::size_t alignment = alignof(std::max_align_t)) override;
+    void deallocate(void* pointer, std::size_t bytes, std::size_t alignment = alignof(std::max_align_t)) override;
+
+    UdpardMemoryResource GetMemoryResource();
+    UdpardRxMemoryResources GetRxMemoryResources();
+
+private:
+    O1HeapPool() = default;
+
+    static void* UdpardAllocate(void* context, std::size_t bytes);
+    static void UdpardDeallocate(void* context, std::size_t bytes, void* pointer);
+};
+
+}    // namespace cyphal
+}    // namespace jarnax
+
+#endif    // JARNAX_CYPHAL_O1HEAP_POOL_HPP