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
165
166
167
168
169
170
171
172
173
//! Binding a Rust type to a sensor ID: the [`SensorData`] trait.
//!
//! Implementing it is what makes a type storable — the sensor ID and the schema
//! version stop being arguments a caller has to remember and become properties
//! of the type. Everything you then *do* with such a type lives on the logs and
//! on the capability ports, not here:
//!
//! ```ignore
//! // On a concrete log — no trait import needed:
//! db.append_sensor(timestamp, &Temperature { celsius: 25.5 })?;
//! let latest = db.latest_sensor::<Temperature>()?;
//!
//! // Over any log, in generic code:
//! use sensor_db::{LogSinkExt, LogSourceExt};
//!
//! fn record<L: LogSinkExt>(log: &mut L, t: u64) -> Result<(), Error> {
//! log.append_sensor(t, &Temperature { celsius: 25.5 })
//! }
//! ```
//!
//! # Example
//!
//! ```ignore
//! use zerocopy::{FromBytes, IntoBytes, KnownLayout, Immutable};
//! use sensor_db::SensorData;
//!
//! #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
//! #[repr(C)]
//! struct Temperature {
//! celsius: f32,
//! }
//!
//! impl SensorData for Temperature {
//! const SENSOR_ID: u16 = 0x01;
//! }
//! ```
use ;
// ---------------------------------------------------------------------------
// SensorData trait (base — users implement this)
// ---------------------------------------------------------------------------
/// Base trait for sensor data types that can be stored and retrieved with type safety.
///
/// Implementors bind a zerocopy-compatible type to a specific sensor ID. Only
/// [`SENSOR_ID`](Self::SENSOR_ID) needs to be defined;
/// [`SCHEMA_VERSION`](Self::SCHEMA_VERSION) defaults to 0.
///
/// The methods that use it live on the logs and on the capability ports:
///
/// ```ignore
/// db.append_sensor(timestamp, &Temperature { celsius: 25.5 })?;
/// if let Some((_, t)) = db.latest_sensor::<Temperature>()? { ... }
/// ```
///
/// # Requirements
///
/// The implementing type must derive the following zerocopy traits:
/// - [`FromBytes`]: Allows reading from raw bytes
/// - [`IntoBytes`]: Allows writing to raw bytes
/// - [`KnownLayout`]: Provides compile-time layout information
/// - [`Immutable`]: Ensures the type has no interior mutability
///
/// Additionally, the type should use `#[repr(C)]` to ensure a stable layout.
///
/// # Endianness
///
/// The entry header uses little-endian wire format, but payload bytes are
/// stored as-is from the `#[repr(C)]` struct's in-memory representation
/// (native endianness). If your data will be read on a different architecture,
/// use `zerocopy::little_endian::*` wrapper types (e.g., `U32`, `I16`) in
/// your struct fields to ensure portable byte order.
///
/// # Struct Padding
///
/// `#[repr(C)]` structs may contain padding bytes between fields, which would
/// waste flash space — but this is not a footgun you have to watch for, because
/// `IntoBytes` refuses to derive for a type with padding and reports the exact
/// number of wasted bytes. When it does, either:
/// - Use `#[repr(C, packed)]` (may cause unaligned access on some platforms)
/// - Order fields from largest to smallest alignment
/// - Use only types with alignment ≤ 1 (e.g., `u8`, `zerocopy::little_endian::*`)
///
/// # Example
///
/// With the `derive` feature, the ID and version are named at the type:
///
/// ```ignore
/// use sensor_db::SensorData;
/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, SensorData)]
/// #[sensor(id = 0x02, version = 1)]
/// #[repr(C)]
/// struct Accelerometer {
/// x: i16,
/// y: i16,
/// z: i16,
/// }
/// ```
///
/// Written out, which is all the derive expands to:
///
/// ```ignore
/// use sensor_db::SensorData;
/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
///
/// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
/// #[repr(C)]
/// struct Accelerometer {
/// x: i16,
/// y: i16,
/// z: i16,
/// }
///
/// impl SensorData for Accelerometer {
/// const SENSOR_ID: u16 = 0x02;
/// const SCHEMA_VERSION: u8 = 1;
/// }
/// ```
///
/// The zerocopy derives are written out in both, because a derive macro cannot
/// add attributes to the item it is applied to, and because zerocopy's derives
/// expand to absolute `::zerocopy::` paths — so `zerocopy` must be a direct
/// dependency of your crate regardless. Import its traits through
/// [`sensor_db::zerocopy`](crate::zerocopy) to keep the version in step with
/// the one this crate's bounds name.