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}