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}