sensor_db/registry.rs
1//! Compile-time checking of the sensor ID space.
2//!
3//! PURE: this module contains only macros. Nothing here touches flash.
4//!
5//! A [`SensorData`](crate::SensorData) type binds a struct to a
6//! `(SENSOR_ID, SCHEMA_VERSION)` pair, and nothing stops two types from
7//! claiming the same one. Most of the time that is caught when the entry is
8//! read back:
9//!
10//! | The other type differs in | Read reports |
11//! |---|---|
12//! | schema version | [`SchemaMismatch`](crate::Error::SchemaMismatch) |
13//! | payload size | [`SizeMismatch`](crate::Error::SizeMismatch) |
14//! | **neither** | nothing — the bytes are reinterpreted |
15//!
16//! That last row is the reason this module exists. Two same-sized types under
17//! one ID at one version are indistinguishable on flash, so a read hands back
18//! the other type's bytes as a plausible value: `Humidity { percent: 41.0 }`
19//! read as `Temperature { celsius: 41.0 }`. No error, no CRC failure — the
20//! entry is perfectly intact, it just is not what was asked for. And because
21//! the damage is in what was *written*, it cannot be repaired later.
22//!
23//! [`sensor_registry!`](crate::sensor_registry) turns that into a compile
24//! error.
25
26/// Assert at compile time that no two sensor types collide.
27///
28/// Lists the [`SensorData`](crate::SensorData) types a firmware uses and fails
29/// the build if any two share a `SENSOR_ID` at the same `SCHEMA_VERSION`.
30///
31/// ```
32/// use sensor_db::{SensorData, sensor_registry};
33/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
34///
35/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
36/// #[repr(C)]
37/// struct Temperature { celsius: f32 }
38/// impl SensorData for Temperature {
39/// const SENSOR_ID: u16 = 0x01;
40/// }
41///
42/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
43/// #[repr(C)]
44/// struct Humidity { percent: f32 }
45/// impl SensorData for Humidity {
46/// const SENSOR_ID: u16 = 0x02;
47/// }
48///
49/// sensor_registry! {
50/// Temperature,
51/// Humidity,
52/// }
53/// ```
54///
55/// Give `Humidity` the same `SENSOR_ID` and the build stops, naming both types:
56///
57/// ```compile_fail
58/// use sensor_db::{SensorData, sensor_registry};
59/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
60///
61/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
62/// #[repr(C)]
63/// struct Temperature { celsius: f32 }
64/// impl SensorData for Temperature {
65/// const SENSOR_ID: u16 = 0x01;
66/// }
67///
68/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
69/// #[repr(C)]
70/// struct Humidity { percent: f32 }
71/// impl SensorData for Humidity {
72/// const SENSOR_ID: u16 = 0x01; // <-- taken, and the same size
73/// }
74///
75/// sensor_registry! { Temperature, Humidity }
76/// ```
77///
78/// ```text
79/// error[E0080]: evaluation panicked: sensor registry: `Temperature` and
80/// `Humidity` share a SENSOR_ID at the same SCHEMA_VERSION. ...
81/// ```
82///
83/// # Schema evolution is not a collision
84///
85/// Sharing an ID at *different* versions is the supported way to evolve a
86/// payload — each type reads its own era out of one log — so the registry
87/// accepts it:
88///
89/// ```
90/// # use sensor_db::{SensorData, sensor_registry};
91/// # use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
92/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
93/// #[repr(C)]
94/// struct TemperatureV0 { celsius: f32 }
95/// impl SensorData for TemperatureV0 {
96/// const SENSOR_ID: u16 = 0x01;
97/// const SCHEMA_VERSION: u8 = 0;
98/// }
99///
100/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
101/// #[repr(C)]
102/// struct TemperatureV1 { millikelvin: u32 }
103/// impl SensorData for TemperatureV1 {
104/// const SENSOR_ID: u16 = 0x01;
105/// const SCHEMA_VERSION: u8 = 1;
106/// }
107///
108/// sensor_registry! { TemperatureV0, TemperatureV1 }
109/// ```
110///
111/// # What it checks, and what it cannot
112///
113/// The macro expands to an anonymous `const` block of assertions and defines
114/// nothing, so it can appear in any module, as often as you like — but it only
115/// ever knows about **the types you list**. It cannot see across crate
116/// boundaries, and a type left off the list is not checked. Keep one
117/// invocation naming every type the firmware writes, next to the ID
118/// definitions, and add to it in the same commit that adds a sensor.
119///
120/// The pairwise expansion is quadratic in the number of types. At the scale a
121/// sensor ID space actually reaches — tens — that is free; it is not built for
122/// thousands.
123#[macro_export]
124macro_rules! sensor_registry {
125 ($($ty:ty),* $(,)?) => {
126 const _: () = { $crate::__sensor_registry_pairs!($($ty),*); };
127 };
128}
129
130/// Walks the list, pairing the head against each of the tail, then recurses.
131#[doc(hidden)]
132#[macro_export]
133macro_rules! __sensor_registry_pairs {
134 () => {};
135 ($head:ty $(, $tail:ty)*) => {
136 $( $crate::__sensor_registry_collide!($head, $tail); )*
137 $crate::__sensor_registry_pairs!($($tail),*);
138 };
139}
140
141/// One pair. Split out so the assertion — the part that has to be exactly
142/// right — is written once rather than inside a repetition.
143#[doc(hidden)]
144#[macro_export]
145macro_rules! __sensor_registry_collide {
146 ($a:ty, $b:ty) => {
147 assert!(
148 !(<$a as $crate::SensorData>::SENSOR_ID == <$b as $crate::SensorData>::SENSOR_ID
149 && <$a as $crate::SensorData>::SCHEMA_VERSION
150 == <$b as $crate::SensorData>::SCHEMA_VERSION),
151 concat!(
152 "sensor registry: `",
153 stringify!($a),
154 "` and `",
155 stringify!($b),
156 "` share a SENSOR_ID at the same SCHEMA_VERSION. Entries written \
157 by one would be read back as the other, and if the two are the \
158 same size nothing detects it. Give one of them a different \
159 SENSOR_ID -- or, if this is a new era of the same measurement, \
160 bump its SCHEMA_VERSION.",
161 )
162 );
163 };
164}