Skip to main content

hart_link/wire/
decoder.rs

1use alloc::{collections::VecDeque, vec::Vec};
2
3use crate::wire::{Address, Frame, FrameKind, FrameRepair, PhysicalLayer, WireError, xor_checksum};
4
5/// Hard upper bound for an incomplete streaming-decoder tail.
6pub const MAXIMUM_DECODE_BUFFER_CAPACITY: usize = 16 * 1024 * 1024;
7/// Largest number of frame or rejection events produced by one input fragment.
8pub const MAXIMUM_DECODE_EVENTS_PER_PUSH: usize = 4096;
9
10/// Strictly bounded compatibility policy for a confirmed gateway behavior.
11#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
12pub enum ChecksumPolicy {
13    /// Reject every checksum mismatch.
14    #[default]
15    Strict,
16    /// Allow only explicitly listed hardware distortions.
17    KnownGateway {
18        /// Allow alteration of the reserved `0x10` delimiter bit.
19        delimiter_bit: bool,
20        /// Allow a checksum calculated before the specified short address was rewritten.
21        checksum_source_node: Option<u8>,
22    },
23}
24
25/// Streaming decoder limits.
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub struct DecodeLimits {
28    /// Maximum number of buffered bytes between calls.
29    pub buffer_capacity: usize,
30    /// Minimum number of preambles required to recognize a frame.
31    pub minimum_preambles: u8,
32    /// Checksum and known-distortion policy.
33    pub checksum_policy: ChecksumPolicy,
34}
35
36impl Default for DecodeLimits {
37    fn default() -> Self {
38        Self {
39            buffer_capacity: 4096,
40            minimum_preambles: 2,
41            checksum_policy: ChecksumPolicy::Strict,
42        }
43    }
44}
45
46impl DecodeLimits {
47    /// Sets the maximum retained incomplete stream tail.
48    pub const fn with_buffer_capacity(mut self, buffer_capacity: usize) -> Self {
49        self.buffer_capacity = buffer_capacity;
50        self
51    }
52
53    /// Sets the minimum preamble run required before a delimiter.
54    pub const fn with_minimum_preambles(mut self, minimum_preambles: u8) -> Self {
55        self.minimum_preambles = minimum_preambles;
56        self
57    }
58
59    /// Sets the checksum acceptance policy.
60    pub const fn with_checksum_policy(mut self, checksum_policy: ChecksumPolicy) -> Self {
61        self.checksum_policy = checksum_policy;
62        self
63    }
64
65    /// Validates direct decoder resource and compatibility settings.
66    pub const fn validate(self) -> Result<(), DecodeLimitsError> {
67        if self.buffer_capacity == 0 {
68            return Err(DecodeLimitsError::EmptyBuffer);
69        }
70        if self.buffer_capacity > MAXIMUM_DECODE_BUFFER_CAPACITY {
71            return Err(DecodeLimitsError::BufferLimit(self.buffer_capacity));
72        }
73        if self.minimum_preambles == 0 {
74            return Err(DecodeLimitsError::NoPreambles);
75        }
76        if let ChecksumPolicy::KnownGateway {
77            checksum_source_node: Some(node),
78            ..
79        } = self.checksum_policy
80            && node > 63
81        {
82            return Err(DecodeLimitsError::ChecksumSourceNode(node));
83        }
84        Ok(())
85    }
86}
87
88/// Invalid direct streaming-decoder configuration.
89#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
90pub enum DecodeLimitsError {
91    /// No bytes could be retained between fragments.
92    #[error("decoder buffer_capacity must be greater than zero")]
93    EmptyBuffer,
94    /// The requested retained tail is implausibly large.
95    #[error("decoder buffer_capacity {0} exceeds the supported limit")]
96    BufferLimit(usize),
97    /// A preamble-free candidate policy is not accepted by validated construction.
98    #[error("decoder minimum_preambles must be greater than zero")]
99    NoPreambles,
100    /// A known gateway source node must fit a short HART address.
101    #[error("checksum source node {0} is outside 0..=63")]
102    ChecksumSourceNode(u8),
103}
104
105/// Streaming decoder counters.
106#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
107pub struct DecodeStatistics {
108    /// Successfully decoded frames.
109    pub frames: u64,
110    /// Discarded unrelated bytes.
111    pub discarded_bytes: u64,
112    /// Frames with an invalid checksum.
113    pub checksum_failures: u64,
114    /// Bytes removed because of the memory limit.
115    pub overflow_bytes: u64,
116    /// Frames accepted only through the explicit compatibility policy.
117    pub repaired_frames: u64,
118    /// Input batches truncated after producing too many individual events.
119    pub event_limit_hits: u64,
120}
121
122/// Result produced while advancing the streaming decoder.
123#[derive(Debug, Clone, PartialEq, Eq)]
124pub enum DecodeEvent {
125    /// A complete validated frame was received.
126    Frame(Frame),
127    /// A damaged frame was found; the decoder continued searching.
128    Rejected(WireError),
129}
130
131/// Decoder that accepts arbitrary transport-stream fragments.
132#[derive(Debug, Clone)]
133pub struct FrameDecoder {
134    bytes: VecDeque<u8>,
135    limits: DecodeLimits,
136    statistics: DecodeStatistics,
137}
138
139enum DecoderStep {
140    NoCandidate,
141    NeedMore,
142    Discard(usize),
143    Rejected {
144        error: WireError,
145        consumed: usize,
146        checksum_failure: bool,
147    },
148    Frame {
149        frame: Frame,
150        consumed: usize,
151        repaired: bool,
152    },
153}
154
155impl FrameDecoder {
156    /// Creates a decoder with the specified memory limit.
157    pub fn new(limits: DecodeLimits) -> Self {
158        let limits = DecodeLimits {
159            buffer_capacity: limits
160                .buffer_capacity
161                .clamp(1, MAXIMUM_DECODE_BUFFER_CAPACITY),
162            minimum_preambles: limits.minimum_preambles.max(1),
163            checksum_policy: limits.checksum_policy,
164        };
165        Self {
166            bytes: VecDeque::new(),
167            limits,
168            statistics: DecodeStatistics::default(),
169        }
170    }
171
172    /// Creates a decoder after rejecting invalid limits instead of clamping them.
173    pub fn try_new(limits: DecodeLimits) -> Result<Self, DecodeLimitsError> {
174        limits.validate()?;
175        Ok(Self::new(limits))
176    }
177
178    /// Returns the effective decoder limits.
179    pub const fn limits(&self) -> DecodeLimits {
180        self.limits
181    }
182
183    /// Adds a fragment and returns all completed events.
184    pub fn push(&mut self, fragment: &[u8]) -> Vec<DecodeEvent> {
185        self.append_bounded(fragment);
186        let mut events = Vec::new();
187        while events.len() < MAXIMUM_DECODE_EVENTS_PER_PUSH
188            && let Some(event) = self.next_event()
189        {
190            events.push(event);
191        }
192        if events.len() == MAXIMUM_DECODE_EVENTS_PER_PUSH && !self.bytes.is_empty() {
193            self.statistics.event_limit_hits = self.statistics.event_limit_hits.saturating_add(1);
194            self.retain_possible_preambles();
195        }
196        events
197    }
198
199    /// Returns accumulated counters.
200    pub const fn statistics(&self) -> DecodeStatistics {
201        self.statistics
202    }
203
204    /// Returns the number of incomplete buffered bytes.
205    pub fn buffered_len(&self) -> usize {
206        self.bytes.len()
207    }
208
209    /// Removes the incomplete stream tail.
210    pub fn clear(&mut self) {
211        self.bytes.clear();
212    }
213
214    fn append_bounded(&mut self, fragment: &[u8]) {
215        let overflow = self
216            .bytes
217            .len()
218            .saturating_add(fragment.len())
219            .saturating_sub(self.limits.buffer_capacity);
220        if overflow == 0 {
221            self.bytes.extend(fragment.iter().copied());
222            return;
223        }
224
225        let from_buffer = overflow.min(self.bytes.len());
226        self.bytes.drain(..from_buffer);
227        let from_fragment = overflow.saturating_sub(from_buffer).min(fragment.len());
228        self.bytes.extend(fragment[from_fragment..].iter().copied());
229        self.statistics.overflow_bytes = self
230            .statistics
231            .overflow_bytes
232            .saturating_add(u64::try_from(overflow).unwrap_or(u64::MAX));
233    }
234
235    fn next_event(&mut self) -> Option<DecodeEvent> {
236        loop {
237            let limits = self.limits;
238            let step = Self::analyze(self.bytes.make_contiguous(), limits);
239            match step {
240                DecoderStep::NoCandidate => {
241                    self.retain_possible_preambles();
242                    return None;
243                }
244                DecoderStep::NeedMore => return None,
245                DecoderStep::Discard(count) => self.discard(count),
246                DecoderStep::Rejected {
247                    error,
248                    consumed,
249                    checksum_failure,
250                } => {
251                    if checksum_failure {
252                        self.statistics.checksum_failures =
253                            self.statistics.checksum_failures.saturating_add(1);
254                    }
255                    self.discard(consumed);
256                    return Some(DecodeEvent::Rejected(error));
257                }
258                DecoderStep::Frame {
259                    frame,
260                    consumed,
261                    repaired,
262                } => {
263                    self.bytes.drain(..consumed);
264                    self.statistics.frames = self.statistics.frames.saturating_add(1);
265                    if repaired {
266                        self.statistics.repaired_frames =
267                            self.statistics.repaired_frames.saturating_add(1);
268                    }
269                    return Some(DecodeEvent::Frame(frame));
270                }
271            }
272        }
273    }
274
275    fn analyze(bytes: &[u8], limits: DecodeLimits) -> DecoderStep {
276        let Some((delimiter_index, preamble_start, preamble_count)) =
277            Self::find_candidate(bytes, limits)
278        else {
279            return DecoderStep::NoCandidate;
280        };
281        if preamble_start > 0 {
282            return DecoderStep::Discard(preamble_start);
283        }
284
285        let mut delimiter = bytes[delimiter_index];
286        let mut repair = None;
287        if FrameKind::from_delimiter(delimiter).is_none()
288            && Self::allow_delimiter_repair(limits.checksum_policy)
289            && FrameKind::from_delimiter(delimiter ^ 0x10).is_some()
290        {
291            delimiter ^= 0x10;
292            repair = Some(FrameRepair::DelimiterBit);
293        }
294        let long = delimiter & 0x80 != 0;
295        let address_len = if long { 5 } else { 1 };
296        let expansion_len = usize::from((delimiter >> 5) & 0x03);
297        let command_index = delimiter_index + 1 + address_len + expansion_len;
298        let count_index = command_index + 1;
299        if bytes.len() <= count_index {
300            return DecoderStep::NeedMore;
301        }
302        let payload_len = usize::from(bytes[count_index]);
303        let checksum_index = count_index + 1 + payload_len;
304        if bytes.len() <= checksum_index {
305            return DecoderStep::NeedMore;
306        }
307
308        let expected = xor_checksum(&bytes[delimiter_index..checksum_index]);
309        let actual = bytes[checksum_index];
310        let delimiter_checksum_matches =
311            Self::allow_delimiter_repair(limits.checksum_policy) && expected ^ 0x10 == actual;
312        let address_repair = if expected != actual && !delimiter_checksum_matches && !long {
313            Self::short_address_repair(
314                limits.checksum_policy,
315                bytes[delimiter_index + 1],
316                expected,
317                actual,
318            )
319        } else {
320            None
321        };
322        if expected != actual && !delimiter_checksum_matches && address_repair.is_none() {
323            return DecoderStep::Rejected {
324                error: WireError::Checksum { expected, actual },
325                consumed: delimiter_index + 1,
326                checksum_failure: true,
327            };
328        }
329        if delimiter_checksum_matches {
330            repair = Some(FrameRepair::DelimiterBit);
331        }
332        if let Some(address_repair) = address_repair {
333            repair = Some(address_repair);
334        }
335
336        let address_start = delimiter_index + 1;
337        let address_end = address_start + address_len;
338        let address = match Address::read_from(&bytes[address_start..address_end], long) {
339            Ok(address) => address,
340            Err(error) => {
341                return DecoderStep::Rejected {
342                    error,
343                    consumed: checksum_index + 1,
344                    checksum_failure: false,
345                };
346            }
347        };
348        let Some(kind) = FrameKind::from_delimiter(delimiter) else {
349            return DecoderStep::Rejected {
350                error: WireError::Delimiter(delimiter),
351                consumed: delimiter_index + 1,
352                checksum_failure: false,
353            };
354        };
355        DecoderStep::Frame {
356            frame: Frame {
357                preambles: u8::try_from(preamble_count).unwrap_or(u8::MAX),
358                kind,
359                physical_layer: PhysicalLayer::from_delimiter(delimiter),
360                address,
361                expansion: bytes[address_end..command_index].to_vec(),
362                wire_command: bytes[command_index],
363                payload: bytes[count_index + 1..checksum_index].to_vec(),
364                repair,
365            },
366            consumed: checksum_index + 1,
367            repaired: repair.is_some(),
368        }
369    }
370
371    fn find_candidate(bytes: &[u8], limits: DecodeLimits) -> Option<(usize, usize, usize)> {
372        let minimum_preambles = usize::from(limits.minimum_preambles);
373        bytes.iter().enumerate().find_map(|(index, byte)| {
374            if !Self::is_possible_delimiter(*byte, limits.checksum_policy) {
375                return None;
376            }
377            let preamble_start = bytes[..index]
378                .iter()
379                .rposition(|value| *value != 0xff)
380                .map_or(0, |position| position + 1);
381            let preamble_count = index - preamble_start;
382            let retained_count = preamble_count.min(usize::from(u8::MAX));
383            let retained_start = index - retained_count;
384            (preamble_count >= minimum_preambles).then_some((index, retained_start, retained_count))
385        })
386    }
387
388    fn retain_possible_preambles(&mut self) {
389        let keep = self
390            .bytes
391            .iter()
392            .rev()
393            .take_while(|byte| **byte == 0xff)
394            .count()
395            .min(usize::from(u8::MAX));
396        let discarded = self.bytes.len().saturating_sub(keep);
397        self.discard(discarded);
398    }
399
400    fn discard(&mut self, count: usize) {
401        self.bytes.drain(..count.min(self.bytes.len()));
402        self.statistics.discarded_bytes = self
403            .statistics
404            .discarded_bytes
405            .saturating_add(u64::try_from(count).unwrap_or(u64::MAX));
406    }
407
408    fn is_possible_delimiter(byte: u8, policy: ChecksumPolicy) -> bool {
409        FrameKind::from_delimiter(byte).is_some()
410            || (Self::allow_delimiter_repair(policy)
411                && FrameKind::from_delimiter(byte ^ 0x10).is_some())
412    }
413
414    const fn allow_delimiter_repair(policy: ChecksumPolicy) -> bool {
415        matches!(
416            policy,
417            ChecksumPolicy::KnownGateway {
418                delimiter_bit: true,
419                ..
420            }
421        )
422    }
423
424    fn short_address_repair(
425        policy: ChecksumPolicy,
426        received_address: u8,
427        expected: u8,
428        actual: u8,
429    ) -> Option<FrameRepair> {
430        let ChecksumPolicy::KnownGateway {
431            checksum_source_node: Some(source),
432            ..
433        } = policy
434        else {
435            return None;
436        };
437        if source > 63 {
438            return None;
439        }
440        let reconstructed = received_address ^ expected ^ actual;
441        (reconstructed & 0xc0 == received_address & 0xc0 && reconstructed & 0x3f == source)
442            .then_some(FrameRepair::ShortAddressRewrite {
443                checksum_source_node: source,
444            })
445    }
446}
447
448impl Default for FrameDecoder {
449    fn default() -> Self {
450        Self::new(DecodeLimits::default())
451    }
452}