1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
//! 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.
/// Walks the list, pairing the head against each of the tail, then recurses.
/// One pair. Split out so the assertion — the part that has to be exactly
/// right — is written once rather than inside a repetition.