kernel/hil/
flash.rs

Help
1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Interface for reading, writing, and erasing flash storage pages.
6//!
7//! Operates on single pages. The page size is set by the associated type
8//! `page`. Here is an example of a page type and implementation of this trait:
9//!
10//! ```rust
11//! use core::ops::{Index, IndexMut};
12//!
13//! use kernel::hil;
14//! use kernel::ErrorCode;
15//!
16//! // Size in bytes
17//! const PAGE_SIZE: u32 = 1024;
18//!
19//! struct NewChipPage(pub [u8; PAGE_SIZE as usize]);
20//!
21//! impl Default for NewChipPage {
22//!     fn default() -> Self {
23//!         Self {
24//!             0: [0; PAGE_SIZE as usize],
25//!         }
26//!     }
27//! }
28//!
29//! impl NewChipPage {
30//!     fn len(&self) -> usize {
31//!         self.0.len()
32//!     }
33//! }
34//!
35//! impl Index<usize> for NewChipPage {
36//!     type Output = u8;
37//!
38//!     fn index(&self, idx: usize) -> &u8 {
39//!         &self.0[idx]
40//!     }
41//! }
42//!
43//! impl IndexMut<usize> for NewChipPage {
44//!     fn index_mut(&mut self, idx: usize) -> &mut u8 {
45//!         &mut self.0[idx]
46//!     }
47//! }
48//!
49//! impl AsMut<[u8]> for NewChipPage {
50//!     fn as_mut(&mut self) -> &mut [u8] {
51//!         &mut self.0
52//!     }
53//! }
54//!
55//! struct NewChipStruct {};
56//!
57//! impl<'a, C> hil::flash::HasClient<'a, C> for NewChipStruct {
58//!     fn set_client(&'a self, client: &'a C) { }
59//! }
60//!
61//! impl hil::flash::Flash for NewChipStruct {
62//!     type Page = NewChipPage;
63//!
64//!     fn read_page(&self, page_number: usize, buf: &'static mut Self::Page) -> Result<(), (ErrorCode, &'static mut Self::Page)> { Err((ErrorCode::FAIL, buf)) }
65//!     fn write_page(&self, page_number: usize, buf: &'static mut Self::Page) -> Result<(), (ErrorCode, &'static mut Self::Page)> { Err((ErrorCode::FAIL, buf)) }
66//!     fn erase_page(&self, page_number: usize) -> Result<(), ErrorCode> { Err(ErrorCode::FAIL) }
67//! }
68//! ```
69//!
70//! A user of this flash interface might look like:
71//!
72//! ```rust
73//! use kernel::utilities::cells::TakeCell;
74//! use kernel::hil;
75//!
76//! pub struct FlashUser<'a, F: hil::flash::Flash + 'static> {
77//!     driver: &'a F,
78//!     buffer: TakeCell<'static, F::Page>,
79//! }
80//!
81//! impl<'a, F: hil::flash::Flash> FlashUser<'a, F> {
82//!     pub fn new(driver: &'a F, buffer: &'static mut F::Page) -> FlashUser<'a, F> {
83//!         FlashUser {
84//!             driver: driver,
85//!             buffer: TakeCell::new(buffer),
86//!         }
87//!     }
88//! }
89//!
90//! impl<'a, F: hil::flash::Flash> hil::flash::Client<F> for FlashUser<'a, F> {
91//!     fn read_complete(&self, buffer: &'static mut F::Page, result: Result<(), hil::flash::Error>) {}
92//!     fn write_complete(&self, buffer: &'static mut F::Page, result: Result<(), hil::flash::Error>) { }
93//!     fn erase_complete(&self, result: Result<(), hil::flash::Error>) {}
94//! }
95//! ```
96
97use crate::ErrorCode;
98
99/// Flash errors returned in the callbacks.
100#[derive(Copy, Clone, Debug, Eq, PartialEq)]
101pub enum Error {
102    /// An error occurred during the flash operation.
103    FlashError,
104
105    /// A flash memory protection violation was detected.
106    FlashMemoryProtectionError,
107}
108
109pub trait HasClient<'a, C> {
110    /// Set the client for this flash peripheral. The client will be called
111    /// when operations complete.
112    fn set_client(&'a self, client: &'a C);
113}
114
115/// A page of writable persistent flash memory.
116pub trait Flash {
117    /// Type of a single flash page for the given implementation.
118    type Page: AsMut<[u8]> + Default;
119
120    /// Read a page of flash into the buffer.
121    fn read_page(
122        &self,
123        page_number: usize,
124        buf: &'static mut Self::Page,
125    ) -> Result<(), (ErrorCode, &'static mut Self::Page)>;
126
127    /// Write a page of flash from the buffer.
128    fn write_page(
129        &self,
130        page_number: usize,
131        buf: &'static mut Self::Page,
132    ) -> Result<(), (ErrorCode, &'static mut Self::Page)>;
133
134    /// Erase a page of flash by setting every byte to 0xFF.
135    fn erase_page(&self, page_number: usize) -> Result<(), ErrorCode>;
136}
137
138/// Implement `Client` to receive callbacks from `Flash`.
139pub trait Client<F: Flash> {
140    /// Flash read complete.
141    fn read_complete(&self, read_buffer: &'static mut F::Page, result: Result<(), Error>);
142
143    /// Flash write complete.
144    fn write_complete(&self, write_buffer: &'static mut F::Page, result: Result<(), Error>);
145
146    /// Flash erase complete.
147    fn erase_complete(&self, result: Result<(), Error>);
148}
kernel/hil/flash.rs

kernel/hil/
flash.rs
