sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! Entry header and CRC computation.

use crc::{CRC_16_IBM_SDLC, CRC_32_ISCSI, Crc};
use zerocopy::{
    FromBytes, Immutable, IntoBytes, KnownLayout, Unaligned,
    little_endian::{U16, U64},
};

/// Entry marker byte: one sample, the payload stored as given.
pub const ENTRY_MARKER: u8 = 0xAA;

/// Entry marker byte for a [run](crate::run): many evenly spaced samples under
/// one header.
///
/// A separate marker rather than a flag in the payload, because the marker is
/// covered by [`header_crc`](EntryHeaderWire::header_crc) and only this crate
/// writes it. A payload flag could not be trusted: the raw
/// [`append`](crate::LogSink::append) path stores arbitrary bytes, so any
/// payload that happened to carry the flag pattern would be read as a run and
/// hand the sector index an invented time span. Here the question "is this a
/// run?" is answered structurally, before the payload is looked at.
pub const ENTRY_MARKER_RUN: u8 = 0xAB;

/// Size of the entry header in bytes (including the trailing header CRC).
pub const ENTRY_HEADER_SIZE: usize = 16;

/// Number of leading header bytes covered by the integrity CRCs (marker through
/// payload_len) — i.e. the header excluding its own `header_crc` field.
pub const ENTRY_HEADER_FIELDS_SIZE: usize = 14;

/// Size of the entry header CRC in bytes.
pub const ENTRY_HEADER_CRC_SIZE: usize = 2;

/// Size of the CRC-32C trailer in bytes.
pub const ENTRY_CRC_SIZE: usize = 4;

/// Total overhead per entry (header + trailing CRC).
pub const ENTRY_OVERHEAD: usize = ENTRY_HEADER_SIZE + ENTRY_CRC_SIZE;

/// Flags byte value for an uncommitted entry (all bits set, NOR flash erased state).
pub const FLAGS_UNCOMMITTED: u8 = 0xFF;

/// Flags byte value for a committed entry (all bits cleared).
pub const FLAGS_COMMITTED: u8 = 0x00;

/// CRC-16 used for the entry header integrity field.
const HEADER_CRC: Crc<u16> = Crc::<u16>::new(&CRC_16_IBM_SDLC);

/// Wire-format entry header for zerocopy serialization.
///
/// Layout (16 bytes):
/// - marker: u8 (0xAA single, 0xAB run)
/// - flags: u8 (0xFF=uncommitted, 0x00=committed)
/// - sensor_id: u16 LE
/// - timestamp: u64 LE
/// - payload_len: u16 LE
/// - header_crc: u16 LE (CRC-16 over the preceding 14 bytes, flags masked)
///
/// The header CRC lets the scanner reject a false `0xAA` marker structurally —
/// before trusting `payload_len` to size a read — rather than relying only on
/// heuristics about the flags and length fields.
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned, Clone, Copy)]
#[repr(C, packed)]
pub struct EntryHeaderWire {
    /// Start-of-entry marker: [`ENTRY_MARKER`] for a single sample,
    /// [`ENTRY_MARKER_RUN`] for a run.
    pub marker: u8,
    /// [`FLAGS_UNCOMMITTED`] until the commit pass clears it to
    /// [`FLAGS_COMMITTED`]. Masked out of both CRCs.
    pub flags: u8,
    /// Which sensor produced the entry.
    pub sensor_id: U16,
    /// Caller-supplied timestamp; the crate never interprets its epoch or unit.
    pub timestamp: U64,
    /// Payload length in bytes, at most `PAGE_SIZE - ENTRY_OVERHEAD`.
    pub payload_len: U16,
    /// CRC-16 over the preceding 14 bytes, validated before `payload_len` is
    /// trusted to size a read.
    pub header_crc: U16,
}

impl EntryHeaderWire {
    /// Create a new entry header with the given parameters.
    ///
    /// The flags field is set to `0xFF` (uncommitted). The commit pass
    /// clears it to `0x00` after the page has been written to flash. The header
    /// CRC is computed with the flags masked, so it is stable across that flip.
    pub fn new(sensor_id: u16, timestamp: u64, payload_len: u16) -> Self {
        Self::with_marker(ENTRY_MARKER, sensor_id, timestamp, payload_len)
    }

    /// Create a header for a [run](crate::run) entry.
    ///
    /// `timestamp` is the *first* sample's; the rest are derived from the
    /// interval stored in the payload.
    pub fn new_run(sensor_id: u16, base_timestamp: u64, payload_len: u16) -> Self {
        Self::with_marker(ENTRY_MARKER_RUN, sensor_id, base_timestamp, payload_len)
    }

    fn with_marker(marker: u8, sensor_id: u16, timestamp: u64, payload_len: u16) -> Self {
        let mut header = Self {
            marker,
            flags: FLAGS_UNCOMMITTED,
            sensor_id: U16::new(sensor_id),
            timestamp: U64::new(timestamp),
            payload_len: U16::new(payload_len),
            header_crc: U16::new(0),
        };
        header.header_crc = U16::new(header.compute_header_crc());
        header
    }

    /// Compute the CRC-16 over the header fields (flags masked to `0xFF`),
    /// excluding the `header_crc` field itself.
    pub fn compute_header_crc(&self) -> u16 {
        let mut bytes = [0u8; ENTRY_HEADER_FIELDS_SIZE];
        bytes.copy_from_slice(&self.as_bytes()[..ENTRY_HEADER_FIELDS_SIZE]);
        bytes[1] = FLAGS_UNCOMMITTED; // mask flags so committed/uncommitted match
        HEADER_CRC.checksum(&bytes)
    }

    /// Check that the stored header CRC matches the header fields.
    pub fn header_crc_valid(&self) -> bool {
        self.header_crc.get() == self.compute_header_crc()
    }

    /// Check if this header has a valid marker byte, of either kind.
    pub fn is_valid_marker(&self) -> bool {
        is_entry_marker(self.marker)
    }

    /// Whether this entry holds a [run](crate::run) rather than one sample.
    pub fn is_run(&self) -> bool {
        self.marker == ENTRY_MARKER_RUN
    }

    /// Convert to the public API struct.
    pub fn to_header(&self) -> EntryHeader {
        EntryHeader {
            sensor_id: self.sensor_id.get(),
            timestamp: self.timestamp.get(),
            payload_len: self.payload_len.get(),
            kind: if self.is_run() {
                EntryKind::Run
            } else {
                EntryKind::Single
            },
        }
    }
}

/// Whether `byte` starts an entry of either kind.
///
/// The scanners resync a byte at a time on anything that is not an entry, so
/// this is the one place that says what "an entry starts here" means.
pub fn is_entry_marker(byte: u8) -> bool {
    byte == ENTRY_MARKER || byte == ENTRY_MARKER_RUN
}

/// What a stored entry holds.
///
/// Reads never hand out [`Run`](Self::Run): every query, `latest` and `oldest`
/// expands a run into the samples it holds, each described as a
/// [`Single`](Self::Single). It surfaces only on the *replication* stream —
/// [`read_from`](crate::SensorDb::read_from) and the unflushed-tail walks —
/// which deals in entries, and where the receiving log needs it to store the
/// entry back as a run rather than as one opaque sample.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum EntryKind {
    /// One sample; the payload is what the caller appended.
    #[default]
    Single,
    /// A [run](crate::run) of evenly spaced samples.
    Run,
}

/// Public API entry header (native endianness).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EntryHeader {
    /// Which sensor produced the entry.
    pub sensor_id: u16,
    /// The timestamp the entry was appended with.
    ///
    /// For a [`Run`](EntryKind::Run) this is the *first* sample's; the rest are
    /// derived from the interval stored in the payload.
    pub timestamp: u64,
    /// Payload length in bytes, excluding the entry header and CRC.
    pub payload_len: u16,
    /// Whether the payload is one sample or a run of them.
    ///
    /// Always [`Single`](EntryKind::Single) on a read path, which expands runs.
    pub kind: EntryKind,
}

impl EntryHeader {
    /// Whether this entry holds a [run](crate::run) rather than one sample.
    pub fn is_run(&self) -> bool {
        matches!(self.kind, EntryKind::Run)
    }
}

/// Compute CRC-32C over offset, header (with flags masked), and payload.
///
/// Uses CRC-32C (CRC-32/ISCSI), the same algorithm used by btrfs, ext4, and iSCSI.
/// The `offset_in_sector` is included in the digest to detect entries transplanted
/// to a different position (e.g. after a partial erase). The flags byte is always
/// masked to `0xFF` before hashing so that the CRC is identical for both the
/// uncommitted and committed states.
pub fn compute_entry_crc(header: &EntryHeaderWire, payload: &[u8], offset_in_sector: u32) -> u32 {
    const CRC: Crc<u32> = Crc::<u32>::new(&CRC_32_ISCSI);
    let mut digest = CRC.digest();

    // Include offset-in-sector (not stored on flash, but known during scan)
    digest.update(&offset_in_sector.to_le_bytes());

    // Include the logical header fields (excluding the header_crc field) with
    // flags masked to 0xFF
    let mut header_bytes = [0u8; ENTRY_HEADER_FIELDS_SIZE];
    header_bytes.copy_from_slice(&header.as_bytes()[..ENTRY_HEADER_FIELDS_SIZE]);
    header_bytes[1] = FLAGS_UNCOMMITTED; // mask flags
    digest.update(&header_bytes);

    // Include payload
    digest.update(payload);
    digest.finalize()
}