sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! Compile-time checking of the sensor ID space.
//!
//! PURE: this module contains only macros. Nothing here touches flash.
//!
//! A [`SensorData`](crate::SensorData) type binds a struct to a
//! `(SENSOR_ID, SCHEMA_VERSION)` pair, and nothing stops two types from
//! claiming the same one. Most of the time that is caught when the entry is
//! read back:
//!
//! | The other type differs in | Read reports |
//! |---|---|
//! | schema version | [`SchemaMismatch`](crate::Error::SchemaMismatch) |
//! | payload size | [`SizeMismatch`](crate::Error::SizeMismatch) |
//! | **neither** | nothing — the bytes are reinterpreted |
//!
//! That last row is the reason this module exists. Two same-sized types under
//! one ID at one version are indistinguishable on flash, so a read hands back
//! the other type's bytes as a plausible value: `Humidity { percent: 41.0 }`
//! read as `Temperature { celsius: 41.0 }`. No error, no CRC failure — the
//! entry is perfectly intact, it just is not what was asked for. And because
//! the damage is in what was *written*, it cannot be repaired later.
//!
//! [`sensor_registry!`](crate::sensor_registry) turns that into a compile
//! error.

/// Assert at compile time that no two sensor types collide.
///
/// Lists the [`SensorData`](crate::SensorData) types a firmware uses and fails
/// the build if any two share a `SENSOR_ID` at the same `SCHEMA_VERSION`.
///
/// ```
/// use sensor_db::{SensorData, sensor_registry};
/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct Temperature { celsius: f32 }
/// impl SensorData for Temperature {
///     const SENSOR_ID: u16 = 0x01;
/// }
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct Humidity { percent: f32 }
/// impl SensorData for Humidity {
///     const SENSOR_ID: u16 = 0x02;
/// }
///
/// sensor_registry! {
///     Temperature,
///     Humidity,
/// }
/// ```
///
/// Give `Humidity` the same `SENSOR_ID` and the build stops, naming both types:
///
/// ```compile_fail
/// use sensor_db::{SensorData, sensor_registry};
/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct Temperature { celsius: f32 }
/// impl SensorData for Temperature {
///     const SENSOR_ID: u16 = 0x01;
/// }
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct Humidity { percent: f32 }
/// impl SensorData for Humidity {
///     const SENSOR_ID: u16 = 0x01;   // <-- taken, and the same size
/// }
///
/// sensor_registry! { Temperature, Humidity }
/// ```
///
/// ```text
/// error[E0080]: evaluation panicked: sensor registry: `Temperature` and
/// `Humidity` share a SENSOR_ID at the same SCHEMA_VERSION. ...
/// ```
///
/// # Schema evolution is not a collision
///
/// Sharing an ID at *different* versions is the supported way to evolve a
/// payload — each type reads its own era out of one log — so the registry
/// accepts it:
///
/// ```
/// # use sensor_db::{SensorData, sensor_registry};
/// # use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct TemperatureV0 { celsius: f32 }
/// impl SensorData for TemperatureV0 {
///     const SENSOR_ID: u16 = 0x01;
///     const SCHEMA_VERSION: u8 = 0;
/// }
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct TemperatureV1 { millikelvin: u32 }
/// impl SensorData for TemperatureV1 {
///     const SENSOR_ID: u16 = 0x01;
///     const SCHEMA_VERSION: u8 = 1;
/// }
///
/// sensor_registry! { TemperatureV0, TemperatureV1 }
/// ```
///
/// # What it checks, and what it cannot
///
/// The macro expands to an anonymous `const` block of assertions and defines
/// nothing, so it can appear in any module, as often as you like — but it only
/// ever knows about **the types you list**. It cannot see across crate
/// boundaries, and a type left off the list is not checked. Keep one
/// invocation naming every type the firmware writes, next to the ID
/// definitions, and add to it in the same commit that adds a sensor.
///
/// The pairwise expansion is quadratic in the number of types. At the scale a
/// sensor ID space actually reaches — tens — that is free; it is not built for
/// thousands.
#[macro_export]
macro_rules! sensor_registry {
    ($($ty:ty),* $(,)?) => {
        const _: () = { $crate::__sensor_registry_pairs!($($ty),*); };
    };
}

/// Walks the list, pairing the head against each of the tail, then recurses.
#[doc(hidden)]
#[macro_export]
macro_rules! __sensor_registry_pairs {
    () => {};
    ($head:ty $(, $tail:ty)*) => {
        $( $crate::__sensor_registry_collide!($head, $tail); )*
        $crate::__sensor_registry_pairs!($($tail),*);
    };
}

/// One pair. Split out so the assertion — the part that has to be exactly
/// right — is written once rather than inside a repetition.
#[doc(hidden)]
#[macro_export]
macro_rules! __sensor_registry_collide {
    ($a:ty, $b:ty) => {
        assert!(
            !(<$a as $crate::SensorData>::SENSOR_ID == <$b as $crate::SensorData>::SENSOR_ID
                && <$a as $crate::SensorData>::SCHEMA_VERSION
                    == <$b as $crate::SensorData>::SCHEMA_VERSION),
            concat!(
                "sensor registry: `",
                stringify!($a),
                "` and `",
                stringify!($b),
                "` share a SENSOR_ID at the same SCHEMA_VERSION. Entries written \
                 by one would be read back as the other, and if the two are the \
                 same size nothing detects it. Give one of them a different \
                 SENSOR_ID -- or, if this is a new era of the same measurement, \
                 bump its SCHEMA_VERSION.",
            )
        );
    };
}