Skip to main content

sensor_db/
entry.rs

1//! Entry header and CRC computation.
2
3use crc::{CRC_16_IBM_SDLC, CRC_32_ISCSI, Crc};
4use zerocopy::{
5    FromBytes, Immutable, IntoBytes, KnownLayout, Unaligned,
6    little_endian::{U16, U64},
7};
8
9/// Entry marker byte: one sample, the payload stored as given.
10pub const ENTRY_MARKER: u8 = 0xAA;
11
12/// Entry marker byte for a [run](crate::run): many evenly spaced samples under
13/// one header.
14///
15/// A separate marker rather than a flag in the payload, because the marker is
16/// covered by [`header_crc`](EntryHeaderWire::header_crc) and only this crate
17/// writes it. A payload flag could not be trusted: the raw
18/// [`append`](crate::LogSink::append) path stores arbitrary bytes, so any
19/// payload that happened to carry the flag pattern would be read as a run and
20/// hand the sector index an invented time span. Here the question "is this a
21/// run?" is answered structurally, before the payload is looked at.
22pub const ENTRY_MARKER_RUN: u8 = 0xAB;
23
24/// Size of the entry header in bytes (including the trailing header CRC).
25pub const ENTRY_HEADER_SIZE: usize = 16;
26
27/// Number of leading header bytes covered by the integrity CRCs (marker through
28/// payload_len) — i.e. the header excluding its own `header_crc` field.
29pub const ENTRY_HEADER_FIELDS_SIZE: usize = 14;
30
31/// Size of the entry header CRC in bytes.
32pub const ENTRY_HEADER_CRC_SIZE: usize = 2;
33
34/// Size of the CRC-32C trailer in bytes.
35pub const ENTRY_CRC_SIZE: usize = 4;
36
37/// Total overhead per entry (header + trailing CRC).
38pub const ENTRY_OVERHEAD: usize = ENTRY_HEADER_SIZE + ENTRY_CRC_SIZE;
39
40/// Flags byte value for an uncommitted entry (all bits set, NOR flash erased state).
41pub const FLAGS_UNCOMMITTED: u8 = 0xFF;
42
43/// Flags byte value for a committed entry (all bits cleared).
44pub const FLAGS_COMMITTED: u8 = 0x00;
45
46/// CRC-16 used for the entry header integrity field.
47const HEADER_CRC: Crc<u16> = Crc::<u16>::new(&CRC_16_IBM_SDLC);
48
49/// Wire-format entry header for zerocopy serialization.
50///
51/// Layout (16 bytes):
52/// - marker: u8 (0xAA single, 0xAB run)
53/// - flags: u8 (0xFF=uncommitted, 0x00=committed)
54/// - sensor_id: u16 LE
55/// - timestamp: u64 LE
56/// - payload_len: u16 LE
57/// - header_crc: u16 LE (CRC-16 over the preceding 14 bytes, flags masked)
58///
59/// The header CRC lets the scanner reject a false `0xAA` marker structurally —
60/// before trusting `payload_len` to size a read — rather than relying only on
61/// heuristics about the flags and length fields.
62#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned, Clone, Copy)]
63#[repr(C, packed)]
64pub struct EntryHeaderWire {
65    /// Start-of-entry marker: [`ENTRY_MARKER`] for a single sample,
66    /// [`ENTRY_MARKER_RUN`] for a run.
67    pub marker: u8,
68    /// [`FLAGS_UNCOMMITTED`] until the commit pass clears it to
69    /// [`FLAGS_COMMITTED`]. Masked out of both CRCs.
70    pub flags: u8,
71    /// Which sensor produced the entry.
72    pub sensor_id: U16,
73    /// Caller-supplied timestamp; the crate never interprets its epoch or unit.
74    pub timestamp: U64,
75    /// Payload length in bytes, at most `PAGE_SIZE - ENTRY_OVERHEAD`.
76    pub payload_len: U16,
77    /// CRC-16 over the preceding 14 bytes, validated before `payload_len` is
78    /// trusted to size a read.
79    pub header_crc: U16,
80}
81
82impl EntryHeaderWire {
83    /// Create a new entry header with the given parameters.
84    ///
85    /// The flags field is set to `0xFF` (uncommitted). The commit pass
86    /// clears it to `0x00` after the page has been written to flash. The header
87    /// CRC is computed with the flags masked, so it is stable across that flip.
88    pub fn new(sensor_id: u16, timestamp: u64, payload_len: u16) -> Self {
89        Self::with_marker(ENTRY_MARKER, sensor_id, timestamp, payload_len)
90    }
91
92    /// Create a header for a [run](crate::run) entry.
93    ///
94    /// `timestamp` is the *first* sample's; the rest are derived from the
95    /// interval stored in the payload.
96    pub fn new_run(sensor_id: u16, base_timestamp: u64, payload_len: u16) -> Self {
97        Self::with_marker(ENTRY_MARKER_RUN, sensor_id, base_timestamp, payload_len)
98    }
99
100    fn with_marker(marker: u8, sensor_id: u16, timestamp: u64, payload_len: u16) -> Self {
101        let mut header = Self {
102            marker,
103            flags: FLAGS_UNCOMMITTED,
104            sensor_id: U16::new(sensor_id),
105            timestamp: U64::new(timestamp),
106            payload_len: U16::new(payload_len),
107            header_crc: U16::new(0),
108        };
109        header.header_crc = U16::new(header.compute_header_crc());
110        header
111    }
112
113    /// Compute the CRC-16 over the header fields (flags masked to `0xFF`),
114    /// excluding the `header_crc` field itself.
115    pub fn compute_header_crc(&self) -> u16 {
116        let mut bytes = [0u8; ENTRY_HEADER_FIELDS_SIZE];
117        bytes.copy_from_slice(&self.as_bytes()[..ENTRY_HEADER_FIELDS_SIZE]);
118        bytes[1] = FLAGS_UNCOMMITTED; // mask flags so committed/uncommitted match
119        HEADER_CRC.checksum(&bytes)
120    }
121
122    /// Check that the stored header CRC matches the header fields.
123    pub fn header_crc_valid(&self) -> bool {
124        self.header_crc.get() == self.compute_header_crc()
125    }
126
127    /// Check if this header has a valid marker byte, of either kind.
128    pub fn is_valid_marker(&self) -> bool {
129        is_entry_marker(self.marker)
130    }
131
132    /// Whether this entry holds a [run](crate::run) rather than one sample.
133    pub fn is_run(&self) -> bool {
134        self.marker == ENTRY_MARKER_RUN
135    }
136
137    /// Convert to the public API struct.
138    pub fn to_header(&self) -> EntryHeader {
139        EntryHeader {
140            sensor_id: self.sensor_id.get(),
141            timestamp: self.timestamp.get(),
142            payload_len: self.payload_len.get(),
143            kind: if self.is_run() {
144                EntryKind::Run
145            } else {
146                EntryKind::Single
147            },
148        }
149    }
150}
151
152/// Whether `byte` starts an entry of either kind.
153///
154/// The scanners resync a byte at a time on anything that is not an entry, so
155/// this is the one place that says what "an entry starts here" means.
156pub fn is_entry_marker(byte: u8) -> bool {
157    byte == ENTRY_MARKER || byte == ENTRY_MARKER_RUN
158}
159
160/// What a stored entry holds.
161///
162/// Reads never hand out [`Run`](Self::Run): every query, `latest` and `oldest`
163/// expands a run into the samples it holds, each described as a
164/// [`Single`](Self::Single). It surfaces only on the *replication* stream —
165/// [`read_from`](crate::SensorDb::read_from) and the unflushed-tail walks —
166/// which deals in entries, and where the receiving log needs it to store the
167/// entry back as a run rather than as one opaque sample.
168#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
169#[cfg_attr(feature = "defmt", derive(defmt::Format))]
170pub enum EntryKind {
171    /// One sample; the payload is what the caller appended.
172    #[default]
173    Single,
174    /// A [run](crate::run) of evenly spaced samples.
175    Run,
176}
177
178/// Public API entry header (native endianness).
179#[derive(Debug, Clone, Copy, PartialEq, Eq)]
180pub struct EntryHeader {
181    /// Which sensor produced the entry.
182    pub sensor_id: u16,
183    /// The timestamp the entry was appended with.
184    ///
185    /// For a [`Run`](EntryKind::Run) this is the *first* sample's; the rest are
186    /// derived from the interval stored in the payload.
187    pub timestamp: u64,
188    /// Payload length in bytes, excluding the entry header and CRC.
189    pub payload_len: u16,
190    /// Whether the payload is one sample or a run of them.
191    ///
192    /// Always [`Single`](EntryKind::Single) on a read path, which expands runs.
193    pub kind: EntryKind,
194}
195
196impl EntryHeader {
197    /// Whether this entry holds a [run](crate::run) rather than one sample.
198    pub fn is_run(&self) -> bool {
199        matches!(self.kind, EntryKind::Run)
200    }
201}
202
203/// Compute CRC-32C over offset, header (with flags masked), and payload.
204///
205/// Uses CRC-32C (CRC-32/ISCSI), the same algorithm used by btrfs, ext4, and iSCSI.
206/// The `offset_in_sector` is included in the digest to detect entries transplanted
207/// to a different position (e.g. after a partial erase). The flags byte is always
208/// masked to `0xFF` before hashing so that the CRC is identical for both the
209/// uncommitted and committed states.
210pub fn compute_entry_crc(header: &EntryHeaderWire, payload: &[u8], offset_in_sector: u32) -> u32 {
211    const CRC: Crc<u32> = Crc::<u32>::new(&CRC_32_ISCSI);
212    let mut digest = CRC.digest();
213
214    // Include offset-in-sector (not stored on flash, but known during scan)
215    digest.update(&offset_in_sector.to_le_bytes());
216
217    // Include the logical header fields (excluding the header_crc field) with
218    // flags masked to 0xFF
219    let mut header_bytes = [0u8; ENTRY_HEADER_FIELDS_SIZE];
220    header_bytes.copy_from_slice(&header.as_bytes()[..ENTRY_HEADER_FIELDS_SIZE]);
221    header_bytes[1] = FLAGS_UNCOMMITTED; // mask flags
222    digest.update(&header_bytes);
223
224    // Include payload
225    digest.update(payload);
226    digest.finalize()
227}