use embedded_storage::nor_flash::{NorFlash, ReadNorFlash};
use zerocopy::IntoBytes;
use crate::db::{LogPosition, Replicated, SensorDb, SpoolStats};
use crate::entry::EntryHeader;
use crate::error::Error;
use crate::run::{Run, deliver_samples, samples_in};
use crate::sector::LogId;
use crate::spool::cursor::{CURSOR_RECORD_SIZE, CursorRegion, SpoolCursorWire};
use crate::spool::policy::{
Attached, BatchSector, CursorFold, CursorScan, EraseTally, RunFingerprint, SpoolBudget,
SpoolFailure, SpoolProgress, SpoolerState, VolumeFill,
};
use crate::spool::port::Removable;
use crate::spool::tier::{
PROMOTE_MAX_BATCHES, TierMode, WriteMode, WritePolicy, merge, volume_gone,
};
enum Slot<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
Empty,
Ready(SensorDb<C, PAGE_SIZE, MAX_SECTORS>),
Faulted(SensorDb<C, PAGE_SIZE, MAX_SECTORS>),
}
pub struct Spooler<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
slot: Slot<C, PAGE_SIZE, MAX_SECTORS>,
state: SpoolerState,
scratch: [u8; PAGE_SIZE],
}
impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS> {
pub fn is_attached(&self) -> bool {
!matches!(self.slot, Slot::Empty)
}
pub fn is_faulted(&self) -> bool {
matches!(self.slot, Slot::Faulted(_))
}
pub fn resume_point(&self) -> Option<LogPosition> {
self.is_attached().then(|| self.state.resume())
}
pub fn source_log(&self) -> Option<LogId> {
self.state.source_log()
}
pub fn region(&self) -> CursorRegion {
*self.state.region()
}
pub fn pending_reconciliation(&self) -> u32 {
self.state.pending_reconciliation()
}
}
impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>
where
C: NorFlash + ReadNorFlash,
{
pub fn new(
source_log: Option<LogId>,
cursor_base: u32,
sector_size: u32,
) -> Result<Self, Error> {
Ok(Self {
slot: Slot::Empty,
state: SpoolerState::new(source_log, cursor_base, sector_size, PAGE_SIZE as u32)?,
scratch: [0xFF; PAGE_SIZE],
})
}
pub fn attach(
&mut self,
volume: SensorDb<C, PAGE_SIZE, MAX_SECTORS>,
) -> Result<Attached, Error> {
if !matches!(self.slot, Slot::Empty) {
return Err(Error::AlreadyAttached);
}
if !volume.is_mounted() {
return Err(Error::NotMounted);
}
let mut volume = volume;
volume.mark_as_replica();
let scan = scan_cursor(&mut volume, &self.state)?;
let landed = fingerprint_landed(&mut volume, &scan)?;
let attached = self.state.adopt_scan(scan, landed);
self.slot = Slot::Ready(volume);
Ok(attached)
}
pub fn reconcile<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
) -> Result<u32, Error>
where
S: NorFlash + ReadNorFlash,
{
let landed = self.state.take_pending();
if landed.is_empty() {
return Ok(0);
}
let mut found = RunFingerprint::new();
let mut moved = Replicated::NONE;
let cursor = source.read_from(
self.state.resume(),
landed.entries(),
|_, header, payload| {
found.push(header.sensor_id, header.timestamp);
moved.push(samples_in(header.is_run(), payload));
Ok(true)
},
)?;
if !self.state.accept_skip(&landed, &found, &cursor) {
return Ok(0);
}
source.note_spooled(cursor.next, moved);
Ok(cursor.entries)
}
pub fn fault(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>> {
if matches!(self.slot, Slot::Ready(_))
&& let Slot::Ready(volume) = core::mem::replace(&mut self.slot, Slot::Empty)
{
self.slot = Slot::Faulted(volume);
}
match &mut self.slot {
Slot::Faulted(volume) => Some(volume),
_ => None,
}
}
pub fn detach(&mut self) -> Option<SensorDb<C, PAGE_SIZE, MAX_SECTORS>> {
let taken = core::mem::replace(&mut self.slot, Slot::Empty);
self.state.reset();
match taken {
Slot::Empty => None,
Slot::Ready(volume) | Slot::Faulted(volume) => Some(volume),
}
}
pub fn volume(&self) -> Option<&SensorDb<C, PAGE_SIZE, MAX_SECTORS>> {
match &self.slot {
Slot::Ready(v) => Some(v),
_ => None,
}
}
pub fn volume_mut(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>> {
match &mut self.slot {
Slot::Ready(v) => Some(v),
_ => None,
}
}
pub fn volume_fill(&self) -> Option<VolumeFill> {
let volume = match &self.slot {
Slot::Empty => return None,
Slot::Ready(v) | Slot::Faulted(v) => v,
};
Some(VolumeFill::from_stats(&volume.stats()))
}
pub fn spool<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
budget: SpoolBudget,
) -> Result<SpoolProgress, Error>
where
S: NorFlash + ReadNorFlash,
{
if SP > PAGE_SIZE {
return Err(Error::GeometryMismatch);
}
match self.slot {
Slot::Empty => return Err(Error::NotAttached),
Slot::Faulted(_) => return Err(Error::VolumeLost),
Slot::Ready(_) => {}
}
match self.spool_inner(source, budget) {
Ok(progress) => Ok(progress),
Err(f) if !f.from_source && matches!(f.error, Error::Flash(_)) => {
self.fault();
Err(Error::VolumeLost)
}
Err(f) => Err(f.error),
}
}
fn spool_inner<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
budget: SpoolBudget,
) -> Result<SpoolProgress, SpoolFailure>
where
S: NorFlash + ReadNorFlash,
{
SpoolFailure::from_source(self.reconcile(source))?;
let Self {
slot,
state,
scratch,
} = self;
let Slot::Ready(volume) = slot else {
return Err(Error::NotAttached.into());
};
let from = state.resume();
let mut erased = EraseTally::new(volume.sectors_erased());
let probe = SpoolFailure::from_source(source.read_from(from, 1, |_, _, _| Ok(false)))?;
if probe.exhausted {
return Ok(SpoolProgress::idle(from, probe.gap));
}
let source_epoch =
SpoolFailure::from_source(source.sector_epoch_at(probe.next))?.unwrap_or(0);
let batch = state.plan_batch(source_epoch, volume.head_position(), budget);
if let Some((start, end)) = batch.erase(state.region()) {
let region = state.region();
volume
.with_region(region.base(), region.total_size(), |p| p.erase(start, end))?
.map_err(Error::from)?;
erased.cursor_erase();
}
write_record(
volume,
state.region(),
batch.sector(),
batch.intent_slot(),
&batch.intent(),
scratch,
)?;
let mut copied = Replicated::NONE;
let mut last_timestamp = 0u64;
let mut batch_sector = BatchSector::new();
let mut volume_failed = false;
let cursor = source
.read_from(from, budget.max_entries, |pos, header, payload| {
if !batch_sector.admits(pos.sequence) {
return Ok(false);
}
volume
.append_framed(header, payload)
.inspect_err(|_| volume_failed = true)?;
copied.push(samples_in(header.is_run(), payload));
last_timestamp = header.timestamp;
Ok(true)
})
.map_err(|error| SpoolFailure {
error,
from_source: !volume_failed,
})?;
volume.sync()?;
write_record(
volume,
state.region(),
batch.sector(),
batch.commit_slot(),
&batch.commit(cursor.next, copied, last_timestamp),
scratch,
)?;
state.commit_batch(&batch, cursor.next);
source.note_spooled(cursor.next, copied);
Ok(SpoolProgress {
entries_copied: copied.entries,
committed_upto: cursor.next,
caught_up: cursor.exhausted,
gap: cursor.gap,
volume_erased: erased.total(volume.sectors_erased()),
})
}
pub fn spool_until_caught_up<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
budget: SpoolBudget,
max_batches: u32,
) -> Result<SpoolProgress, Error>
where
S: NorFlash + ReadNorFlash,
{
let mut total = SpoolProgress {
committed_upto: self.state.resume(),
..SpoolProgress::default()
};
for _ in 0..max_batches {
let progress = self.spool(source, budget)?;
total.absorb(&progress);
if progress.caught_up {
break;
}
}
Ok(total)
}
}
impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>
where
C: NorFlash + ReadNorFlash + Removable,
{
pub fn spool_if_present<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
budget: SpoolBudget,
) -> Result<Option<SpoolProgress>, Error>
where
S: NorFlash + ReadNorFlash,
{
let present = match &mut self.slot {
Slot::Empty => return Err(Error::NotAttached),
Slot::Faulted(_) => return Err(Error::VolumeLost),
Slot::Ready(volume) => volume.driver_mut().is_present(),
};
if !present {
return Ok(None);
}
self.spool(source, budget).map(Some)
}
pub fn is_present(&mut self) -> bool {
match &mut self.slot {
Slot::Ready(volume) => volume.driver_mut().is_present(),
_ => false,
}
}
}
fn scan_cursor<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize>(
volume: &mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>,
state: &SpoolerState,
) -> Result<CursorScan, Error>
where
C: NorFlash + ReadNorFlash,
{
let region = *state.region();
let expected = state.expected_log();
let mut fold = CursorFold::new();
let mut buf = [0u8; CURSOR_RECORD_SIZE];
for at in region.slots() {
volume.with_region(region.base(), region.total_size(), |p| {
p.read(at.offset, &mut buf)
})??;
fold.feed(at, &buf, expected)?;
}
Ok(fold.finish())
}
fn fingerprint_landed<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize>(
volume: &mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>,
scan: &CursorScan,
) -> Result<RunFingerprint, Error>
where
C: NorFlash + ReadNorFlash,
{
let Some((dest, limit)) = scan.landed_probe() else {
return Ok(RunFingerprint::new());
};
let mut run = RunFingerprint::new();
let cursor = volume.read_from(dest, limit, |_, header, _| {
run.push(header.sensor_id, header.timestamp);
Ok(true)
})?;
Ok(scan.accept_landed(run, &cursor))
}
fn write_record<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize>(
volume: &mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>,
region: &CursorRegion,
sector: u8,
slot: u32,
record: &SpoolCursorWire,
scratch: &mut [u8; PAGE_SIZE],
) -> Result<(), Error>
where
C: NorFlash + ReadNorFlash,
{
scratch.fill(0xFF);
scratch[..CURSOR_RECORD_SIZE].copy_from_slice(record.as_bytes());
let offset = region.slot_offset(sector, slot);
volume.with_region(region.base(), region.total_size(), |p| {
p.write(offset, &scratch[..])
})??;
Ok(())
}
pub struct TieredDb<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize> {
onboard: SensorDb<S, SP, SS>,
spooler: Spooler<C, CP, CS>,
tier: TierMode,
}
impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
TieredDb<S, C, SP, SS, CP, CS>
where
S: NorFlash + ReadNorFlash,
C: NorFlash + ReadNorFlash,
{
pub fn new(
onboard: SensorDb<S, SP, SS>,
spooler: Spooler<C, CP, CS>,
policy: WritePolicy,
) -> Result<Self, Error> {
if !onboard.is_mounted() {
return Err(Error::NotMounted);
}
if SP > CP {
return Err(Error::GeometryMismatch);
}
Ok(Self {
onboard,
spooler,
tier: TierMode::new(policy),
})
}
pub fn attach(&mut self, volume: SensorDb<C, CP, CS>) -> Result<Attached, Error> {
let mut attached = self.spooler.attach(volume)?;
self.tier.attached();
self.onboard.restore_spool_watermark(attached.resume_from)?;
self.spooler.reconcile(&mut self.onboard)?;
if let Some(resume) = self.spooler.resume_point() {
attached.resume_from = resume;
}
Ok(attached)
}
pub fn detach(&mut self) -> Option<SensorDb<C, CP, CS>> {
let _ = self.recover_from_volume_loss();
self.tier.fell_back();
self.spooler.detach()
}
pub fn detach_without_recovery(&mut self) -> Option<SensorDb<C, CP, CS>> {
self.tier.fell_back();
self.spooler.detach()
}
pub fn append(&mut self, sensor_id: u16, timestamp: u64, payload: &[u8]) -> Result<(), Error> {
if !self.tier.writes_to_volume() {
return self.onboard.append(sensor_id, timestamp, payload);
}
let attempt = match self.spooler.volume_mut() {
Some(volume) => volume.append(sensor_id, timestamp, payload),
None => Err(Error::NotAttached),
};
match attempt {
Ok(()) => Ok(()),
Err(e) if volume_gone(&e) => {
self.recover_from_volume_loss()?;
self.onboard.append(sensor_id, timestamp, payload)
}
Err(e) => Err(e),
}
}
pub fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
if !self.tier.writes_to_volume() {
return self.onboard.append_run(run);
}
let attempt = match self.spooler.volume_mut() {
Some(volume) => volume.append_run(run),
None => Err(Error::NotAttached),
};
match attempt {
Ok(()) => Ok(()),
Err(e) if volume_gone(&e) => {
self.recover_from_volume_loss()?;
self.onboard.append_run(run)
}
Err(e) => Err(e),
}
}
pub fn sync(&mut self) -> Result<(), Error> {
if !self.tier.writes_to_volume() {
return self.onboard.sync();
}
let attempt = match self.spooler.volume_mut() {
Some(volume) => volume.sync(),
None => Err(Error::NotAttached),
};
match attempt {
Ok(()) => Ok(()),
Err(e) if volume_gone(&e) => {
self.recover_from_volume_loss()?;
self.onboard.sync()
}
Err(e) => Err(e),
}
}
fn recover_from_volume_loss(&mut self) -> Result<u32, Error> {
let Self {
onboard,
spooler,
tier,
} = self;
tier.fell_back();
let Some(volume) = spooler.fault() else {
return Ok(0);
};
volume.drain_unflushed(|header, payload| onboard.append_framed(header, payload))
}
fn try_promote(&mut self, budget: SpoolBudget) -> Result<(), Error> {
if !self
.tier
.may_promote(self.spooler.is_attached(), self.spooler.is_faulted())
{
return Ok(());
}
self.onboard.sync()?;
let progress =
self.spooler
.spool_until_caught_up(&mut self.onboard, budget, PROMOTE_MAX_BATCHES)?;
if progress.caught_up {
self.tier.promoted();
}
Ok(())
}
pub fn spool_step(&mut self, budget: SpoolBudget) -> Result<Option<SpoolProgress>, Error> {
if !self
.tier
.ready_to_spool(self.spooler.is_attached(), self.spooler.is_faulted())?
{
return Ok(None);
}
let progress = self.spooler.spool(&mut self.onboard, budget)?;
self.tier.spooled();
if progress.caught_up {
self.try_promote(budget)?;
}
Ok(Some(progress))
}
pub fn drain(
&mut self,
budget: SpoolBudget,
max_batches: u32,
) -> Result<Option<SpoolProgress>, Error> {
if !self
.tier
.ready_to_spool(self.spooler.is_attached(), self.spooler.is_faulted())?
{
return Ok(None);
}
let progress =
self.spooler
.spool_until_caught_up(&mut self.onboard, budget, max_batches)?;
self.tier.spooled();
if progress.caught_up {
self.try_promote(budget)?;
}
Ok(Some(progress))
}
pub fn mode(&self) -> WriteMode {
self.tier.mode()
}
pub fn policy(&self) -> WritePolicy {
self.tier.policy()
}
pub fn is_attached(&self) -> bool {
self.spooler.is_attached()
}
pub fn spool_stats(&self) -> SpoolStats {
self.onboard.spool_stats()
}
pub fn volume_fill(&self) -> Option<VolumeFill> {
self.spooler.volume_fill()
}
pub fn volume(&self) -> Option<&SensorDb<C, CP, CS>> {
self.spooler.volume()
}
pub fn volume_mut(&mut self) -> Option<&mut SensorDb<C, CP, CS>> {
self.spooler.volume_mut()
}
pub fn onboard(&self) -> &SensorDb<S, SP, SS> {
&self.onboard
}
pub fn onboard_mut(&mut self) -> &mut SensorDb<S, SP, SS> {
&mut self.onboard
}
pub fn into_parts(self) -> (SensorDb<S, SP, SS>, Spooler<C, CP, CS>) {
(self.onboard, self.spooler)
}
pub fn latest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error> {
let onboard = self.onboard.latest(sensor_id, buf)?;
let mut alt = [0u8; CP];
let from_volume = match self.spooler.volume_mut() {
Some(volume) => volume.latest(sensor_id, &mut alt)?,
None => return Ok(onboard),
};
merge(onboard, from_volume, &alt, buf, |v, o| v > o)
}
pub fn oldest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error> {
let onboard = self.onboard.oldest(sensor_id, buf)?;
let mut alt = [0u8; CP];
let from_volume = match self.spooler.volume_mut() {
Some(volume) => volume.oldest(sensor_id, &mut alt)?,
None => return Ok(onboard),
};
merge(onboard, from_volume, &alt, buf, |v, o| v < o)
}
pub fn query_range<F>(
&mut self,
sensor_id: Option<u16>,
t_start: u64,
t_end: u64,
mut callback: F,
) -> Result<u32, Error>
where
F: FnMut(&EntryHeader, &[u8]) -> bool,
{
let Some(volume) = self.spooler.volume_mut() else {
return self
.onboard
.query_range(sensor_id, t_start, t_end, callback);
};
let mut stopped = false;
let mut delivered = {
let mut watched = |header: &EntryHeader, payload: &[u8]| {
let go = callback(header, payload);
stopped |= !go;
go
};
volume.query_range(sensor_id, t_start, t_end, &mut watched)?
};
if stopped {
return Ok(delivered);
}
let mut scratch = [0u8; SP];
let mut expand =
|header: &EntryHeader, payload: &[u8], delivered: &mut u32, callback: &mut F| {
if sensor_id.is_some_and(|id| header.sensor_id != id) {
return false;
}
let Some(dst) = scratch.get_mut(..payload.len()) else {
return false;
};
dst.copy_from_slice(payload);
deliver_samples(
header.is_run(),
header.sensor_id,
header.timestamp,
dst,
t_start,
t_end,
delivered,
callback,
)
};
let watermark = self.onboard.spool_stats().watermark;
self.onboard
.read_from(watermark, u32::MAX, |_, header, payload| {
stopped = expand(header, payload, &mut delivered, &mut callback);
Ok(!stopped)
})?;
if stopped {
return Ok(delivered);
}
self.onboard.peek_unflushed(|header, payload| {
if !stopped {
stopped = expand(header, payload, &mut delivered, &mut callback);
}
Ok(())
})?;
Ok(delivered)
}
pub fn query_all<F>(&mut self, sensor_id: Option<u16>, callback: F) -> Result<u32, Error>
where
F: FnMut(&EntryHeader, &[u8]) -> bool,
{
self.query_range(sensor_id, 0, u64::MAX, callback)
}
pub fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
let unspooled = self.onboard.spool_stats().unspooled_samples;
let Some(volume) = self.spooler.volume_mut() else {
return self.onboard.count(sensor_id);
};
match sensor_id {
None => Ok(volume.count(None)?.saturating_add(unspooled)),
Some(id) => {
let on_volume = volume.count(Some(id))?;
let watermark = self.onboard.spool_stats().watermark;
let mut tail = 0u32;
let mut tally = |header: &EntryHeader, payload: &[u8]| {
if header.sensor_id == id {
tail += samples_in(header.is_run(), payload);
}
};
self.onboard
.read_from(watermark, u32::MAX, |_, header, payload| {
tally(header, payload);
Ok(true)
})?;
self.onboard.peek_unflushed(|header, payload| {
tally(header, payload);
Ok(())
})?;
Ok(on_volume.saturating_add(tail))
}
}
}
}
impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
TieredDb<S, C, SP, SS, CP, CS>
where
S: NorFlash + ReadNorFlash,
C: NorFlash + ReadNorFlash + Removable,
{
pub fn check_presence(&mut self) -> Result<u32, Error> {
if !self.spooler.is_attached() || self.spooler.is_faulted() {
return Ok(0);
}
if self.spooler.is_present() {
return Ok(0);
}
self.recover_from_volume_loss()
}
pub fn spool_step_if_present(
&mut self,
budget: SpoolBudget,
) -> Result<Option<SpoolProgress>, Error> {
self.check_presence()?;
if !self.spooler.is_attached() || self.spooler.is_faulted() {
return Ok(None);
}
self.spool_step(budget)
}
}
impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize> crate::port::LogSink
for TieredDb<S, C, SP, SS, CP, CS>
where
S: NorFlash + ReadNorFlash,
C: NorFlash + ReadNorFlash,
{
fn append(&mut self, sensor_id: u16, timestamp: u64, payload: &[u8]) -> Result<(), Error> {
TieredDb::append(self, sensor_id, timestamp, payload)
}
fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
TieredDb::append_run(self, run)
}
fn sync(&mut self) -> Result<(), Error> {
TieredDb::sync(self)
}
}
impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
crate::port::LogSource for TieredDb<S, C, SP, SS, CP, CS>
where
S: NorFlash + ReadNorFlash,
C: NorFlash + ReadNorFlash,
{
fn latest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error> {
TieredDb::latest(self, sensor_id, buf)
}
fn oldest(
&mut self,
sensor_id: u16,
buf: &mut [u8],
) -> Result<Option<(EntryHeader, usize)>, Error> {
TieredDb::oldest(self, sensor_id, buf)
}
fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
TieredDb::count(self, sensor_id)
}
fn query_range(
&mut self,
sensor_id: Option<u16>,
t_start: u64,
t_end: u64,
callback: &mut dyn FnMut(&EntryHeader, &[u8]) -> bool,
) -> Result<u32, Error> {
TieredDb::query_range(self, sensor_id, t_start, t_end, callback)
}
}
impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize> core::fmt::Debug
for TieredDb<S, C, SP, SS, CP, CS>
{
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("TieredDb")
.field("policy", &self.tier.policy())
.field("mode", &self.tier.mode())
.field("attached", &self.spooler.is_attached())
.finish_non_exhaustive()
}
}