diff --git a/chips/nrf52/src/nvmc.rs b/chips/nrf52/src/nvmc.rs index adbc2a2b5..4092cf346 100644 --- a/chips/nrf52/src/nvmc.rs +++ b/chips/nrf52/src/nvmc.rs @@ -3,15 +3,19 @@ //! Used in order read and write to internal flash. use core::cell::Cell; +use core::convert::TryFrom; use core::ops::{Index, IndexMut}; use kernel::common::cells::OptionalCell; use kernel::common::cells::TakeCell; use kernel::common::cells::VolatileCell; use kernel::common::deferred_call::DeferredCall; +use kernel::common::dynamic_deferred_call::{ + DeferredCallHandle, DynamicDeferredCall, DynamicDeferredCallClient, +}; use kernel::common::registers::{register_bitfields, ReadOnly, ReadWrite}; use kernel::common::StaticRef; use kernel::hil; -use kernel::ReturnCode; +use kernel::{AppId, AppSlice, Callback, Driver, Grant, ReturnCode, Shared}; use crate::deferred_call_tasks::DeferredCallTask; @@ -141,7 +145,13 @@ register_bitfields! [u32, static DEFERRED_CALL: DeferredCall = unsafe { DeferredCall::new(DeferredCallTask::Nvmc) }; +type WORD = u32; +const WORD_SIZE: usize = core::mem::size_of::(); const PAGE_SIZE: usize = 4096; +const MAX_WORD_WRITES: usize = 2; +const MAX_PAGE_ERASES: usize = 10000; +const WORD_MASK: usize = WORD_SIZE - 1; +const PAGE_MASK: usize = PAGE_SIZE - 1; /// This is a wrapper around a u8 array that is sized to a single page for the /// nrf. Users of this module must pass an object of this type to use the @@ -217,6 +227,10 @@ impl Nvmc { } } + pub fn configure_readonly(&self) { + self.registers.config.write(Configuration::WEN::Ren); + } + /// Configure the NVMC to allow writes to flash. pub fn configure_writeable(&self) { self.registers.config.write(Configuration::WEN::Wen); @@ -229,9 +243,7 @@ impl Nvmc { pub fn erase_uicr(&self) { self.registers.config.write(Configuration::WEN::Een); while !self.is_ready() {} - self.registers - .erasepage - .write(ErasePage::ERASEPAGE.val(0x10001000)); + self.registers.eraseuicr.write(EraseUicr::ERASEUICR::ERASE); while !self.is_ready() {} } @@ -319,7 +331,7 @@ impl Nvmc { // Put the NVMC in write mode. self.registers.config.write(Configuration::WEN::Wen); - for i in (0..data.len()).step_by(4) { + for i in (0..data.len()).step_by(WORD_SIZE) { let word: u32 = (data[i + 0] as u32) << 0 | (data[i + 1] as u32) << 8 | (data[i + 2] as u32) << 16 @@ -387,3 +399,237 @@ impl hil::flash::Flash for Nvmc { self.erase_page(page_number) } } + +/// Provides access to the writeable flash regions of the application. +/// +/// The purpose of this driver is to provide low-level access to the embedded flash of nRF52 boards +/// to allow applications to implement flash-aware (like wear-leveling) data-structures. The driver +/// only permits applications to operate on their writeable flash regions. The API is blocking since +/// the CPU is halted during write and erase operations. +/// +/// Supported boards: +/// - nRF52840 (tested) +/// - nRF52833 +/// - nRF52811 +/// - nRF52810 +/// +/// The maximum number of writes for the nRF52832 board is not per word but per block (512 bytes) +/// and as such doesn't exactly fit this API. However, it could be safely supported by returning +/// either 1 for the maximum number of word writes (i.e. the flash can only be written once before +/// being erased) or 8 for the word size (i.e. the write granularity is doubled). In both cases, +/// only 128 writes per block are permitted while the flash supports 181. +/// +/// # Syscalls +/// +/// - SUBSCRIBE(0, done): The callback for COMMAND(2) and COMMAND(3). +/// - COMMAND(0): Check the driver. +/// - COMMAND(1, 0): Get the word size (always 4). +/// - COMMAND(1, 1): Get the page size (always 4096). +/// - COMMAND(1, 2): Get the maximum number of word writes between page erasures (always 2). +/// - COMMAND(1, 3): Get the maximum number page erasures in the lifetime of the flash (always +/// 10000). +/// - COMMAND(2, ptr, len): Write the allow slice to the flash region starting at `ptr`. +/// - `ptr` must be word-aligned. +/// - The allow slice length must be word aligned. +/// - The region starting at `ptr` of the same length as the allow slice must be in a writeable +/// flash region. +/// - COMMAND(3, ptr, len): Erase a page. +/// - `ptr` must be page-aligned. +/// - The page starting at `ptr` must be in a writeable flash region. +/// - ALLOW(0): The allow slice for COMMAND(2). +pub struct SyscallDriver { + nvmc: &'static Nvmc, + apps: Grant, + waiting: OptionalCell, + deferred_caller: &'static DynamicDeferredCall, + deferred_handle: OptionalCell, +} + +pub const DRIVER_NUM: usize = 0x50003; + +#[derive(Default)] +pub struct App { + /// The callback for COMMAND(2) and COMMAND(3). + callback: Option, + /// The allow slice for COMMAND(2). + slice: Option>, +} + +fn is_write_needed(old: u32, new: u32) -> bool { + // No need to write if it would not modify the current value. + old & new != old +} + +impl SyscallDriver { + pub fn new( + nvmc: &'static Nvmc, + apps: Grant, + deferred_caller: &'static DynamicDeferredCall, + ) -> SyscallDriver { + nvmc.configure_readonly(); + SyscallDriver { + nvmc, + apps, + waiting: OptionalCell::empty(), + deferred_caller, + deferred_handle: OptionalCell::empty(), + } + } + + pub fn set_deferred_handle(&self, handle: DeferredCallHandle) { + self.deferred_handle.replace(handle); + } + + /// Writes a word-aligned slice at a word-aligned address. + /// + /// Words are written only if necessary, i.e. if writing the new value would change the current + /// value. This can be used to simplify recovery operations (e.g. if power is lost during a + /// write operation). The application doesn't need to check which prefix has already been + /// written and may repeat the complete write that was interrupted. + /// + /// # Safety + /// + /// The words in this range must have been written less than `MAX_WORD_WRITES` since their last + /// page erasure. + /// + /// # Errors + /// + /// Fails with `EINVAL` if any of the following conditions does not hold: + /// - `ptr` must be word-aligned. + /// - `slice.len()` must be word-aligned. + /// - The slice starting at `ptr` of length `slice.len()` must fit in the storage. + fn write_slice(&self, ptr: usize, slice: &[u8]) -> ReturnCode { + if ptr & WORD_MASK != 0 || slice.len() & WORD_MASK != 0 { + return ReturnCode::EINVAL; + } + self.nvmc.configure_writeable(); + for (i, chunk) in slice.chunks(WORD_SIZE).enumerate() { + // `unwrap` cannot fail because `slice.len()` is word-aligned (see above). + let val = WORD::from_ne_bytes(<[u8; WORD_SIZE]>::try_from(chunk).unwrap()); + let loc = unsafe { &*(ptr as *const VolatileCell).add(i) }; + if is_write_needed(loc.get(), val) { + loc.set(val); + } + } + while !self.nvmc.is_ready() {} + self.nvmc.configure_readonly(); + self.deferred_handle + .map(|handle| self.deferred_caller.set(*handle)); + ReturnCode::SUCCESS + } + + /// Erases a page at a page-aligned address. + /// + /// # Errors + /// + /// Fails with `EINVAL` if any of the following conditions does not hold: + /// - `ptr` must be page-aligned. + /// - The slice starting at `ptr` of length `PAGE_SIZE` must fit in the storage. + fn erase_page(&self, ptr: usize) -> ReturnCode { + if ptr & PAGE_MASK != 0 { + return ReturnCode::EINVAL; + } + self.nvmc.erase_page_helper(ptr / PAGE_SIZE); + self.nvmc.configure_readonly(); + self.deferred_handle + .map(|handle| self.deferred_caller.set(*handle)); + ReturnCode::SUCCESS + } +} + +impl DynamicDeferredCallClient for SyscallDriver { + fn call(&self, _handle: DeferredCallHandle) { + self.waiting.take().map(|appid| { + self.apps.enter(appid, |app, _| { + app.callback.map(|mut cb| { + cb.schedule(0, 0, 0); + }); + }) + }); + } +} + +impl Driver for SyscallDriver { + fn subscribe( + &self, + subscribe_num: usize, + callback: Option, + appid: AppId, + ) -> ReturnCode { + match subscribe_num { + 0 => self + .apps + .enter(appid, |app, _| { + app.callback = callback; + ReturnCode::SUCCESS + }) + .unwrap_or_else(|err| err.into()), + _ => ReturnCode::ENOSUPPORT, + } + } + + fn command(&self, cmd: usize, arg0: usize, arg1: usize, appid: AppId) -> ReturnCode { + match (cmd, arg0, arg1) { + (0, _, _) => ReturnCode::SUCCESS, + + (1, 0, _) => ReturnCode::SuccessWithValue { value: WORD_SIZE }, + (1, 1, _) => ReturnCode::SuccessWithValue { value: PAGE_SIZE }, + (1, 2, _) => ReturnCode::SuccessWithValue { + value: MAX_WORD_WRITES, + }, + (1, 3, _) => ReturnCode::SuccessWithValue { + value: MAX_PAGE_ERASES, + }, + (1, _, _) => ReturnCode::EINVAL, + + (2, ptr, len) => self + .apps + .enter(appid, |app, _| { + let slice = match app.slice.take() { + None => return ReturnCode::EINVAL, + Some(slice) => slice, + }; + if len != slice.len() { + return ReturnCode::EINVAL; + } + if self.waiting.is_some() { + return ReturnCode::EBUSY; + } + self.waiting.set(appid); + self.write_slice(ptr, slice.as_ref()) + }) + .unwrap_or_else(|err| err.into()), + + (3, ptr, len) => { + if len != PAGE_SIZE { + return ReturnCode::EINVAL; + } + if self.waiting.is_some() { + return ReturnCode::EBUSY; + } + self.waiting.set(appid); + self.erase_page(ptr) + } + + _ => ReturnCode::ENOSUPPORT, + } + } + + fn allow( + &self, + appid: AppId, + allow_num: usize, + slice: Option>, + ) -> ReturnCode { + match allow_num { + 0 => self + .apps + .enter(appid, |app, _| { + app.slice = slice; + ReturnCode::SUCCESS + }) + .unwrap_or_else(|err| err.into()), + _ => ReturnCode::ENOSUPPORT, + } + } +} diff --git a/kernel/src/lib.rs b/kernel/src/lib.rs index 49e1e5182..807170195 100644 --- a/kernel/src/lib.rs +++ b/kernel/src/lib.rs @@ -122,7 +122,7 @@ pub use crate::sched::cooperative::{CoopProcessNode, CooperativeSched}; pub use crate::sched::mlfq::{MLFQProcessNode, MLFQSched}; pub use crate::sched::priority::PrioritySched; pub use crate::sched::round_robin::{RoundRobinProcessNode, RoundRobinSched}; -pub use crate::sched::{Kernel, Scheduler}; +pub use crate::sched::{Kernel, Scheduler, StorageLocation}; // Export only select items from the process module. To remove the name conflict // this cannot be called `process`, so we use a shortened version. These diff --git a/kernel/src/memop.rs b/kernel/src/memop.rs index 348c746a5..5465c95f4 100644 --- a/kernel/src/memop.rs +++ b/kernel/src/memop.rs @@ -108,6 +108,25 @@ pub(crate) fn memop(process: &dyn ProcessType, op_type: usize, r1: usize) -> Ret ReturnCode::SUCCESS } + // Op Type 12: Number of storage locations. + 12 => ReturnCode::SuccessWithValue { value: process.number_storage_locations() }, + + // Op Type 13: The start address of the storage location indexed by r1. + 13 => { + match process.get_storage_location(r1) { + None => ReturnCode::FAIL, + Some(x) => ReturnCode::SuccessWithValue { value: x.address } + } + } + + // Op Type 14: The size of the storage location indexed by r1. + 14 => { + match process.get_storage_location(r1) { + None => ReturnCode::FAIL, + Some(x) => ReturnCode::SuccessWithValue { value: x.size } + } + } + _ => ReturnCode::ENOSUPPORT, } } diff --git a/kernel/src/process.rs b/kernel/src/process.rs index c52754be3..ae6a58341 100644 --- a/kernel/src/process.rs +++ b/kernel/src/process.rs @@ -359,6 +359,15 @@ pub trait ProcessType { /// writeable flash region. fn get_writeable_flash_region(&self, region_index: usize) -> (u32, u32); + /// How many storage locations are defined for this process. + fn number_storage_locations(&self) -> usize; + + /// Get the i-th storage location. + fn get_storage_location(&self, index: usize) -> Option<&crate::StorageLocation>; + + /// Whether a slice fits in a storage location. + fn fits_in_storage_location(&self, ptr: usize, len: usize) -> bool; + /// Debug function to update the kernel on where the stack starts for this /// process. Processes are not required to call this through the memop /// system call, but it aids in debugging the process. @@ -1048,6 +1057,35 @@ impl ProcessType for Process<'_, C> { self.header.get_writeable_flash_region(region_index) } + fn number_storage_locations(&self) -> usize { + self.kernel.storage_locations().len() + } + + fn get_storage_location(&self, index: usize) -> Option<&crate::StorageLocation> { + self.kernel.storage_locations().get(index) + } + + fn fits_in_storage_location(&self, ptr: usize, len: usize) -> bool { + self.kernel + .storage_locations() + .iter() + .any(|storage_location| { + let storage_ptr = storage_location.address; + let storage_len = storage_location.size; + // We want to check the 2 following inequalities: + // (1) `storage_ptr <= ptr` + // (2) `ptr + len <= storage_ptr + storage_len` + // However, the second one may overflow written as is. We introduce a third + // inequality to solve this issue: + // (3) `len <= storage_len` + // Using this third inequality, we can rewrite the second one as: + // (4) `ptr - storage_ptr <= storage_len - len` + // This fourth inequality is equivalent to the second one but doesn't overflow when + // the first and third inequalities hold. + storage_ptr <= ptr && len <= storage_len && ptr - storage_ptr <= storage_len - len + }) + } + fn update_stack_start_pointer(&self, stack_pointer: *const u8) { if stack_pointer >= self.mem_start() && stack_pointer < self.mem_end() { self.debug.map(|debug| { @@ -1751,6 +1789,33 @@ impl Process<'_, C> { return Err(ProcessLoadError::MpuInvalidFlashLength); } + // Allocate MPU region for the storage locations. The storage locations are currently + // readable by all processes due to lack of stable app id. + for storage_location in kernel.storage_locations() { + if chip + .mpu() + .allocate_region( + storage_location.address as *const u8, + storage_location.size, + storage_location.size, + mpu::Permissions::ReadOnly, + &mut mpu_config, + ) + .is_some() + { + continue; + } + if config::CONFIG.debug_load_processes { + debug!( + "[!] flash=[{:#010X}:{:#010X}] process={:?} - couldn't allocate flash region", + storage_location.address, + storage_location.address + storage_location.size, + process_name + ); + } + return Ok((None, remaining_memory)); + } + // Determine how much space we need in the application's // memory space just for kernel and grant state. We need to make // sure we allocate enough memory just for that. diff --git a/kernel/src/sched.rs b/kernel/src/sched.rs index 10626a2e1..8844bc6c3 100644 --- a/kernel/src/sched.rs +++ b/kernel/src/sched.rs @@ -118,6 +118,12 @@ pub enum SchedulingDecision { TrySleep, } +/// Represents a storage location in flash. +pub struct StorageLocation { + pub address: usize, + pub size: usize, +} + /// Main object for the kernel. Each board will need to create one. pub struct Kernel { /// How many "to-do" items exist at any given time. These include @@ -127,6 +133,9 @@ pub struct Kernel { /// This holds a pointer to the static array of Process pointers. processes: &'static [Option<&'static dyn process::ProcessType>], + /// List of storage locations. + storage_locations: &'static [StorageLocation], + /// A counter which keeps track of how many process identifiers have been /// created. This is used to create new unique identifiers for processes. process_identifier_max: Cell, @@ -170,9 +179,17 @@ pub enum StoppedExecutingReason { impl Kernel { pub fn new(processes: &'static [Option<&'static dyn process::ProcessType>]) -> Kernel { + Kernel::new_with_storage(processes, &[]) + } + + pub fn new_with_storage( + processes: &'static [Option<&'static dyn process::ProcessType>], + storage_locations: &'static [StorageLocation], + ) -> Kernel { Kernel { work: Cell::new(0), processes, + storage_locations: storage_locations, process_identifier_max: Cell::new(0), grant_counter: Cell::new(0), grants_finalized: Cell::new(false), @@ -900,4 +917,8 @@ impl Kernel { (return_reason, time_executed_us) } + + pub fn storage_locations(&self) -> &'static [StorageLocation] { + self.storage_locations + } }