wasefire_store/
storage.rs

1// Copyright 2019 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Flash storage abstraction.
16
17use alloc::borrow::Cow;
18
19use wasefire_error::{Code, Error};
20
21/// Represents a byte position in a storage.
22#[derive(Copy, Clone, Debug, PartialEq, Eq)]
23pub struct StorageIndex {
24    pub page: usize,
25    pub byte: usize,
26}
27
28/// Abstracts a flash storage.
29pub trait Storage {
30    /// The size of a word in bytes.
31    ///
32    /// A word is the smallest unit of writable flash.
33    fn word_size(&self) -> usize;
34
35    /// The size of a page in bytes.
36    ///
37    /// A page is the smallest unit of erasable flash.
38    fn page_size(&self) -> usize;
39
40    /// The number of pages in the storage.
41    fn num_pages(&self) -> usize;
42
43    /// Maximum number of times a word can be written between page erasures.
44    fn max_word_writes(&self) -> usize;
45
46    /// Maximum number of times a page can be erased.
47    fn max_page_erases(&self) -> usize;
48
49    /// Reads a byte slice from the storage.
50    ///
51    /// The `index` must designate `length` bytes in the storage.
52    ///
53    /// Note that we use `Cow` just because it derefs to `[u8]`. We don't really need the fact that
54    /// one can convert it to a `Vec`. In particular we don't do it in the store implementation.
55    fn read_slice(&self, index: StorageIndex, length: usize) -> Result<Cow<'_, [u8]>, Error>;
56
57    /// Writes a word slice to the storage.
58    ///
59    /// The following pre-conditions must hold:
60    /// - The `index` must designate `value.len()` bytes in the storage.
61    /// - Both `index` and `value.len()` must be word-aligned.
62    /// - The written words should not have been written [too many](Self::max_word_writes) times
63    ///   since the last page erasure.
64    fn write_slice(&mut self, index: StorageIndex, value: &[u8]) -> Result<(), Error>;
65
66    /// Erases a page of the storage.
67    ///
68    /// The `page` must be in the storage, i.e. less than [`Storage::num_pages`]. And the page
69    /// should not have been erased [too many](Self::max_page_erases) times.
70    fn erase_page(&mut self, page: usize) -> Result<(), Error>;
71}
72
73impl StorageIndex {
74    /// Whether a slice fits in a storage page.
75    fn is_valid(self, length: usize, storage: &impl Storage) -> bool {
76        let page_size = storage.page_size();
77        self.page < storage.num_pages() && length <= page_size && self.byte <= page_size - length
78    }
79
80    /// Returns the range of a valid slice.
81    ///
82    /// The range starts at `self` with `length` bytes.
83    pub fn range(
84        self, length: usize, storage: &impl Storage,
85    ) -> Result<core::ops::Range<usize>, Error> {
86        if self.is_valid(length, storage) {
87            let start = self.page * storage.page_size() + self.byte;
88            Ok(start .. start + length)
89        } else {
90            Err(Error::user(Code::OutOfBounds))
91        }
92    }
93}
wasefire_store/storage.rs

wasefire_store/
storage.rs
