diff --git a/boards/nordic/nrf52840_dongle/src/main.rs b/boards/nordic/nrf52840_dongle/src/main.rs index fc53f59c8..d72d20482 100644 --- a/boards/nordic/nrf52840_dongle/src/main.rs +++ b/boards/nordic/nrf52840_dongle/src/main.rs @@ -55,6 +55,11 @@ const NUM_PROCS: usize = 8; static mut PROCESSES: [Option<&'static dyn kernel::procs::ProcessType>; NUM_PROCS] = [None; NUM_PROCS]; +static mut STORAGE_LOCATIONS: [kernel::StorageLocation; 1] = [kernel::StorageLocation { + address: 0xC0000, + size: 0x40000, +}]; + // Static reference to chip for panic dumps static mut CHIP: Option<&'static nrf52840::chip::Chip> = None; @@ -90,6 +95,7 @@ pub struct Platform { 'static, capsules::virtual_alarm::VirtualMuxAlarm<'static, nrf52840::rtc::Rtc<'static>>, >, + nvmc: &'static nrf52840::nvmc::SyscallDriver, } impl kernel::Platform for Platform { @@ -108,10 +114,30 @@ impl kernel::Platform for Platform { capsules::ieee802154::DRIVER_NUM => f(Some(self.ieee802154_radio)), capsules::temperature::DRIVER_NUM => f(Some(self.temp)), capsules::analog_comparator::DRIVER_NUM => f(Some(self.analog_comparator)), + nrf52840::nvmc::DRIVER_NUM => f(Some(self.nvmc)), kernel::ipc::DRIVER_NUM => f(Some(&self.ipc)), _ => f(None), } } + + fn filter_syscall( + &self, + process: &dyn kernel::procs::ProcessType, + syscall: &kernel::syscall::Syscall, + ) -> Result<(), kernel::ReturnCode> { + use kernel::syscall::Syscall; + match *syscall { + Syscall::COMMAND { + driver_number: nrf52840::nvmc::DRIVER_NUM, + subdriver_number: cmd, + arg0: ptr, + arg1: len, + } if (cmd == 2 || cmd == 3) && !process.fits_in_storage_location(ptr, len) => { + Err(kernel::ReturnCode::EINVAL) + } + _ => Ok(()), + } + } } /// Entry point in the vector table called on hard reset. @@ -120,7 +146,10 @@ pub unsafe fn reset_handler() { // Loads relocations and clears BSS nrf52840::init(); - let board_kernel = static_init!(kernel::Kernel, kernel::Kernel::new(&PROCESSES)); + let board_kernel = static_init!( + kernel::Kernel, + kernel::Kernel::new_with_storage(&PROCESSES, &STORAGE_LOCATIONS) + ); // GPIOs let gpio = components::gpio::GpioComponent::new( @@ -286,6 +315,14 @@ pub unsafe fn reset_handler() { nrf52840::acomp::Comparator )); + let nvmc = static_init!( + nrf52840::nvmc::SyscallDriver, + nrf52840::nvmc::SyscallDriver::new( + &nrf52840::nvmc::NVMC, + board_kernel.create_grant(&memory_allocation_capability), + ) + ); + nrf52_components::NrfClockComponent::new().finalize(()); let platform = Platform { @@ -300,6 +337,7 @@ pub unsafe fn reset_handler() { temp, alarm, analog_comparator, + nvmc, ipc: kernel::ipc::IPC::new(board_kernel, &memory_allocation_capability), }; diff --git a/boards/nordic/nrf52840dk/src/main.rs b/boards/nordic/nrf52840dk/src/main.rs index 169f3d393..2ebb384d8 100644 --- a/boards/nordic/nrf52840dk/src/main.rs +++ b/boards/nordic/nrf52840dk/src/main.rs @@ -123,6 +123,11 @@ const NUM_PROCS: usize = 8; static mut PROCESSES: [Option<&'static dyn kernel::procs::ProcessType>; NUM_PROCS] = [None; NUM_PROCS]; +static mut STORAGE_LOCATIONS: [kernel::StorageLocation; 1] = [kernel::StorageLocation { + address: 0xC0000, + size: 0x40000, +}]; + static mut CHIP: Option<&'static nrf52840::chip::Chip> = None; /// Dummy buffer that causes the linker to reserve enough space for the stack. @@ -158,6 +163,7 @@ pub struct Platform { capsules::virtual_alarm::VirtualMuxAlarm<'static, nrf52840::rtc::Rtc<'static>>, >, nonvolatile_storage: &'static capsules::nonvolatile_storage_driver::NonvolatileStorage<'static>, + nvmc: &'static nrf52840::nvmc::SyscallDriver, } impl kernel::Platform for Platform { @@ -177,10 +183,30 @@ impl kernel::Platform for Platform { capsules::temperature::DRIVER_NUM => f(Some(self.temp)), capsules::analog_comparator::DRIVER_NUM => f(Some(self.analog_comparator)), capsules::nonvolatile_storage_driver::DRIVER_NUM => f(Some(self.nonvolatile_storage)), + nrf52840::nvmc::DRIVER_NUM => f(Some(self.nvmc)), kernel::ipc::DRIVER_NUM => f(Some(&self.ipc)), _ => f(None), } } + + fn filter_syscall( + &self, + process: &dyn kernel::procs::ProcessType, + syscall: &kernel::syscall::Syscall, + ) -> Result<(), kernel::ReturnCode> { + use kernel::syscall::Syscall; + match *syscall { + Syscall::COMMAND { + driver_number: nrf52840::nvmc::DRIVER_NUM, + subdriver_number: cmd, + arg0: ptr, + arg1: len, + } if (cmd == 2 || cmd == 3) && !process.fits_in_storage_location(ptr, len) => { + Err(kernel::ReturnCode::EINVAL) + } + _ => Ok(()), + } + } } /// Entry point in the vector table called on hard reset. @@ -204,7 +230,10 @@ pub unsafe fn reset_handler() { UartChannel::Pins(UartPins::new(UART_RTS, UART_TXD, UART_CTS, UART_RXD)) }; - let board_kernel = static_init!(kernel::Kernel, kernel::Kernel::new(&PROCESSES)); + let board_kernel = static_init!( + kernel::Kernel, + kernel::Kernel::new_with_storage(&PROCESSES, &STORAGE_LOCATIONS) + ); let gpio = components::gpio::GpioComponent::new( board_kernel, @@ -411,6 +440,14 @@ pub unsafe fn reset_handler() { nrf52840::acomp::Comparator )); + let nvmc = static_init!( + nrf52840::nvmc::SyscallDriver, + nrf52840::nvmc::SyscallDriver::new( + &nrf52840::nvmc::NVMC, + board_kernel.create_grant(&memory_allocation_capability), + ) + ); + nrf52_components::NrfClockComponent::new().finalize(()); let platform = Platform { @@ -426,6 +463,7 @@ pub unsafe fn reset_handler() { alarm, analog_comparator, nonvolatile_storage, + nvmc, ipc: kernel::ipc::IPC::new(board_kernel, &memory_allocation_capability), }; diff --git a/chips/nrf52/src/nvmc.rs b/chips/nrf52/src/nvmc.rs index b70162cae..9dcb82b07 100644 --- a/chips/nrf52/src/nvmc.rs +++ b/chips/nrf52/src/nvmc.rs @@ -3,6 +3,7 @@ //! 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; @@ -11,7 +12,7 @@ use kernel::common::deferred_call::DeferredCall; 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 +142,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 @@ -219,6 +226,11 @@ impl Nvmc { } } + pub fn configure_readonly(&self) { + let regs = &*self.registers; + regs.config.write(Configuration::WEN::Ren); + } + /// Configure the NVMC to allow writes to flash. pub fn configure_writeable(&self) { let regs = &*self.registers; @@ -234,7 +246,7 @@ impl Nvmc { let regs = &*self.registers; regs.config.write(Configuration::WEN::Een); while !self.is_ready() {} - regs.erasepage.write(ErasePage::ERASEPAGE.val(0x10001000)); + regs.eraseuicr.write(EraseUicr::ERASEUICR::ERASE); while !self.is_ready() {} } @@ -326,7 +338,7 @@ impl Nvmc { // Put the NVMC in write mode. regs.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 @@ -394,3 +406,180 @@ 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 +/// +/// - 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, +} + +pub const DRIVER_NUM: usize = 0x50003; + +#[derive(Default)] +pub struct App { + /// The allow slice for COMMAND(2). + slice: Option>, +} + +impl SyscallDriver { + pub fn new(nvmc: &'static Nvmc, apps: Grant) -> SyscallDriver { + SyscallDriver { nvmc, apps } + } +} + +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 { + /// 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(); + 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(); + ReturnCode::SUCCESS + } +} + +impl Driver for SyscallDriver { + fn subscribe(&self, _: usize, _: Option, _: AppId) -> ReturnCode { + 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; + } + self.write_slice(ptr, slice.as_ref()) + }) + .unwrap_or_else(|err| err.into()), + + (3, ptr, len) => { + if len != PAGE_SIZE { + return ReturnCode::EINVAL; + } + 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 dbe503515..428d90c29 100644 --- a/kernel/src/lib.rs +++ b/kernel/src/lib.rs @@ -123,7 +123,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 4dfde3b4f..8380af673 100644 --- a/kernel/src/process.rs +++ b/kernel/src/process.rs @@ -360,6 +360,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. @@ -1015,6 +1024,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| { @@ -1664,6 +1702,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 88eea4042..ed3ae8260 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), @@ -899,4 +916,8 @@ impl Kernel { (return_reason, time_executed_us) } + + pub fn storage_locations(&self) -> &'static [StorageLocation] { + self.storage_locations + } }