Skip to main content

zigbee_core/storage/
flash.rs

1use core::future::poll_fn;
2use core::ops::Range;
3use core::pin::pin;
4use core::task::Poll;
5
6use embedded_storage_async::nor_flash::NorFlash;
7use sequential_storage::cache::NoCache;
8use sequential_storage::map::MapConfig;
9use sequential_storage::map::MapStorage;
10use zigbee_types::sync::yield_now;
11
12use super::StorageDriver;
13use crate::aps::aib;
14use crate::nwk::nib;
15
16// outgoing frame counters are stored this far ahead of the live value
17const HEADROOM: u32 = 1024;
18// incoming frame counters are stored rounded down to this granularity
19const WINDOW: u32 = 1024;
20
21pub(crate) const DATA: usize = {
22    let a = nib::NibId::MAX_FIELD_SIZE;
23    let b = aib::AibId::MAX_FIELD_SIZE;
24    if a > b { a } else { b }
25};
26// sequential-storage work buffer: encoded field + item overhead
27const SCRATCH: usize = DATA + 64;
28// every map item must fit into one flash sector (4 KiB on esp32)
29const _: () = assert!(SCRATCH <= 4096);
30
31// last-stored normalized image of a counter-bearing field, used to skip
32// writes while counters stay within their stored headroom
33pub(crate) type Shadow = ([u8; DATA], usize);
34
35// next counter value a rebooted device may use; two boundaries ahead so
36// the stored bound is refreshed a full HEADROOM before it could be reached
37pub(crate) const fn round_up(counter: u32) -> u32 {
38    (counter / HEADROOM)
39        .saturating_add(2)
40        .saturating_mul(HEADROOM)
41}
42
43pub(crate) const fn round_down(counter: u32) -> u32 {
44    (counter / WINDOW) * WINDOW
45}
46
47// key-value flash map shared by the information bases; `data` is the
48// staging buffer, encode a field into it then persist the prefix via store
49pub(crate) struct FlashMap<F: NorFlash> {
50    map: MapStorage<u16, F, NoCache>,
51    scratch: [u8; SCRATCH],
52    pub(crate) data: [u8; DATA],
53}
54
55impl<F: NorFlash> FlashMap<F> {
56    fn new(flash: F, range: Range<u32>) -> Self {
57        Self {
58            map: MapStorage::new(flash, MapConfig::new(range), NoCache::new()),
59            scratch: [0; SCRATCH],
60            data: [0; DATA],
61        }
62    }
63
64    pub(crate) async fn fetch(&mut self, key: u16) -> Option<&[u8]> {
65        self.map
66            .fetch_item::<&[u8]>(&mut self.scratch, &key)
67            .await
68            .ok()
69            .flatten()
70    }
71
72    // persists data[..len] under key; wear-leveled and crash-safe
73    pub(crate) async fn store(&mut self, key: u16, len: usize) -> bool {
74        let value: &[u8] = &self.data[..len];
75        self.map
76            .store_item(&mut self.scratch, &key, &value)
77            .await
78            .is_ok()
79    }
80}
81
82/// Persistence of the information bases over a NOR flash region.
83///
84/// Each persisted field is one map item, so a frame-counter update never
85/// rewrites keys or tables.
86pub struct FlashStorage<F: NorFlash> {
87    // held across awaits during flush; flush waits via a yielding
88    // try_lock loop so a concurrent flush cannot be starved
89    inner: spin::Mutex<Inner<F>>,
90}
91
92struct Inner<F: NorFlash> {
93    map: FlashMap<F>,
94    nib_shadow: Shadow,
95    aib_shadow: Shadow,
96}
97
98/// Initializes the NIB and AIB backed by the given flash region.
99///
100/// Restores all persisted fields on boot; fields never stored (or stored
101/// by an incompatible firmware) keep their defaults. Must be called
102/// instead of — not in addition to — the plain `init()` functions.
103/// Spawn a task running [`FlashStorage::run`] to persist changes.
104///
105/// `range` must be erase-sector aligned and span at least two sectors so
106/// `sequential-storage` has a spare sector for garbage collection, and
107/// must not overlap the firmware image or partition table.
108pub async fn init_with_flash<F: NorFlash>(flash: F, range: Range<u32>) -> FlashStorage<F> {
109    nib::init();
110    aib::init();
111
112    let mut map = FlashMap::new(flash, range);
113    nib::storage::restore(&mut map, nib::get_ref()).await;
114    aib::storage::restore(&mut map, aib::get_ref()).await;
115
116    FlashStorage {
117        inner: spin::Mutex::new(Inner {
118            map,
119            nib_shadow: ([0; DATA], 0),
120            aib_shadow: ([0; DATA], 0),
121        }),
122    }
123}
124
125impl<F: NorFlash> StorageDriver for FlashStorage<F> {
126    /// Persists information-base changes as they happen; run this in its own
127    /// task, or let the application runtime drive it.
128    ///
129    /// Wakes whenever a persisted NIB/AIB attribute changes and flushes the
130    /// dirty fields. Counter headroom keeps the actual flash write rate far
131    /// below the change rate.
132    async fn run(&self) {
133        loop {
134            wait_any(nib::changed(), aib::changed()).await;
135            self.flush().await;
136        }
137    }
138
139    async fn flush(&self) {
140        let mut inner = loop {
141            if let Some(inner) = self.inner.try_lock() {
142                break inner;
143            }
144            // another task is mid-flush; let it finish
145            yield_now().await;
146        };
147        let Inner {
148            map,
149            nib_shadow,
150            aib_shadow,
151        } = &mut *inner;
152        nib::storage::flush(map, nib_shadow, nib::get_ref()).await;
153        aib::storage::flush(map, aib_shadow, aib::get_ref()).await;
154    }
155}
156
157async fn wait_any(a: impl Future<Output = ()>, b: impl Future<Output = ()>) {
158    let mut a = pin!(a);
159    let mut b = pin!(b);
160    poll_fn(|cx| {
161        if a.as_mut().poll(cx).is_ready() || b.as_mut().poll(cx).is_ready() {
162            Poll::Ready(())
163        } else {
164            Poll::Pending
165        }
166    })
167    .await;
168}
169
170#[cfg(test)]
171mod tests {
172    use core::pin::pin;
173    use core::task::Context;
174    use core::task::RawWaker;
175    use core::task::RawWakerVTable;
176    use core::task::Waker;
177
178    use sequential_storage::mock_flash::MockFlashBase;
179    use sequential_storage::mock_flash::WriteCountCheck;
180    use zigbee_types::IeeeAddress;
181    use zigbee_types::StorageVec;
182
183    use super::*;
184    use crate::aps::aib::Aib;
185    use crate::aps::aib::AibId;
186    use crate::nwk::nib::NetworkSecurityMaterialDescriptor;
187    use crate::nwk::nib::Nib;
188    use crate::nwk::nib::NibId;
189
190    // 4 pages of 4 KiB, 1-byte words: mirrors the esp32-c6 layout
191    type Flash = MockFlashBase<4, 1, 4096>;
192
193    fn block_on<F: Future>(fut: F) -> F::Output {
194        fn noop(_: *const ()) {}
195        fn clone(p: *const ()) -> RawWaker {
196            RawWaker::new(p, &VTABLE)
197        }
198        static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, noop, noop, noop);
199        let waker = unsafe { Waker::from_raw(RawWaker::new(core::ptr::null(), &VTABLE)) };
200        let mut cx = Context::from_waker(&waker);
201        let mut fut = pin!(fut);
202        loop {
203            if let Poll::Ready(v) = fut.as_mut().poll(&mut cx) {
204                return v;
205            }
206        }
207    }
208
209    fn fresh_ibs() -> (Nib, Aib) {
210        let nib = Nib::new();
211        let aib = Aib::new();
212        (nib, aib)
213    }
214
215    fn new_map() -> FlashMap<Flash> {
216        FlashMap::new(
217            Flash::new(WriteCountCheck::Twice, None, true),
218            Flash::FULL_FLASH_RANGE,
219        )
220    }
221
222    fn security_material(counter: u32) -> StorageVec<NetworkSecurityMaterialDescriptor, 2> {
223        let mut set = StorageVec::new();
224        let _ = set.push(NetworkSecurityMaterialDescriptor {
225            key_seq_number: 0,
226            outgoing_frame_counter: counter,
227            incoming_frame_counter_set: StorageVec::new(),
228            key: zigbee_types::ByteArray([0xaa; 16]),
229            network_key_type: 0x01,
230        });
231        set
232    }
233
234    #[test]
235    fn setter_marks_dirty_getter_does_not() {
236        let (nib, _) = fresh_ibs();
237        let _ = nib.take_dirty();
238
239        let _ = nib.network_address();
240        assert_eq!(nib.take_dirty(), 0);
241
242        nib.update_network_address(|value| *value = 0x1234);
243        assert_eq!(nib.take_dirty(), 1 << (NibId::network_address as u64));
244        assert_eq!(nib.take_dirty(), 0);
245    }
246
247    #[test]
248    fn ram_only_setter_does_not_mark_dirty() {
249        let (nib, _) = fresh_ibs();
250        let _ = nib.take_dirty();
251        nib.update_sequence_number(|value| *value = 42);
252        assert_eq!(nib.take_dirty(), 0);
253    }
254
255    #[test]
256    fn setter_signals_change() {
257        let (nib, _) = fresh_ibs();
258        nib.update_network_address(|value| *value = 0x4321);
259        block_on(nib::changed());
260    }
261
262    #[test]
263    fn export_is_compact_and_roundtrips() {
264        let (nib, _) = fresh_ibs();
265        let mut buf = [0u8; NibId::MAX_FIELD_SIZE];
266
267        let len = nib.export_field(NibId::neighbor_table, &mut buf).unwrap();
268        assert_eq!(len, 2);
269
270        nib.update_security_material_set(|value| *value = security_material(7));
271        let len = nib
272            .export_field(NibId::security_material_set, &mut buf)
273            .unwrap();
274
275        let (nib2, _) = fresh_ibs();
276        let _ = nib2.take_dirty();
277        assert!(nib2.import_field(NibId::security_material_set, &buf[..len]));
278        let restored = nib2.security_material_set();
279        assert_eq!(restored.first().unwrap().outgoing_frame_counter, 7);
280        assert_eq!(restored.first().unwrap().key.0, [0xaa; 16]);
281        assert_eq!(nib2.take_dirty(), 0);
282    }
283
284    #[test]
285    fn import_of_garbage_keeps_default() {
286        let (nib, _) = fresh_ibs();
287        assert!(!nib.import_field(NibId::network_address, &[0x01]));
288        assert_eq!(*nib.network_address(), 0xffff);
289    }
290
291    #[test]
292    fn storage_keys_are_bijective() {
293        for id in NibId::VARIANTS {
294            if let Some(key) = id.storage_key() {
295                assert_eq!(NibId::from_storage_key(key), Some(*id));
296            }
297        }
298        for id in AibId::VARIANTS {
299            if let Some(key) = id.storage_key() {
300                assert_eq!(AibId::from_storage_key(key), Some(*id));
301            }
302        }
303    }
304
305    #[test]
306    fn restore_from_empty_flash_keeps_defaults() {
307        let (nib, aib) = fresh_ibs();
308        let mut map = new_map();
309        block_on(nib::storage::restore(&mut map, &nib));
310        block_on(aib::storage::restore(&mut map, &aib));
311        assert_eq!(*nib.network_address(), 0xffff);
312        assert_eq!(
313            *aib.trust_center_address(),
314            IeeeAddress(0xffff_ffff_ffff_ffff)
315        );
316    }
317
318    #[test]
319    fn flush_and_restore_roundtrip() {
320        let (nib, aib) = fresh_ibs();
321        let mut map = new_map();
322        let mut nib_shadow: Shadow = ([0; DATA], 0);
323        let mut aib_shadow: Shadow = ([0; DATA], 0);
324
325        nib.update_network_address(|value| *value = 0x1234);
326        nib.update_panid(|value| *value = 0xabcd);
327        nib.update_extended_panid(|value| *value = 0x1122_3344_5566_7788);
328        aib.update_trust_center_address(|value| *value = IeeeAddress(0xdead_beef));
329        block_on(nib::storage::flush(&mut map, &mut nib_shadow, &nib));
330        block_on(aib::storage::flush(&mut map, &mut aib_shadow, &aib));
331
332        let (nib2, aib2) = fresh_ibs();
333        block_on(nib::storage::restore(&mut map, &nib2));
334        block_on(aib::storage::restore(&mut map, &aib2));
335        assert_eq!(*nib2.network_address(), 0x1234);
336        assert_eq!(*nib2.panid(), 0xabcd);
337        assert_eq!(*nib2.extended_panid(), 0x1122_3344_5566_7788);
338        assert_eq!(*aib2.trust_center_address(), IeeeAddress(0xdead_beef));
339    }
340
341    #[test]
342    fn restored_outgoing_counter_is_ahead_of_any_used_value() {
343        let (nib, _) = fresh_ibs();
344        let mut map = new_map();
345        let mut shadow: Shadow = ([0; DATA], 0);
346
347        nib.update_security_material_set(|value| *value = security_material(5));
348        block_on(nib::storage::flush(&mut map, &mut shadow, &nib));
349
350        let (nib2, _) = fresh_ibs();
351        block_on(nib::storage::restore(&mut map, &nib2));
352        let restored = nib2
353            .security_material_set()
354            .first()
355            .unwrap()
356            .outgoing_frame_counter;
357        assert_eq!(restored, round_up(5));
358        assert!(restored > 5 + HEADROOM);
359    }
360
361    #[test]
362    fn counter_ticks_within_headroom_do_not_write_flash() {
363        let flush_writes = |ticks: u32| {
364            let (nib, _) = fresh_ibs();
365            let flash = Flash::new(WriteCountCheck::Twice, None, true);
366            let baseline = flash.stats_snapshot();
367            let mut map = FlashMap::new(flash, Flash::FULL_FLASH_RANGE);
368            let mut shadow: Shadow = ([0; DATA], 0);
369
370            nib.update_security_material_set(|value| *value = security_material(0));
371            block_on(nib::storage::flush(&mut map, &mut shadow, &nib));
372            for counter in 1..=ticks {
373                nib.update_security_material_set(|value| *value = security_material(counter));
374                block_on(nib::storage::flush(&mut map, &mut shadow, &nib));
375            }
376
377            let FlashMap { map, .. } = map;
378            let (flash, _) = map.destroy();
379            baseline.compare_to(flash.stats_snapshot()).bytes_written
380        };
381
382        assert_eq!(flush_writes(0), flush_writes(HEADROOM - 1));
383        assert!(flush_writes(HEADROOM) > flush_writes(HEADROOM - 1));
384    }
385
386    #[test]
387    fn failed_store_rearms_dirty_bit() {
388        let (nib, _) = fresh_ibs();
389        let mut flash = Flash::new(WriteCountCheck::Twice, None, true);
390        flash.bytes_until_shutoff = Some(0);
391        let mut map = FlashMap::new(flash, Flash::FULL_FLASH_RANGE);
392        let mut shadow: Shadow = ([0; DATA], 0);
393
394        nib.update_network_address(|value| *value = 0x1234);
395        block_on(nib::storage::flush(&mut map, &mut shadow, &nib));
396        assert_eq!(nib.take_dirty(), 1 << (NibId::network_address as u64));
397    }
398}