blob: 8566ab26a477891e21b1508a7c8ef90cba02df80 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! The flash controllers of the Caliptra MCU emulator.
use core::num::NonZero;
use caliptra_ss_registers::primary_flash_ctrl::bits::{CtrlRegwen, FlInterruptState};
use caliptra_ss_registers::primary_flash_ctrl::PRIMARY_FLASH_CTRL_ADDR;
use caliptra_ss_registers::secondary_flash_ctrl::SECONDARY_FLASH_CTRL_ADDR;
use util_error::{self as error, ErrorCode};
use crate::{
page_range, Mmio, MmioBlock, Op, PageController, Reg, FLASH_VEER_OP_FAILED, FLASH_VEER_TIMEOUT,
PAGE_SIZE, POLL_LIMIT,
};
/// One of the emulator's flash controllers.
pub struct EmulatorFlashCtrl<M: Mmio> {
mmio: M,
/// The page buffer. The controller reads and writes it without the
/// compiler's knowledge, so the driver only accesses it with volatile
/// operations.
page: [u8; PAGE_SIZE],
}
impl EmulatorFlashCtrl<MmioBlock> {
/// # Safety
///
/// The primary flash controller's registers must be mapped for the caller,
/// and no other code on the MCU may access them.
pub unsafe fn primary() -> Self {
// SAFETY: the address is the controller's and is a multiple of 4. The
// caller guarantees the rest of `MmioBlock::new`'s contract.
Self::new(unsafe { MmioBlock::new(PRIMARY_FLASH_CTRL_ADDR as usize) })
}
/// # Safety
///
/// The secondary flash controller's registers must be mapped for the
/// caller, and no other code on the MCU may access them.
pub unsafe fn secondary() -> Self {
// SAFETY: the address is the controller's and is a multiple of 4. The
// caller guarantees the rest of `MmioBlock::new`'s contract.
Self::new(unsafe { MmioBlock::new(SECONDARY_FLASH_CTRL_ADDR as usize) })
}
}
impl<M: Mmio> EmulatorFlashCtrl<M> {
/// The controller copies pages to and from the page buffer in the returned
/// value, and fails an operation if the buffer is not in MCU RAM. The
/// driver gives the controller the buffer's address at the start of each
/// operation, so the value can be moved between operations.
pub fn new(mut mmio: M) -> Self {
// The driver polls for completion, so disable the interrupts.
mmio.write(Reg::FlInterruptEnable, 0);
// Clear the status of any earlier operation. FL_INTERRUPT_STATE is
// write-one-to-clear.
mmio.write(Reg::OpStatus, 0);
mmio.write(
Reg::FlInterruptState,
(FlInterruptState::Error::SET + FlInterruptState::Event::SET).into(),
);
Self {
mmio,
page: [0; PAGE_SIZE],
}
}
fn run(&mut self, op: Op, page: u32) -> Result<(), ErrorCode> {
// The controller clears CTRL_REGWEN when an operation starts, and
// ignores writes to FL_CONTROL until the driver acknowledges that
// operation by clearing FL_INTERRUPT_STATE.
if !CtrlRegwen::En.is_set(self.mmio.read(Reg::CtrlRegwen)) {
return Err(error::FLASH_GENERIC_BUSY);
}
self.mmio.write(Reg::FlControl, 0);
self.mmio.write(Reg::PageNum, page);
self.mmio.write(
Reg::PageAddr,
(&raw mut self.page).expose_provenance() as u32,
);
self.mmio.write(Reg::PageSize, PAGE_SIZE as u32);
self.mmio.write(Reg::FlControl, op.start());
// On a read error the controller sets OP_STATUS.ERR to 0, which is
// also its value on success, so the driver uses FL_INTERRUPT_STATE to
// detect completion and failure.
for _ in 0..POLL_LIMIT {
let state = self.mmio.read(Reg::FlInterruptState);
let failed = FlInterruptState::Error.is_set(state);
if failed || FlInterruptState::Event.is_set(state) {
// The controller does not clear OP_STATUS itself.
self.mmio.write(Reg::OpStatus, 0);
// Acknowledge the operation. The controller then sets
// CTRL_REGWEN again.
self.mmio.write(Reg::FlInterruptState, state);
return if failed {
Err(FLASH_VEER_OP_FAILED)
} else {
Ok(())
};
}
}
Err(FLASH_VEER_TIMEOUT)
}
}
impl<M: Mmio> PageController for EmulatorFlashCtrl<M> {
// `DummyFlashCtrl::MAX_PAGES * PAGE_SIZE` in caliptra-mcu-sw.
const SIZE: NonZero<usize> = NonZero::new(64 * 1024 * 1024).unwrap();
// `DummyFlashCtrl::ERASE_SECTOR_SIZE` in caliptra-mcu-sw.
const ERASE_OP_SIZE: usize = 4096;
fn load(&mut self, page: u32) -> Result<(), ErrorCode> {
self.run(Op::Read, page)
}
fn store(&mut self, page: u32) -> Result<(), ErrorCode> {
self.run(Op::Write, page)
}
fn erase(&mut self, page: u32) -> Result<(), ErrorCode> {
self.run(Op::Erase, page)
}
fn read_buffer(&self, offset: usize, out: &mut [u8]) -> Result<(), ErrorCode> {
let range = page_range(offset, out.len())?;
let page = (&raw const self.page).cast::<u8>();
for (byte, index) in out.iter_mut().zip(range) {
// SAFETY: `page_range` checked that `index` is inside `self.page`.
*byte = unsafe { page.add(index).read_volatile() };
}
Ok(())
}
fn program_buffer(&mut self, offset: usize, data: &[u8]) -> Result<(), ErrorCode> {
let range = page_range(offset, data.len())?;
let page = (&raw mut self.page).cast::<u8>();
for (&byte, index) in data.iter().zip(range) {
// SAFETY: `page_range` checked that `index` is inside `self.page`.
unsafe {
let cell = page.add(index);
cell.write_volatile(cell.read_volatile() & byte);
}
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Registers that read as zero and ignore writes.
struct NoMmio;
impl Mmio for NoMmio {
fn read(&self, _reg: Reg) -> u32 {
0
}
fn write(&mut self, _reg: Reg, _value: u32) {}
}
#[test]
fn page_buffer_round_trip() {
let mut controller = EmulatorFlashCtrl::new(NoMmio);
controller.page = [0xff; PAGE_SIZE];
let data = [0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc];
controller.program_buffer(250, &data).unwrap();
controller.program_buffer(250, &[0x0f]).unwrap();
let mut buf = [0; 8];
controller.read_buffer(248, &mut buf).unwrap();
assert_eq!(buf, [0xff, 0xff, 0x02, 0x34, 0x56, 0x78, 0x9a, 0xbc]);
}
#[test]
fn page_buffer_rejects_ranges_outside_the_page() {
let mut controller = EmulatorFlashCtrl::new(NoMmio);
let out_of_bounds = Err(error::FLASH_GENERIC_ADDR_OUT_OF_BOUNDS);
assert_eq!(controller.read_buffer(PAGE_SIZE - 1, &mut [0; 1]), Ok(()));
assert_eq!(
controller.read_buffer(PAGE_SIZE - 1, &mut [0; 2]),
out_of_bounds
);
assert_eq!(
controller.read_buffer(usize::MAX, &mut [0; 2]),
out_of_bounds
);
assert_eq!(controller.program_buffer(PAGE_SIZE, &[0]), out_of_bounds);
}
}