sensor_db/db.rs
1//! SensorDb implementation.
2//!
3//! Append-only sensor database for NOR flash with circular sector management.
4//!
5//! ## Usage
6//!
7//! ```ignore
8//! use sensor_db::{MockFlash, SensorDb};
9//!
10//! const PAGE: usize = 256;
11//! const SECTOR: usize = 4096;
12//! const SECTORS: usize = 32;
13//!
14//! let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
15//! let mut db: SensorDb<_, PAGE, SECTORS> = SensorDb::new(flash, 0, 32, 2).unwrap();
16//! db.format().unwrap();
17//!
18//! db.append(1, 1000, &[0xAB, 0xCD]).unwrap();
19//! let mut buf = [0u8; 16];
20//! let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
21//! assert_eq!(&buf[..n], &[0xAB, 0xCD]);
22//! ```
23
24use crate::entry::{
25 ENTRY_CRC_SIZE, ENTRY_HEADER_SIZE, ENTRY_OVERHEAD, EntryHeader, EntryHeaderWire, EntryKind,
26 FLAGS_COMMITTED, FLAGS_UNCOMMITTED, compute_entry_crc, is_entry_marker,
27};
28use crate::error::Error;
29use crate::partition::Partition;
30use crate::run::{RUN_FRAME_SIZE, Run, RunFrame, deliver_samples, samples_in};
31use crate::schema;
32use crate::sector::{
33 LogId, SECTOR_FOOTER_SIZE, SECTOR_HEADER_SIZE, SectorClass, SectorFooter, SectorHeader,
34 SectorState, SectorSummary, sensor_id_to_bit,
35};
36use crate::typed::SensorData;
37use embedded_storage::nor_flash::{NorFlash, ReadNorFlash};
38use heapless::Vec as HeaplessVec;
39use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
40
41/// Simple insertion sort for small heapless vectors (no alloc required).
42/// Sorts by the second element of the tuple using the given comparator.
43pub(crate) fn sort_by_seq<const N: usize>(
44 vec: &mut HeaplessVec<(u16, u32), N>,
45 cmp: fn(&u32, &u32) -> core::cmp::Ordering,
46) {
47 for i in 1..vec.len() {
48 let mut j = i;
49 while j > 0 && cmp(&vec[j - 1].1, &vec[j].1) == core::cmp::Ordering::Greater {
50 vec.swap(j - 1, j);
51 j -= 1;
52 }
53 }
54}
55
56/// Statistics about the database state.
57#[derive(Debug, Clone, Copy, Default)]
58#[cfg_attr(feature = "defmt", derive(defmt::Format))]
59pub struct DbStats {
60 /// Total number of valid entries across all sectors.
61 ///
62 /// *Entries*, so a [run](crate::run) counts once however many samples it
63 /// holds. This is what the log wrote and what replication moves;
64 /// [`total_samples`](Self::total_samples) is what a reader sees, and their
65 /// ratio is what run encoding bought.
66 pub total_entries: u32,
67 /// Total number of readable samples across all sectors.
68 ///
69 /// What [`count(None)`](crate::SensorDb::count) reports, and what a query
70 /// over the whole time range yields.
71 pub total_samples: u32,
72 /// Number of sectors currently in use (active or sealed).
73 pub used_sectors: u16,
74 /// Number of erased sectors available.
75 pub free_sectors: u16,
76 /// Number of reserved sectors for headroom.
77 pub reserved_sectors: u16,
78 /// Minimum erase count across all sectors.
79 pub min_erase_count: u32,
80 /// Maximum erase count across all sectors.
81 pub max_erase_count: u32,
82 /// Total erase count summed across all sectors.
83 pub total_erase_count: u64,
84}
85
86/// Geometry and identity of a database region.
87///
88/// Validated once, here, so everything downstream receives a configuration that
89/// is already known-good.
90///
91/// ```
92/// use sensor_db::db::DbConfig;
93/// use sensor_db::sector::LogId;
94///
95/// let config = DbConfig::new(0, 8, 1)?
96/// .with_log_id(LogId::new(0xC0FFEE).unwrap());
97/// # Ok::<(), sensor_db::Error>(())
98/// ```
99#[derive(Debug, Clone, Copy, PartialEq, Eq)]
100#[cfg_attr(feature = "defmt", derive(defmt::Format))]
101pub struct DbConfig {
102 base_offset: u32,
103 sector_count: u16,
104 reserved_sectors: u16,
105 log_id: Option<LogId>,
106}
107
108impl DbConfig {
109 /// Describe a database region.
110 ///
111 /// # Arguments
112 /// - `base_offset`: starting byte offset of the region in flash
113 /// - `sector_count`: number of erase sectors the region spans
114 /// - `reserved_sectors`: sectors kept free as compaction headroom
115 ///
116 /// # Errors
117 /// - `InvalidConfig` if `reserved_sectors >= sector_count`
118 pub fn new(base_offset: u32, sector_count: u16, reserved_sectors: u16) -> Result<Self, Error> {
119 if reserved_sectors >= sector_count {
120 return Err(Error::InvalidConfig);
121 }
122 Ok(Self {
123 base_offset,
124 sector_count,
125 reserved_sectors,
126 log_id: None,
127 })
128 }
129
130 /// Declare this database's logical identity.
131 ///
132 /// The id is written into every sector header, and mounting a medium whose
133 /// sectors carry a *different* id fails with
134 /// [`Error::ForeignVolume`] instead of treating them as free space. Set this
135 /// on any database whose storage can be swapped between devices.
136 pub fn with_log_id(mut self, log_id: LogId) -> Self {
137 self.log_id = Some(log_id);
138 self
139 }
140
141 /// Starting byte offset of the region.
142 pub fn base_offset(&self) -> u32 {
143 self.base_offset
144 }
145
146 /// Number of erase sectors in the region.
147 pub fn sector_count(&self) -> u16 {
148 self.sector_count
149 }
150
151 /// Sectors kept free as compaction headroom.
152 pub fn reserved_sectors(&self) -> u16 {
153 self.reserved_sectors
154 }
155
156 /// Declared logical identity, if any.
157 pub fn log_id(&self) -> Option<LogId> {
158 self.log_id
159 }
160}
161
162/// Which sealed sectors [`SensorDb::compact`] may erase.
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
164#[cfg_attr(feature = "defmt", derive(defmt::Format))]
165pub enum CompactScope {
166 /// Every sealed sector is eligible, oldest first, replicated or not.
167 #[default]
168 All,
169 /// Only sealed sectors whose contents are fully replicated elsewhere.
170 ///
171 /// Reclaims space without ever destroying data that has not been copied off
172 /// the device. Erases nothing until a replica has acknowledged something —
173 /// on a log with no replica this is always a no-op.
174 SpooledOnly,
175}
176
177/// How much of the log to index when mounting.
178#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
179#[cfg_attr(feature = "defmt", derive(defmt::Format))]
180pub enum MountMode {
181 /// Rebuild the full index — entry counts, timestamp ranges and bloom
182 /// filters — reading each sealed sector's
183 /// [`SectorFooter`] where one is present and
184 /// valid, and scanning the sector body only where it is not.
185 ///
186 /// Required for reads, and the default. Cost is one page read per sealed
187 /// sector, so it is proportional to the *sector count* on a log this build
188 /// wrote. It falls back to a body scan — proportional to the data stored —
189 /// for the sector a crashed run left active, and for any sector whose footer
190 /// is missing or fails to validate.
191 ///
192 /// Because a footer records what was written rather than what is still
193 /// readable, this mode does not re-verify sealed entries and therefore
194 /// reports no [`corrupt_entries`](MountStats::corrupt_entries) for the
195 /// sectors it took from a footer. Reads are unaffected: every entry a query
196 /// returns is CRC-checked when it is read. Use [`Verify`](Self::Verify) to
197 /// check the whole medium at mount instead.
198 #[default]
199 Full,
200 /// Scan every entry of every valid sector, ignoring footers.
201 ///
202 /// Identical to [`Full`](Self::Full) in what it produces, and the only mode
203 /// that re-verifies stored data at mount: the index is built from entries
204 /// whose CRCs pass *now*, and
205 /// [`corrupt_entries`](MountStats::corrupt_entries) counts the rest. Cost is
206 /// proportional to the data stored, so a large nearly-full medium can take
207 /// seconds on a slow bus.
208 ///
209 /// This is what `Full` did before sectors carried footers.
210 Verify,
211 /// Read sector headers only, plus a full scan of the single highest-sequence
212 /// sector so appends can resume at the right offset.
213 ///
214 /// Bloom filters, per-sector entry counts and timestamp ranges are not
215 /// rebuilt, so [`latest`](SensorDb::latest), [`oldest`](SensorDb::oldest),
216 /// [`count`](SensorDb::count) and [`query_range`](SensorDb::query_range)
217 /// return [`Error::ReadsUnavailable`]. Streaming via
218 /// [`read_from`](SensorDb::read_from) still works.
219 ///
220 /// Now that sealed sectors carry footers, [`Full`](Self::Full) costs one
221 /// page read per sector where this costs one header read, so the gap is
222 /// small on a log this build wrote. What `HeadersOnly` still guarantees is
223 /// that the cost is `O(sector_count)` *unconditionally* — it never falls
224 /// back to a body scan, whatever state the medium is in. That is the reason
225 /// to keep reaching for it on a write-only replica read elsewhere.
226 HeadersOnly,
227}
228
229/// Replication accounting for a log.
230///
231/// Returned by [`SensorDb::spool_stats`]. Kept separate from [`DbStats`], which
232/// describes the sector index and means the same thing whether or not anything
233/// is replicating this log.
234#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
235#[cfg_attr(feature = "defmt", derive(defmt::Format))]
236pub struct SpoolStats {
237 /// Durable entries not yet known to be replicated elsewhere.
238 ///
239 /// Entries, which is the unit a spool pass moves and its
240 /// [budget](crate::SpoolBudget) is denominated in. For "how many readings
241 /// are still only here", see
242 /// [`unspooled_samples`](Self::unspooled_samples).
243 pub unspooled_entries: u32,
244 /// Durable *samples* not yet known to be replicated elsewhere.
245 ///
246 /// Larger than [`unspooled_entries`](Self::unspooled_entries) when the
247 /// un-replicated tail holds [runs](crate::run).
248 pub unspooled_samples: u32,
249 /// Everything strictly before this position is durably replicated.
250 pub watermark: LogPosition,
251 /// Position after the newest entry.
252 pub head: LogPosition,
253 /// Entries the ring overwrote before they could be replicated.
254 ///
255 /// Counted against the watermark *as it stood at the time of the eviction*.
256 /// Because [`mount`](SensorDb::mount) starts every run with the watermark at
257 /// [`LogPosition::BEGINNING`], data overwritten before a replica reappears
258 /// and calls [`restore_spool_watermark`](SensorDb::restore_spool_watermark)
259 /// is counted here even if a replica already had it. Attach early in boot,
260 /// or seed the watermark from wherever the application stashed it.
261 pub dropped_unspooled: u32,
262 /// Sticky: set once any un-replicated data has been overwritten, never
263 /// cleared. Surface this to the operator — it means data may have been lost.
264 ///
265 /// On a log that never replicates, *everything* is un-replicated, so this
266 /// becomes true the first time the ring wraps. That is accurate but rarely
267 /// interesting: `SpoolStats` is only meaningful for a log with a replica.
268 pub data_lost: bool,
269}
270
271/// How much one replication step carried, in both units the accounting needs.
272///
273/// A pair rather than two arguments because they are trivially transposable and
274/// a swap would be silent: entries drive the eviction and budget arithmetic,
275/// samples drive `count`.
276#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
277#[cfg_attr(feature = "defmt", derive(defmt::Format))]
278pub struct Replicated {
279 /// Entries copied.
280 pub entries: u32,
281 /// Samples those entries hold; equal to `entries` unless runs were copied.
282 pub samples: u32,
283}
284
285impl Replicated {
286 /// Nothing carried.
287 pub const NONE: Self = Self {
288 entries: 0,
289 samples: 0,
290 };
291
292 /// `n` entries holding one sample each — what a log with no runs in it
293 /// carries, and the shape a caller driving replication by hand usually has.
294 pub const fn singles(n: u32) -> Self {
295 Self {
296 entries: n,
297 samples: n,
298 }
299 }
300
301 /// Record one more entry holding `samples` samples.
302 pub fn push(&mut self, samples: u32) {
303 self.entries = self.entries.saturating_add(1);
304 self.samples = self.samples.saturating_add(samples);
305 }
306}
307
308/// A position in the log: sector sequence plus byte offset within that sector.
309///
310/// Sequence numbers are monotonic for the lifetime of a database, so ordering
311/// `LogPosition` lexicographically — which is what the derived `Ord` does — is
312/// exactly log order. This is the coordinate system used to resume a replication
313/// stream across reboots and across removals of the destination medium.
314///
315/// A position is *not* portable between databases: sequence numbers are
316/// allocated per database, so a position from one log means nothing in another.
317#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default, Hash)]
318#[cfg_attr(feature = "defmt", derive(defmt::Format))]
319pub struct LogPosition {
320 /// Sequence number of the sector this position falls in.
321 pub sequence: u32,
322 /// Byte offset within that sector.
323 pub offset: u32,
324}
325
326impl LogPosition {
327 /// A position before every entry the log has ever held.
328 ///
329 /// Real sector sequences start at 1, so sequence 0 is an unambiguous
330 /// sentinel. Reading from `BEGINNING` yields whatever the log still
331 /// retains, and never reports a gap.
332 pub const BEGINNING: Self = Self {
333 sequence: 0,
334 offset: 0,
335 };
336}
337
338/// Outcome of a [`SensorDb::read_from`] pass.
339#[derive(Debug, Clone, Copy, PartialEq, Eq)]
340#[cfg_attr(feature = "defmt", derive(defmt::Format))]
341pub struct ReadCursor {
342 /// Position immediately after the last entry delivered — pass this back as
343 /// `from` to continue where this pass stopped.
344 pub next: LogPosition,
345 /// Number of entries delivered to the callback in this pass.
346 pub entries: u32,
347 /// No further durable entries exist after [`next`](Self::next).
348 ///
349 /// False when the pass stopped because it hit `max_entries` or because the
350 /// callback asked to stop.
351 pub exhausted: bool,
352 /// The requested `from` had already fallen off the tail of the ring, so
353 /// entries between it and the oldest retained sector were skipped.
354 ///
355 /// This is not an error: it is the expected consequence of the log wrapping
356 /// while a replication target was unavailable.
357 pub gap: bool,
358}
359
360/// Statistics returned after mounting.
361#[derive(Debug, Clone, Copy, Default)]
362#[cfg_attr(feature = "defmt", derive(defmt::Format))]
363pub struct MountStats {
364 /// Total entries found during scan.
365 pub total_entries: u32,
366 /// Total readable samples found during scan, which exceeds
367 /// [`total_entries`](Self::total_entries) by what the log's
368 /// [runs](crate::run) hold.
369 pub total_samples: u32,
370 /// Number of sealed sectors found.
371 pub sealed_sectors: u16,
372 /// Number of corrupt entries skipped.
373 ///
374 /// Only sectors this mount actually read end to end can contribute: a
375 /// sector indexed from its [`SectorFooter`] is
376 /// not re-verified. See [`MountMode::Full`] and [`MountMode::Verify`].
377 pub corrupt_entries: u32,
378 /// Sector bodies this mount read end to end, rather than indexing from a
379 /// footer or skipping.
380 ///
381 /// This is the number that says what the footers bought: it is the mount
382 /// cost that scales with *data stored* instead of with sector count. On a
383 /// medium written entirely by this build it is 1 — the sector the last run
384 /// left active.
385 pub scanned_sectors: u16,
386}
387
388/// A parsed entry returned by [`SectorScanner`] (and its async twin).
389pub(crate) struct ScannedEntry {
390 /// The wire-format header.
391 pub(crate) header: EntryHeaderWire,
392 /// Byte offset of this entry within the sector.
393 pub(crate) offset_in_sector: u32,
394 /// Payload length in bytes.
395 pub(crate) payload_len: usize,
396 /// Total entry size (header + payload + CRC).
397 pub(crate) entry_size: u32,
398}
399
400impl ScannedEntry {
401 /// Whether this entry holds a [run](crate::run).
402 pub(crate) fn is_run(&self) -> bool {
403 self.header.is_run()
404 }
405
406 /// The sensor id, which every sample of a run shares.
407 pub(crate) fn sensor_id(&self) -> u16 {
408 self.header.sensor_id.get()
409 }
410
411 /// The header timestamp, which for a run is its *first* sample's.
412 pub(crate) fn timestamp(&self) -> u64 {
413 self.header.timestamp.get()
414 }
415}
416
417/// One whole entry found in the RAM page buffer.
418struct BufferedEntry {
419 header: EntryHeaderWire,
420 payload_start: usize,
421 payload_len: usize,
422}
423
424/// Which end of an entry a single-entry read wants: for a run, its first or its
425/// last sample, which are its oldest and newest.
426#[derive(Clone, Copy)]
427pub(crate) enum Edge {
428 First,
429 Last,
430}
431
432/// One chosen sample, located in the page buffer and not yet framed.
433///
434/// `latest` picks a winner across the whole buffer and copies once, so the
435/// choice and the copy have to be separable.
436#[derive(Clone, Copy)]
437struct BufferedSample {
438 payload_start: usize,
439 payload_len: usize,
440 /// The run this sample came from, and which sample it is. `None` for a
441 /// single-sample entry, whose payload is already exactly what to hand back.
442 run: Option<(RunFrame, u32)>,
443}
444
445impl BufferedEntry {
446 fn is_committed(&self) -> bool {
447 self.header.flags == FLAGS_COMMITTED
448 }
449
450 fn is_run(&self) -> bool {
451 self.header.is_run()
452 }
453
454 fn sensor_id(&self) -> u16 {
455 self.header.sensor_id.get()
456 }
457
458 fn timestamp(&self) -> u64 {
459 self.header.timestamp.get()
460 }
461}
462
463/// What a body scan learned about one sector.
464///
465/// Exactly the fields a [`SectorFooter`] carries, which is the point: mount
466/// takes whichever is available and nothing downstream can tell which.
467#[derive(Debug, Clone, Copy)]
468pub(crate) struct ScannedSector {
469 pub(crate) entries: u32,
470 pub(crate) samples: u32,
471 pub(crate) write_offset: u32,
472 pub(crate) min_timestamp: u64,
473 pub(crate) max_timestamp: u64,
474 pub(crate) sensor_bloom: u64,
475}
476
477impl ScannedSector {
478 /// A sector with nothing in it, with the bounds inverted so the first entry
479 /// scanned sets both.
480 pub(crate) const EMPTY: Self = Self {
481 entries: 0,
482 samples: 0,
483 write_offset: 0,
484 min_timestamp: u64::MAX,
485 max_timestamp: 0,
486 sensor_bloom: 0,
487 };
488
489 /// Fold one accepted entry into the running scan.
490 ///
491 /// Pure, and shared by both drivers: a run reaches past its header
492 /// timestamp, and the index has to know it — otherwise a query for the run's
493 /// tail prunes away the very sector the run lives in.
494 pub(crate) fn record(&mut self, entry: &ScannedEntry, payload: &[u8]) {
495 let base = entry.timestamp();
496 let span_end = match RunFrame::parse(payload).filter(|_| entry.is_run()) {
497 Some(frame) => {
498 self.samples += frame.count();
499 frame.span_end(base)
500 }
501 None => {
502 self.samples += 1;
503 base
504 }
505 };
506
507 self.entries += 1;
508 self.min_timestamp = self.min_timestamp.min(base);
509 self.max_timestamp = self.max_timestamp.max(span_end);
510 self.sensor_bloom |= sensor_id_to_bit(entry.sensor_id());
511 }
512
513 /// Copy the scan's findings into `summary`, leaving `state`, `sequence` and
514 /// `erase_count` — which come from the sector *header* — alone.
515 pub(crate) fn apply_to(&self, summary: &mut SectorSummary) {
516 summary.entry_count = self.entries;
517 summary.sample_count = self.samples;
518 summary.write_offset = self.write_offset;
519 summary.min_timestamp = self.min_timestamp;
520 summary.max_timestamp = self.max_timestamp;
521 summary.sensor_bloom = self.sensor_bloom;
522 }
523}
524
525/// What a [`SectorScanner`] needs next, or what it found.
526///
527/// This is the whole reason the scanner is I/O-free: the decisions it makes —
528/// where to resume after a bad byte, when an erased region ends the scan, which
529/// headers to reject before their `payload_len` is trusted — are identical for
530/// the blocking and async drivers, and a sector walked differently by two of
531/// them is exactly how `count` and `query_range` came to disagree once before.
532/// Stating the decisions once and letting each driver supply only the read is
533/// what makes that class of drift impossible rather than merely tested for.
534pub(crate) enum Scan {
535 /// Read [`ENTRY_HEADER_SIZE`] bytes at this **absolute** flash address, then
536 /// hand them to [`SectorScanner::feed`].
537 Read(u32),
538 /// A committed entry, at the scanner's current offset.
539 Found(ScannedEntry),
540 /// The sector is exhausted.
541 Done,
542}
543
544/// Stateful, I/O-free cursor that walks committed entry headers within a single
545/// sector.
546///
547/// Drive it with [`begin`](Self::begin) and [`feed`](Self::feed); each driver
548/// wraps those in a small loop that performs the reads
549/// ([`SectorScanner::next_entry`] here, its `.await`ing twin in
550/// [`async_db`](crate::async_db)).
551pub(crate) struct SectorScanner {
552 /// Absolute flash address of the sector start.
553 sector_offset: u32,
554 /// Current read position (relative to sector start).
555 offset: u32,
556 /// Upper bound for scanning (typically `write_offset` or `sector_size`).
557 limit: u32,
558 /// Number of corrupt/invalid bytes skipped.
559 pub(crate) corrupt_count: u32,
560}
561
562impl SectorScanner {
563 pub(crate) fn new(sector_offset: u32, entry_start: u32, limit: u32) -> Self {
564 Self {
565 sector_offset,
566 offset: entry_start,
567 limit,
568 corrupt_count: 0,
569 }
570 }
571
572 /// Current byte offset within the sector.
573 pub(crate) fn offset(&self) -> u32 {
574 self.offset
575 }
576
577 /// Number of corrupt/invalid bytes encountered so far.
578 pub(crate) fn corrupt_count(&self) -> u32 {
579 self.corrupt_count
580 }
581
582 /// Advance past an entry of the given size.
583 pub(crate) fn skip(&mut self, entry_size: u32) {
584 self.offset += entry_size;
585 }
586
587 /// What to read next from the current position, or `Done` if no entry can
588 /// still fit before the limit.
589 pub(crate) fn begin(&self) -> Scan {
590 if self.offset + ENTRY_OVERHEAD as u32 > self.limit {
591 return Scan::Done;
592 }
593 Scan::Read(self.sector_offset + self.offset)
594 }
595
596 /// Interpret the header bytes just read, and say what comes next.
597 ///
598 /// Skips erased regions (jumping to the next page boundary) and uncommitted
599 /// entries, and resyncs one byte forward past anything that does not parse.
600 pub(crate) fn feed(&mut self, header_buf: &[u8; ENTRY_HEADER_SIZE], page_size: usize) -> Scan {
601 // Erased area — skip to next page boundary
602 if header_buf[0] == 0xFF {
603 let next_page = ((self.offset as usize / page_size) + 1) * page_size;
604 if next_page as u32 + ENTRY_OVERHEAD as u32 > self.limit {
605 return Scan::Done;
606 }
607 self.offset = next_page as u32;
608 return self.begin();
609 }
610
611 // Not a valid marker — skip one byte
612 if !is_entry_marker(header_buf[0]) {
613 return self.resync();
614 }
615
616 let Ok(header) = EntryHeaderWire::read_from_bytes(&header_buf[..]) else {
617 return self.resync();
618 };
619
620 let payload_len = header.payload_len.get() as usize;
621
622 // Validate the header before trusting its length. The marker byte
623 // (0xAA) occurs naturally inside payload data, so matching it alone is
624 // not enough: without validation a false marker yields a garbage
625 // `payload_len` that desyncs the scan and — via `accept_entry` —
626 // slices a fixed buffer out of bounds. We reject on three grounds, in
627 // increasing cost: `flags` must be exactly COMMITTED or UNCOMMITTED
628 // (the header CRC masks flags, so it cannot vouch for them); the
629 // payload must fit within a page (defends against a CRC collision that
630 // still yields an impossible length); and the header CRC must match,
631 // which rejects false markers structurally rather than heuristically.
632 // On any failure, treat it as a stray byte and resync one byte forward.
633 let max_payload = page_size.saturating_sub(ENTRY_OVERHEAD);
634 if (header.flags != FLAGS_COMMITTED && header.flags != FLAGS_UNCOMMITTED)
635 || payload_len > max_payload
636 || !header.header_crc_valid()
637 {
638 return self.resync();
639 }
640
641 let entry_size = (ENTRY_OVERHEAD + payload_len) as u32;
642
643 if self.offset + entry_size > self.limit {
644 return Scan::Done;
645 }
646
647 // Skip uncommitted entries (power loss before commit)
648 if header.flags != FLAGS_COMMITTED {
649 self.offset += entry_size;
650 return self.begin();
651 }
652
653 Scan::Found(ScannedEntry {
654 header,
655 offset_in_sector: self.offset,
656 payload_len,
657 entry_size,
658 })
659 }
660
661 /// Count a bad byte and step over it.
662 fn resync(&mut self) -> Scan {
663 self.corrupt_count += 1;
664 self.offset += 1;
665 self.begin()
666 }
667
668 /// Read the next committed entry header from flash.
669 ///
670 /// The blocking driver's loop over [`begin`](Self::begin) and
671 /// [`feed`](Self::feed) — everything it decides lives there, so this is only
672 /// the read.
673 fn next_entry<F: ReadNorFlash>(
674 &mut self,
675 flash: &mut F,
676 header_buf: &mut [u8; ENTRY_HEADER_SIZE],
677 page_size: usize,
678 ) -> Result<Option<ScannedEntry>, Error> {
679 let mut step = self.begin();
680 loop {
681 match step {
682 Scan::Done => return Ok(None),
683 Scan::Found(entry) => return Ok(Some(entry)),
684 Scan::Read(addr) => {
685 flash.read(addr, &mut header_buf[..])?;
686 step = self.feed(header_buf, page_size);
687 }
688 }
689 }
690 }
691}
692
693/// Whether an entry's stored bytes are the ones that were written.
694///
695/// Two tests, and every scan applies both so that they all walk a sector
696/// identically — `count` and `query_range` disagreeing about how many entries
697/// exist is a defect, not an optimisation:
698///
699/// - the entry CRC must match, which is what says these bytes are the ones that
700/// were written;
701/// - a *run* must additionally carry a well-formed [`RunFrame`], because the
702/// scans downstream index by its sample count and span. Only a writer this
703/// crate does not have could produce a run that fails this, so it is a
704/// structural backstop rather than a case that arises — and rejecting it here
705/// means every caller handles it by the resync it already performs for a bad
706/// CRC.
707impl ScannedEntry {
708 /// The header and payload of this entry's first or last sample.
709 ///
710 /// For an ordinary entry both edges are the entry itself. For a run they are
711 /// its first and last samples — which are its oldest and newest, because the
712 /// interval is unsigned and a run's timestamps therefore never decrease.
713 ///
714 /// Shared by `latest` and `oldest` in both drivers, so the run/single
715 /// distinction is drawn once rather than in four places.
716 pub(crate) fn edge<'a>(&self, payload: &'a mut [u8], edge: Edge) -> (EntryHeader, &'a [u8]) {
717 // `RunFrame` borrows nothing, so the immutable parse ends before
718 // `tagged_sample` takes the buffer mutably.
719 match RunFrame::parse(payload).filter(|_| self.is_run()) {
720 Some(frame) => {
721 let index = match edge {
722 Edge::First => 0,
723 Edge::Last => frame.count() - 1,
724 };
725 (
726 frame.header_at(self.sensor_id(), self.timestamp(), index),
727 frame.tagged_sample(payload, index),
728 )
729 }
730 None => (self.header.to_header(), payload),
731 }
732 }
733
734 /// Where this entry's payload and CRC live, and how many bytes that is.
735 ///
736 /// Absolute address, so a driver can read it without knowing the layout.
737 pub(crate) fn payload_read(&self, sector_offset: u32) -> (u32, usize) {
738 (
739 sector_offset + self.offset_in_sector + ENTRY_HEADER_SIZE as u32,
740 self.payload_len + ENTRY_CRC_SIZE,
741 )
742 }
743
744 /// Verify the bytes [`payload_read`](Self::payload_read) asked for.
745 ///
746 /// `buf` holds `payload_len` payload bytes followed by the stored CRC.
747 pub(crate) fn accept(&self, buf: &[u8]) -> bool {
748 let stored_crc = u32::from_le_bytes([
749 buf[self.payload_len],
750 buf[self.payload_len + 1],
751 buf[self.payload_len + 2],
752 buf[self.payload_len + 3],
753 ]);
754 let computed_crc = compute_entry_crc(
755 &self.header,
756 &buf[..self.payload_len],
757 self.offset_in_sector,
758 );
759
760 if stored_crc != computed_crc {
761 return false;
762 }
763
764 !self.is_run() || RunFrame::parse(&buf[..self.payload_len]).is_some()
765 }
766}
767
768/// Read an entry's payload into `buf` and decide whether to accept it.
769///
770/// The blocking driver's read around [`ScannedEntry::accept`]; the async driver
771/// has the same four lines with an `.await`.
772///
773/// On success returns `true` and `buf[..entry.payload_len]` holds the payload.
774fn accept_entry<F: ReadNorFlash>(
775 flash: &mut F,
776 sector_offset: u32,
777 entry: &ScannedEntry,
778 buf: &mut [u8],
779) -> Result<bool, Error> {
780 let (addr, read_len) = entry.payload_read(sector_offset);
781 // Defensive: never slice past the caller's buffer on a malformed entry.
782 // The scanner already bounds `payload_len` to a page, but treat an
783 // oversized length as a CRC failure rather than panicking.
784 if read_len > buf.len() {
785 return Ok(false);
786 }
787 flash.read(addr, &mut buf[..read_len])?;
788 Ok(entry.accept(buf))
789}
790
791/// What a seal has decided, between the parts of it that touch flash.
792///
793/// [`begin_seal`](SensorDbState::begin_seal) produces it, the driver performs
794/// the erase and the header write, and
795/// [`finish_seal`](SensorDbState::finish_seal) consumes it — so the sequencing
796/// is the only thing each driver states for itself.
797pub(crate) struct SealPlan {
798 /// The sector being erased and made active.
799 pub(crate) new_active: u16,
800 /// Its erase count after this erase, carried over from the victim.
801 pub(crate) erase_count: u32,
802 /// The victim as it stood before the erase, for eviction accounting.
803 victim: SectorSummary,
804}
805
806/// What has to happen on flash before an entry can be staged.
807///
808/// [`plan_append`](SensorDbState::plan_append) decides; each driver's loop only
809/// performs. The decision is subtle enough to be worth stating once: an entry
810/// never spans a page, sealing does *not* hand back an empty page (page 0
811/// carries the 28-byte sector header), and a maximum-size entry therefore has to
812/// start on page 1 — which is why the driver loops rather than checking once.
813/// Checking once wrote such an entry at offset `SECTOR_HEADER_SIZE` of a
814/// `PAGE_SIZE` buffer and panicked on the slice index, reachable from a plain
815/// `append` of exactly the documented maximum payload.
816pub(crate) enum AppendStep {
817 /// There is room — call [`stage_entry`](SensorDbState::stage_entry).
818 Stage,
819 /// Close the current page, then ask again.
820 FlushPage,
821 /// Seal the active sector and advance, then ask again.
822 Seal,
823}
824
825/// Internal state of the sensor database (everything except the flash device).
826///
827/// Separated from [`SensorDb`] so a method can borrow `flash` and `state`
828/// disjointly — the flash-touching helpers take `&mut F` alongside `&mut self`,
829/// which the borrow checker only permits across two fields.
830///
831/// Shared verbatim with [`SensorDbAsync`](crate::SensorDbAsync), and it holds
832/// the **logic**, not merely the fields.
833///
834/// `embedded-storage` and `embedded-storage-async` are unrelated trait families,
835/// so the async driver cannot call a helper that takes a sync `&mut F`. It used
836/// to answer that by reimplementing the algorithm — 80% of `async_db.rs` was a
837/// line-for-line copy — which is worse than it sounds: the async test suite is
838/// largely byte-for-byte *parity* assertions against the blocking driver, so a
839/// defect present in both is invisible to it by construction.
840///
841/// So each flash-touching operation is split: the decisions live here, pure, and
842/// each driver contributes only the reads and writes between them. `flush_page`
843/// is [`commit_target`](Self::commit_target) →
844/// [`mark_page_committed`](Self::mark_page_committed) →
845/// [`advance_page`](Self::advance_page) with two writes interleaved;
846/// `seal_and_advance` is [`sealing`](Self::sealing) →
847/// [`begin_seal`](Self::begin_seal) → [`account_seal`](Self::account_seal) →
848/// [`finish_seal`](Self::finish_seal); `append_entry` is a loop over
849/// [`plan_append`](Self::plan_append) ending in
850/// [`stage_entry`](Self::stage_entry); and the scan itself is
851/// [`SectorScanner::feed`].
852///
853/// **A driver method that is more than I/O choreography belongs here instead.**
854pub(crate) struct SensorDbState<const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
855 pub(crate) base_offset: u32,
856 pub(crate) sector_count: u16,
857 pub(crate) reserved_sectors: u16,
858 pub(crate) sector_size: u32,
859 pub(crate) sectors: [SectorSummary; MAX_SECTORS],
860 pub(crate) active_sector: Option<u16>,
861 pub(crate) page_buf: [u8; PAGE_SIZE],
862 pub(crate) page_buf_offset: usize,
863 /// Bytes of `page_buf` below this offset are already durable on flash.
864 ///
865 /// Non-zero only after a `mount` that adopted a partially filled page: every
866 /// successful flush empties the buffer. This — not the flags byte — is what
867 /// says whether a buffered entry is safe on flash. `flush_page` flips flags
868 /// to committed *in RAM* before writing them, so a failed commit pass leaves
869 /// the buffer claiming a durability that flash does not have.
870 pub(crate) page_buf_durable: usize,
871 pub(crate) page_flash_offset: u32,
872 pub(crate) mounted: bool,
873 pub(crate) next_sequence: u32,
874 /// Valid entries the ring holds — the unit replication and eviction work in.
875 pub(crate) total_entries: u32,
876 /// Readable samples the ring holds, which exceeds `total_entries` by what
877 /// its [runs](crate::run) hold.
878 ///
879 /// Kept alongside rather than replacing it because the two answer different
880 /// questions: a spool pass moves *entries* and its budget is in entries,
881 /// while `count` and `query_range` speak in samples. Collapsing them would
882 /// make one of the two silently wrong the moment a run is written.
883 pub(crate) total_samples: u32,
884 /// Declared identity of this log, written into every sector header.
885 pub(crate) log_id: Option<LogId>,
886 /// Incremented once per mount; disambiguates boot-relative timestamps.
887 pub(crate) epoch: u32,
888 /// This run adopted a sector an earlier run created, so its epoch is not yet
889 /// recorded anywhere on the medium.
890 ///
891 /// Cleared by rolling to a fresh sector, which stamps it. Deferred to the
892 /// first append so that a run which only reads costs nothing.
893 pub(crate) epoch_pending: bool,
894 /// How much of the index this mount rebuilt.
895 pub(crate) mount_mode: MountMode,
896 /// Everything strictly before this position is durably replicated elsewhere.
897 ///
898 /// Not persisted here: the replica is the source of truth, and it restores
899 /// this via [`SensorDb::restore_spool_watermark`] when it reappears. That is
900 /// what lets two media be rotated against one log with no local state.
901 pub(crate) spool_watermark: LogPosition,
902 /// Entries counted as replicated, mirroring `total_entries` accounting.
903 pub(crate) spooled_entries: u32,
904 /// Samples counted as replicated, mirroring `total_samples` accounting.
905 ///
906 /// The pair moves together everywhere `spooled_entries` does, because a
907 /// tiered `count` needs "how many samples are *not* yet on the card" and
908 /// the entry figure cannot answer it once runs exist.
909 pub(crate) spooled_samples: u32,
910 /// Entries the ring overwrote before they could be replicated.
911 pub(crate) dropped_unspooled: u32,
912 /// Sector erases this instance has performed, saturating.
913 ///
914 /// An erase costs 100 ms or more on many NOR parts, against microseconds for
915 /// a page write, so it is the one operation whose latency a caller may need
916 /// to see. Counted here rather than derived from the per-sector erase counts
917 /// in [`DbStats`] because those are a *wear* history that survives remounts
918 /// and says nothing about when the erases happened.
919 pub(crate) sectors_erased: u32,
920}
921
922/// Compile-time check that a driver's write granularity divides `PAGE_SIZE`.
923///
924/// The database writes a page at a time, so a `PAGE_SIZE` the driver cannot
925/// express as a whole number of writes fails at the first flush with
926/// `NotAligned` — a geometry mistake reported as a runtime I/O error, on a
927/// device, long after the type that caused it was chosen.
928///
929/// The check is a *multiple*, not equality, because `embedded-storage`'s
930/// `WRITE_SIZE` is the minimum write **granularity** and not the program-page
931/// size: several HALs report 1, which divides every `PAGE_SIZE`. The other half
932/// of the contract — that `PAGE_SIZE` not exceed the part's physical program
933/// page — cannot be checked here, because the trait does not carry it.
934///
935/// An associated const rather than a bare `const` block, which cannot name the
936/// generic parameters it would need. Instantiating it in a constructor is what
937/// forces evaluation.
938pub(crate) struct Geometry<F: ?Sized, const PAGE_SIZE: usize>(core::marker::PhantomData<F>);
939
940impl<F: NorFlash + ?Sized, const PAGE_SIZE: usize> Geometry<F, PAGE_SIZE> {
941 /// Fails the build when `PAGE_SIZE` is not a whole number of writes.
942 pub(crate) const PAGE_IS_WRITABLE: () = assert!(
943 PAGE_SIZE.is_multiple_of(F::WRITE_SIZE),
944 "PAGE_SIZE must be a multiple of the flash driver's WRITE_SIZE",
945 );
946}
947
948impl<const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbState<PAGE_SIZE, MAX_SECTORS> {
949 /// Validate the geometry and build the initial (unmounted) state.
950 ///
951 /// Shared by both `SensorDb::new` and `SensorDbAsync::new` so the geometry
952 /// rules are stated exactly once.
953 ///
954 /// # Errors
955 /// - `TooManySectors` if `sector_count > MAX_SECTORS`
956 /// - `InvalidConfig` if a sector is smaller than three pages
957 /// - `Overflow` if the region does not fit in a `u32` address space
958 pub(crate) fn new(config: DbConfig, sector_size: u32) -> Result<Self, Error> {
959 if config.sector_count as usize > MAX_SECTORS {
960 return Err(Error::TooManySectors);
961 }
962
963 // Page 0 carries the sector header, the last page carries the footer,
964 // and an entry of the documented maximum payload needs a whole page to
965 // itself. Below three pages a sector could be initialised and then have
966 // nowhere to put a legal entry, which `append` could only report as
967 // `PayloadTooLarge` — a geometry mistake dressed up as a call mistake.
968 if sector_size < 3 * PAGE_SIZE as u32 {
969 return Err(Error::InvalidConfig);
970 }
971
972 let total_size = (config.sector_count as u32)
973 .checked_mul(sector_size)
974 .ok_or(Error::Overflow)?;
975 config
976 .base_offset
977 .checked_add(total_size)
978 .ok_or(Error::Overflow)?;
979
980 Ok(Self {
981 base_offset: config.base_offset,
982 sector_count: config.sector_count,
983 reserved_sectors: config.reserved_sectors,
984 sector_size,
985 sectors: [SectorSummary::default(); MAX_SECTORS],
986 active_sector: None,
987 page_buf: [0xFF; PAGE_SIZE],
988 page_buf_offset: 0,
989 page_buf_durable: 0,
990 page_flash_offset: 0,
991 mounted: false,
992 next_sequence: 1,
993 total_entries: 0,
994 total_samples: 0,
995 log_id: config.log_id,
996 epoch: 1,
997 epoch_pending: false,
998 mount_mode: MountMode::Full,
999 spool_watermark: LogPosition::BEGINNING,
1000 spooled_entries: 0,
1001 spooled_samples: 0,
1002 dropped_unspooled: 0,
1003 sectors_erased: 0,
1004 })
1005 }
1006
1007 /// The raw `log_id` this database expects, 0 when anonymous.
1008 pub(crate) fn log_id_raw(&self) -> u32 {
1009 self.log_id.map_or(0, LogId::get)
1010 }
1011
1012 /// Gate for query methods: mounted, and with an index good enough to answer.
1013 ///
1014 /// A [`MountMode::HeadersOnly`] mount deliberately skips the per-sector
1015 /// entry counts, timestamp ranges and bloom filters that every query relies
1016 /// on, so those queries must refuse rather than quietly return a subset.
1017 /// Streaming via `read_from` still works, because it reads flash directly.
1018 pub(crate) fn require_reads(&self) -> Result<(), Error> {
1019 if !self.mounted {
1020 return Err(Error::NotMounted);
1021 }
1022 if self.mount_mode == MountMode::HeadersOnly {
1023 return Err(Error::ReadsUnavailable);
1024 }
1025 Ok(())
1026 }
1027
1028 /// Build a sector header carrying this database's identity and epoch.
1029 pub(crate) fn sector_header(&self, sequence: u32, erase_count: u32) -> SectorHeader {
1030 SectorHeader::new(self.log_id, self.epoch, sequence, erase_count)
1031 }
1032
1033 /// Whether a sealed sector's contents are entirely replicated.
1034 ///
1035 /// Derived rather than stored, so there is no second copy of the truth to
1036 /// keep in sync. The comparison is strict: if the watermark falls *inside*
1037 /// sector `S`, every sector below `S` is fully replicated and `S` is not.
1038 pub(crate) fn is_fully_spooled(&self, summary: &SectorSummary) -> bool {
1039 summary.sequence < self.spool_watermark.sequence
1040 }
1041
1042 /// Apply the accounting for a sector whose contents have just been erased.
1043 ///
1044 /// Called *after* the erase succeeds, never before: an erase that fails must
1045 /// not leave the index claiming data is gone, and must not report a loss
1046 /// that did not happen.
1047 pub(crate) fn account_eviction(&mut self, victim: &SectorSummary) {
1048 let entries = victim.entry_count;
1049 let samples = victim.sample_count;
1050 self.total_entries = self.total_entries.saturating_sub(entries);
1051 self.total_samples = self.total_samples.saturating_sub(samples);
1052 if self.is_fully_spooled(victim) {
1053 self.spooled_entries = self.spooled_entries.saturating_sub(entries);
1054 self.spooled_samples = self.spooled_samples.saturating_sub(samples);
1055 return;
1056 }
1057
1058 // The victim is the sector the watermark falls inside, or one above it.
1059 // In the first case part of it *was* replicated and is counted in
1060 // `spooled_entries`; only the rest is a loss. The split is recoverable
1061 // without a scan: whatever stays replicated is exactly what the other
1062 // fully-spooled sectors hold, so the remainder is the victim's share.
1063 // Charging the whole sector to `dropped_unspooled` would report a loss
1064 // of data a replica demonstrably has.
1065 let spooled_elsewhere = self.spooled_in_whole_sectors();
1066 let victim_share = self.spooled_entries.saturating_sub(spooled_elsewhere);
1067 self.spooled_entries = spooled_elsewhere;
1068 self.dropped_unspooled = self
1069 .dropped_unspooled
1070 .saturating_add(entries.saturating_sub(victim_share));
1071
1072 // The same split, in samples. `dropped_unspooled` stays in entries: it
1073 // reports loss against the replication budget, which is entry-shaped.
1074 let samples_elsewhere = self.spooled_samples_in_whole_sectors();
1075 self.spooled_samples = samples_elsewhere;
1076 }
1077
1078 /// Entries held by retained sectors that lie entirely below the watermark.
1079 ///
1080 /// Excludes the sector the watermark falls inside, whose replicated prefix
1081 /// the in-RAM index cannot measure.
1082 fn spooled_in_whole_sectors(&self) -> u32 {
1083 self.fold_whole_spooled_sectors(|s| s.entry_count)
1084 }
1085
1086 /// The same, in samples.
1087 fn spooled_samples_in_whole_sectors(&self) -> u32 {
1088 self.fold_whole_spooled_sectors(|s| s.sample_count)
1089 }
1090
1091 fn fold_whole_spooled_sectors(&self, of: impl Fn(&SectorSummary) -> u32) -> u32 {
1092 (0..self.sector_count)
1093 .map(|i| &self.sectors[i as usize])
1094 .filter(|s| s.state != SectorState::Erased && self.is_fully_spooled(s))
1095 .fold(0u32, |acc, s| acc.saturating_add(of(s)))
1096 }
1097}
1098
1099/// Append-only sensor database for NOR flash.
1100///
1101/// Generic parameters:
1102/// - `F`: Flash storage implementing `NorFlash` and `ReadNorFlash`
1103/// - `PAGE_SIZE`: the unit this database writes in. Must be a multiple of
1104/// `F::WRITE_SIZE` — checked at compile time — and must not exceed the part's
1105/// physical program page, which `embedded-storage` does not express and so
1106/// cannot be checked. Note `WRITE_SIZE` is the minimum write *granularity*,
1107/// not the program-page size; a driver reporting 1 constrains nothing.
1108/// - `MAX_SECTORS`: Maximum number of sectors this instance can manage
1109///
1110/// # Memory Usage
1111///
1112/// The struct's RAM footprint is approximately:
1113/// - `MAX_SECTORS × 48` bytes for the in-RAM sector index ([`SectorSummary`] array)
1114/// - `PAGE_SIZE` bytes for the write page buffer
1115/// - ~30 bytes for bookkeeping fields
1116///
1117/// Example: with `PAGE_SIZE = 256` and `MAX_SECTORS = 32`, total ≈ 1,822 bytes.
1118///
1119/// # NOR Flash Constraints
1120///
1121/// Entries cannot span page boundaries because NOR flash requires page-aligned
1122/// writes. Each entry (header + payload + CRC) must fit within a single
1123/// `PAGE_SIZE` page. The maximum payload size is `PAGE_SIZE - 20` bytes.
1124///
1125/// The database does not perform active wear leveling beyond the implicit
1126/// distribution of the circular sector ring. Sectors are used round-robin
1127/// starting from the sector after the current active one. For applications
1128/// needing precise wear balancing, consider tracking erase counts externally.
1129///
1130/// # Read Model
1131///
1132/// Reads do **not** write to flash: `latest`, `oldest`, `count`, `query_range`
1133/// and their typed variants scan committed entries and transparently include
1134/// any buffered (unflushed) entries from the page buffer, so a read never
1135/// triggers a flash write and `sync()` is needed for **durability** alone, not
1136/// for read visibility.
1137///
1138/// They do take `&mut self`, because `ReadNorFlash::read` does. An earlier
1139/// revision wrapped the driver in a `RefCell` so they could take `&self`, and
1140/// it bought nothing: `RefCell<F>` is `!Sync`, so the only way to share a
1141/// `SensorDb` was a `Mutex`, which hands back `&mut` anyway. What it cost was
1142/// real — reads split into two shapes (`&self` here, `&mut self` on
1143/// [`LogSource`](crate::LogSource), which
1144/// [`TieredDb`](crate::TieredDb) forces), a re-entrancy panic to fence off
1145/// (a callback capturing `&db` and calling `latest()` double-borrowed), and a
1146/// panic path in a `no_std` crate. Without it `SensorDb` is `Sync` whenever
1147/// `F` is, and the port and the inherent methods agree.
1148///
1149/// Methods that touch no flash — [`stats`](Self::stats),
1150/// [`is_mounted`](Self::is_mounted), [`head_position`](Self::head_position),
1151/// [`peek_unflushed`](Self::peek_unflushed) and the rest — still take `&self`.
1152///
1153/// # Stack Usage
1154///
1155/// Most public methods allocate a single `[u8; PAGE_SIZE]` temporary buffer
1156/// on the stack. The deepest call chains (e.g., `latest_value` → `latest` →
1157/// `find_latest_in_sector`) pass buffers through rather than allocating new
1158/// ones, so the worst-case stack overhead per call is approximately
1159/// `1 × PAGE_SIZE` bytes on top of the `SensorDb` struct itself.
1160///
1161/// With `PAGE_SIZE = 256`, this is negligible. With `PAGE_SIZE = 4096`, each
1162/// read/query call uses ~4 KB of stack — plan accordingly on Cortex-M targets
1163/// with limited stack space.
1164pub struct SensorDb<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
1165 flash: F,
1166 state: SensorDbState<PAGE_SIZE, MAX_SECTORS>,
1167}
1168
1169impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> core::fmt::Debug
1170 for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
1171{
1172 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1173 f.debug_struct("SensorDb")
1174 .field("base_offset", &self.state.base_offset)
1175 .field("sector_count", &self.state.sector_count)
1176 .field("sector_size", &self.state.sector_size)
1177 .field("mounted", &self.state.mounted)
1178 .field("active_sector", &self.state.active_sector)
1179 .field("total_entries", &self.state.total_entries)
1180 .finish_non_exhaustive()
1181 }
1182}
1183
1184impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDb<F, PAGE_SIZE, MAX_SECTORS>
1185where
1186 F: NorFlash + ReadNorFlash,
1187{
1188 /// Create a new SensorDb instance.
1189 ///
1190 /// # Arguments
1191 /// - `flash`: Flash storage
1192 /// - `base_offset`: Starting offset in flash for the database region
1193 /// - `sector_count`: Number of sectors to use
1194 /// - `reserved_sectors`: Number of sectors to keep free for compaction headroom
1195 ///
1196 /// # Limits
1197 ///
1198 /// - The entire database region (`sector_count × ERASE_SIZE + base_offset`)
1199 /// must fit within `u32` address space (4 GB).
1200 /// - `SectorSummary.write_offset` is `u32`, supporting individual sectors
1201 /// up to 4 GB.
1202 /// - `sector_count` must not exceed `MAX_SECTORS`.
1203 ///
1204 /// # Errors
1205 /// - `TooManySectors` if `sector_count > MAX_SECTORS`
1206 /// - `InvalidConfig` if `reserved_sectors >= sector_count`
1207 pub fn new(
1208 flash: F,
1209 base_offset: u32,
1210 sector_count: u16,
1211 reserved_sectors: u16,
1212 ) -> Result<Self, Error> {
1213 Self::with_config(
1214 flash,
1215 DbConfig::new(base_offset, sector_count, reserved_sectors)?,
1216 )
1217 }
1218
1219 /// Create a `SensorDb` from a validated [`DbConfig`].
1220 ///
1221 /// Use this instead of [`new`](Self::new) when the database needs a
1222 /// [`LogId`] — for example when its storage is removable and could be
1223 /// carried to, or confused with, another device.
1224 ///
1225 /// # Errors
1226 /// - `TooManySectors` if `config.sector_count() > MAX_SECTORS`
1227 /// - `Overflow` if the region does not fit in `u32` address space
1228 ///
1229 /// # Panics
1230 ///
1231 /// Fails to *compile*, not to run, if `PAGE_SIZE` is not a multiple of
1232 /// `F::WRITE_SIZE` — the compile-time `Geometry` assert.
1233 pub fn with_config(flash: F, config: DbConfig) -> Result<Self, Error> {
1234 let () = Geometry::<F, PAGE_SIZE>::PAGE_IS_WRITABLE;
1235 Ok(Self {
1236 flash,
1237 state: SensorDbState::new(config, F::ERASE_SIZE as u32)?,
1238 })
1239 }
1240
1241 /// Format the database region, erasing all sectors and initializing the first as active.
1242 ///
1243 /// After format, the database is automatically mounted. All sectors carry
1244 /// this database's [`LogId`] and `erase_count = 1`, and the epoch restarts
1245 /// at 1.
1246 ///
1247 /// This destroys everything in the region unconditionally — including a
1248 /// foreign volume. Use [`mount`](Self::mount), which refuses to touch
1249 /// another log's data, when the medium's provenance is not certain.
1250 pub fn format(&mut self) -> Result<(), Error> {
1251 let flash = &mut self.flash;
1252 // Erase all sectors
1253 for i in 0..self.state.sector_count {
1254 self.state.erase_sector(flash, i)?;
1255 self.state.sectors[i as usize] = SectorSummary::erased();
1256 self.state.sectors[i as usize].erase_count = 1;
1257 }
1258
1259 self.state.epoch = 1;
1260 // `init_sector` below stamps epoch 1, so nothing is owed.
1261 self.state.epoch_pending = false;
1262
1263 // Initialize first sector as active
1264 self.state.init_sector(flash, 0, 1, 1)?;
1265 self.state.sectors[0].state = SectorState::Active;
1266 self.state.sectors[0].sequence = 1;
1267 self.state.sectors[0].write_offset = SECTOR_HEADER_SIZE as u32;
1268 self.state.sectors[0].erase_count = 1;
1269
1270 self.state.active_sector = Some(0);
1271 self.state.next_sequence = 2;
1272 self.state.total_entries = 0;
1273 self.state.total_samples = 0;
1274 self.state.mounted = true;
1275 self.state.mount_mode = MountMode::Full;
1276 self.state.spool_watermark = LogPosition::BEGINNING;
1277 self.state.spooled_entries = 0;
1278 self.state.spooled_samples = 0;
1279 self.state.dropped_unspooled = 0;
1280
1281 // Initialize page buffer for the active sector
1282 self.state.page_flash_offset = self.state.base_offset;
1283 self.state.page_buf_offset = SECTOR_HEADER_SIZE;
1284 self.state.page_buf_durable = SECTOR_HEADER_SIZE;
1285 self.state.page_buf.fill(0xFF);
1286 // Read the sector header into the page buffer
1287 let header = self.state.sector_header(1, 1);
1288 self.state.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
1289
1290 Ok(())
1291 }
1292
1293 /// Mount an existing database by scanning all sectors and rebuilding the index.
1294 ///
1295 /// Equivalent to [`mount_with(MountMode::Full)`](Self::mount_with).
1296 ///
1297 /// # Errors
1298 /// - `AlreadyMounted` if already mounted
1299 /// - `ForeignVolume` if the medium belongs to a different log
1300 /// - `UnsupportedVersion` if the medium uses a newer format
1301 pub fn mount(&mut self) -> Result<MountStats, Error> {
1302 self.mount_with(MountMode::Full)
1303 }
1304
1305 /// Mount an existing database, choosing how much of the index to rebuild.
1306 ///
1307 /// # Foreign media
1308 ///
1309 /// A sector whose header parses as this format but carries a different
1310 /// [`LogId`] aborts the mount with [`Error::ForeignVolume`], **before**
1311 /// anything is written. This matters for removable storage: the fallback
1312 /// path for "no valid sectors found" erases a sector to bootstrap the log,
1313 /// so without this check, inserting another device's card and mounting it
1314 /// would destroy its data.
1315 ///
1316 /// An anonymous database (no `log_id` in its [`DbConfig`]) accepts any
1317 /// medium, preserving the behaviour of databases that never declare an
1318 /// identity.
1319 ///
1320 /// # Epoch
1321 ///
1322 /// Each successful mount takes an epoch one higher than any found on the
1323 /// medium, and stamps it into every sector header written from then on.
1324 /// Timestamps from a device with no real-time clock restart at zero on every
1325 /// boot; the epoch is what lets a reader tell those runs apart.
1326 ///
1327 /// # Errors
1328 /// - `AlreadyMounted` if already mounted
1329 /// - `ForeignVolume` if the medium belongs to a different log
1330 /// - `UnsupportedVersion` if the medium uses a newer format
1331 pub fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error> {
1332 if self.state.mounted {
1333 return Err(Error::AlreadyMounted);
1334 }
1335
1336 let flash = &mut self.flash;
1337 let mut stats = MountStats::default();
1338 let mut max_sequence: u32 = 0;
1339 let mut max_epoch: u32 = 0;
1340
1341 // Pass 1: read every sector header. Classification happens before any
1342 // write, so a foreign or unreadable volume is rejected intact.
1343 let mut valid: HeaplessVec<u16, MAX_SECTORS> = HeaplessVec::new();
1344 for i in 0..self.state.sector_count {
1345 let sector_offset = self.state.sector_offset(i);
1346 let mut header_buf = [0u8; SECTOR_HEADER_SIZE];
1347 flash.read(sector_offset, &mut header_buf)?;
1348
1349 let header =
1350 SectorHeader::read_from_bytes(&header_buf).map_err(|_| Error::CorruptEntry)?;
1351
1352 match header.classify(self.state.log_id) {
1353 SectorClass::Valid => {
1354 let seq = header.sequence.get();
1355 let epoch = header.epoch.get();
1356 self.state.sectors[i as usize].sequence = seq;
1357 self.state.sectors[i as usize].erase_count = header.erase_count.get();
1358 max_sequence = max_sequence.max(seq);
1359 max_epoch = max_epoch.max(epoch);
1360 let _ = valid.push(i);
1361 }
1362 SectorClass::Free => {
1363 // Erased, never written, or data this format cannot parse.
1364 // The body is not a valid entry stream, so treat the sector
1365 // as free rather than scanning it.
1366 self.state.sectors[i as usize] = SectorSummary::erased();
1367 }
1368 SectorClass::Foreign { found } => {
1369 return Err(Error::ForeignVolume {
1370 expected: self.state.log_id_raw(),
1371 found,
1372 });
1373 }
1374 SectorClass::Unsupported { found } => {
1375 return Err(Error::UnsupportedVersion { found });
1376 }
1377 }
1378 }
1379
1380 // The newest sector is the only one an append can land in, so it must be
1381 // scanned in every mode to find the resume offset.
1382 let newest = valid
1383 .iter()
1384 .copied()
1385 .max_by_key(|i| self.state.sectors[*i as usize].sequence);
1386
1387 // Pass 2: rebuild the entry index for the sectors this mode covers.
1388 //
1389 // The newest sector is where an append resumes, so it is always indexed
1390 // exactly — but even it can carry a footer: a run that sealed a sector
1391 // and then died before the successor's header reached flash leaves the
1392 // sealed sector holding the highest valid sequence. `newest_sealed`
1393 // records that, because the cursor must then be parked at the footer
1394 // page rather than inside data the footer already describes.
1395 let mut newest_sealed = false;
1396 for i in valid.iter().copied() {
1397 let is_newest = Some(i) == newest;
1398
1399 // Read a footer when it can index the sector — and always for the
1400 // newest one, where it is not an optimisation at all but the signal
1401 // that the sector is already closed. `HeadersOnly` keeps its
1402 // one-read-per-sector promise everywhere else.
1403 let footer = if self.state.wants_footer(mode, is_newest) {
1404 self.state.read_sector_footer(flash, i)?
1405 } else {
1406 None
1407 };
1408 if is_newest {
1409 newest_sealed = footer.is_some();
1410 }
1411
1412 // `Verify` exists to re-read the medium, so it indexes from entries
1413 // even where a footer would have answered.
1414 if let Some(footer) = footer.filter(|_| mode != MountMode::Verify) {
1415 self.state.adopt_footer(i, &footer, &mut stats);
1416 } else if mode != MountMode::HeadersOnly || is_newest {
1417 let (scanned, corrupt) = self.state.scan_sector_entries(flash, i)?;
1418 self.state.adopt_scan(i, &scanned, corrupt, &mut stats);
1419 } else {
1420 self.state.adopt_unindexed(i);
1421 }
1422 self.state.sectors[i as usize].state = SectorState::Sealed;
1423 stats.sealed_sectors += 1;
1424 }
1425
1426 self.state
1427 .finish_mount(mode, max_sequence, max_epoch, &stats);
1428
1429 if let Some(idx) = newest {
1430 self.state.sectors[idx as usize].state = SectorState::Active;
1431 self.state.active_sector = Some(idx);
1432 stats.sealed_sectors = stats.sealed_sectors.saturating_sub(1);
1433
1434 // This sector was created by an earlier run, so it carries that run's
1435 // epoch. Anything appended into it would be attributed to that run.
1436 // Owe a sector roll, paid on the first append.
1437 self.state.epoch_pending = true;
1438
1439 let sector_offset = self.state.sector_offset(idx);
1440
1441 // Where writing resumes inside this sector. Normally the end of its
1442 // data — but a sector that already carries a footer was *sealed*,
1443 // and its frozen summary would become a lie if anything were
1444 // appended into it. Resume such a sector at its footer page, which
1445 // is where `append`'s boundary check seals and moves on. That
1446 // happens when a run sealed a sector and then lost power before the
1447 // successor's header landed, leaving the sealed sector holding the
1448 // highest valid sequence.
1449 let resume = if newest_sealed {
1450 self.state.footer_offset()
1451 } else {
1452 self.state.sectors[idx as usize].write_offset
1453 };
1454
1455 // Load the partial page into the buffer
1456 let page_start = (resume / PAGE_SIZE as u32) * PAGE_SIZE as u32;
1457 self.state.page_flash_offset = sector_offset + page_start;
1458 self.state.page_buf_offset = (resume % PAGE_SIZE as u32) as usize;
1459 self.state.page_buf_durable = self.state.page_buf_offset;
1460 self.state.page_buf.fill(0xFF);
1461
1462 // A power loss can leave written bytes *past* the last valid entry,
1463 // and not only in this page: the scanner steps over uncommitted
1464 // entries without adopting them, so whole pages of half-committed
1465 // data can sit ahead of the resume point. Appending before them
1466 // would eventually flush into a dirty page, and NOR cannot set bits
1467 // back — the write fails and the log wedges.
1468 //
1469 // Find the last page in this sector that still holds data, and
1470 // resume after it. This costs one read per page of the active
1471 // sector, on a path that has already read every entry.
1472 //
1473 // Usually nothing depends on it: `epoch_pending` was just set, so
1474 // the first append rolls to a fresh sector and abandons this one
1475 // before any of it matters. But that roll is skipped when the ring
1476 // has no sector to give (`append` swallows `NoSpace` rather than
1477 // fail a write for the sake of provenance metadata), and *then* this
1478 // is the only thing standing between a torn page and a log that
1479 // cannot be written to again. A full ring is exactly when losing the
1480 // log would hurt most.
1481 //
1482 // Bounded by the footer offset: the final page is not data, and on a
1483 // sector parked there by `newest_sealed` the probe does not run at
1484 // all — there is nothing ahead of the cursor to be in the way of.
1485 let mut last_dirty: Option<u32> = None;
1486 let mut probe = page_start;
1487 while probe < self.state.footer_offset() {
1488 flash.read(sector_offset + probe, &mut self.state.page_buf)?;
1489 // In the resume page, only what lies *after* the write position
1490 // counts as in the way.
1491 let from = if probe == page_start {
1492 self.state.page_buf_offset
1493 } else {
1494 0
1495 };
1496 if self.state.page_buf[from..].iter().any(|b| *b != 0xFF) {
1497 last_dirty = Some(probe);
1498 }
1499 probe += PAGE_SIZE as u32;
1500 }
1501
1502 match last_dirty {
1503 // Everything from the write position on is erased: resume there,
1504 // continuing to fill the partial page. Nothing to re-read when
1505 // the cursor is parked on the footer page.
1506 None if resume < self.state.footer_offset() => {
1507 flash.read(self.state.page_flash_offset, &mut self.state.page_buf)?;
1508 }
1509 None => {}
1510 // Something is in the way. Start after it, giving up the rest of
1511 // the skipped pages — cheaper than an unusable log.
1512 Some(dirty) => {
1513 self.state.page_flash_offset = sector_offset + dirty + PAGE_SIZE as u32;
1514 self.state.page_buf_offset = 0;
1515 self.state.page_buf_durable = 0;
1516 self.state.page_buf.fill(0xFF);
1517 self.state.sectors[idx as usize].write_offset = dirty + PAGE_SIZE as u32;
1518 }
1519 }
1520 } else {
1521 // No valid sectors found. The chosen sector may hold stale data from a
1522 // previous format (NOR writes only clear bits, so writing a fresh
1523 // header over it would corrupt the magic), so erase before init.
1524 //
1525 // Reaching here means every sector classified as Free, so nothing
1526 // another log owns is being destroyed.
1527 self.state.erase_sector(flash, 0)?;
1528 self.state
1529 .init_sector(flash, 0, self.state.next_sequence, 1)?;
1530 // That header carries this run's epoch, so nothing is owed.
1531 self.state.epoch_pending = false;
1532 self.state.sectors[0].state = SectorState::Active;
1533 self.state.sectors[0].sequence = self.state.next_sequence;
1534 self.state.sectors[0].write_offset = SECTOR_HEADER_SIZE as u32;
1535 self.state.sectors[0].erase_count = 1;
1536 self.state.active_sector = Some(0);
1537 self.state.next_sequence += 1;
1538
1539 self.state.page_flash_offset = self.state.base_offset;
1540 self.state.page_buf_offset = SECTOR_HEADER_SIZE;
1541 self.state.page_buf_durable = SECTOR_HEADER_SIZE;
1542 self.state.page_buf.fill(0xFF);
1543 let header = self.state.sector_header(self.state.sectors[0].sequence, 1);
1544 self.state.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
1545 }
1546
1547 self.state.mounted = true;
1548 Ok(stats)
1549 }
1550
1551 /// Append a sensor reading to the database.
1552 ///
1553 /// # Arguments
1554 /// - `sensor_id`: Sensor identifier
1555 /// - `timestamp`: Timestamp (typically microseconds since epoch)
1556 /// - `payload`: Raw sensor data
1557 ///
1558 /// # Errors
1559 /// - `NotMounted` if not mounted
1560 /// - `PayloadTooLarge` if payload exceeds max size
1561 /// - `NoSpace` if no sectors available
1562 pub fn append(&mut self, sensor_id: u16, timestamp: u64, payload: &[u8]) -> Result<(), Error> {
1563 self.append_entry(
1564 EntryKind::Single,
1565 sensor_id,
1566 timestamp,
1567 timestamp,
1568 1,
1569 &[],
1570 payload,
1571 )
1572 }
1573
1574 /// Append a [run](crate::run): many evenly spaced samples under one header.
1575 ///
1576 /// One entry header and one CRC for the whole burst, which is what makes it
1577 /// worth doing — thirty-two `f32` samples cost 148 bytes here against 800
1578 /// appended one at a time.
1579 ///
1580 /// The run is **invisible to every read**: [`query_range`](Self::query_range),
1581 /// [`latest`](Self::latest), [`oldest`](Self::oldest) and
1582 /// [`count`](Self::count) expand it back into the samples it holds, so they
1583 /// deliver byte for byte what [`append_sensor`](Self::append_sensor) of the
1584 /// same samples would have delivered. Only
1585 /// [`read_from`](Self::read_from) sees it as one entry, because replication
1586 /// copies entries and a replica should keep the amortisation.
1587 ///
1588 /// ```ignore
1589 /// use sensor_db::Run;
1590 ///
1591 /// let burst: [Temperature; 32] = collect_burst();
1592 /// db.append_run(&Run::of(t0, 10_000, &burst)?)?;
1593 /// ```
1594 ///
1595 /// # Errors
1596 /// - `NotMounted` if not mounted
1597 /// - `PayloadTooLarge` if the framed run exceeds
1598 /// [`max_payload_size`](Self::max_payload_size); split the burst
1599 /// - `NoSpace` if no sectors available
1600 pub fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
1601 let mut frame = [0u8; RUN_FRAME_SIZE];
1602 run.write_frame(&mut frame);
1603 self.append_entry(
1604 EntryKind::Run,
1605 run.sensor_id(),
1606 run.base_timestamp(),
1607 run.span_end(),
1608 run.count(),
1609 &frame,
1610 run.samples(),
1611 )
1612 }
1613
1614 /// Append an entry exactly as another log stored it.
1615 ///
1616 /// The write side of replication, and the mirror of
1617 /// [`read_from`](Self::read_from): hand back the `(header, payload)` pair a
1618 /// stream delivered and the entry is reproduced here — a
1619 /// [run](crate::run) as a run, so the copy keeps the amortisation instead of
1620 /// storing the frame as one opaque sample no read could interpret.
1621 ///
1622 /// # Errors
1623 /// - `CorruptEntry` if the header claims a run and the payload is not one
1624 /// - otherwise as [`append`](Self::append)
1625 pub fn append_framed(&mut self, header: &EntryHeader, payload: &[u8]) -> Result<(), Error> {
1626 match header.kind {
1627 EntryKind::Single => self.append(header.sensor_id, header.timestamp, payload),
1628 EntryKind::Run => {
1629 let frame = RunFrame::parse(payload).ok_or(Error::CorruptEntry)?;
1630 self.append_entry(
1631 EntryKind::Run,
1632 header.sensor_id,
1633 header.timestamp,
1634 frame.span_end(header.timestamp),
1635 frame.count(),
1636 &[],
1637 payload,
1638 )
1639 }
1640 }
1641 }
1642
1643 /// The one write path: buffer an entry of either kind, sealing as needed.
1644 ///
1645 /// The payload arrives in two pieces so a run costs no staging buffer — the
1646 /// frame header and the sample bytes go straight into the page buffer, which
1647 /// is also where the entry CRC is then computed from.
1648 ///
1649 /// `span_end` and `samples` describe what the entry contributes to the
1650 /// sector index: a single sample spans its own timestamp and counts once, a
1651 /// run spans to its last sample and counts all of them.
1652 #[allow(clippy::too_many_arguments)]
1653 fn append_entry(
1654 &mut self,
1655 kind: EntryKind,
1656 sensor_id: u16,
1657 timestamp: u64,
1658 span_end: u64,
1659 samples: u32,
1660 head: &[u8],
1661 tail: &[u8],
1662 ) -> Result<(), Error> {
1663 if !self.state.mounted {
1664 return Err(Error::NotMounted);
1665 }
1666
1667 let payload_len = head.len() + tail.len();
1668 let entry_size = ENTRY_OVERHEAD + payload_len;
1669 if payload_len > self.max_payload_size() {
1670 return Err(Error::PayloadTooLarge);
1671 }
1672
1673 let flash = &mut self.flash;
1674
1675 // This run inherited a sector an earlier run created, so appending into
1676 // it would stamp these entries with the earlier run's epoch. Roll to a
1677 // fresh sector, which records this run's epoch on the medium.
1678 //
1679 // Deferred to here rather than done at mount so a run that only reads
1680 // costs no erase at all.
1681 if self.state.epoch_pending {
1682 match self.state.seal_and_advance(flash) {
1683 Ok(()) => {}
1684 // Provenance metadata must never cost a write. If the ring has
1685 // no sector to give, append into the inherited one; the only
1686 // casualty is epoch precision.
1687 Err(Error::NoSpace) => self.state.epoch_pending = false,
1688 Err(e) => return Err(e),
1689 }
1690 }
1691
1692 // Make room. One seal always suffices: a fresh sector gives a whole page
1693 // after its header page. A second would mean the geometry cannot hold
1694 // this entry anywhere, so refuse rather than seal forever — burning the
1695 // entire ring one sector per iteration.
1696 let mut sealed_once = false;
1697 loop {
1698 match self.state.plan_append(entry_size)? {
1699 AppendStep::Stage => break,
1700 AppendStep::FlushPage => self.state.flush_page(flash)?,
1701 AppendStep::Seal => {
1702 if sealed_once {
1703 return Err(Error::PayloadTooLarge);
1704 }
1705 sealed_once = true;
1706 self.state.seal_and_advance(flash)?;
1707 }
1708 }
1709 }
1710
1711 self.state
1712 .stage_entry(kind, sensor_id, timestamp, span_end, samples, head, tail)
1713 }
1714
1715 /// Flush the page buffer to flash, committing buffered entries.
1716 ///
1717 /// Call this after writing entries to ensure they survive a power loss.
1718 /// Read methods (`latest`, `query_range`, `oldest`, `count`) do **not**
1719 /// require a prior `sync()` — they transparently scan the page buffer for
1720 /// unflushed entries. `sync()` is only needed for **durability**, not for
1721 /// read visibility.
1722 ///
1723 /// # Sync Policy
1724 ///
1725 /// There is a trade-off between data safety and flash wear:
1726 /// - **Sync after every append**: Maximum durability — no data loss on power
1727 /// failure, but each sync writes a full flash page (two writes for the
1728 /// two-phase commit), increasing wear.
1729 /// - **Sync periodically** (e.g., every N entries or every T seconds):
1730 /// Reduces wear but risks losing buffered entries on power failure.
1731 /// Entries written since the last sync are not yet committed to flash.
1732 ///
1733 /// On embedded systems with limited flash endurance (~100K erase cycles),
1734 /// prefer batching writes and syncing periodically.
1735 pub fn sync(&mut self) -> Result<(), Error> {
1736 if !self.state.mounted {
1737 return Err(Error::NotMounted);
1738 }
1739 self.state.flush_page(&mut self.flash)?;
1740 Ok(())
1741 }
1742
1743 /// Find the most recent entry for a given sensor.
1744 ///
1745 /// This method does **not** write to flash. It scans committed entries on
1746 /// flash and any buffered (unflushed) entries in the page buffer, returning
1747 /// the one with the highest timestamp.
1748 ///
1749 /// # Arguments
1750 /// - `sensor_id`: Sensor to query
1751 /// - `buf`: Buffer to receive payload
1752 ///
1753 /// # Returns
1754 /// `Some((header, payload_len))` if found, `None` if no entries for this sensor.
1755 pub fn latest(
1756 &mut self,
1757 sensor_id: u16,
1758 buf: &mut [u8],
1759 ) -> Result<Option<(EntryHeader, usize)>, Error> {
1760 self.state.require_reads()?;
1761
1762 let flash = &mut self.flash;
1763
1764 // Sort sectors by sequence (newest first), skipping sectors that
1765 // definitely don't contain this sensor (bloom filter)
1766 let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
1767 for i in 0..self.state.sector_count {
1768 let summary = &self.state.sectors[i as usize];
1769 if summary.state != SectorState::Erased && summary.might_contain_sensor(sensor_id) {
1770 // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
1771 let _ = sector_order.push((i, summary.sequence));
1772 }
1773 }
1774 // Sort descending by sequence
1775 sort_by_seq(&mut sector_order, |a, b| b.cmp(a));
1776
1777 // Scan committed sectors from flash (newest first, writes payload to buf)
1778 let mut best: Option<(EntryHeader, usize)> = None;
1779 for (sector_idx, _) in sector_order {
1780 if let Some(result) =
1781 self.state
1782 .find_latest_in_sector(&mut *flash, sector_idx, sensor_id, buf)?
1783 {
1784 best = Some(result);
1785 break;
1786 }
1787 }
1788
1789 // Scan page buffer for unflushed entries. Only accepts entries with
1790 // timestamp >= the committed best, so buf is only overwritten if the
1791 // page buffer entry actually wins.
1792 let min_ts = best.as_ref().map_or(0, |(h, _)| h.timestamp);
1793 if let Some((hdr, len)) = self
1794 .state
1795 .scan_page_buf_for_latest(sensor_id, min_ts, buf)?
1796 {
1797 best = Some((hdr, len));
1798 }
1799
1800 Ok(best)
1801 }
1802
1803 /// Query entries within a time range.
1804 ///
1805 /// This method does **not** write to flash. It scans committed entries on
1806 /// flash and any buffered (unflushed) entries in the page buffer.
1807 ///
1808 /// # Arguments
1809 /// - `sensor_id`: Optional sensor filter (None for all sensors)
1810 /// - `t_start`: Start timestamp (inclusive)
1811 /// - `t_end`: End timestamp (inclusive)
1812 /// - `callback`: Called for each matching entry. Return `false` to stop early.
1813 ///
1814 /// # Returns
1815 /// Number of entries that matched.
1816 ///
1817 /// **Note:** Entries are returned in write order (sector sequence, then offset
1818 /// within sector), not sorted by timestamp. If timestamps are non-monotonic,
1819 /// the callback will see them out of chronological order.
1820 pub fn query_range<C>(
1821 &mut self,
1822 sensor_id: Option<u16>,
1823 t_start: u64,
1824 t_end: u64,
1825 mut callback: C,
1826 ) -> Result<u32, Error>
1827 where
1828 C: FnMut(&EntryHeader, &[u8]) -> bool,
1829 {
1830 self.state.require_reads()?;
1831
1832 let flash = &mut self.flash;
1833 let mut count = 0u32;
1834
1835 // Sort sectors by sequence (oldest first for chronological order)
1836 let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
1837 for i in 0..self.state.sector_count {
1838 let summary = &self.state.sectors[i as usize];
1839 if summary.state != SectorState::Erased
1840 && summary.entry_count > 0
1841 && summary.overlaps_time_range(t_start, t_end)
1842 && sensor_id.is_none_or(|id| summary.might_contain_sensor(id))
1843 {
1844 // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
1845 let _ = sector_order.push((i, summary.sequence));
1846 }
1847 }
1848 // Sort ascending by sequence for chronological order
1849 sort_by_seq(&mut sector_order, u32::cmp);
1850
1851 let mut entry_buf = [0u8; PAGE_SIZE];
1852 let mut stopped = false;
1853
1854 for (sector_idx, _) in sector_order {
1855 stopped = self.state.scan_sector_for_query(
1856 flash,
1857 sector_idx,
1858 sensor_id,
1859 t_start,
1860 t_end,
1861 &mut entry_buf,
1862 &mut count,
1863 &mut callback,
1864 )?;
1865 if stopped {
1866 break;
1867 }
1868 }
1869
1870 // Scan page buffer for unflushed entries (newest, after all committed)
1871 if !stopped {
1872 self.state.scan_page_buf_for_query(
1873 sensor_id,
1874 t_start,
1875 t_end,
1876 &mut entry_buf,
1877 &mut count,
1878 &mut callback,
1879 );
1880 }
1881
1882 Ok(count)
1883 }
1884
1885 /// Query all entries for a sensor (or all sensors) without time constraints.
1886 ///
1887 /// This is a convenience wrapper around `query_range` that uses the full timestamp range.
1888 ///
1889 /// # Arguments
1890 /// - `sensor_id`: Optional sensor filter (None for all sensors)
1891 /// - `callback`: Called for each matching entry. Return `false` to stop early.
1892 ///
1893 /// # Returns
1894 /// Number of entries that matched.
1895 ///
1896 /// # Example
1897 ///
1898 /// ```ignore
1899 /// let count = db.query_all(Some(SENSOR_TEMP), |hdr, payload| {
1900 /// println!("Entry at {}: {:?}", hdr.timestamp, payload);
1901 /// true
1902 /// })?;
1903 /// ```
1904 pub fn query_all<C>(&mut self, sensor_id: Option<u16>, callback: C) -> Result<u32, Error>
1905 where
1906 C: FnMut(&EntryHeader, &[u8]) -> bool,
1907 {
1908 self.query_range(sensor_id, 0, u64::MAX, callback)
1909 }
1910
1911 /// Find the oldest (earliest) entry for a given sensor.
1912 ///
1913 /// This method does **not** write to flash. It scans committed entries on
1914 /// flash and falls back to the page buffer if no committed entries exist
1915 /// for this sensor.
1916 ///
1917 /// # Arguments
1918 /// - `sensor_id`: Sensor to query
1919 /// - `buf`: Buffer to receive payload
1920 ///
1921 /// # Returns
1922 /// `Some((header, payload_len))` if found, `None` if no entries for this sensor.
1923 ///
1924 /// # Example
1925 ///
1926 /// ```ignore
1927 /// let mut buf = [0u8; 64];
1928 /// if let Some((hdr, n)) = db.oldest(SENSOR_TEMP, &mut buf)? {
1929 /// let first_reading = &buf[..n];
1930 /// println!("First reading at {}", hdr.timestamp);
1931 /// }
1932 /// ```
1933 pub fn oldest(
1934 &mut self,
1935 sensor_id: u16,
1936 buf: &mut [u8],
1937 ) -> Result<Option<(EntryHeader, usize)>, Error> {
1938 self.state.require_reads()?;
1939
1940 let flash = &mut self.flash;
1941
1942 // Sort sectors by sequence (oldest first), skipping sectors that
1943 // definitely don't contain this sensor (bloom filter)
1944 let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
1945 for i in 0..self.state.sector_count {
1946 let summary = &self.state.sectors[i as usize];
1947 if summary.state != SectorState::Erased && summary.might_contain_sensor(sensor_id) {
1948 // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
1949 let _ = sector_order.push((i, summary.sequence));
1950 }
1951 }
1952 // Sort ascending by sequence (oldest first)
1953 sort_by_seq(&mut sector_order, u32::cmp);
1954
1955 for (sector_idx, _) in sector_order {
1956 if let Some((header, payload_len)) =
1957 self.state
1958 .find_oldest_in_sector(&mut *flash, sector_idx, sensor_id, buf)?
1959 {
1960 return Ok(Some((header, payload_len)));
1961 }
1962 }
1963
1964 // Fallback: check page buffer. The active sector is the newest, so
1965 // buffered entries can only be "oldest" if no committed entries exist.
1966 if let Some(result) = self.state.scan_page_buf_for_oldest(sensor_id, buf) {
1967 return Ok(Some(result));
1968 }
1969
1970 Ok(None)
1971 }
1972
1973 /// Count entries for a specific sensor (or all sensors).
1974 ///
1975 /// Exact: the count is the number of entries
1976 /// [`query_range`](Self::query_range) would yield over the whole time range,
1977 /// because both apply the same acceptance test — a matching entry CRC — and
1978 /// resync the same way when one fails. Buffered entries not yet on flash are
1979 /// included, as they are for [`latest`](Self::latest).
1980 ///
1981 /// This method does **not** write to flash.
1982 ///
1983 /// # Cost
1984 ///
1985 /// `None` is free: it returns the total the mount scan established.
1986 ///
1987 /// A sensor filter scans every sector the per-sector bloom filter does not
1988 /// reject, reading each entry's payload to verify its CRC. That payload read
1989 /// is the price of agreeing with the read path; it was once skipped, which
1990 /// made `count` cheaper and wrong — it included entries `latest` and
1991 /// `query_range` refused to return. It is still cheaper than
1992 /// [`query_all`](Self::query_all), which has no bloom filter to skip
1993 /// sectors by.
1994 ///
1995 /// # Arguments
1996 /// - `sensor_id`: Optional sensor filter (None to count all entries)
1997 ///
1998 /// # Returns
1999 /// Number of entries matching the filter.
2000 ///
2001 /// # Example
2002 ///
2003 /// ```ignore
2004 /// let temp_count = db.count(Some(SENSOR_TEMP))?;
2005 /// let total = db.count(None)?;
2006 /// ```
2007 pub fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
2008 self.state.require_reads()?;
2009
2010 // For counting all entries, we can use the cached total
2011 let Some(target) = sensor_id else {
2012 return Ok(self.state.total_samples);
2013 };
2014
2015 let flash = &mut self.flash;
2016 let mut count = 0u32;
2017
2018 for i in 0..self.state.sector_count {
2019 let summary = &self.state.sectors[i as usize];
2020 if summary.state != SectorState::Erased && summary.might_contain_sensor(target) {
2021 count += self.state.count_sensor_in_sector(&mut *flash, i, target)?;
2022 }
2023 }
2024
2025 // Include unflushed entries in the page buffer
2026 count += self.state.count_sensor_in_page_buf(target);
2027
2028 Ok(count)
2029 }
2030
2031 /// Compact the database by erasing the oldest sealed sectors.
2032 ///
2033 /// # Arguments
2034 /// - `count`: Maximum number of sectors to erase
2035 /// - `scope`: Which sealed sectors are eligible. Use
2036 /// [`CompactScope::SpooledOnly`] to reclaim space without destroying
2037 /// anything that has not been replicated yet.
2038 ///
2039 /// # Returns
2040 /// Number of sectors actually erased.
2041 pub fn compact(&mut self, count: u16, scope: CompactScope) -> Result<u16, Error> {
2042 if !self.state.mounted {
2043 return Err(Error::NotMounted);
2044 }
2045
2046 // Find eligible sealed sectors
2047 let mut sealed: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
2048 for i in 0..self.state.sector_count {
2049 let summary = &self.state.sectors[i as usize];
2050 if summary.state != SectorState::Sealed {
2051 continue;
2052 }
2053 if scope == CompactScope::SpooledOnly && !self.state.is_fully_spooled(summary) {
2054 continue;
2055 }
2056 // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
2057 let _ = sealed.push((i, summary.sequence));
2058 }
2059
2060 // Sort by sequence (oldest first)
2061 sort_by_seq(&mut sealed, u32::cmp);
2062
2063 let flash = &mut self.flash;
2064 let mut erased = 0u16;
2065 for (sector_idx, _) in sealed.iter().take(count as usize) {
2066 let victim = self.state.sectors[*sector_idx as usize];
2067 self.state.erase_sector(flash, *sector_idx)?;
2068 // Only after the erase actually succeeded.
2069 self.state.account_eviction(&victim);
2070 self.state.sectors[*sector_idx as usize] = SectorSummary::erased();
2071 // Preserve erase count — incremented when sector is later initialized
2072 self.state.sectors[*sector_idx as usize].erase_count = victim.erase_count;
2073 erased += 1;
2074 }
2075
2076 Ok(erased)
2077 }
2078
2079 /// Get database statistics.
2080 pub fn stats(&self) -> DbStats {
2081 self.state.stats()
2082 }
2083
2084 /// Sectors this instance has erased, since it was created.
2085 ///
2086 /// An erase takes 100 ms or more on many NOR parts, against microseconds for
2087 /// a page write, so it is the one operation that can make a single `append`
2088 /// or [`compact`](Self::compact) call visibly slow. Sampling this around a
2089 /// call says whether one happened — useful for a caller with a real-time
2090 /// deadline, and for
2091 /// [`WritePolicy::CardFirst`](crate::spool::WritePolicy::CardFirst), where
2092 /// appends go straight to a removable volume.
2093 ///
2094 /// Not the same as [`DbStats::total_erase_count`], which is a *wear* history
2095 /// read back from the sector headers and therefore counts erases from every
2096 /// previous run too. This counter starts at zero for each `SensorDb` value,
2097 /// including across a remount, and saturates rather than wrapping.
2098 pub fn sectors_erased(&self) -> u32 {
2099 self.state.sectors_erased
2100 }
2101
2102 /// Check if the database is mounted.
2103 pub fn is_mounted(&self) -> bool {
2104 self.state.mounted
2105 }
2106
2107 /// Maximum payload size that can fit in a single entry.
2108 ///
2109 /// Returns `PAGE_SIZE - 20` bytes (`PAGE_SIZE` minus the 16-byte entry
2110 /// header and 4-byte CRC-32C). Each entry must fit entirely within a
2111 /// single flash page.
2112 ///
2113 /// A *typed* payload carries a one-byte schema tag, so the largest storable
2114 /// `T` is one byte smaller again — see
2115 /// [`SCHEMA_TAG_SIZE`](crate::SCHEMA_TAG_SIZE).
2116 pub fn max_payload_size(&self) -> usize {
2117 PAGE_SIZE - ENTRY_OVERHEAD
2118 }
2119
2120 // -------------------------------------------------------------------------
2121 // Typed API - Layer 1: Explicit sensor ID with zerocopy types
2122 // -------------------------------------------------------------------------
2123
2124 /// Append a typed value to the database with an explicit sensor ID.
2125 ///
2126 /// This is the Layer 1 API where you provide the sensor ID explicitly.
2127 /// The value type must implement [`IntoBytes`] and [`Immutable`] from zerocopy.
2128 ///
2129 /// # Arguments
2130 /// - `sensor_id`: Sensor identifier
2131 /// - `timestamp`: Timestamp (typically microseconds since epoch)
2132 /// - `data`: Reference to the typed value to store
2133 ///
2134 /// # Example
2135 ///
2136 /// ```ignore
2137 /// #[derive(IntoBytes, Immutable)]
2138 /// #[repr(C)]
2139 /// struct Temperature { celsius: f32 }
2140 ///
2141 /// db.append_value(0x01, timestamp, &Temperature { celsius: 25.5 })?;
2142 /// ```
2143 pub fn append_value<T: IntoBytes + Immutable>(
2144 &mut self,
2145 sensor_id: u16,
2146 timestamp: u64,
2147 data: &T,
2148 ) -> Result<(), Error> {
2149 self.append(sensor_id, timestamp, data.as_bytes())
2150 }
2151
2152 /// Find the most recent entry for a given sensor and interpret as a typed value.
2153 ///
2154 /// This is the Layer 1 API where you provide the sensor ID explicitly.
2155 /// The value type must implement [`FromBytes`] and [`KnownLayout`] from zerocopy.
2156 ///
2157 /// # Arguments
2158 /// - `sensor_id`: Sensor to query
2159 ///
2160 /// # Returns
2161 /// `Some((header, value))` if found, `None` if no entries for this sensor.
2162 ///
2163 /// # Errors
2164 /// - `SizeMismatch` if the stored payload size doesn't match `size_of::<T>()`
2165 /// - `InvalidData` if the bytes cannot be interpreted as type `T`
2166 ///
2167 /// # Example
2168 ///
2169 /// ```ignore
2170 /// #[derive(FromBytes, KnownLayout)]
2171 /// #[repr(C)]
2172 /// struct Temperature { celsius: f32 }
2173 ///
2174 /// if let Some((hdr, temp)) = db.latest_value::<Temperature>(0x01)? {
2175 /// println!("Temperature: {} °C", temp.celsius);
2176 /// }
2177 /// ```
2178 pub fn latest_value<T: FromBytes + KnownLayout>(
2179 &mut self,
2180 sensor_id: u16,
2181 ) -> Result<Option<(EntryHeader, T)>, Error> {
2182 let expected_size = core::mem::size_of::<T>();
2183 let mut buf = [0u8; PAGE_SIZE];
2184
2185 match self.latest(sensor_id, &mut buf)? {
2186 Some((header, payload_len)) => {
2187 if payload_len != expected_size {
2188 return Err(Error::SizeMismatch {
2189 expected: expected_size,
2190 actual: payload_len,
2191 });
2192 }
2193 let value =
2194 T::read_from_bytes(&buf[..payload_len]).map_err(|_| Error::InvalidData)?;
2195 Ok(Some((header, value)))
2196 }
2197 None => Ok(None),
2198 }
2199 }
2200
2201 // -------------------------------------------------------------------------
2202 // Typed API - Layer 2: Type-driven sensor ID via SensorData trait
2203 // -------------------------------------------------------------------------
2204
2205 /// Append a sensor reading using the type-driven API.
2206 ///
2207 /// This is the Layer 2 API where the sensor ID is derived from the type.
2208 /// The data type must implement [`SensorData`].
2209 ///
2210 /// # Arguments
2211 /// - `timestamp`: Timestamp (typically microseconds since epoch)
2212 /// - `data`: Reference to the sensor data to store
2213 ///
2214 /// # Example
2215 ///
2216 /// ```ignore
2217 /// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
2218 /// #[repr(C)]
2219 /// struct Temperature { celsius: f32 }
2220 ///
2221 /// impl SensorData for Temperature {
2222 /// const SENSOR_ID: u16 = 0x01;
2223 /// }
2224 ///
2225 /// db.append_sensor(timestamp, &Temperature { celsius: 25.5 })?;
2226 /// ```
2227 ///
2228 /// # Schema tag
2229 ///
2230 /// The payload is the type's
2231 /// [`SCHEMA_VERSION`](SensorData::SCHEMA_VERSION) followed by the value's
2232 /// bytes, so the entry's `payload_len` is `size_of::<T>() + 1`. Entries
2233 /// written with the untagged [`append_value`](Self::append_value) are not
2234 /// readable through the `*_sensor` methods, and vice versa.
2235 pub fn append_sensor<T: SensorData>(&mut self, timestamp: u64, data: &T) -> Result<(), Error> {
2236 let framed = schema::tag(data);
2237 self.append(T::SENSOR_ID, timestamp, framed.bytes())
2238 }
2239
2240 /// Find the most recent entry for a sensor type.
2241 ///
2242 /// This is the Layer 2 API where the sensor ID is derived from the type.
2243 /// The data type must implement [`SensorData`].
2244 ///
2245 /// # Returns
2246 /// `Some((header, value))` if found, `None` if no entries for this sensor.
2247 ///
2248 /// # Errors
2249 /// - `SizeMismatch` if the stored payload is not `size_of::<T>() + 1` bytes
2250 /// - `SchemaMismatch` if it was written under another
2251 /// [`SCHEMA_VERSION`](SensorData::SCHEMA_VERSION) of this type
2252 ///
2253 /// # Example
2254 ///
2255 /// ```ignore
2256 /// if let Some((hdr, temp)) = db.latest_sensor::<Temperature>()? {
2257 /// println!("Temperature: {} °C at {}", temp.celsius, hdr.timestamp);
2258 /// }
2259 /// ```
2260 pub fn latest_sensor<T: SensorData>(&mut self) -> Result<Option<(EntryHeader, T)>, Error> {
2261 schema::read_tagged(|buf| self.latest(T::SENSOR_ID, buf))
2262 }
2263
2264 /// Query sensor entries within a time range using the type-driven API.
2265 ///
2266 /// This is the Layer 2 API where the sensor ID is derived from the type.
2267 /// The data type must implement [`SensorData`].
2268 ///
2269 /// # Arguments
2270 /// - `t_start`: Start timestamp (inclusive)
2271 /// - `t_end`: End timestamp (inclusive)
2272 /// - `callback`: Called for each matching entry with the header and typed value.
2273 /// Return `false` to stop early.
2274 ///
2275 /// # Returns
2276 /// Number of entries that matched and were successfully deserialized.
2277 ///
2278 /// # Example
2279 ///
2280 /// ```ignore
2281 /// let count = db.query_sensor::<Temperature, _>(t_start, t_end, |hdr, temp| {
2282 /// println!("{}: {} °C", hdr.timestamp, temp.celsius);
2283 /// true // continue iterating
2284 /// })?;
2285 /// ```
2286 pub fn query_sensor<T: SensorData, C>(
2287 &mut self,
2288 t_start: u64,
2289 t_end: u64,
2290 mut callback: C,
2291 ) -> Result<u32, Error>
2292 where
2293 C: FnMut(&EntryHeader, &T) -> bool,
2294 {
2295 let mut count = 0u32;
2296
2297 self.query_range(Some(T::SENSOR_ID), t_start, t_end, |header, payload| {
2298 // Entries of another schema version, or of another shape entirely,
2299 // are skipped rather than raised: aborting on the first stale one
2300 // would hide every good entry behind it. Two types sharing a sensor
2301 // ID at different versions therefore each read their own era.
2302 let Some(value) = schema::untag_payload::<T>(payload) else {
2303 return true;
2304 };
2305 count += 1;
2306 callback(header, &value)
2307 })?;
2308
2309 Ok(count)
2310 }
2311
2312 /// Query all entries for a sensor type without time constraints.
2313 ///
2314 /// This is a convenience wrapper that queries all entries for the sensor type.
2315 ///
2316 /// # Arguments
2317 /// - `callback`: Called for each matching entry with the header and typed value.
2318 /// Return `false` to stop early.
2319 ///
2320 /// # Returns
2321 /// Number of entries that matched and were successfully deserialized.
2322 ///
2323 /// # Example
2324 ///
2325 /// ```ignore
2326 /// let count = db.query_all_sensor::<Temperature, _>(|hdr, temp| {
2327 /// println!("{}: {} °C", hdr.timestamp, temp.celsius);
2328 /// true
2329 /// })?;
2330 /// ```
2331 pub fn query_all_sensor<T: SensorData, C>(&mut self, callback: C) -> Result<u32, Error>
2332 where
2333 C: FnMut(&EntryHeader, &T) -> bool,
2334 {
2335 self.query_sensor(0, u64::MAX, callback)
2336 }
2337
2338 /// Find the oldest (earliest) entry for a sensor type.
2339 ///
2340 /// # Returns
2341 /// `Some((header, value))` if found, `None` if no entries for this sensor.
2342 ///
2343 /// # Errors
2344 /// - `SizeMismatch` if the stored payload size doesn't match `size_of::<T>()`
2345 /// - `InvalidData` if the bytes cannot be interpreted as type `T`
2346 ///
2347 /// # Example
2348 ///
2349 /// ```ignore
2350 /// if let Some((hdr, temp)) = db.oldest_sensor::<Temperature>()? {
2351 /// println!("First reading: {} °C at {}", temp.celsius, hdr.timestamp);
2352 /// }
2353 /// ```
2354 pub fn oldest_sensor<T: SensorData>(&mut self) -> Result<Option<(EntryHeader, T)>, Error> {
2355 schema::read_tagged(|buf| self.oldest(T::SENSOR_ID, buf))
2356 }
2357
2358 /// Count entries for a sensor type.
2359 ///
2360 /// # Returns
2361 /// Number of entries for this sensor type.
2362 ///
2363 /// # Example
2364 ///
2365 /// ```ignore
2366 /// let temp_count = db.count_sensor::<Temperature>()?;
2367 /// ```
2368 pub fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error> {
2369 self.count(Some(T::SENSOR_ID))
2370 }
2371
2372 // -------------------------------------------------------------------------
2373 // Replication primitives
2374 // -------------------------------------------------------------------------
2375
2376 /// Deliver committed entries in log order, starting at `from` (inclusive).
2377 ///
2378 /// This is the read side of replication: it walks the log as a *stream*
2379 /// rather than a query, so a copy can be resumed from a durable position
2380 /// after a reboot or after the destination went away.
2381 ///
2382 /// # Durability boundary
2383 ///
2384 /// Only entries that are **durable on flash** are delivered. Entries still
2385 /// sitting in the page buffer are excluded, so a caller replicating this log
2386 /// never copies something the source itself could still lose to a power cut.
2387 /// Call [`sync`](Self::sync) first to make the tail eligible.
2388 ///
2389 /// # Arguments
2390 /// - `from`: where to resume. Use [`LogPosition::BEGINNING`] to start at
2391 /// whatever the log still retains.
2392 /// - `max_entries`: upper bound on entries delivered in this pass. Bounds
2393 /// both the work done and, for a replicating caller, the amount that has
2394 /// to be redone after a crash.
2395 /// - `callback`: receives each entry's position, header, and payload.
2396 /// Return `Ok(false)` to stop, **rejecting** the entry just offered; return
2397 /// `Err` to abort the pass.
2398 ///
2399 /// # Rejection semantics
2400 ///
2401 /// `Ok(false)` means *"I did not take this one, and I want to stop"*. The
2402 /// entry is not counted in [`ReadCursor::entries`] and
2403 /// [`ReadCursor::next`] stops **before** it, so resuming from `next`
2404 /// re-offers it. Likewise, an `Err` from the callback leaves `next` at the
2405 /// last entry the callback actually accepted.
2406 ///
2407 /// This is the opposite of [`query_range`](Self::query_range), where
2408 /// returning `false` stops *after* consuming the entry — and deliberately
2409 /// so. A caller forwarding this stream to somewhere else must be able to
2410 /// decline an entry (because the destination is full, or the batch has
2411 /// reached a boundary) without the log recording it as delivered.
2412 ///
2413 /// The callback returns `Result<bool, Error>` rather than a bare `bool`
2414 /// because its dominant use is writing each entry somewhere that can fail;
2415 /// a bare `bool` would force every such caller to smuggle the error out
2416 /// through captured state.
2417 ///
2418 /// # Ordering
2419 ///
2420 /// Entries are delivered in write order (ascending sector sequence, then
2421 /// ascending offset), which is not necessarily timestamp order — the same
2422 /// caveat as [`query_range`](Self::query_range).
2423 ///
2424 /// # Errors
2425 /// - `NotMounted` if the database is not mounted
2426 /// - whatever the callback returns
2427 pub fn read_from<C>(
2428 &mut self,
2429 from: LogPosition,
2430 max_entries: u32,
2431 mut callback: C,
2432 ) -> Result<ReadCursor, Error>
2433 where
2434 C: FnMut(LogPosition, &EntryHeader, &[u8]) -> Result<bool, Error>,
2435 {
2436 if !self.state.mounted {
2437 return Err(Error::NotMounted);
2438 }
2439
2440 // Collect retained sectors at or after `from`, and find the oldest
2441 // retained sequence so we can tell whether `from` fell off the tail.
2442 let mut order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
2443 let mut oldest_seq = u32::MAX;
2444 for i in 0..self.state.sector_count {
2445 let summary = &self.state.sectors[i as usize];
2446 if summary.state == SectorState::Erased {
2447 continue;
2448 }
2449 if summary.sequence < oldest_seq {
2450 oldest_seq = summary.sequence;
2451 }
2452 if summary.sequence >= from.sequence {
2453 let _ = order.push((i, summary.sequence));
2454 }
2455 }
2456 sort_by_seq(&mut order, u32::cmp);
2457
2458 let gap =
2459 from != LogPosition::BEGINNING && oldest_seq != u32::MAX && from.sequence < oldest_seq;
2460
2461 let mut cursor = ReadCursor {
2462 next: from,
2463 entries: 0,
2464 exhausted: false,
2465 gap,
2466 };
2467
2468 if max_entries == 0 {
2469 return Ok(cursor);
2470 }
2471
2472 let flash = &mut self.flash;
2473 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
2474 let mut buf = [0u8; PAGE_SIZE];
2475 let mut stopped = false;
2476
2477 for (sector_idx, seq) in order {
2478 let sector_offset = self.state.sector_offset(sector_idx);
2479 // `write_offset` is the right limit even for the active sector: the
2480 // bytes past the last flush read back as 0xFF, so the scanner runs
2481 // out of page before it runs out of limit and stops on its own.
2482 let limit = self.state.sectors[sector_idx as usize].write_offset;
2483 let start = if seq == from.sequence {
2484 from.offset.max(SECTOR_HEADER_SIZE as u32)
2485 } else {
2486 SECTOR_HEADER_SIZE as u32
2487 };
2488 if start >= limit {
2489 continue;
2490 }
2491
2492 let mut scanner = SectorScanner::new(sector_offset, start, limit);
2493 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
2494 if !accept_entry(flash, sector_offset, &entry, &mut buf)? {
2495 scanner.skip(1);
2496 continue;
2497 }
2498
2499 let position = LogPosition {
2500 sequence: seq,
2501 offset: entry.offset_in_sector,
2502 };
2503 let header = entry.header.to_header();
2504 // A rejected entry must not advance the cursor past it, or the
2505 // caller would resume after something it never accepted.
2506 if !callback(position, &header, &buf[..entry.payload_len])? {
2507 stopped = true;
2508 break;
2509 }
2510
2511 scanner.skip(entry.entry_size);
2512 cursor.entries += 1;
2513 cursor.next = LogPosition {
2514 sequence: seq,
2515 offset: scanner.offset(),
2516 };
2517
2518 if cursor.entries >= max_entries {
2519 stopped = true;
2520 break;
2521 }
2522 }
2523
2524 if stopped {
2525 break;
2526 }
2527 }
2528
2529 cursor.exhausted = !stopped;
2530 Ok(cursor)
2531 }
2532
2533 /// Hand out entries that are buffered in RAM but not yet durable, then
2534 /// discard them from this database.
2535 ///
2536 /// **Touches no flash.** This is what makes it usable when the underlying
2537 /// device has physically gone away: a removable medium can be pulled
2538 /// mid-page, and the entries still sitting in the page buffer are recovered
2539 /// into RAM and can be re-appended somewhere that still exists. A yank is
2540 /// not a power loss — the processor is still running, so nothing needs to be
2541 /// lost.
2542 ///
2543 /// Entries already durable on flash are left alone; only the RAM-only tail
2544 /// is drained. On return the page buffer is truncated to its durable prefix
2545 /// and the entry accounting is adjusted to match.
2546 ///
2547 /// "Durable" here means *written to flash*, which is not the same as the
2548 /// entry's committed flag: a commit pass that failed part-way leaves entries
2549 /// flagged committed in RAM that flash never received. Those are drained,
2550 /// because a later `mount` would not see them.
2551 ///
2552 /// The per-sector bloom filter and timestamp range are *not* rolled back —
2553 /// they may stay wider than the data warrants, which costs a redundant
2554 /// sector scan on some queries but never returns a wrong answer.
2555 ///
2556 /// # Returns
2557 /// The number of entries handed to the callback.
2558 ///
2559 /// # Errors
2560 /// - `NotMounted` if the database is not mounted
2561 /// - whatever the callback returns; the drain stops there and the buffer is
2562 /// left untouched, so the operation can be retried
2563 pub fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
2564 where
2565 C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
2566 {
2567 self.state.drain_unflushed(callback)
2568 }
2569
2570 /// Show the entries that are buffered in RAM but not yet durable, without
2571 /// removing them.
2572 ///
2573 /// The non-destructive twin of [`drain_unflushed`](Self::drain_unflushed),
2574 /// and the piece [`read_from`](Self::read_from) deliberately leaves out:
2575 /// `read_from` streams only what flash has, because a replica must never be
2576 /// told about data the source could still lose, whereas a *reader* of this
2577 /// log should see everything the log holds. Composing the two covers the
2578 /// whole log from a position.
2579 ///
2580 /// Touches no flash, so it costs nothing, works on a device that has gone
2581 /// away, and is one of the few reads that still takes `&self`.
2582 ///
2583 /// # Errors
2584 /// - `NotMounted` if the database is not mounted
2585 /// - whatever the callback returns, which stops the walk
2586 pub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
2587 where
2588 C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
2589 {
2590 self.state.peek_unflushed(callback)
2591 }
2592
2593 /// The epoch of the sector containing `position`.
2594 ///
2595 /// Reads the sector header from flash on demand rather than caching an
2596 /// epoch per sector in RAM — with `MAX_SECTORS = 512` that cache would cost
2597 /// 2 KB for a field consulted once per replication batch.
2598 ///
2599 /// Returns `None` when no retained sector holds that position, which is the
2600 /// normal answer for a position that has fallen off the tail of the ring.
2601 pub fn sector_epoch_at(&mut self, position: LogPosition) -> Result<Option<u32>, Error> {
2602 if !self.state.mounted {
2603 return Err(Error::NotMounted);
2604 }
2605 let Some(idx) = self.state.sector_at_sequence(position.sequence) else {
2606 return Ok(None);
2607 };
2608
2609 let offset = self.state.sector_offset(idx);
2610 let mut buf = [0u8; SECTOR_HEADER_SIZE];
2611 self.flash.read(offset, &mut buf)?;
2612 let header = SectorHeader::read_from_bytes(&buf).map_err(|_| Error::CorruptEntry)?;
2613 Ok(header.is_valid().then(|| header.epoch.get()))
2614 }
2615
2616 /// Position immediately after the newest entry, buffered entries included.
2617 ///
2618 /// Note this can be ahead of what [`read_from`](Self::read_from) will
2619 /// deliver, which stops at the durable tail. Returns
2620 /// [`LogPosition::BEGINNING`] when there is no active sector.
2621 pub fn head_position(&self) -> LogPosition {
2622 self.state.head_position()
2623 }
2624
2625 /// Position of the oldest entry the log still retains.
2626 ///
2627 /// A [`read_from`](Self::read_from) starting before this reports a gap.
2628 /// Returns [`LogPosition::BEGINNING`] when the log is empty.
2629 pub fn tail_position(&self) -> LogPosition {
2630 self.state.tail_position()
2631 }
2632
2633 /// Run `f` with flash access bounded to `[base, base + len)`.
2634 ///
2635 /// This is how something else on the same chip — a config store, a
2636 /// replication cursor, a firmware slot — reaches the device the database
2637 /// owns by value. The closure gets a [`Partition`], so its offsets are
2638 /// relative to `base` and an access past `len` is
2639 /// [`PartitionError::OutOfBounds`](crate::PartitionError::OutOfBounds)
2640 /// rather than a write into a neighbour.
2641 ///
2642 /// A region intersecting `[base_offset, base_offset + sector_count *
2643 /// sector_size)` is rejected with [`Error::RegionOverlap`]. That check is
2644 /// the point of this method: writing inside the database region behind the
2645 /// database's back corrupts the log, the in-RAM index silently disagrees
2646 /// with flash, and nothing surfaces until a later mount.
2647 ///
2648 /// For a *driver* capability rather than a region — presence detection, a
2649 /// wear counter, a chip id, deep power-down — use
2650 /// [`driver_mut`](Self::driver_mut).
2651 ///
2652 /// # Errors
2653 /// - `RegionOverlap` if the region intersects the database's sectors
2654 /// - `InvalidConfig` if `base` or `len` is misaligned, `len` is zero, or the
2655 /// region runs past the device's capacity
2656 /// - `Overflow` if `base + len` does not fit in `u32`
2657 ///
2658 /// ```ignore
2659 /// // Read the config block that lives just below the log.
2660 /// let mut buf = [0u8; 64];
2661 /// db.with_region(CONFIG_BASE, CONFIG_LEN, |p| p.read(0, &mut buf))??;
2662 /// ```
2663 pub fn with_region<R>(
2664 &mut self,
2665 base: u32,
2666 len: u32,
2667 f: impl FnOnce(&mut Partition<&mut F>) -> R,
2668 ) -> Result<R, Error> {
2669 self.state.check_disjoint(base, len)?;
2670 let mut partition = Partition::new(&mut self.flash, base, len)?;
2671 Ok(f(&mut partition))
2672 }
2673
2674 /// Borrow the underlying flash driver.
2675 ///
2676 /// For capabilities that belong to the *driver* rather than to any region of
2677 /// the chip: presence detection, wear counters, chip identification, power
2678 /// modes, and test introspection. The database owns `F` by value, so without
2679 /// this nothing else can reach those.
2680 ///
2681 /// # Correctness
2682 ///
2683 /// This is the unbounded escape hatch, and nothing here can enforce
2684 /// anything: `F` is a `NorFlash`, so a caller *can* write anywhere on the
2685 /// chip. **Do not address flash through it.** Use
2686 /// [`with_region`](Self::with_region), which is checked.
2687 pub fn driver_mut(&mut self) -> &mut F {
2688 &mut self.flash
2689 }
2690
2691 /// Advance the replication watermark.
2692 ///
2693 /// Call this only after `moved`, ending at `upto`, is **durably** stored
2694 /// somewhere else. Advancing it early is the one way to turn this design's
2695 /// at-least-once guarantee into data loss: the watermark is what tells the
2696 /// ring which sectors are safe to overwrite first.
2697 ///
2698 /// Monotonic — an `upto` at or behind the current watermark is ignored, so
2699 /// replaying an old acknowledgement cannot move it backwards.
2700 pub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated) {
2701 self.state.note_spooled(upto, moved);
2702 }
2703
2704 /// Restore the replication watermark from an external source of truth.
2705 ///
2706 /// [`mount`](Self::mount) deliberately cannot recover this: the watermark
2707 /// lives on the replica, which is what lets two removable media be rotated
2708 /// against one log with no local state. Until a replica reappears and calls
2709 /// this, [`spool_stats`](Self::spool_stats) reports everything as
2710 /// un-replicated — the safe direction, because it can only cause redundant
2711 /// copying, never loss.
2712 ///
2713 /// Accounting is recomputed from the in-RAM index for whole sectors, plus one
2714 /// scan of the sector the watermark falls *inside* — the index knows how many
2715 /// entries a sector holds but not where each one starts, so the entries below
2716 /// the watermark within that sector have to be counted off flash. The result
2717 /// matches what [`note_spooled`](Self::note_spooled) would have accumulated
2718 /// had the replica never gone away.
2719 ///
2720 /// # Errors
2721 ///
2722 /// Only from that one scan, and only ever `Flash`. The watermark itself is
2723 /// restored *before* the scan and stays restored, because it is the part that
2724 /// matters: it is what tells the ring which sectors are safe to overwrite.
2725 /// An `Err` therefore means the log is fully usable and only
2726 /// [`spool_stats`](Self::spool_stats) is degraded — it over-reports
2727 /// `unspooled_entries` by at most one sector's worth, the same conservative
2728 /// answer this method used to give unconditionally.
2729 pub fn restore_spool_watermark(&mut self, upto: LogPosition) -> Result<(), Error> {
2730 let Some(boundary) = self.state.restore_spool_watermark(upto) else {
2731 return Ok(());
2732 };
2733 let counted = self
2734 .state
2735 .count_entries_before(&mut self.flash, boundary, upto.offset)?;
2736 self.state.add_spooled(counted);
2737 Ok(())
2738 }
2739
2740 /// Replication accounting for this log.
2741 ///
2742 /// `unspooled_entries` is O(1). See [`SpoolStats`] for the meaning of each
2743 /// field, and note that `data_lost` is sticky.
2744 pub fn spool_stats(&self) -> SpoolStats {
2745 self.state.spool_stats()
2746 }
2747
2748 /// This log's declared identity, if any.
2749 pub fn log_id(&self) -> Option<LogId> {
2750 self.state.log_id
2751 }
2752
2753 /// The current epoch — one higher than any epoch found on the medium at mount.
2754 ///
2755 /// Stamped into every sector header this run creates, which is what lets a
2756 /// reader attribute data to a particular run of a device whose clock
2757 /// restarts at zero on every boot.
2758 ///
2759 /// # How a run's epoch reaches the medium
2760 ///
2761 /// Epochs live in sector headers, so a run only records one by creating a
2762 /// sector. To keep the attribution exact, the **first append after a mount
2763 /// rolls to a fresh sector** rather than continuing in the one the previous
2764 /// run left open. Every entry a run writes therefore sits in a sector
2765 /// stamped with that run's epoch.
2766 ///
2767 /// The roll is deferred to the first append, so a run that only reads costs
2768 /// nothing. A run that writes costs one extra sector transition — one erase,
2769 /// plus whatever space was left unused in the inherited sector. That is
2770 /// cheap when reboots are rare, which is the case this is built for.
2771 ///
2772 /// If the ring is completely full and cannot yield a sector, the roll is
2773 /// skipped rather than failing the append: losing epoch precision is always
2774 /// preferable to losing a sample. Replication correctness never depends on
2775 /// the epoch — it rests on [`LogPosition`].
2776 pub fn epoch(&self) -> u32 {
2777 self.state.epoch
2778 }
2779
2780 /// How much of the index the current mount rebuilt.
2781 pub fn mount_mode(&self) -> MountMode {
2782 self.state.mount_mode
2783 }
2784
2785 /// Declare this log a replica of another, suppressing the per-run epoch roll.
2786 ///
2787 /// A primary log rolls to a fresh sector on its first append after a mount
2788 /// so that the run's [`epoch`](Self::epoch) is recorded on the medium. For a
2789 /// replica that is pure waste: its entries are copies, and their provenance
2790 /// lives in the replication cursor, not in this log's sector headers. Left
2791 /// enabled it would burn a sector — and on a full ring, evict the oldest one
2792 /// — every single time the medium is inserted.
2793 ///
2794 /// [`Spooler::attach`](crate::spool::Spooler::attach) calls this, so a
2795 /// volume managed by a spooler needs no action. Call it directly only when
2796 /// maintaining a replica by hand.
2797 ///
2798 /// Takes effect for the current mount; call it again after each `mount`.
2799 pub fn mark_as_replica(&mut self) {
2800 self.state.epoch_pending = false;
2801 }
2802
2803 /// Consume the database and return the underlying flash storage.
2804 pub fn into_inner(self) -> F {
2805 self.flash
2806 }
2807}
2808
2809// =============================================================================
2810// SensorDbState — all non-flash state and helpers
2811// =============================================================================
2812
2813impl<const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbState<PAGE_SIZE, MAX_SECTORS> {
2814 // -------------------------------------------------------------------------
2815 // Pure state helpers (no flash parameter)
2816 // -------------------------------------------------------------------------
2817
2818 pub(crate) fn sector_offset(&self, sector_idx: u16) -> u32 {
2819 // Safety: `new()` validates that base_offset + sector_count * sector_size
2820 // fits in u32, so this cannot overflow for any valid sector_idx.
2821 self.base_offset + sector_idx as u32 * self.sector_size
2822 }
2823
2824 /// Offset within a sector of the reserved footer page.
2825 ///
2826 /// Doubles as the limit for entry data: everything from here to the end of
2827 /// the sector belongs to the [`SectorFooter`]
2828 /// written when the sector is sealed, so `append` must stop before it and
2829 /// every scan must be bounded by it.
2830 ///
2831 /// Cannot underflow: `new` rejects a sector smaller than three pages.
2832 pub(crate) fn footer_offset(&self) -> u32 {
2833 self.sector_size - PAGE_SIZE as u32
2834 }
2835
2836 /// Byte after the last byte of the database region.
2837 pub(crate) fn region_end(&self) -> u32 {
2838 self.base_offset + self.sector_count as u32 * self.sector_size
2839 }
2840
2841 /// Reject a region that intersects the database's own sectors.
2842 ///
2843 /// This is the check that turns the old "only touch addresses outside the
2844 /// database region" doc comment into something enforced. Shared by both
2845 /// drivers so the rule is stated once.
2846 pub(crate) fn check_disjoint(&self, base: u32, len: u32) -> Result<(), Error> {
2847 let end = (base as u64)
2848 .checked_add(len as u64)
2849 .ok_or(Error::Overflow)?;
2850 let (db_base, db_end) = (self.base_offset, self.region_end());
2851 if (base as u64) < db_end as u64 && (db_base as u64) < end {
2852 return Err(Error::RegionOverlap { db_base, db_end });
2853 }
2854 Ok(())
2855 }
2856
2857 /// Choose the sector to write into next.
2858 ///
2859 /// Pure selection — this mutates no counters. The caller applies
2860 /// [`account_eviction`](Self::account_eviction) *after* the erase succeeds,
2861 /// so a failed erase cannot leave the index claiming data is gone.
2862 pub(crate) fn find_next_sector(&mut self) -> Result<u16, Error> {
2863 // Tier 1: an already-erased sector, lowest erase count (wear levelling).
2864 // Tie-break: round-robin starting from active_sector + 1.
2865 let start = self
2866 .active_sector
2867 .map_or(0, |a| (a + 1) % self.sector_count);
2868 let mut best_idx: Option<u16> = None;
2869 let mut best_erase = u32::MAX;
2870 for offset in 0..self.sector_count {
2871 let i = (start + offset) % self.sector_count;
2872 let summary = &self.sectors[i as usize];
2873 if summary.state == SectorState::Erased && summary.erase_count < best_erase {
2874 best_erase = summary.erase_count;
2875 best_idx = Some(i);
2876 }
2877 }
2878 if let Some(idx) = best_idx {
2879 return Ok(idx);
2880 }
2881
2882 // No erased sectors — reclaim a sealed one, respecting reserved_sectors.
2883 let sealed_count: u16 = self.sectors[..self.sector_count as usize]
2884 .iter()
2885 .filter(|s| s.state == SectorState::Sealed)
2886 .count() as u16;
2887
2888 if sealed_count <= self.reserved_sectors {
2889 return Err(Error::NoSpace);
2890 }
2891
2892 // Tier 2: the oldest sealed sector whose contents are fully replicated.
2893 // Tier 3: the oldest sealed sector at all — this destroys data that was
2894 // never replicated, which `account_eviction` records as a loss.
2895 //
2896 // These select the same sector in every state reachable today, because
2897 // replication proceeds oldest-first and so the replicated set is always a
2898 // prefix of the ring by sequence. The tiers are written out anyway: they
2899 // make the choice explicit rather than incidental, and they are where a
2900 // refuse-to-overwrite policy would hook in.
2901 self.oldest_sealed(true)
2902 .or_else(|| self.oldest_sealed(false))
2903 .ok_or(Error::NoSpace)
2904 }
2905
2906 // -------------------------------------------------------------------------
2907 // Replication bookkeeping (pure; shared by both flavours)
2908 // -------------------------------------------------------------------------
2909
2910 pub(crate) fn head_position(&self) -> LogPosition {
2911 match self.active_sector {
2912 Some(idx) => LogPosition {
2913 sequence: self.sectors[idx as usize].sequence,
2914 offset: self.sectors[idx as usize].write_offset,
2915 },
2916 None => LogPosition::BEGINNING,
2917 }
2918 }
2919
2920 pub(crate) fn tail_position(&self) -> LogPosition {
2921 let mut oldest: Option<u32> = None;
2922 for i in 0..self.sector_count {
2923 let summary = &self.sectors[i as usize];
2924 if summary.state != SectorState::Erased
2925 && oldest.is_none_or(|seq| summary.sequence < seq)
2926 {
2927 oldest = Some(summary.sequence);
2928 }
2929 }
2930 match oldest {
2931 Some(sequence) => LogPosition {
2932 sequence,
2933 offset: SECTOR_HEADER_SIZE as u32,
2934 },
2935 None => LogPosition::BEGINNING,
2936 }
2937 }
2938
2939 pub(crate) fn note_spooled(&mut self, upto: LogPosition, moved: Replicated) {
2940 if upto <= self.spool_watermark {
2941 return;
2942 }
2943 self.spool_watermark = upto;
2944 self.add_spooled(moved);
2945 }
2946
2947 /// Index of the retained sector carrying `sequence`, if the ring still holds it.
2948 pub(crate) fn sector_at_sequence(&self, sequence: u32) -> Option<u16> {
2949 (0..self.sector_count).find(|i| {
2950 let summary = &self.sectors[*i as usize];
2951 summary.state != SectorState::Erased && summary.sequence == sequence
2952 })
2953 }
2954
2955 /// Set the watermark and recompute accounting from whole sectors alone.
2956 ///
2957 /// Returns the sector the watermark falls *inside*, whose entries below it
2958 /// this cannot count from the in-RAM index — sector summaries record how many
2959 /// entries a sector holds, not where each one starts. Refining that is one
2960 /// bounded scan, which only the flash-holding caller can perform; until it
2961 /// does, the accounting under-reports what has been replicated, which is the
2962 /// safe direction.
2963 pub(crate) fn restore_spool_watermark(&mut self, upto: LogPosition) -> Option<u16> {
2964 if upto <= self.spool_watermark {
2965 return None;
2966 }
2967 self.spool_watermark = upto;
2968 self.spooled_entries = self.spooled_in_whole_sectors().min(self.total_entries);
2969 self.spooled_samples = self
2970 .spooled_samples_in_whole_sectors()
2971 .min(self.total_samples);
2972
2973 // The sector the watermark falls inside, if it holds anything below it.
2974 self.sector_at_sequence(upto.sequence).filter(|i| {
2975 upto.offset > SECTOR_HEADER_SIZE as u32 && self.sectors[*i as usize].entry_count > 0
2976 })
2977 }
2978
2979 /// Credit more as replicated, never past what the log still holds.
2980 pub(crate) fn add_spooled(&mut self, moved: Replicated) {
2981 self.spooled_entries = self
2982 .spooled_entries
2983 .saturating_add(moved.entries)
2984 .min(self.total_entries);
2985 self.spooled_samples = self
2986 .spooled_samples
2987 .saturating_add(moved.samples)
2988 .min(self.total_samples);
2989 }
2990
2991 pub(crate) fn spool_stats(&self) -> SpoolStats {
2992 SpoolStats {
2993 unspooled_entries: self.total_entries.saturating_sub(self.spooled_entries),
2994 unspooled_samples: self.total_samples.saturating_sub(self.spooled_samples),
2995 watermark: self.spool_watermark,
2996 head: self.head_position(),
2997 dropped_unspooled: self.dropped_unspooled,
2998 data_lost: self.dropped_unspooled > 0,
2999 }
3000 }
3001
3002 /// First byte of the page buffer that flash does not yet have.
3003 ///
3004 /// Everything below `page_buf_durable` is on flash; everything from here to
3005 /// `page_buf_offset` exists only in RAM.
3006 ///
3007 /// The flags byte deliberately plays no part. `flush_page` sets flags to
3008 /// committed in the buffer *before* writing it, so a commit pass that failed
3009 /// leaves entries marked committed in RAM while flash still has them
3010 /// uncommitted — invisible to a later `mount`. Trusting the flag would
3011 /// silently skip exactly the entries this boundary exists to identify.
3012 fn unflushed_start(&self) -> usize {
3013 self.page_buf_scan_start().max(self.page_buf_durable)
3014 }
3015
3016 /// Walk the RAM-only tail of the page buffer without changing it.
3017 ///
3018 /// Stops at the first byte that is not the start of a whole entry, which is
3019 /// how a partially written tail is bounded.
3020 /// Walks *entries*, not samples: this is the replication and rescue side,
3021 /// where a run must stay a run so the copy keeps its amortisation.
3022 fn walk_unflushed<C>(&self, mut callback: C) -> Result<Replicated, Error>
3023 where
3024 C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
3025 {
3026 let end = self.page_buf_offset;
3027 let mut seen = Replicated::NONE;
3028 let mut pos = self.unflushed_start();
3029 while let Some(entry) = self.next_buffered(&mut pos, end) {
3030 let payload = self.buffered_payload(&entry);
3031 callback(&entry.header.to_header(), payload)?;
3032 seen.push(samples_in(entry.is_run(), payload));
3033 }
3034 Ok(seen)
3035 }
3036
3037 pub(crate) fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
3038 where
3039 C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
3040 {
3041 if !self.mounted {
3042 return Err(Error::NotMounted);
3043 }
3044 Ok(self.walk_unflushed(callback)?.entries)
3045 }
3046
3047 pub(crate) fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
3048 where
3049 C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
3050 {
3051 if !self.mounted {
3052 return Err(Error::NotMounted);
3053 }
3054
3055 let scan_start = self.unflushed_start();
3056 let end = self.page_buf_offset;
3057 if scan_start >= end {
3058 return Ok(0);
3059 }
3060
3061 let drained = self.walk_unflushed(callback)?;
3062 if drained.entries == 0 {
3063 return Ok(0);
3064 }
3065 let truncate_to = scan_start;
3066
3067 // Drop the non-durable suffix from the page buffer and undo its
3068 // contribution to the in-RAM index.
3069 let bytes_dropped = (end - truncate_to) as u32;
3070 self.page_buf[truncate_to..].fill(0xFF);
3071 self.page_buf_offset = truncate_to;
3072
3073 if let Some(active_idx) = self.active_sector {
3074 let summary = &mut self.sectors[active_idx as usize];
3075 summary.entry_count = summary.entry_count.saturating_sub(drained.entries);
3076 summary.sample_count = summary.sample_count.saturating_sub(drained.samples);
3077 summary.write_offset = summary.write_offset.saturating_sub(bytes_dropped);
3078 }
3079 self.total_entries = self.total_entries.saturating_sub(drained.entries);
3080 self.total_samples = self.total_samples.saturating_sub(drained.samples);
3081
3082 Ok(drained.entries)
3083 }
3084
3085 /// Index of the oldest sealed sector, optionally restricted to sectors whose
3086 /// contents are fully replicated.
3087 fn oldest_sealed(&self, require_spooled: bool) -> Option<u16> {
3088 let mut oldest_idx = None;
3089 let mut oldest_seq = u32::MAX;
3090 for i in 0..self.sector_count {
3091 let summary = &self.sectors[i as usize];
3092 if summary.state != SectorState::Sealed || summary.sequence >= oldest_seq {
3093 continue;
3094 }
3095 if require_spooled && !self.is_fully_spooled(summary) {
3096 continue;
3097 }
3098 oldest_seq = summary.sequence;
3099 oldest_idx = Some(i);
3100 }
3101 oldest_idx
3102 }
3103
3104 // -------------------------------------------------------------------------
3105 // Page buffer scanning helpers (flush-free reads, no flash needed)
3106 // -------------------------------------------------------------------------
3107
3108 /// Returns the starting offset within `page_buf` for entry scanning.
3109 pub(crate) fn page_buf_scan_start(&self) -> usize {
3110 let active_idx = match self.active_sector {
3111 Some(idx) => idx,
3112 None => return self.page_buf_offset, // no active sector, nothing to scan
3113 };
3114 if self.page_flash_offset == self.sector_offset(active_idx) {
3115 SECTOR_HEADER_SIZE
3116 } else {
3117 0
3118 }
3119 }
3120
3121 /// Step the cursor `pos` over one whole entry in the page buffer.
3122 ///
3123 /// Returns `None` at the first byte that does not begin one, which is how a
3124 /// partially written tail is bounded — and is why every page-buffer walk
3125 /// goes through here rather than repeating the arithmetic. Committed entries
3126 /// are returned too: whether to skip them differs by caller (a reader has
3127 /// them from flash already; a rescue must not assume flash does).
3128 fn next_buffered(&self, pos: &mut usize, end: usize) -> Option<BufferedEntry> {
3129 if *pos + ENTRY_HEADER_SIZE > end || !is_entry_marker(self.page_buf[*pos]) {
3130 return None;
3131 }
3132 let header =
3133 EntryHeaderWire::read_from_bytes(&self.page_buf[*pos..*pos + ENTRY_HEADER_SIZE])
3134 .ok()?;
3135 let payload_len = header.payload_len.get() as usize;
3136 if *pos + ENTRY_OVERHEAD + payload_len > end {
3137 return None;
3138 }
3139 let payload_start = *pos + ENTRY_HEADER_SIZE;
3140 *pos += ENTRY_OVERHEAD + payload_len;
3141 Some(BufferedEntry {
3142 header,
3143 payload_start,
3144 payload_len,
3145 })
3146 }
3147
3148 /// The payload of a buffered entry.
3149 fn buffered_payload(&self, entry: &BufferedEntry) -> &[u8] {
3150 &self.page_buf[entry.payload_start..entry.payload_start + entry.payload_len]
3151 }
3152
3153 /// The sample at one `edge` of a buffered entry, and the header it would
3154 /// have carried had it been appended alone.
3155 fn buffered_sample(&self, entry: &BufferedEntry, edge: Edge) -> (EntryHeader, BufferedSample) {
3156 let located = |run| BufferedSample {
3157 payload_start: entry.payload_start,
3158 payload_len: entry.payload_len,
3159 run,
3160 };
3161
3162 match RunFrame::parse(self.buffered_payload(entry)).filter(|_| entry.is_run()) {
3163 Some(frame) => {
3164 let index = match edge {
3165 Edge::First => 0,
3166 Edge::Last => frame.count() - 1,
3167 };
3168 (
3169 frame.header_at(entry.sensor_id(), entry.timestamp(), index),
3170 located(Some((frame, index))),
3171 )
3172 }
3173 None => (entry.header.to_header(), located(None)),
3174 }
3175 }
3176
3177 /// Write a located sample into `out` as a schema-tagged payload.
3178 fn copy_buffered_sample(
3179 &self,
3180 sample: &BufferedSample,
3181 out: &mut [u8],
3182 ) -> Result<usize, Error> {
3183 let payload =
3184 &self.page_buf[sample.payload_start..sample.payload_start + sample.payload_len];
3185 match sample.run {
3186 Some((frame, index)) => frame
3187 .write_tagged_sample(payload, index, out)
3188 .ok_or(Error::BufferTooSmall),
3189 None => {
3190 if payload.len() > out.len() {
3191 return Err(Error::BufferTooSmall);
3192 }
3193 out[..payload.len()].copy_from_slice(payload);
3194 Ok(payload.len())
3195 }
3196 }
3197 }
3198
3199 /// The newest unflushed entry for a sensor, if it beats `min_ts`.
3200 ///
3201 /// Reports `BufferTooSmall` when the winner does not fit `buf`, matching
3202 /// [`find_latest_in_sector`](Self::find_latest_in_sector). Skipping it
3203 /// instead — as this used to — meant a caller with a small buffer was
3204 /// handed an *older* entry, or `None`, and told it was the latest.
3205 pub(crate) fn scan_page_buf_for_latest(
3206 &self,
3207 sensor_id: u16,
3208 min_ts: u64,
3209 buf: &mut [u8],
3210 ) -> Result<Option<(EntryHeader, usize)>, Error> {
3211 let scan_start = self.page_buf_scan_start();
3212 if scan_start >= self.page_buf_offset {
3213 return Ok(None);
3214 }
3215
3216 let mut best: Option<(EntryHeader, BufferedSample)> = None;
3217 let mut best_ts: u64 = min_ts;
3218 let mut pos = scan_start;
3219
3220 while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3221 // Skip committed entries — they are already on flash
3222 if entry.is_committed() || entry.sensor_id() != sensor_id {
3223 continue;
3224 }
3225
3226 // The buffer bound is deliberately *not* part of this test: an
3227 // entry that wins on timestamp wins, and its size is reported
3228 // below rather than letting an older entry take its place.
3229 let (header, sample) = self.buffered_sample(&entry, Edge::Last);
3230 if header.timestamp >= best_ts {
3231 best_ts = header.timestamp;
3232 best = Some((header, sample));
3233 }
3234 }
3235
3236 // Copy payload only for the final winner
3237 let Some((header, sample)) = best else {
3238 return Ok(None);
3239 };
3240 let len = self.copy_buffered_sample(&sample, buf)?;
3241 Ok(Some((header, len)))
3242 }
3243
3244 /// Deliver unflushed samples in a time range.
3245 ///
3246 /// `scratch` receives a copy of each entry's payload, because
3247 /// [`deliver_samples`] frames a run's samples by writing through the buffer
3248 /// it is given and the page buffer is behind a shared reference. The caller
3249 /// lends the same buffer the sector scan used, so this costs no stack.
3250 pub(crate) fn scan_page_buf_for_query<C>(
3251 &self,
3252 sensor_filter: Option<u16>,
3253 t_start: u64,
3254 t_end: u64,
3255 scratch: &mut [u8],
3256 count: &mut u32,
3257 callback: &mut C,
3258 ) -> bool
3259 where
3260 C: FnMut(&EntryHeader, &[u8]) -> bool,
3261 {
3262 let mut pos = self.page_buf_scan_start();
3263
3264 while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3265 // Skip committed entries — already visible via flash reads
3266 let sensor = entry.sensor_id();
3267 if entry.is_committed() || sensor_filter.is_some_and(|f| f != sensor) {
3268 continue;
3269 }
3270
3271 let payload = self.buffered_payload(&entry);
3272 // Cannot fail: `scratch` is a page and a payload is smaller.
3273 let Some(dst) = scratch.get_mut(..payload.len()) else {
3274 continue;
3275 };
3276 dst.copy_from_slice(payload);
3277
3278 if deliver_samples(
3279 entry.is_run(),
3280 sensor,
3281 entry.timestamp(),
3282 dst,
3283 t_start,
3284 t_end,
3285 count,
3286 callback,
3287 ) {
3288 return true; // stopped early
3289 }
3290 }
3291
3292 false
3293 }
3294
3295 pub(crate) fn scan_page_buf_for_oldest(
3296 &self,
3297 sensor_id: u16,
3298 buf: &mut [u8],
3299 ) -> Option<(EntryHeader, usize)> {
3300 let mut pos = self.page_buf_scan_start();
3301
3302 while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3303 // Skip committed entries — already visible via flash reads
3304 if entry.is_committed() || entry.sensor_id() != sensor_id {
3305 continue;
3306 }
3307
3308 let (header, sample) = self.buffered_sample(&entry, Edge::First);
3309 if let Ok(len) = self.copy_buffered_sample(&sample, buf) {
3310 return Some((header, len));
3311 }
3312 }
3313
3314 None
3315 }
3316
3317 pub(crate) fn count_sensor_in_page_buf(&self, sensor_id: u16) -> u32 {
3318 let mut count = 0u32;
3319 let mut pos = self.page_buf_scan_start();
3320
3321 while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3322 // Skip committed entries — already counted via sector scanning
3323 if entry.is_committed() || entry.sensor_id() != sensor_id {
3324 continue;
3325 }
3326 count += samples_in(entry.is_run(), self.buffered_payload(&entry));
3327 }
3328
3329 count
3330 }
3331
3332 // -------------------------------------------------------------------------
3333 // Flash-accessing helpers (take explicit `flash: &mut F` parameter)
3334 // -------------------------------------------------------------------------
3335
3336 fn erase_sector<F: NorFlash>(&mut self, flash: &mut F, sector_idx: u16) -> Result<(), Error> {
3337 let offset = self.sector_offset(sector_idx);
3338 flash.erase(offset, offset + self.sector_size)?;
3339 // After the erase, so the count is of sectors actually erased. A failure
3340 // reaches the caller as an error, which is a louder signal than this.
3341 self.sectors_erased = self.sectors_erased.saturating_add(1);
3342 Ok(())
3343 }
3344
3345 fn init_sector<F: NorFlash>(
3346 &self,
3347 flash: &mut F,
3348 sector_idx: u16,
3349 sequence: u32,
3350 erase_count: u32,
3351 ) -> Result<(), Error> {
3352 let header = self.sector_header(sequence, erase_count);
3353 let offset = self.sector_offset(sector_idx);
3354
3355 // Write header (padded to page size)
3356 let mut page = [0xFFu8; PAGE_SIZE];
3357 page[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
3358 flash.write(offset, &page)?;
3359
3360 Ok(())
3361 }
3362
3363 /// Read and validate the footer of `sector_idx`.
3364 ///
3365 /// Returns `None` for anything that does not describe this sector's current
3366 /// incarnation — an erased page, a torn write, a stale summary — which the
3367 /// caller answers with a body scan.
3368 fn read_sector_footer<F: ReadNorFlash>(
3369 &self,
3370 flash: &mut F,
3371 sector_idx: u16,
3372 ) -> Result<Option<SectorFooter>, Error> {
3373 let offset = self.sector_offset(sector_idx) + self.footer_offset();
3374 let mut buf = [0u8; SECTOR_FOOTER_SIZE];
3375 flash.read(offset, &mut buf)?;
3376
3377 let footer = SectorFooter::read_from_bytes(&buf).map_err(|_| Error::CorruptEntry)?;
3378 let sequence = self.sectors[sector_idx as usize].sequence;
3379 Ok(footer.describes(sequence).then_some(footer))
3380 }
3381
3382 /// Write `sector_idx`'s summary into its reserved final page.
3383 ///
3384 /// Called once per sector, when it is sealed and its contents are final.
3385 fn write_sector_footer<F: NorFlash>(
3386 &self,
3387 flash: &mut F,
3388 sector_idx: u16,
3389 ) -> Result<(), Error> {
3390 // Nothing buffered may be missing from the summary being frozen. Every
3391 // path into `seal_and_advance` either has just flushed or is holding a
3392 // page whose contents are already on flash, so this holds — but it is
3393 // the invariant the footer's correctness rests on, so state it.
3394 debug_assert_eq!(
3395 self.page_buf_offset, self.page_buf_durable,
3396 "a sector is sealed only with a page buffer that flash already has"
3397 );
3398
3399 let footer = SectorFooter::new(&self.sectors[sector_idx as usize]);
3400 let mut page = [0xFFu8; PAGE_SIZE];
3401 page[..SECTOR_FOOTER_SIZE].copy_from_slice(footer.as_bytes());
3402 flash.write(self.sector_offset(sector_idx) + self.footer_offset(), &page)?;
3403 Ok(())
3404 }
3405
3406 /// What must happen before an entry of `entry_size` bytes can be staged.
3407 ///
3408 /// The sector-room test comes first and subsumes the old separate
3409 /// "cursor sat on the data boundary" pre-check: a page never straddles the
3410 /// footer, so whenever an entry fits the *current page* the sector has at
3411 /// least `PAGE_SIZE` left, and the only way `sector_remaining` can fall
3412 /// short is the cursor having already passed the boundary — which is
3413 /// precisely the case that pre-check existed for.
3414 pub(crate) fn plan_append(&self, entry_size: usize) -> Result<AppendStep, Error> {
3415 let active = self.active_sector.ok_or(Error::NoSpace)?;
3416
3417 // Against the footer offset, not the sector size: the last page is
3418 // reserved for the summary written at seal time.
3419 let used = self.page_flash_offset - self.sector_offset(active);
3420 let sector_remaining = self.footer_offset().saturating_sub(used) as usize;
3421
3422 if sector_remaining < entry_size || sector_remaining < ENTRY_OVERHEAD {
3423 return Ok(AppendStep::Seal);
3424 }
3425
3426 if entry_size > PAGE_SIZE - self.page_buf_offset {
3427 return Ok(AppendStep::FlushPage);
3428 }
3429
3430 Ok(AppendStep::Stage)
3431 }
3432
3433 /// Write the entry into the page buffer and record it in the sector index.
3434 ///
3435 /// Pure, and only correct once [`plan_append`](Self::plan_append) has
3436 /// answered [`Stage`](AppendStep::Stage).
3437 ///
3438 /// The payload arrives in two pieces so a run costs no staging buffer — the
3439 /// frame header and the sample bytes go straight into the page buffer, which
3440 /// is also where the entry CRC is then computed from.
3441 #[allow(clippy::too_many_arguments)]
3442 pub(crate) fn stage_entry(
3443 &mut self,
3444 kind: EntryKind,
3445 sensor_id: u16,
3446 timestamp: u64,
3447 span_end: u64,
3448 samples: u32,
3449 head: &[u8],
3450 tail: &[u8],
3451 ) -> Result<(), Error> {
3452 let payload_len = head.len() + tail.len();
3453 let entry_size = ENTRY_OVERHEAD + payload_len;
3454
3455 let header = match kind {
3456 EntryKind::Single => EntryHeaderWire::new(sensor_id, timestamp, payload_len as u16),
3457 EntryKind::Run => EntryHeaderWire::new_run(sensor_id, timestamp, payload_len as u16),
3458 };
3459
3460 // Compute offset_in_sector for CRC: where this entry sits within its sector
3461 let active_idx = self.active_sector.ok_or(Error::NoSpace)?;
3462 let sector_offset = self.sector_offset(active_idx);
3463 let offset_in_sector =
3464 (self.page_flash_offset - sector_offset) + self.page_buf_offset as u32;
3465
3466 // The payload is assembled in the page buffer first, so the CRC is
3467 // computed over one contiguous slice however many pieces it arrived in.
3468 let offset = self.page_buf_offset;
3469 let body = offset + ENTRY_HEADER_SIZE;
3470 self.page_buf[offset..body].copy_from_slice(header.as_bytes());
3471 self.page_buf[body..body + head.len()].copy_from_slice(head);
3472 self.page_buf[body + head.len()..body + payload_len].copy_from_slice(tail);
3473
3474 let crc = compute_entry_crc(
3475 &header,
3476 &self.page_buf[body..body + payload_len],
3477 offset_in_sector,
3478 );
3479 self.page_buf[body + payload_len..offset + entry_size].copy_from_slice(&crc.to_le_bytes());
3480
3481 self.page_buf_offset += entry_size;
3482
3483 // Update sector summary
3484 let summary = &mut self.sectors[active_idx as usize];
3485 summary.entry_count += 1;
3486 summary.sample_count += samples;
3487 summary.write_offset += entry_size as u32;
3488 summary.record_span(timestamp, span_end);
3489 summary.record_sensor(sensor_id);
3490 self.total_entries += 1;
3491 self.total_samples += samples;
3492
3493 Ok(())
3494 }
3495
3496 /// Where the page buffer must be written, or `None` if there is nothing to
3497 /// flush.
3498 ///
3499 /// The three `commit_*`/`*_page` helpers exist so both drivers can express
3500 /// the two-phase commit as *write, mark, write, advance* without either of
3501 /// them restating what marking or advancing means.
3502 pub(crate) fn commit_target(&self) -> Option<u32> {
3503 (self.page_buf_offset > 0).then_some(self.page_flash_offset)
3504 }
3505
3506 /// Flip the buffered entries' flags to committed, in RAM.
3507 ///
3508 /// Phase 2 of the two-phase commit: the caller re-writes the same page
3509 /// afterwards, which only clears bits (1→0) and so needs no erase.
3510 ///
3511 /// Note this makes the buffer claim a durability flash does not yet have —
3512 /// which is exactly why `page_buf_durable`, and not the flags byte, is what
3513 /// [`drain_unflushed`](Self::drain_unflushed) trusts.
3514 pub(crate) fn mark_page_committed(&mut self) {
3515 let scan_start =
3516 if self.page_flash_offset == self.sector_offset(self.active_sector.unwrap_or(0)) {
3517 // First page of sector: entries start after the sector header
3518 SECTOR_HEADER_SIZE
3519 } else {
3520 0
3521 };
3522
3523 let mut pos = scan_start;
3524 while pos + ENTRY_HEADER_SIZE <= self.page_buf_offset {
3525 if is_entry_marker(self.page_buf[pos]) {
3526 // Set flags byte to COMMITTED (0x00)
3527 self.page_buf[pos + 1] = FLAGS_COMMITTED;
3528
3529 // Skip past this entry
3530 let payload_len =
3531 u16::from_le_bytes([self.page_buf[pos + 12], self.page_buf[pos + 13]]) as usize;
3532 let entry_size = ENTRY_OVERHEAD + payload_len;
3533 pos += entry_size;
3534 } else {
3535 break;
3536 }
3537 }
3538 }
3539
3540 /// Move past the page just made durable and empty the buffer.
3541 pub(crate) fn advance_page(&mut self) {
3542 self.page_flash_offset += PAGE_SIZE as u32;
3543 self.page_buf.fill(0xFF);
3544 self.page_buf_offset = 0;
3545 self.page_buf_durable = 0;
3546
3547 // Update the sector's write_offset to reflect the new page boundary
3548 // so that subsequent appends and reads see the correct position
3549 if let Some(active_idx) = self.active_sector {
3550 let sector_offset = self.sector_offset(active_idx);
3551 self.sectors[active_idx as usize].write_offset = self.page_flash_offset - sector_offset;
3552 }
3553 }
3554
3555 fn flush_page<F: NorFlash>(&mut self, flash: &mut F) -> Result<(), Error> {
3556 let Some(addr) = self.commit_target() else {
3557 return Ok(());
3558 };
3559 // Phase 1: the entries still carry flags=0xFF (uncommitted).
3560 flash.write(addr, &self.page_buf)?;
3561 // Phase 2: mark, then re-write the same page.
3562 self.mark_page_committed();
3563 flash.write(addr, &self.page_buf)?;
3564 self.advance_page();
3565 Ok(())
3566 }
3567
3568 /// Sector-index statistics.
3569 ///
3570 /// Pure — both drivers forward to this rather than each walking the sector
3571 /// array themselves, which they used to do in 30 identical lines apiece.
3572 pub(crate) fn stats(&self) -> DbStats {
3573 let mut used = 0u16;
3574 let mut free = 0u16;
3575 let mut min_erase = u32::MAX;
3576 let mut max_erase = 0u32;
3577 let mut total_erase = 0u64;
3578
3579 for i in 0..self.sector_count as usize {
3580 let ec = self.sectors[i].erase_count;
3581 if ec < min_erase {
3582 min_erase = ec;
3583 }
3584 if ec > max_erase {
3585 max_erase = ec;
3586 }
3587 total_erase += ec as u64;
3588 match self.sectors[i].state {
3589 SectorState::Erased => free += 1,
3590 SectorState::Active | SectorState::Sealed => used += 1,
3591 }
3592 }
3593
3594 if self.sector_count == 0 {
3595 min_erase = 0;
3596 }
3597
3598 DbStats {
3599 total_entries: self.total_entries,
3600 total_samples: self.total_samples,
3601 used_sectors: used,
3602 free_sectors: free,
3603 reserved_sectors: self.reserved_sectors,
3604 min_erase_count: min_erase,
3605 max_erase_count: max_erase,
3606 total_erase_count: total_erase,
3607 }
3608 }
3609
3610 /// Whether this mount mode wants a footer read for this sector.
3611 ///
3612 /// The newest sector's footer is read in **every** mode: there it is not an
3613 /// optimisation but the signal that the sector is already sealed, and
3614 /// appending into it would make its frozen summary a lie.
3615 pub(crate) fn wants_footer(&self, mode: MountMode, is_newest: bool) -> bool {
3616 mode == MountMode::Full || is_newest
3617 }
3618
3619 /// Index a sector from its footer.
3620 pub(crate) fn adopt_footer(&mut self, i: u16, footer: &SectorFooter, stats: &mut MountStats) {
3621 footer.apply_to(&mut self.sectors[i as usize]);
3622 stats.total_entries += footer.entry_count.get();
3623 stats.total_samples += footer.sample_count.get();
3624 }
3625
3626 /// Index a sector from a body scan.
3627 pub(crate) fn adopt_scan(
3628 &mut self,
3629 i: u16,
3630 scanned: &ScannedSector,
3631 corrupt: u32,
3632 stats: &mut MountStats,
3633 ) {
3634 scanned.apply_to(&mut self.sectors[i as usize]);
3635 stats.total_entries += scanned.entries;
3636 stats.total_samples += scanned.samples;
3637 stats.corrupt_entries += corrupt;
3638 stats.scanned_sectors += 1;
3639 }
3640
3641 /// Record a sector known to exist and be sealed, but not indexed.
3642 ///
3643 /// `HeadersOnly` with no footer. `write_offset` covers the whole data region
3644 /// so a later `read_from` still streams it end to end, and the bounds are
3645 /// set wide open so nothing prunes it.
3646 pub(crate) fn adopt_unindexed(&mut self, i: u16) {
3647 let data_limit = self.footer_offset();
3648 let summary = &mut self.sectors[i as usize];
3649 summary.entry_count = 0;
3650 summary.sample_count = 0;
3651 summary.write_offset = data_limit;
3652 summary.min_timestamp = 0;
3653 summary.max_timestamp = u64::MAX;
3654 summary.sensor_bloom = u64::MAX;
3655 }
3656
3657 /// Adopt the totals a mount established, before the active sector is chosen.
3658 pub(crate) fn finish_mount(
3659 &mut self,
3660 mode: MountMode,
3661 max_sequence: u32,
3662 max_epoch: u32,
3663 stats: &MountStats,
3664 ) {
3665 self.total_entries = stats.total_entries;
3666 self.total_samples = stats.total_samples;
3667 self.next_sequence = max_sequence + 1;
3668 self.epoch = max_epoch.saturating_add(1);
3669 self.mount_mode = mode;
3670 // The replica holds the replication watermark, not this log. Until it is
3671 // restored, everything reads as un-replicated — the safe direction.
3672 self.spool_watermark = LogPosition::BEGINNING;
3673 self.spooled_entries = 0;
3674 self.spooled_samples = 0;
3675 self.dropped_unspooled = 0;
3676 }
3677
3678 /// The sector a seal is about to close.
3679 pub(crate) fn sealing(&self) -> Result<u16, Error> {
3680 self.active_sector.ok_or(Error::NoSpace)
3681 }
3682
3683 /// Seal the active sector and choose its successor.
3684 ///
3685 /// **Order is load-bearing.** Marking `old_active` sealed has to happen
3686 /// before [`find_next_sector`](Self::find_next_sector), which counts sealed
3687 /// sectors against `reserved_sectors` and may pick this very one as the
3688 /// victim. Call this only *after* the footer write, which is where the
3689 /// blocking driver had it.
3690 pub(crate) fn begin_seal(&mut self, old_active: u16) -> Result<SealPlan, Error> {
3691 // Seal current sector
3692 self.sectors[old_active as usize].state = SectorState::Sealed;
3693
3694 // Find next sector: prefer erased, otherwise erase oldest sealed
3695 let new_active = self.find_next_sector()?;
3696
3697 // Snapshot the victim before anything touches it: if it was sealed, its
3698 // entries are about to be destroyed and must be accounted for.
3699 let victim = self.sectors[new_active as usize];
3700
3701 // Increment erase count from the target sector (preserving wear history)
3702 let erase_count = victim.erase_count.saturating_add(1);
3703
3704 Ok(SealPlan {
3705 new_active,
3706 erase_count,
3707 victim,
3708 })
3709 }
3710
3711 /// Charge the ring for what the erase just destroyed.
3712 ///
3713 /// Must follow a **successful** erase. Doing it earlier would leave the
3714 /// index claiming a loss that never happened if `erase` failed.
3715 pub(crate) fn account_seal(&mut self, plan: &SealPlan) {
3716 if plan.victim.state == SectorState::Sealed {
3717 self.account_eviction(&plan.victim);
3718 }
3719 }
3720
3721 /// Adopt the freshly initialised sector, after its header has been written.
3722 pub(crate) fn finish_seal(&mut self, plan: &SealPlan) {
3723 // That header carries the current epoch, so any debt from `mount` is paid.
3724 self.epoch_pending = false;
3725
3726 self.sectors[plan.new_active as usize] = SectorSummary {
3727 state: SectorState::Active,
3728 sequence: self.next_sequence,
3729 entry_count: 0,
3730 sample_count: 0,
3731 write_offset: SECTOR_HEADER_SIZE as u32,
3732 min_timestamp: u64::MAX,
3733 max_timestamp: 0,
3734 sensor_bloom: 0,
3735 erase_count: plan.erase_count,
3736 };
3737
3738 self.active_sector = Some(plan.new_active);
3739 self.next_sequence += 1;
3740
3741 // Reset page buffer
3742 let sector_offset = self.sector_offset(plan.new_active);
3743 self.page_flash_offset = sector_offset;
3744 self.page_buf.fill(0xFF);
3745 let header = self.sector_header(
3746 self.sectors[plan.new_active as usize].sequence,
3747 plan.erase_count,
3748 );
3749 self.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
3750 self.page_buf_offset = SECTOR_HEADER_SIZE;
3751 self.page_buf_durable = SECTOR_HEADER_SIZE;
3752 }
3753
3754 fn seal_and_advance<F: NorFlash>(&mut self, flash: &mut F) -> Result<(), Error> {
3755 let old_active = self.sealing()?;
3756
3757 // The sector's contents are final, so record its summary in the
3758 // reserved final page: that is what lets the next mount index it with a
3759 // single page read instead of a body scan.
3760 //
3761 // A failure here is deliberately not propagated. The footer is an
3762 // optimisation and must never make the log less usable than it would be
3763 // without one — and the failure that matters is exactly the persistent
3764 // kind. A footer page left dirty by an earlier torn write answers
3765 // `NotErased` forever, which would wedge every subsequent append for the
3766 // sake of metadata a body scan reconstructs anyway. Flash that is
3767 // genuinely broken still reports it: the erase and header write below
3768 // are on the same device and are not forgiving.
3769 let _ = self.write_sector_footer(flash, old_active);
3770
3771 let plan = self.begin_seal(old_active)?;
3772 self.erase_sector(flash, plan.new_active)?;
3773 self.account_seal(&plan);
3774 self.init_sector(flash, plan.new_active, self.next_sequence, plan.erase_count)?;
3775 self.finish_seal(&plan);
3776
3777 Ok(())
3778 }
3779
3780 fn scan_sector_entries<F: ReadNorFlash>(
3781 &mut self,
3782 flash: &mut F,
3783 sector_idx: u16,
3784 ) -> Result<(ScannedSector, u32), Error> {
3785 let sector_offset = self.sector_offset(sector_idx);
3786 let entry_start = SECTOR_HEADER_SIZE as u32;
3787 // Bounded by the footer offset, not the sector size: the final page
3788 // holds a summary, not entries.
3789 let mut scanner = SectorScanner::new(sector_offset, entry_start, self.footer_offset());
3790 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3791 let mut buf = [0u8; PAGE_SIZE];
3792
3793 let mut found = ScannedSector {
3794 write_offset: entry_start,
3795 ..ScannedSector::EMPTY
3796 };
3797
3798 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3799 if !accept_entry(flash, sector_offset, &entry, &mut buf)? {
3800 scanner.corrupt_count += 1;
3801 scanner.skip(1);
3802 continue;
3803 }
3804
3805 found.record(&entry, &buf[..entry.payload_len]);
3806
3807 scanner.skip(entry.entry_size);
3808 found.write_offset = scanner.offset();
3809 }
3810
3811 Ok((found, scanner.corrupt_count()))
3812 }
3813
3814 fn find_latest_in_sector<F: ReadNorFlash>(
3815 &self,
3816 flash: &mut F,
3817 sector_idx: u16,
3818 target_sensor: u16,
3819 buf: &mut [u8],
3820 ) -> Result<Option<(EntryHeader, usize)>, Error> {
3821 let sector_offset = self.sector_offset(sector_idx);
3822 let write_offset = self.sectors[sector_idx as usize].write_offset;
3823 let entry_start = SECTOR_HEADER_SIZE as u32;
3824 let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
3825 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3826 let mut payload_buf = [0u8; PAGE_SIZE];
3827
3828 let mut latest: Option<(EntryHeader, usize)> = None;
3829 let mut latest_ts = 0u64;
3830
3831 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3832 if !accept_entry(flash, sector_offset, &entry, &mut payload_buf)? {
3833 scanner.skip(1);
3834 continue;
3835 }
3836
3837 if entry.sensor_id() == target_sensor {
3838 let (header, payload) =
3839 entry.edge(&mut payload_buf[..entry.payload_len], Edge::Last);
3840
3841 if header.timestamp >= latest_ts {
3842 let len = payload.len();
3843 if len > buf.len() {
3844 return Err(Error::BufferTooSmall);
3845 }
3846 buf[..len].copy_from_slice(payload);
3847 latest_ts = header.timestamp;
3848 latest = Some((header, len));
3849 }
3850 }
3851
3852 scanner.skip(entry.entry_size);
3853 }
3854
3855 Ok(latest)
3856 }
3857
3858 #[allow(clippy::too_many_arguments)]
3859 fn scan_sector_for_query<F: ReadNorFlash, C>(
3860 &self,
3861 flash: &mut F,
3862 sector_idx: u16,
3863 sensor_filter: Option<u16>,
3864 t_start: u64,
3865 t_end: u64,
3866 buf: &mut [u8],
3867 count: &mut u32,
3868 callback: &mut C,
3869 ) -> Result<bool, Error>
3870 where
3871 C: FnMut(&EntryHeader, &[u8]) -> bool,
3872 {
3873 let sector_offset = self.sector_offset(sector_idx);
3874 let write_offset = self.sectors[sector_idx as usize].write_offset;
3875 let entry_start = SECTOR_HEADER_SIZE as u32;
3876 let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
3877 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3878
3879 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3880 if !accept_entry(flash, sector_offset, &entry, buf)? {
3881 scanner.skip(1);
3882 continue;
3883 }
3884
3885 let sensor = entry.sensor_id();
3886 let base = entry.timestamp();
3887
3888 if sensor_filter.is_none_or(|f| f == sensor)
3889 && deliver_samples(
3890 entry.is_run(),
3891 sensor,
3892 base,
3893 &mut buf[..entry.payload_len],
3894 t_start,
3895 t_end,
3896 count,
3897 callback,
3898 )
3899 {
3900 return Ok(true); // stopped early
3901 }
3902
3903 scanner.skip(entry.entry_size);
3904 }
3905
3906 Ok(false)
3907 }
3908
3909 fn find_oldest_in_sector<F: ReadNorFlash>(
3910 &self,
3911 flash: &mut F,
3912 sector_idx: u16,
3913 target_sensor: u16,
3914 buf: &mut [u8],
3915 ) -> Result<Option<(EntryHeader, usize)>, Error> {
3916 let sector_offset = self.sector_offset(sector_idx);
3917 let write_offset = self.sectors[sector_idx as usize].write_offset;
3918 let entry_start = SECTOR_HEADER_SIZE as u32;
3919 let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
3920 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3921 let mut payload_buf = [0u8; PAGE_SIZE];
3922
3923 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3924 if !accept_entry(flash, sector_offset, &entry, &mut payload_buf)? {
3925 scanner.skip(1);
3926 continue;
3927 }
3928
3929 let sensor = entry.sensor_id();
3930
3931 if sensor == target_sensor {
3932 let (header, payload) =
3933 entry.edge(&mut payload_buf[..entry.payload_len], Edge::First);
3934
3935 if payload.len() > buf.len() {
3936 return Err(Error::BufferTooSmall);
3937 }
3938 buf[..payload.len()].copy_from_slice(payload);
3939 return Ok(Some((header, payload.len())));
3940 }
3941
3942 scanner.skip(entry.entry_size);
3943 }
3944
3945 Ok(None)
3946 }
3947
3948 /// Count the entries in `sector_idx` that start below `offset_limit`.
3949 ///
3950 /// Uses the same acceptance test as the mount scan — committed flags and a
3951 /// matching CRC — so the result is always a subset of the sector's
3952 /// `entry_count`, and the accounting it feeds stays comparable with the one
3953 /// `note_spooled` builds incrementally.
3954 ///
3955 /// An entry that straddles `offset_limit` is not counted: the scanner stops
3956 /// when the next entry would cross its limit. Watermarks land on entry
3957 /// boundaries, so that case does not arise from a well-formed position.
3958 pub(crate) fn count_entries_before<F: ReadNorFlash>(
3959 &self,
3960 flash: &mut F,
3961 sector_idx: u16,
3962 offset_limit: u32,
3963 ) -> Result<Replicated, Error> {
3964 let summary = &self.sectors[sector_idx as usize];
3965 let sector_offset = self.sector_offset(sector_idx);
3966 let entry_start = SECTOR_HEADER_SIZE as u32;
3967 let limit = offset_limit.min(summary.write_offset);
3968 if limit <= entry_start {
3969 return Ok(Replicated::NONE);
3970 }
3971
3972 let mut scanner = SectorScanner::new(sector_offset, entry_start, limit);
3973 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3974 let mut buf = [0u8; PAGE_SIZE];
3975 let mut found = Replicated::NONE;
3976
3977 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3978 if !accept_entry(flash, sector_offset, &entry, &mut buf)? {
3979 scanner.skip(1);
3980 continue;
3981 }
3982 found.push(samples_in(entry.is_run(), &buf[..entry.payload_len]));
3983 scanner.skip(entry.entry_size);
3984 }
3985
3986 // A prefix cannot hold more than the whole. The clamp matters for a
3987 // `HeadersOnly` mount, where an unscanned sector reports `entry_count = 0`
3988 // and contributes nothing to `total_entries`.
3989 Ok(Replicated {
3990 entries: found.entries.min(summary.entry_count),
3991 samples: found.samples.min(summary.sample_count),
3992 })
3993 }
3994
3995 /// Count the entries in `sector_idx` belonging to `target_sensor`.
3996 ///
3997 /// Uses the same acceptance test as [`scan_sector_for_query`] — a matching
3998 /// entry CRC, and a one-byte resync on failure — because `count` and
3999 /// `query_range` disagreeing about how many entries exist is a defect, not
4000 /// an optimisation. This costs a payload read per entry, and it is the same
4001 /// read `query_range` performs, paid only on sectors the bloom filter did
4002 /// not reject.
4003 ///
4004 /// [`scan_sector_for_query`]: Self::scan_sector_for_query
4005 fn count_sensor_in_sector<F: ReadNorFlash>(
4006 &self,
4007 flash: &mut F,
4008 sector_idx: u16,
4009 target_sensor: u16,
4010 ) -> Result<u32, Error> {
4011 let sector_offset = self.sector_offset(sector_idx);
4012 let write_offset = self.sectors[sector_idx as usize].write_offset;
4013 let entry_start = SECTOR_HEADER_SIZE as u32;
4014 let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
4015 let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
4016 let mut payload_buf = [0u8; PAGE_SIZE];
4017 let mut count = 0u32;
4018
4019 while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
4020 // Every entry is verified, not only the matching ones: a failure
4021 // resyncs by one byte, so skipping the check for a non-matching
4022 // sensor would walk the sector differently from the read path and
4023 // reintroduce the disagreement from the other side.
4024 if !accept_entry(flash, sector_offset, &entry, &mut payload_buf)? {
4025 scanner.skip(1);
4026 continue;
4027 }
4028 if entry.sensor_id() == target_sensor {
4029 // Samples, not entries: a run answers for all of its own, which
4030 // is what `query_range` would yield for it.
4031 count += samples_in(entry.is_run(), &payload_buf[..entry.payload_len]);
4032 }
4033 scanner.skip(entry.entry_size);
4034 }
4035
4036 Ok(count)
4037 }
4038}
4039
4040// ---------------------------------------------------------------------------
4041// Capability ports
4042// ---------------------------------------------------------------------------
4043//
4044// Delegation only, spelled with UFCS. Written as `self.append(..)` these would
4045// be ambiguous to read — the inherent method and the trait method share a name
4046// — and a future signature change on the inherent one would silently turn the
4047// call into unbounded recursion.
4048
4049impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> crate::port::LogSink
4050 for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
4051where
4052 F: NorFlash + ReadNorFlash,
4053{
4054 fn append(&mut self, sensor_id: u16, timestamp: u64, payload: &[u8]) -> Result<(), Error> {
4055 SensorDb::append(self, sensor_id, timestamp, payload)
4056 }
4057
4058 fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
4059 SensorDb::append_run(self, run)
4060 }
4061
4062 fn sync(&mut self) -> Result<(), Error> {
4063 SensorDb::sync(self)
4064 }
4065}
4066
4067impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> crate::port::LogSource
4068 for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
4069where
4070 F: NorFlash + ReadNorFlash,
4071{
4072 fn latest(
4073 &mut self,
4074 sensor_id: u16,
4075 buf: &mut [u8],
4076 ) -> Result<Option<(EntryHeader, usize)>, Error> {
4077 SensorDb::latest(self, sensor_id, buf)
4078 }
4079
4080 fn oldest(
4081 &mut self,
4082 sensor_id: u16,
4083 buf: &mut [u8],
4084 ) -> Result<Option<(EntryHeader, usize)>, Error> {
4085 SensorDb::oldest(self, sensor_id, buf)
4086 }
4087
4088 fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
4089 SensorDb::count(self, sensor_id)
4090 }
4091
4092 fn query_range(
4093 &mut self,
4094 sensor_id: Option<u16>,
4095 t_start: u64,
4096 t_end: u64,
4097 callback: &mut dyn FnMut(&EntryHeader, &[u8]) -> bool,
4098 ) -> Result<u32, Error> {
4099 SensorDb::query_range(self, sensor_id, t_start, t_end, callback)
4100 }
4101}
4102
4103#[cfg(all(test, feature = "std"))]
4104mod tests {
4105 extern crate alloc;
4106 use alloc::vec;
4107
4108 use super::*;
4109 use crate::mock::MockFlash;
4110
4111 const PAGE: usize = 256;
4112 const SECTOR: usize = 4096;
4113 const SECTORS: usize = 8;
4114
4115 fn make_db() -> SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS> {
4116 let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4117 let mut db = SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4118 db.format().unwrap();
4119 db
4120 }
4121
4122 #[test]
4123 fn format_and_mount() {
4124 let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4125 let mut db: SensorDb<_, PAGE, SECTORS> =
4126 SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4127 db.format().unwrap();
4128 assert!(db.is_mounted());
4129 assert_eq!(db.stats().total_entries, 0);
4130 }
4131
4132 #[test]
4133 fn append_and_latest() {
4134 let mut db = make_db();
4135 let payload = [0xDE, 0xAD, 0xBE, 0xEF];
4136 db.append(1, 1000, &payload).unwrap();
4137 db.append(2, 1001, &[0x42]).unwrap();
4138 db.append(1, 1002, &[0x01, 0x02]).unwrap();
4139
4140 // Latest for sensor 1 should be the third entry
4141 let mut buf = [0u8; 16];
4142 let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4143 assert_eq!(hdr.sensor_id, 1);
4144 assert_eq!(hdr.timestamp, 1002);
4145 assert_eq!(&buf[..n], &[0x01, 0x02]);
4146
4147 // Latest for sensor 2
4148 let (hdr2, n2) = db.latest(2, &mut buf).unwrap().unwrap();
4149 assert_eq!(hdr2.sensor_id, 2);
4150 assert_eq!(&buf[..n2], &[0x42]);
4151 }
4152
4153 #[test]
4154 fn query_range_filters_correctly() {
4155 let mut db = make_db();
4156 db.append(1, 100, &[0x01]).unwrap();
4157 db.append(1, 200, &[0x02]).unwrap();
4158 db.append(2, 150, &[0x0A]).unwrap();
4159 db.append(1, 300, &[0x03]).unwrap();
4160 db.sync().unwrap();
4161
4162 // Query sensor 1, time range 100..250
4163 let mut results = alloc::vec::Vec::new();
4164 let count = db
4165 .query_range(Some(1), 100, 250, |hdr, payload| {
4166 results.push((hdr.timestamp, payload[0]));
4167 true
4168 })
4169 .unwrap();
4170
4171 assert_eq!(count, 2);
4172 assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4173 }
4174
4175 #[test]
4176 fn survives_remount() {
4177 let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4178 let mut db: SensorDb<_, PAGE, SECTORS> =
4179 SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4180 db.format().unwrap();
4181
4182 db.append(5, 42, &[0xAA, 0xBB]).unwrap();
4183 db.append(5, 43, &[0xCC]).unwrap();
4184 db.sync().unwrap();
4185
4186 let _stats_before = db.stats();
4187
4188 // Simulate power cycle: extract flash, create new DB, mount
4189 let flash = db.into_inner();
4190 let mut db2: SensorDb<_, PAGE, SECTORS> =
4191 SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4192 let mount_stats = db2.mount().unwrap();
4193
4194 assert_eq!(mount_stats.total_entries, 2);
4195
4196 // Verify data survived
4197 let mut buf = [0u8; 16];
4198 let (hdr, n) = db2.latest(5, &mut buf).unwrap().unwrap();
4199 assert_eq!(hdr.timestamp, 43);
4200 assert_eq!(&buf[..n], &[0xCC]);
4201 }
4202
4203 #[test]
4204 fn circular_wrap_reclaims_old_sectors() {
4205 // Use only 4 sectors to force wrapping quickly
4206 const SMALL: usize = 4;
4207 let flash = MockFlash::<PAGE, SECTOR>::new(SMALL * SECTOR);
4208 let mut db: SensorDb<_, PAGE, SMALL> = SensorDb::new(flash, 0, SMALL as u16, 1).unwrap();
4209 db.format().unwrap();
4210
4211 // Fill enough entries to wrap around. Each entry is ~20 bytes.
4212 // Each 4KB sector fits roughly (4096 - 8) / 20 ≈ 204 entries per page,
4213 // but entries can't span pages so per page (256 - 8 first page) / 20 ≈ 12 entries.
4214 // With 16 pages per sector, ~192 entries per sector × 4 sectors = ~768 entries.
4215 // But we have 1 reserved sector so usable = 3 sectors ≈ 576 entries.
4216 for i in 0..800u64 {
4217 let payload = (i as u32).to_le_bytes();
4218 db.append(1, i * 100, &payload).unwrap();
4219 }
4220
4221 let stats = db.stats();
4222 assert!(stats.total_entries > 0);
4223 assert!(stats.used_sectors <= SMALL as u16);
4224
4225 // Most recent entry should still be queryable
4226 let mut buf = [0u8; 4];
4227 let (hdr, _) = db.latest(1, &mut buf).unwrap().unwrap();
4228 assert_eq!(hdr.timestamp, 799 * 100);
4229 }
4230
4231 #[test]
4232 fn compact_frees_sectors() {
4233 let mut db = make_db();
4234 for i in 0..50u64 {
4235 db.append(1, i, &[i as u8]).unwrap();
4236 }
4237 db.sync().unwrap();
4238
4239 let before = db.stats();
4240 let freed = db.compact(1, CompactScope::All).unwrap();
4241 let after = db.stats();
4242
4243 if before.used_sectors > 1 {
4244 assert!(freed > 0);
4245 assert!(after.free_sectors > before.free_sectors);
4246 }
4247 }
4248
4249 #[test]
4250 fn max_payload_works() {
4251 let mut db = make_db();
4252 let max = db.max_payload_size();
4253 let payload = vec![0x42u8; max];
4254 db.append(1, 999, &payload).unwrap();
4255 db.sync().unwrap();
4256
4257 let mut buf = vec![0u8; max];
4258 let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4259 assert_eq!(n, max);
4260 assert_eq!(hdr.payload_len as usize, max);
4261 }
4262
4263 #[test]
4264 fn rejects_oversized_payload() {
4265 let mut db = make_db();
4266 let too_big = vec![0u8; db.max_payload_size() + 1];
4267 let result = db.append(1, 100, &too_big);
4268 assert!(result.is_err());
4269 }
4270
4271 // =========================================================================
4272 // Typed API Tests
4273 // =========================================================================
4274
4275 mod typed_api {
4276 use super::*;
4277 use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
4278
4279 /// Example sensor type for testing: temperature reading
4280 #[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
4281 #[repr(C)]
4282 struct Temperature {
4283 celsius: f32,
4284 }
4285
4286 impl SensorData for Temperature {
4287 const SENSOR_ID: u16 = 0x01;
4288 }
4289
4290 /// Example sensor type: accelerometer reading
4291 #[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
4292 #[repr(C)]
4293 struct Accelerometer {
4294 x: i16,
4295 y: i16,
4296 z: i16,
4297 }
4298
4299 impl SensorData for Accelerometer {
4300 const SENSOR_ID: u16 = 0x02;
4301 }
4302
4303 #[test]
4304 fn typed_roundtrip_layer1() {
4305 let mut db = make_db();
4306
4307 let temp = Temperature { celsius: 25.5 };
4308 db.append_value(0x01, 1000, &temp).unwrap();
4309
4310 let (hdr, retrieved) = db.latest_value::<Temperature>(0x01).unwrap().unwrap();
4311 assert_eq!(hdr.sensor_id, 0x01);
4312 assert_eq!(hdr.timestamp, 1000);
4313 assert_eq!(retrieved.celsius, 25.5);
4314 }
4315
4316 #[test]
4317 fn typed_roundtrip_layer2() {
4318 let mut db = make_db();
4319
4320 let temp = Temperature { celsius: -10.0 };
4321 db.append_sensor(2000, &temp).unwrap();
4322
4323 let (hdr, retrieved) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4324 assert_eq!(hdr.sensor_id, Temperature::SENSOR_ID);
4325 assert_eq!(hdr.timestamp, 2000);
4326 assert_eq!(retrieved.celsius, -10.0);
4327 }
4328
4329 #[test]
4330 fn typed_multiple_sensors() {
4331 let mut db = make_db();
4332
4333 let temp = Temperature { celsius: 22.5 };
4334 let accel = Accelerometer {
4335 x: 100,
4336 y: -50,
4337 z: 980,
4338 };
4339
4340 db.append_sensor(1000, &temp).unwrap();
4341 db.append_sensor(1001, &accel).unwrap();
4342
4343 // Retrieve each type independently
4344 let (_, t) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4345 let (_, a) = db.latest_sensor::<Accelerometer>().unwrap().unwrap();
4346
4347 assert_eq!(t.celsius, 22.5);
4348 assert_eq!(a.x, 100);
4349 assert_eq!(a.y, -50);
4350 assert_eq!(a.z, 980);
4351 }
4352
4353 #[test]
4354 fn cross_api_raw_write_typed_read() {
4355 let mut db = make_db();
4356
4357 // A bare value written raw is *not* a Temperature: the typed API
4358 // frames a schema tag in front, so the untagged bytes are a byte
4359 // short of what it expects.
4360 db.append(Temperature::SENSOR_ID, 3000, &30.0f32.to_ne_bytes())
4361 .unwrap();
4362 assert_eq!(
4363 db.latest_sensor::<Temperature>(),
4364 Err(Error::SizeMismatch {
4365 expected: 5,
4366 actual: 4
4367 })
4368 );
4369
4370 // Include the tag and the raw route reaches the typed one.
4371 let mut framed = [0u8; 5];
4372 framed[0] = Temperature::SCHEMA_VERSION;
4373 framed[1..].copy_from_slice(&31.0f32.to_ne_bytes());
4374 db.append(Temperature::SENSOR_ID, 3100, &framed).unwrap();
4375
4376 let (hdr, temp) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4377 assert_eq!(hdr.timestamp, 3100);
4378 assert_eq!(temp.celsius, 31.0);
4379 }
4380
4381 #[test]
4382 fn cross_api_typed_write_raw_read() {
4383 let mut db = make_db();
4384
4385 // Write using typed API
4386 let temp = Temperature { celsius: 42.0 };
4387 db.append_sensor(4000, &temp).unwrap();
4388
4389 // Read using raw API: the schema tag is the first payload byte, so
4390 // the entry is one longer than the value.
4391 let mut buf = [0u8; 16];
4392 let (hdr, n) = db
4393 .latest(Temperature::SENSOR_ID, &mut buf)
4394 .unwrap()
4395 .unwrap();
4396 assert_eq!(hdr.timestamp, 4000);
4397 assert_eq!(n, crate::SCHEMA_TAG_SIZE + 4);
4398 assert_eq!(hdr.payload_len as usize, n);
4399 assert_eq!(buf[0], Temperature::SCHEMA_VERSION);
4400 let celsius = f32::from_ne_bytes([buf[1], buf[2], buf[3], buf[4]]);
4401 assert_eq!(celsius, 42.0);
4402 }
4403
4404 #[test]
4405 fn size_mismatch_detection() {
4406 let mut db = make_db();
4407
4408 // A lone tag byte: the right schema version, the wrong length. That
4409 // is what SizeMismatch now means — the struct changed and
4410 // SCHEMA_VERSION did not.
4411 db.append(Temperature::SENSOR_ID, 5000, &[Temperature::SCHEMA_VERSION])
4412 .unwrap();
4413
4414 let result = db.latest_sensor::<Temperature>();
4415 match result {
4416 Err(Error::SizeMismatch { expected, actual }) => {
4417 assert_eq!(expected, 5);
4418 assert_eq!(actual, 1);
4419 }
4420 _ => panic!("Expected SizeMismatch error"),
4421 }
4422 }
4423
4424 #[test]
4425 fn a_foreign_first_byte_is_reported_as_the_version_it_claims() {
4426 let mut db = make_db();
4427 db.append(Temperature::SENSOR_ID, 5000, &[0x42]).unwrap();
4428
4429 assert_eq!(
4430 db.latest_sensor::<Temperature>(),
4431 Err(Error::SchemaMismatch {
4432 expected: 0,
4433 found: 0x42
4434 })
4435 );
4436 }
4437
4438 #[test]
4439 fn an_entry_of_another_schema_version_is_named_not_misread() {
4440 // Same layout, different meaning — the case a length check cannot
4441 // catch, and the whole reason the tag exists.
4442 #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Debug, PartialEq)]
4443 #[repr(C)]
4444 struct Fahrenheit {
4445 degrees: f32,
4446 }
4447
4448 impl SensorData for Fahrenheit {
4449 const SENSOR_ID: u16 = Temperature::SENSOR_ID;
4450 const SCHEMA_VERSION: u8 = 1;
4451 }
4452
4453 let mut db = make_db();
4454 db.append_sensor(1000, &Temperature { celsius: 100.0 })
4455 .unwrap();
4456
4457 assert_eq!(
4458 db.latest_sensor::<Fahrenheit>(),
4459 Err(Error::SchemaMismatch {
4460 expected: 1,
4461 found: 0
4462 })
4463 );
4464
4465 // Both eras live in one log under one sensor ID, and each type
4466 // queries its own.
4467 db.append_sensor(2000, &Fahrenheit { degrees: 212.0 })
4468 .unwrap();
4469
4470 let mut celsius = alloc::vec::Vec::new();
4471 db.query_all_sensor::<Temperature, _>(|_, t| {
4472 celsius.push(t.celsius);
4473 true
4474 })
4475 .unwrap();
4476
4477 let mut degrees = alloc::vec::Vec::new();
4478 db.query_all_sensor::<Fahrenheit, _>(|_, f| {
4479 degrees.push(f.degrees);
4480 true
4481 })
4482 .unwrap();
4483
4484 assert_eq!(celsius, [100.0]);
4485 assert_eq!(degrees, [212.0]);
4486
4487 // And the newest entry now is a Fahrenheit.
4488 let (_, f) = db.latest_sensor::<Fahrenheit>().unwrap().unwrap();
4489 assert_eq!(f.degrees, 212.0);
4490 }
4491
4492 #[test]
4493 fn query_sensor_typed() {
4494 let mut db = make_db();
4495
4496 // Write several temperature readings
4497 for i in 0..5 {
4498 let temp = Temperature {
4499 celsius: 20.0 + i as f32,
4500 };
4501 db.append_sensor(100 + i * 10, &temp).unwrap();
4502 }
4503 db.sync().unwrap();
4504
4505 // Query a time range
4506 let mut readings = alloc::vec::Vec::new();
4507 let count = db
4508 .query_sensor::<Temperature, _>(110, 130, |hdr, temp| {
4509 readings.push((hdr.timestamp, temp.celsius));
4510 true
4511 })
4512 .unwrap();
4513
4514 assert_eq!(count, 3); // timestamps 110, 120, 130
4515 assert_eq!(readings.len(), 3);
4516 assert_eq!(readings[0], (110, 21.0));
4517 assert_eq!(readings[1], (120, 22.0));
4518 assert_eq!(readings[2], (130, 23.0));
4519 }
4520
4521 #[test]
4522 fn query_sensor_skips_wrong_size() {
4523 let mut db = make_db();
4524
4525 // Write a valid temperature
4526 let temp = Temperature { celsius: 25.0 };
4527 db.append_sensor(1000, &temp).unwrap();
4528
4529 // Write raw data with wrong size using Temperature's sensor ID
4530 db.append(Temperature::SENSOR_ID, 2000, &[0x01, 0x02])
4531 .unwrap();
4532
4533 // Write another valid temperature
4534 let temp2 = Temperature { celsius: 30.0 };
4535 db.append_sensor(3000, &temp2).unwrap();
4536
4537 db.sync().unwrap();
4538
4539 // Query should skip the malformed entry
4540 let mut readings = alloc::vec::Vec::new();
4541 let count = db
4542 .query_sensor::<Temperature, _>(0, 10000, |hdr, temp| {
4543 readings.push((hdr.timestamp, temp.celsius));
4544 true
4545 })
4546 .unwrap();
4547
4548 assert_eq!(count, 2);
4549 assert_eq!(readings[0], (1000, 25.0));
4550 assert_eq!(readings[1], (3000, 30.0));
4551 }
4552
4553 #[test]
4554 fn typed_survives_remount() {
4555 let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4556 let mut db: SensorDb<_, PAGE, SECTORS> =
4557 SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4558 db.format().unwrap();
4559
4560 let temp = Temperature { celsius: 99.9 };
4561 db.append_sensor(6000, &temp).unwrap();
4562 db.sync().unwrap();
4563
4564 // Simulate power cycle
4565 let flash = db.into_inner();
4566 let mut db2: SensorDb<_, PAGE, SECTORS> =
4567 SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4568 db2.mount().unwrap();
4569
4570 // Verify typed data survived
4571 let (hdr, retrieved) = db2.latest_sensor::<Temperature>().unwrap().unwrap();
4572 assert_eq!(hdr.timestamp, 6000);
4573 assert_eq!(retrieved.celsius, 99.9);
4574 }
4575
4576 #[test]
4577 fn latest_returns_most_recent() {
4578 let mut db = make_db();
4579
4580 db.append_sensor(100, &Temperature { celsius: 10.0 })
4581 .unwrap();
4582 db.append_sensor(200, &Temperature { celsius: 20.0 })
4583 .unwrap();
4584 db.append_sensor(300, &Temperature { celsius: 30.0 })
4585 .unwrap();
4586
4587 let (hdr, temp) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4588 assert_eq!(hdr.timestamp, 300);
4589 assert_eq!(temp.celsius, 30.0);
4590 }
4591
4592 #[test]
4593 fn no_entries_returns_none() {
4594 let mut db = make_db();
4595
4596 // No entries written
4597 let result = db.latest_sensor::<Temperature>().unwrap();
4598 assert!(result.is_none());
4599 }
4600
4601 #[test]
4602 fn oldest_returns_first_entry() {
4603 let mut db = make_db();
4604
4605 db.append_sensor(100, &Temperature { celsius: 10.0 })
4606 .unwrap();
4607 db.append_sensor(200, &Temperature { celsius: 20.0 })
4608 .unwrap();
4609 db.append_sensor(300, &Temperature { celsius: 30.0 })
4610 .unwrap();
4611
4612 let (hdr, temp) = db.oldest_sensor::<Temperature>().unwrap().unwrap();
4613 assert_eq!(hdr.timestamp, 100);
4614 assert_eq!(temp.celsius, 10.0);
4615 }
4616
4617 #[test]
4618 fn oldest_returns_none_when_empty() {
4619 let mut db = make_db();
4620
4621 let result = db.oldest_sensor::<Temperature>().unwrap();
4622 assert!(result.is_none());
4623 }
4624
4625 #[test]
4626 fn count_sensor_counts_correctly() {
4627 let mut db = make_db();
4628
4629 // Write some temperature entries
4630 for i in 0..5 {
4631 db.append_sensor(i * 100, &Temperature { celsius: i as f32 })
4632 .unwrap();
4633 }
4634
4635 // Write some accelerometer entries
4636 for i in 0..3 {
4637 db.append_sensor(
4638 i * 100 + 50,
4639 &Accelerometer {
4640 x: i as i16,
4641 y: 0,
4642 z: 0,
4643 },
4644 )
4645 .unwrap();
4646 }
4647
4648 db.sync().unwrap();
4649
4650 // Count each sensor type
4651 let temp_count = db.count_sensor::<Temperature>().unwrap();
4652 let accel_count = db.count_sensor::<Accelerometer>().unwrap();
4653 let total = db.count(None).unwrap();
4654
4655 assert_eq!(temp_count, 5);
4656 assert_eq!(accel_count, 3);
4657 assert_eq!(total, 8);
4658 }
4659
4660 #[test]
4661 fn query_all_sensor_gets_all_entries() {
4662 let mut db = make_db();
4663
4664 for i in 0..5 {
4665 db.append_sensor(
4666 i * 100,
4667 &Temperature {
4668 celsius: i as f32 * 10.0,
4669 },
4670 )
4671 .unwrap();
4672 }
4673 db.sync().unwrap();
4674
4675 let mut readings = alloc::vec::Vec::new();
4676 let count = db
4677 .query_all_sensor::<Temperature, _>(|hdr, temp| {
4678 readings.push((hdr.timestamp, temp.celsius));
4679 true
4680 })
4681 .unwrap();
4682
4683 assert_eq!(count, 5);
4684 assert_eq!(readings.len(), 5);
4685 assert_eq!(readings[0], (0, 0.0));
4686 assert_eq!(readings[4], (400, 40.0));
4687 }
4688 }
4689
4690 // =========================================================================
4691 // Raw API Tests for new methods
4692 // =========================================================================
4693
4694 #[test]
4695 fn query_all_gets_all_entries() {
4696 let mut db = make_db();
4697
4698 db.append(1, 100, &[0x01]).unwrap();
4699 db.append(1, 200, &[0x02]).unwrap();
4700 db.append(2, 150, &[0x0A]).unwrap();
4701 db.sync().unwrap();
4702
4703 // Query all entries for sensor 1
4704 let mut results = alloc::vec::Vec::new();
4705 let count = db
4706 .query_all(Some(1), |hdr, payload| {
4707 results.push((hdr.timestamp, payload[0]));
4708 true
4709 })
4710 .unwrap();
4711
4712 assert_eq!(count, 2);
4713 assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4714
4715 // Query all entries (no filter)
4716 let mut all_results = alloc::vec::Vec::new();
4717 let total = db
4718 .query_all(None, |hdr, _| {
4719 all_results.push(hdr.timestamp);
4720 true
4721 })
4722 .unwrap();
4723
4724 assert_eq!(total, 3);
4725 }
4726
4727 #[test]
4728 fn oldest_gets_first_entry() {
4729 let mut db = make_db();
4730
4731 db.append(1, 300, &[0x03]).unwrap();
4732 db.append(1, 100, &[0x01]).unwrap();
4733 db.append(1, 200, &[0x02]).unwrap();
4734 db.sync().unwrap();
4735
4736 let mut buf = [0u8; 16];
4737 // oldest() returns by sequence order (write order), not timestamp
4738 let (hdr, n) = db.oldest(1, &mut buf).unwrap().unwrap();
4739 assert_eq!(hdr.timestamp, 300); // First written entry
4740 assert_eq!(&buf[..n], &[0x03]);
4741 }
4742
4743 #[test]
4744 fn oldest_returns_none_for_missing_sensor() {
4745 let mut db = make_db();
4746
4747 db.append(1, 100, &[0x01]).unwrap();
4748 db.sync().unwrap();
4749
4750 let mut buf = [0u8; 16];
4751 let result = db.oldest(99, &mut buf).unwrap();
4752 assert!(result.is_none());
4753 }
4754
4755 #[test]
4756 fn count_works_correctly() {
4757 let mut db = make_db();
4758
4759 db.append(1, 100, &[0x01]).unwrap();
4760 db.append(1, 200, &[0x02]).unwrap();
4761 db.append(2, 150, &[0x0A]).unwrap();
4762 db.sync().unwrap();
4763
4764 assert_eq!(db.count(Some(1)).unwrap(), 2);
4765 assert_eq!(db.count(Some(2)).unwrap(), 1);
4766 assert_eq!(db.count(Some(99)).unwrap(), 0);
4767 assert_eq!(db.count(None).unwrap(), 3);
4768 }
4769
4770 #[test]
4771 fn count_uses_cached_total_for_none() {
4772 let mut db = make_db();
4773
4774 for i in 0..10 {
4775 db.append(1, i, &[i as u8]).unwrap();
4776 }
4777
4778 // count(None) should use cached total without scanning
4779 assert_eq!(db.count(None).unwrap(), 10);
4780 assert_eq!(db.stats().total_entries, 10);
4781 }
4782
4783 // =========================================================================
4784 // Sector rotation
4785 // =========================================================================
4786
4787 #[test]
4788 fn a_long_run_of_appends_rotates_sectors() {
4789 // Small enough that 500 entries cannot fit without rotating.
4790 const SMALL: usize = 4;
4791 let flash = MockFlash::<PAGE, SECTOR>::new(SMALL * SECTOR);
4792 let mut db: SensorDb<_, PAGE, SMALL> = SensorDb::new(flash, 0, SMALL as u16, 1).unwrap();
4793 db.format().unwrap();
4794
4795 let payload = [0x42u8; 4];
4796 for i in 0..500u64 {
4797 db.append(1, i * 10, &payload).unwrap();
4798 }
4799 db.sync().unwrap();
4800
4801 let stats = db.stats();
4802 assert!(stats.total_entries > 0);
4803 assert!(stats.used_sectors > 1);
4804
4805 let mut buf = [0u8; 4];
4806 let (hdr, _) = db.latest(1, &mut buf).unwrap().unwrap();
4807 assert_eq!(hdr.timestamp, 499 * 10);
4808 }
4809
4810 // =========================================================================
4811 // Auto traits
4812 // =========================================================================
4813
4814 #[test]
4815 fn a_database_is_sync_when_its_driver_is() {
4816 // The whole payoff of dropping the `RefCell`. It was `!Sync`, so the
4817 // only way to share a `SensorDb` was a `Mutex` — which yields `&mut`,
4818 // making the `&self` reads it bought unreachable in exactly the setting
4819 // they were for. A compile-time check, so it cannot rot into a comment.
4820 fn assert_sync<T: Sync>() {}
4821 fn assert_send<T: Send>() {}
4822
4823 assert_sync::<SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS>>();
4824 assert_send::<SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS>>();
4825 }
4826
4827 // =========================================================================
4828 // Flush-free read tests
4829 // =========================================================================
4830
4831 #[test]
4832 fn read_without_sync_sees_buffered_entries() {
4833 let mut db = make_db();
4834
4835 db.append(1, 100, &[0x01]).unwrap();
4836 db.append(1, 200, &[0x02]).unwrap();
4837 db.append(2, 150, &[0x0A]).unwrap();
4838 // No sync!
4839
4840 // latest sees the buffered entry
4841 let mut buf = [0u8; 16];
4842 let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4843 assert_eq!(hdr.timestamp, 200);
4844 assert_eq!(&buf[..n], &[0x02]);
4845
4846 // oldest sees the first buffered entry
4847 let (hdr, n) = db.oldest(1, &mut buf).unwrap().unwrap();
4848 assert_eq!(hdr.timestamp, 100);
4849 assert_eq!(&buf[..n], &[0x01]);
4850
4851 // count sees all buffered entries
4852 assert_eq!(db.count(Some(1)).unwrap(), 2);
4853 assert_eq!(db.count(Some(2)).unwrap(), 1);
4854 assert_eq!(db.count(None).unwrap(), 3);
4855
4856 // query_range sees all buffered entries
4857 let mut results = alloc::vec::Vec::new();
4858 let count = db
4859 .query_range(Some(1), 0, u64::MAX, |hdr, payload| {
4860 results.push((hdr.timestamp, payload[0]));
4861 true
4862 })
4863 .unwrap();
4864 assert_eq!(count, 2);
4865 assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4866 }
4867
4868 #[test]
4869 fn read_after_sync_sees_committed_and_buffered() {
4870 let mut db = make_db();
4871
4872 // Write and sync (committed)
4873 db.append(1, 100, &[0x01]).unwrap();
4874 db.append(1, 200, &[0x02]).unwrap();
4875 db.sync().unwrap();
4876
4877 // Write more without sync (buffered)
4878 db.append(1, 300, &[0x03]).unwrap();
4879 db.append(2, 250, &[0x0B]).unwrap();
4880
4881 // latest sees the newest buffered entry
4882 let mut buf = [0u8; 16];
4883 let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4884 assert_eq!(hdr.timestamp, 300);
4885 assert_eq!(&buf[..n], &[0x03]);
4886
4887 // oldest sees the oldest committed entry
4888 let (hdr, n) = db.oldest(1, &mut buf).unwrap().unwrap();
4889 assert_eq!(hdr.timestamp, 100);
4890 assert_eq!(&buf[..n], &[0x01]);
4891
4892 // count sees committed + buffered
4893 assert_eq!(db.count(Some(1)).unwrap(), 3);
4894 assert_eq!(db.count(Some(2)).unwrap(), 1);
4895 assert_eq!(db.count(None).unwrap(), 4);
4896
4897 // query_range sees both committed and buffered
4898 let mut results = alloc::vec::Vec::new();
4899 db.query_range(Some(1), 0, u64::MAX, |hdr, payload| {
4900 results.push((hdr.timestamp, payload[0]));
4901 true
4902 })
4903 .unwrap();
4904 assert_eq!(results, vec![(100, 0x01), (200, 0x02), (300, 0x03)]);
4905 }
4906
4907 #[test]
4908 fn query_range_order_with_buffered() {
4909 let mut db = make_db();
4910
4911 // Committed entries
4912 db.append(1, 100, &[0x01]).unwrap();
4913 db.append(1, 200, &[0x02]).unwrap();
4914 db.sync().unwrap();
4915
4916 // Buffered entries
4917 db.append(1, 300, &[0x03]).unwrap();
4918 db.append(1, 400, &[0x04]).unwrap();
4919
4920 // Verify committed entries come first, buffered entries come after
4921 let mut timestamps = alloc::vec::Vec::new();
4922 db.query_range(Some(1), 0, u64::MAX, |hdr, _| {
4923 timestamps.push(hdr.timestamp);
4924 true
4925 })
4926 .unwrap();
4927 assert_eq!(timestamps, vec![100, 200, 300, 400]);
4928 }
4929
4930 #[test]
4931 fn page_buf_empty_after_sync() {
4932 let mut db = make_db();
4933
4934 db.append(1, 100, &[0x01]).unwrap();
4935 db.append(1, 200, &[0x02]).unwrap();
4936 db.sync().unwrap();
4937
4938 // After sync, page buffer scanning should find nothing
4939 // (all entries are committed on flash). Verify by checking
4940 // that count(Some(1)) matches the sector-scanned count.
4941 assert_eq!(db.count(Some(1)).unwrap(), 2);
4942
4943 // Verify with query_range too
4944 let mut results = alloc::vec::Vec::new();
4945 db.query_range(Some(1), 0, u64::MAX, |hdr, payload| {
4946 results.push((hdr.timestamp, payload[0]));
4947 true
4948 })
4949 .unwrap();
4950 assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4951 }
4952}