feat(log): add bounded diagnostic transport

libs/kaptan-data-channel/src/lib.rs

@@ -9,11 +9,14 @@
 
 use kaptan_board::{BoardConfig, DataChannelRates};
 use kaptan_dma::TxCompletion;
+use kaptan_log::KaptanError;
+use kaptan_mavlink::message::MessageData;
 use kaptan_mavlink::{
     MavlinkFrame,
     encoder::{DistanceSensorConfig, MavlinkEncoder},
     message::{MavCmd, MavResult, MavState},
     transmitter::FrameClass,
+    transmitter::TransmitFaultKind,
 };
 use kaptan_sensor::{optical_flow::OpticalFlowSnapshot, range::RangeSnapshot};
 
@@ -27,10 +30,78 @@ pub use mailbox::{LatestImuMailbox, LatestOpticalFlowMailbox, LatestRangeMailbox
 /// delivery class. The platform retains only DMA endpoint ownership.
 pub trait FrameSink {
     /// Admits one fully encoded frame to the platform's bounded transport.
-    fn send(&mut self, class: FrameClass, frame: MavlinkFrame);
+    fn send(&mut self, class: FrameClass, frame: MavlinkFrame) -> FrameAdmission;
 
     /// Releases or faults the active DMA frame after a terminal interrupt.
-    fn on_dma_complete(&mut self, completion: TxCompletion);
+    fn on_dma_complete(&mut self, completion: TxCompletion) -> DmaCompletion;
+
+    /// Returns unconfigurable sole-link loss counters.
+    fn health(&self) -> TxHealth;
+
+    /// Removes one exact terminal transport-fault category for the central
+    /// observability owner. It is never encoded from an ISR or transport
+    /// driver directly.
+    fn take_transport_fault(&mut self) -> Option<TransmitFaultKind>;
+}
+
+/// Outcome returned to the one platform telemetry owner for each attempted
+/// frame admission. It never triggers logging recursively.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum FrameAdmission {
+    /// The queue retained this encoded frame, possibly after replacing a
+    /// pending lower-priority frame.
+    Retained(kaptan_mavlink::transmitter::EnqueueResult),
+}
+
+impl FrameAdmission {
+    /// Whether the frame is represented by the lower transport and the log
+    /// hub may acknowledge its source record.
+    pub const fn is_retained(self) -> bool {
+        matches!(
+            self,
+            Self::Retained(
+                kaptan_mavlink::transmitter::EnqueueResult::Enqueued
+                    | kaptan_mavlink::transmitter::EnqueueResult::ReplacedBestEffort
+                    | kaptan_mavlink::transmitter::EnqueueResult::ReplacedCritical
+            )
+        )
+    }
+
+    /// Whether no pending queue slot accepted the source frame.
+    pub const fn is_queue_full(self) -> bool {
+        matches!(
+            self,
+            Self::Retained(
+                kaptan_mavlink::transmitter::EnqueueResult::VitalQueueFull
+                    | kaptan_mavlink::transmitter::EnqueueResult::CriticalQueueFull
+                    | kaptan_mavlink::transmitter::EnqueueResult::BestEffortDropped
+            )
+        )
+    }
+}
+
+/// Terminal outcome from the sole DMA owner.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DmaCompletion {
+    /// No new transport fault was observed.
+    Complete,
+    /// A DMA terminal or restart fault was counted by the platform.
+    Fault,
+}
+
+/// Unconfigurable loss counters from sole-link admission/DMA ownership.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct TxHealth {
+    /// Dropped or displaced pending frames, including vital admission loss.
+    pub admission_loss_count: u32,
+    /// DMA preparation/start/terminal transfer faults.
+    pub dma_fault_count: u32,
+    /// DMA-visible memory preparation faults.
+    pub memory_fault_count: u32,
+    /// DMA-engine transfer-start faults.
+    pub engine_fault_count: u32,
+    /// Active-DMA terminal faults or halts.
+    pub terminal_fault_count: u32,
 }
 
 /// Mailboxes read by one data-channel worker.
@@ -56,7 +127,7 @@ pub struct VerticalDataConfig {
 }
 
 /// Data-channel construction failure.
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[derive(Clone, Copy, Debug, Eq, PartialEq, KaptanError)]
 pub enum DataChannelError {
     /// Rejected profiles must not construct a physical telemetry channel.
     NotTelemetryProfile,
@@ -126,7 +197,7 @@ where
         match self.schedule.next_due() {
             Some(DueData::RawImu) => {
                 if let Some(sample) = self.sources.imu.take_newer(&mut self.observed_imu) {
-                    self.sink.send(
+                    let _ = self.sink.send(
                         FrameClass::BestEffort,
                         self.encoder.raw_imu_snapshot(&sample),
                     );
@@ -134,7 +205,7 @@ where
             }
             Some(DueData::Distance) if self.range_age_ticks <= self.vertical.maximum_age_ticks => {
                 if let (Some(range), Some(config)) = (self.last_range, self.vertical.distance) {
-                    self.sink.send(
+                    let _ = self.sink.send(
                         FrameClass::BestEffort,
                         self.encoder.distance_sensor_snapshot(&range, config),
                     );
@@ -146,33 +217,58 @@ where
                 if let (Some(flow), Some(sensor_id)) =
                     (self.last_optical_flow, self.vertical.optical_flow_sensor_id)
                 {
-                    self.sink.send(
+                    let _ = self.sink.send(
                         FrameClass::BestEffort,
                         self.encoder.optical_flow_snapshot(&flow, sensor_id),
                     );
                 }
             }
-            Some(DueData::Heartbeat) => self.sink.send(
-                FrameClass::Critical,
-                self.encoder.heartbeat(system_status, motors_armed),
-            ),
+            Some(DueData::Heartbeat) => {
+                let _ = self.sink.send(
+                    FrameClass::Vital,
+                    self.encoder.heartbeat(system_status, motors_armed),
+                );
+            }
             Some(DueData::Distance | DueData::OpticalFlow) | None => {}
         }
     }
 
     /// Completes the active DMA lifecycle for this channel's transport.
-    pub fn on_dma_complete(&mut self, completion: TxCompletion) {
-        self.sink.on_dma_complete(completion);
+    pub fn on_dma_complete(&mut self, completion: TxCompletion) -> DmaCompletion {
+        self.sink.on_dma_complete(completion)
     }
 
     /// Emits a critical acknowledgement for a received MAVLink command.
     pub fn acknowledge_command(&mut self, command: MavCmd, result: MavResult) {
-        self.sink.send(
+        let _ = self.sink.send(
             FrameClass::Critical,
             self.encoder.command_ack(command, result),
         );
     }
 
+    /// Encodes an adapter-owned generated MAVLink data record through the
+    /// channel's sole encoder and bounded transport sink.
+    pub fn send_custom<M: MessageData>(
+        &mut self,
+        class: FrameClass,
+        message: &M,
+    ) -> FrameAdmission {
+        self.sink.send(class, self.encoder.custom(message))
+    }
+
+    /// Returns local sole-link accounting for platform diagnostics. It is not
+    /// serialized through Kaptan's bounded diagnostic messages.
+    pub fn transport_health(&self) -> TxHealth {
+        self.sink.health()
+    }
+
+    /// Removes one exact sole-link transport fault category after the platform
+    /// has counted it. The platform maps it to a typed log record on its
+    /// bounded telemetry worker.
+    pub fn take_transport_fault(&mut self) -> Option<TransmitFaultKind> {
+        self.sink.take_transport_fault()
+    }
+
     fn refresh_vertical_data(&mut self) {
         if let Some(range) = self.sources.range.take_newer(&mut self.observed_range) {
             self.last_range = Some(range);
@@ -275,11 +371,16 @@ impl<const SERVICE_HZ: usize> Schedule<SERVICE_HZ> {
 #[cfg(test)]
 mod tests {
     use super::{
-        DataChannel, DataSources, FrameSink, LatestImuMailbox, LatestOpticalFlowMailbox,
-        LatestRangeMailbox, VerticalDataConfig,
+        DataChannel, DataSources, DmaCompletion, FrameAdmission, FrameSink, LatestImuMailbox,
+        LatestOpticalFlowMailbox, LatestRangeMailbox, TransmitFaultKind, TxHealth,
+        VerticalDataConfig,
+    };
+    use kaptan_board::{
+        BoardConfig, DataChannelRates, ImuDevice, ImuMount, MavlinkEndpoint, MavlinkPort,
+        VerticalSensingKind,
     };
-    use kaptan_board::{BoardConfig, DataChannelRates, MavlinkEndpoint, VerticalSensingKind};
     use kaptan_dma::TxCompletion;
+    use kaptan_log::Severity;
     use kaptan_mavlink::{MavlinkFrame, message::MavState, transmitter::FrameClass};
     use kaptan_sensor::{
         imu::ImuSnapshot, optical_flow::OpticalFlowSnapshot, range::RangeSnapshot,
@@ -293,15 +394,26 @@ mod tests {
     }
 
     impl FrameSink for Sink {
-        fn send(&mut self, class: FrameClass, _: MavlinkFrame) {
+        fn send(&mut self, class: FrameClass, _: MavlinkFrame) -> FrameAdmission {
             match class {
+                FrameClass::Vital => self.critical += 1,
                 FrameClass::BestEffort => self.best_effort += 1,
                 FrameClass::Critical => self.critical += 1,
             }
+            FrameAdmission::Retained(kaptan_mavlink::transmitter::EnqueueResult::Enqueued)
         }
 
-        fn on_dma_complete(&mut self, _: TxCompletion) {
+        fn on_dma_complete(&mut self, _: TxCompletion) -> DmaCompletion {
             self.completions += 1;
+            DmaCompletion::Complete
+        }
+
+        fn health(&self) -> TxHealth {
+            TxHealth::default()
+        }
+
+        fn take_transport_fault(&mut self) -> Option<TransmitFaultKind> {
+            None
         }
     }
 
@@ -310,8 +422,12 @@ mod tests {
         mavlink: MavlinkEndpoint {
             system_id: 1,
             component_id: 1,
+            port: MavlinkPort::Serial1,
+            baud: 115_200,
         },
         profile: kaptan_board::BoardProfile::TelemetryOnly(kaptan_board::TelemetryProfile {
+            imu: ImuDevice::Mpu6000,
+            imu_mount: ImuMount::BodyAligned,
             vertical_sensing: VerticalSensingKind::RangeAndOpticalFlow,
             data_channel: DataChannelRates {
                 service_hz: 100,
@@ -320,6 +436,7 @@ mod tests {
                 optical_flow_hz: Some(20),
                 heartbeat_hz: 2,
             },
+            maximum_log_level: Severity::Info,
         }),
     };