Skip to main content

sensor_db/spool/
tier.rs

1//! Routing a tiered log: which medium `append` writes to, and when that moves.
2//!
3//! Pure module — no I/O. [`TieredDb`](crate::spool::TieredDb) and
4//! [`TieredDbAsync`](crate::spool::asynch::TieredDbAsync) hold a `TierMode`
5//! and supply only the flash work around it.
6
7use crate::entry::EntryHeader;
8use crate::error::Error;
9
10/// Batches allowed when draining the backlog to promote to direct writes.
11///
12/// Bounded so a pathological backlog cannot make a single `spool_step` run
13/// unboundedly; the promotion simply happens on a later pass instead.
14pub(crate) const PROMOTE_MAX_BATCHES: u32 = 256;
15
16/// Where new samples land.
17///
18/// Chosen at construction with no default, because the right answer depends on
19/// what the deployment values and both answers are defensible.
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21#[cfg_attr(feature = "defmt", derive(defmt::Format))]
22pub enum WritePolicy {
23    /// Always append to the onboard log; copy to the volume in the background.
24    ///
25    /// The write path never depends on the volume being present, so a removal at
26    /// any instant — clean or not — cannot lose a sample. Costs onboard write
27    /// endurance and space, since every sample is written twice.
28    OnboardFirst,
29    /// Append directly to the volume once the backlog is drained.
30    ///
31    /// Spares the onboard log both space and wear while the volume is present:
32    /// samples bypass it entirely, so it is written only while the volume is
33    /// out. A removal at any instant still loses nothing — whatever the volume
34    /// held in RAM is rescued into the onboard log, because a yank leaves the
35    /// processor running.
36    ///
37    /// Two costs to weigh against that:
38    ///
39    /// - **A power cut is not a yank.** It takes the processor too, so samples
40    ///   buffered on the volume and not yet [`sync`](crate::spool::TieredDb::sync)ed
41    ///   are gone. That window is one page — the same as any un-synced write —
42    ///   but under [`OnboardFirst`](Self::OnboardFirst) those samples would have
43    ///   been onboard already.
44    /// - **There is only one copy.** Under `OnboardFirst` a sample exists in
45    ///   both logs until the onboard ring reclaims it. Here, once a sample is on
46    ///   the volume it is only there, so the volume filling up and wrapping is
47    ///   real loss rather than the loss of a redundant copy. Size the volume for
48    ///   the collection interval, and swap it before it wraps —
49    ///   [`TieredDb::volume_fill`](crate::spool::TieredDb::volume_fill) is the
50    ///   signal that says when that is due.
51    ///
52    /// One more thing to know about this mode: appends land on the volume, so a
53    /// sector rotation there — 100 ms or more on many NOR parts — lands on the
54    /// `append` path rather than on replication. Sample
55    /// [`SensorDb::sectors_erased`](crate::SensorDb::sectors_erased) on the
56    /// volume to see them.
57    CardFirst,
58}
59
60/// Which log `append` is currently writing to.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62#[cfg_attr(feature = "defmt", derive(defmt::Format))]
63pub enum WriteMode {
64    /// No volume, or the volume faulted: samples go to the onboard log.
65    Onboard,
66    /// A volume is attached but the onboard backlog has not drained yet.
67    Draining,
68    /// The backlog is empty and samples go straight to the volume.
69    ///
70    /// Only reachable under [`WritePolicy::CardFirst`].
71    Direct,
72}
73
74/// The write-routing state machine of a tiered log.
75///
76/// Every transition is here rather than in the drivers, for the reason the whole
77/// spool layer is split this way: `tests/tiered_async.rs` compares the two
78/// drivers' media byte for byte, so a routing decision duplicated between them
79/// is one the parity suite calls correct by construction.
80#[derive(Debug, Clone, Copy)]
81pub(crate) struct TierMode {
82    policy: WritePolicy,
83    mode: WriteMode,
84}
85
86impl TierMode {
87    /// A tier with nothing attached, writing onboard.
88    pub(crate) fn new(policy: WritePolicy) -> Self {
89        Self {
90            policy,
91            mode: WriteMode::Onboard,
92        }
93    }
94
95    /// Which log `append` is currently writing to.
96    pub(crate) fn mode(&self) -> WriteMode {
97        self.mode
98    }
99
100    /// The configured write policy.
101    pub(crate) fn policy(&self) -> WritePolicy {
102        self.policy
103    }
104
105    /// Whether an append should be attempted on the volume.
106    pub(crate) fn writes_to_volume(&self) -> bool {
107        self.mode == WriteMode::Direct
108    }
109
110    /// A volume has been attached: begin draining the backlog onto it.
111    ///
112    /// Set **before** the fallible part of an attach, so an error cannot strand
113    /// an attached volume behind a mode that will never drain it.
114    pub(crate) fn attached(&mut self) {
115        self.mode = WriteMode::Draining;
116    }
117
118    /// The volume is gone, faulted, or being detached: write onboard.
119    pub(crate) fn fell_back(&mut self) {
120        self.mode = WriteMode::Onboard;
121    }
122
123    /// A replication pass ran, so a volume is attached and usable.
124    ///
125    /// Does not disturb [`Direct`](WriteMode::Direct): under
126    /// [`CardFirst`](WritePolicy::CardFirst) a pass can still find work — the
127    /// tail the onboard log buffered before the promotion — without that meaning
128    /// the tier has stopped writing direct.
129    pub(crate) fn spooled(&mut self) {
130        if self.mode != WriteMode::Direct {
131            self.mode = WriteMode::Draining;
132        }
133    }
134
135    /// Whether a caught-up tier should try to promote to direct writes.
136    pub(crate) fn may_promote(&self, attached: bool, faulted: bool) -> bool {
137        self.policy == WritePolicy::CardFirst
138            && self.mode != WriteMode::Direct
139            && attached
140            && !faulted
141    }
142
143    /// The backlog drained to nothing: appends may go straight to the volume.
144    pub(crate) fn promoted(&mut self) {
145        self.mode = WriteMode::Direct;
146    }
147
148    /// Whether a replication pass can run, falling back to the onboard log when
149    /// it cannot.
150    ///
151    /// `Ok(false)` means no volume — the normal state while the card is out, and
152    /// not an error. A **faulted** volume is different, and is reported as
153    /// [`Error::VolumeLost`] until it is detached: answering `Ok(false)` there
154    /// would let a card that fell out mid-write look identical to no card at
155    /// all, and the backlog would grow silently until the ring began dropping
156    /// it.
157    pub(crate) fn ready_to_spool(&mut self, attached: bool, faulted: bool) -> Result<bool, Error> {
158        if faulted {
159            self.fell_back();
160            return Err(Error::VolumeLost);
161        }
162        if !attached {
163            self.fell_back();
164            return Ok(false);
165        }
166        Ok(true)
167    }
168}
169
170/// Whether a failed volume operation means the medium should be given up on.
171///
172/// A driver cannot tell a yanked card from a genuine fault — both arrive as
173/// `NorFlashErrorKind::Other` — so any flash error on the volume is treated as
174/// removal, and so is finding nothing attached at all. Both lead to the same
175/// recovery: rescue whatever the volume still held in RAM into the onboard log
176/// and carry on as if the card had never been there.
177///
178/// Anything else is a real error about the operation requested — a payload too
179/// large, an unmounted log — and re-routing the write would only hide it.
180pub(crate) fn volume_gone(error: &Error) -> bool {
181    matches!(error, Error::Flash(_) | Error::NotAttached)
182}
183
184/// Pick between an onboard and a volume result, copying the winner into `buf`.
185///
186/// `volume_wins` is given the two timestamps, volume first, so the caller
187/// supplies only the direction — `>` for the latest entry, `<` for the oldest.
188///
189/// The union is exact and needs no de-duplication: where the two logs overlap
190/// they hold identical entries, so taking one side by timestamp cannot be
191/// perturbed by the duplication.
192///
193/// # Errors
194/// - `BufferTooSmall` if the volume's entry wins but does not fit `buf`. It is
195///   raised rather than falling back to the onboard entry, because reporting an
196///   older entry as the latest is a wrong answer where an error is merely an
197///   inconvenient one.
198pub(crate) fn merge(
199    onboard: Option<(EntryHeader, usize)>,
200    from_volume: Option<(EntryHeader, usize)>,
201    alt: &[u8],
202    buf: &mut [u8],
203    volume_wins: impl Fn(u64, u64) -> bool,
204) -> Result<Option<(EntryHeader, usize)>, Error> {
205    let take_volume = |vh: EntryHeader, vn: usize, buf: &mut [u8]| {
206        if vn > buf.len() {
207            return Err(Error::BufferTooSmall);
208        }
209        buf[..vn].copy_from_slice(&alt[..vn]);
210        Ok(Some((vh, vn)))
211    };
212
213    match (onboard, from_volume) {
214        (Some((oh, on)), Some((vh, vn))) => {
215            if volume_wins(vh.timestamp, oh.timestamp) {
216                take_volume(vh, vn, buf)
217            } else {
218                Ok(Some((oh, on)))
219            }
220        }
221        (None, Some((vh, vn))) => take_volume(vh, vn, buf),
222        (some, None) => Ok(some),
223    }
224}
225
226#[cfg(test)]
227mod tests {
228    use super::*;
229    use crate::entry::EntryKind;
230
231    fn header(timestamp: u64) -> EntryHeader {
232        EntryHeader {
233            sensor_id: 1,
234            timestamp,
235            payload_len: 2,
236            kind: EntryKind::Single,
237        }
238    }
239
240    #[test]
241    fn a_tier_starts_onboard_and_only_card_first_ever_leaves_draining() {
242        let mut onboard_first = TierMode::new(WritePolicy::OnboardFirst);
243        assert_eq!(onboard_first.mode(), WriteMode::Onboard);
244        onboard_first.attached();
245        assert_eq!(onboard_first.mode(), WriteMode::Draining);
246        assert!(!onboard_first.writes_to_volume());
247        assert!(
248            !onboard_first.may_promote(true, false),
249            "OnboardFirst never writes direct, however drained the backlog is"
250        );
251
252        let mut card_first = TierMode::new(WritePolicy::CardFirst);
253        card_first.attached();
254        assert!(card_first.may_promote(true, false));
255        card_first.promoted();
256        assert_eq!(card_first.mode(), WriteMode::Direct);
257        assert!(card_first.writes_to_volume());
258        assert!(
259            !card_first.may_promote(true, false),
260            "already there, so nothing to drain for"
261        );
262    }
263
264    #[test]
265    fn a_pass_over_a_direct_tier_does_not_demote_it() {
266        // Under CardFirst a pass can still find the tail the onboard log
267        // buffered before the promotion; that is not a reason to stop writing
268        // direct.
269        let mut tier = TierMode::new(WritePolicy::CardFirst);
270        tier.attached();
271        tier.promoted();
272        tier.spooled();
273        assert_eq!(tier.mode(), WriteMode::Direct);
274
275        let mut draining = TierMode::new(WritePolicy::CardFirst);
276        draining.attached();
277        draining.spooled();
278        assert_eq!(draining.mode(), WriteMode::Draining);
279    }
280
281    #[test]
282    fn a_missing_volume_is_not_an_error_but_a_faulted_one_is() {
283        let mut tier = TierMode::new(WritePolicy::CardFirst);
284        tier.attached();
285        tier.promoted();
286
287        assert_eq!(tier.ready_to_spool(false, false), Ok(false));
288        assert_eq!(
289            tier.mode(),
290            WriteMode::Onboard,
291            "with no card, appends must stop being aimed at one"
292        );
293
294        tier.attached();
295        tier.promoted();
296        assert_eq!(tier.ready_to_spool(true, true), Err(Error::VolumeLost));
297        assert_eq!(tier.mode(), WriteMode::Onboard);
298        assert!(
299            !tier.may_promote(true, true),
300            "a faulted volume is not a target"
301        );
302
303        tier.attached();
304        assert_eq!(tier.ready_to_spool(true, false), Ok(true));
305    }
306
307    #[test]
308    fn only_a_missing_medium_reroutes_a_write() {
309        assert!(volume_gone(&Error::NotAttached));
310        assert!(volume_gone(&Error::Flash(
311            embedded_storage::nor_flash::NorFlashErrorKind::Other
312        )));
313        // A real complaint about the operation must surface, not be hidden by
314        // writing the sample somewhere else.
315        assert!(!volume_gone(&Error::PayloadTooLarge));
316        assert!(!volume_gone(&Error::NotMounted));
317        assert!(!volume_gone(&Error::NoSpace));
318    }
319
320    #[test]
321    fn merge_takes_the_winner_and_leaves_the_loser_alone() {
322        let alt = [0xAAu8; 8];
323        let mut buf = [0u8; 8];
324
325        // Volume newer: its bytes land in the caller's buffer.
326        let out = merge(
327            Some((header(10), 2)),
328            Some((header(20), 4)),
329            &alt,
330            &mut buf,
331            |v, o| v > o,
332        )
333        .unwrap()
334        .unwrap();
335        assert_eq!(out.0.timestamp, 20);
336        assert_eq!(&buf[..4], &[0xAA; 4]);
337
338        // Onboard newer: the buffer already holds it, so it is not touched.
339        buf = [0u8; 8];
340        let out = merge(
341            Some((header(30), 2)),
342            Some((header(20), 4)),
343            &alt,
344            &mut buf,
345            |v, o| v > o,
346        )
347        .unwrap()
348        .unwrap();
349        assert_eq!(out.0.timestamp, 30);
350        assert_eq!(buf, [0u8; 8], "the onboard read already filled it");
351
352        // The same helper reads the other direction for `oldest`.
353        let out = merge(
354            Some((header(30), 2)),
355            Some((header(20), 4)),
356            &alt,
357            &mut buf,
358            |v, o| v < o,
359        )
360        .unwrap()
361        .unwrap();
362        assert_eq!(out.0.timestamp, 20);
363    }
364
365    #[test]
366    fn merge_raises_rather_than_reporting_the_wrong_entry() {
367        let alt = [0xAAu8; 8];
368        let mut buf = [0u8; 2];
369        assert_eq!(
370            merge(
371                Some((header(10), 2)),
372                Some((header(20), 4)),
373                &alt,
374                &mut buf,
375                |v, o| v > o
376            ),
377            Err(Error::BufferTooSmall),
378            "silently reporting the onboard entry would answer a different question"
379        );
380
381        // Nothing onboard at all takes the same path.
382        assert_eq!(
383            merge(None, Some((header(20), 4)), &alt, &mut buf, |v, o| v > o),
384            Err(Error::BufferTooSmall)
385        );
386
387        // Nothing on the volume: the onboard answer passes through untouched.
388        assert_eq!(
389            merge(Some((header(10), 2)), None, &alt, &mut buf, |v, o| v > o),
390            Ok(Some((header(10), 2)))
391        );
392    }
393}