blob: 842ae0a6e0fc30f484cdcd3cf2efaa9cf9c8e0cc [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! Tests the FPGA flash driver against a copy of the host code that implements
//! the FPGA's flash controllers.
//!
//! On the VCK190 FPGA board, the FPGA wrapper provides a block of registers
//! for each flash controller. The host is the board's ARM cores, which run
//! caliptra-sw's `ModelFpgaSubsystem`. A program on the host calls
//! `ModelFpgaSubsystem::step` in a loop (the step loop). Each call polls
//! those registers and transfers pages between them and host memory. This
//! test runs the driver against a copy of that host code:
//!
//! * [`FpgaHost`] contains the flash handling of `ModelFpgaSubsystem`, copied
//! from caliptra-sw `hw-model/src/model_fpga_subsystem.rs` at commit
//! b99535d. The copy does not follow the pin in
//! `third_party/caliptra/versions.bzl`, so compare it with upstream when
//! the pin changes. The copy differs from upstream in three places, each
//! marked with a comment that begins `Changed from upstream`.
//! * `caliptra_hw_model_fpga_regs` provides the register layout. It is built
//! from `hw-model/src/fpga_regs.rs` at the caliptra-sw commit that
//! `third_party/caliptra` pins, so it follows the pin.
//! * [`Wrapper`] is the storage for the registers. [`Board::new`] sets their
//! reset values, which are from caliptra-mcu-sw
//! `hw/fpga/src/caliptra_fpga_realtime_regs.rdl`.
//!
//! The driver accesses the registers through [`FpgaMmioBlock`]. [`Board::mcu`]
//! translates the address that the driver uses on the board to the same
//! offset in [`Wrapper`]. [`Board`] runs the host's step loop between the
//! driver's register accesses.
use core::cell::{Cell, RefCell, UnsafeCell};
use core::ops::Range;
use caliptra_hw_model_fpga_regs::{FlashControl, FlashCtrlRegs, FlashOpStatus};
use hal_flash::{BlockingFlash, Flash, FlashAddress};
use tock_registers::interfaces::{ReadWriteable, Readable, Writeable};
use util_error::FLASH_GENERIC_ADDR_OUT_OF_BOUNDS;
use util_types::PowerOf2Usize;
use veer_flash::{
BufWord, FpgaFlashCtrl, FpgaMmio, FpgaMmioBlock, Mmio, NoWait, PageController, Reg, SoftFlash,
ERASE_SIZE, FLASH_VEER_OP_FAILED, FLASH_VEER_TIMEOUT, FPGA_PRIMARY_FLASH_CTRL_ADDR,
FPGA_SECONDARY_FLASH_CTRL_ADDR, PAGE_SIZE,
};
/// Address of the FPGA wrapper on the AXI bus that the MCU and the host share.
/// The host's mapping of the wrapper starts at this address (caliptra-sw
/// `hw/fpga/io_module/mcu_io_module.c`).
const WRAPPER_ADDR: usize = 0xA401_0000;
/// Length of the host's mapping of the wrapper.
const WRAPPER_SIZE: usize = 0x1_0000;
/// Storage for the registers of the FPGA wrapper.
struct Wrapper {
/// The host's mapping of the registers, as in `ModelFpgaSubsystem`.
ptr: *mut u32,
_registers: Box<[UnsafeCell<u32>]>,
}
impl Wrapper {
fn new() -> Self {
let registers: Box<[UnsafeCell<u32>]> =
(0..WRAPPER_SIZE / 4).map(|_| UnsafeCell::new(0)).collect();
Self {
ptr: UnsafeCell::raw_get(registers.as_ptr()),
_registers: registers,
}
}
}
// Copied from caliptra-sw: the next two constants, and `flash_ctrl_regs`,
// `handle_flash` and `handle_flash_ctrl` in `FpgaHost`.
// Default flash size: 16MB each, initialized to 0xFF
const DEFAULT_FLASH_SIZE: usize = 16 * 1024 * 1024;
// page size of simulated flash
const FLASH_PAGE_SIZE: usize = 256;
/// The flash handling of caliptra-sw's `ModelFpgaSubsystem`.
struct FpgaHost {
wrapper: Wrapper,
// Flash storage buffers for the flash controllers
primary_flash: Vec<u8>,
secondary_flash: Vec<u8>,
}
impl FpgaHost {
/// Creates the flash storage in the same way as
/// `ModelFpgaSubsystem::new_unbooted` does when it is given no initial
/// contents.
fn new() -> Self {
Self {
wrapper: Wrapper::new(),
primary_flash: vec![0xFF; DEFAULT_FLASH_SIZE],
secondary_flash: vec![0xFF; DEFAULT_FLASH_SIZE],
}
}
/// Get a reference to the flash controller registers at the specified offset
fn flash_ctrl_regs(&self, is_primary: bool) -> &FlashCtrlRegs {
let offset = if is_primary { 0x2000 } else { 0x3000 };
// SAFETY: These are at fixed, known addresses relative to the wrapper.
unsafe {
let wrapper_base = self.wrapper.ptr as *const u8;
let flash_ctrl_ptr = wrapper_base.add(offset) as *const FlashCtrlRegs;
&*flash_ctrl_ptr
}
}
/// Implement a pair of simulated flash controllers, backed by data
/// stored in the host memory.
fn handle_flash(&mut self) {
self.handle_flash_ctrl(true);
self.handle_flash_ctrl(false);
}
/// Handle operations for a single flash controller
///
/// Changed from upstream: upstream returns early while the Caliptra
/// subsystem is in reset. This test has no reset state, so the copy omits
/// that check.
fn handle_flash_ctrl(&mut self, is_primary: bool) {
let (start, page_num, op) = {
let regs = self.flash_ctrl_regs(is_primary);
(
regs.fl_control.read(FlashControl::START),
regs.page_num.get() as usize,
regs.fl_control.read(FlashControl::OP),
)
};
// Check if START bit is set
if start == 0 {
return;
}
let flash = if is_primary {
&mut self.primary_flash
} else {
&mut self.secondary_flash
};
let flash_len = flash.len();
let flash_offset = page_num * FLASH_PAGE_SIZE;
// Ensure flash buffer is large enough
let required_size = flash_offset + FLASH_PAGE_SIZE;
if flash_len < required_size {
flash.resize(required_size, 0xFF);
}
let mut error = 0u32;
if flash_offset + FLASH_PAGE_SIZE > flash.len() {
error = 1;
println!(
"[flash-ctrl] Flash operation FAILED: Flash offset 0x{:x} + size {} exceeds flash length {}",
flash_offset,
FLASH_PAGE_SIZE,
flash.len()
);
} else {
match op {
1 => {
// Read page: copy from flash buffer to memory at page_addr
let page_data = flash[flash_offset..flash_offset + FLASH_PAGE_SIZE].to_vec();
let word_count = FLASH_PAGE_SIZE / 4;
// re-borrow to avoid borrow checker
let flash_ctrl = self.flash_ctrl_regs(is_primary);
for i in 0..word_count {
let byte_offset = i * 4;
let value = u32::from_le_bytes(
page_data[byte_offset..byte_offset + 4].try_into().unwrap(),
);
flash_ctrl.buffer[i].set(value);
}
}
2 => {
// Write page: copy from memory at page_addr to flash buffer
let word_count = FLASH_PAGE_SIZE / 4;
let flash_ctrl = self.flash_ctrl_regs(is_primary);
// Changed from upstream: the range has no `.into_iter()`,
// for clippy.
let buffer: Vec<u8> = (0..word_count)
.flat_map(|i| flash_ctrl.buffer[i].get().to_le_bytes())
.collect();
// re-borrow to avoid borrow checker conflicts
let flash = if is_primary {
&mut self.primary_flash
} else {
&mut self.secondary_flash
};
flash[flash_offset..flash_offset + FLASH_PAGE_SIZE].copy_from_slice(&buffer);
}
3 => {
// Erase page: fill with 0xFF
flash[flash_offset..flash_offset + FLASH_PAGE_SIZE].fill(0xFF);
}
_ => {
// Changed from upstream: `op` is an inline format
// argument in the `println!`, for clippy.
error = 1; // Treat invalid operation as read error
println!("[flash-ctrl] FAILED: Invalid operation code {op}");
}
}
}
// Clear START bit and set DONE
let regs = self.flash_ctrl_regs(is_primary);
regs.fl_control.modify(FlashControl::START::CLEAR);
regs.op_status
.modify(FlashOpStatus::DONE::SET + FlashOpStatus::ERR.val(error));
regs.fl_interrupt_state.set(2); // event interrupt
}
/// `ModelFpgaSubsystem::step`, reduced to its call to `handle_flash`.
fn step(&mut self) {
self.handle_flash();
}
}
/// Models the parts of a VCK190 that the flash driver uses: the wrapper
/// registers and the host. The host runs one pass of its step loop for every
/// `period` register accesses by the MCU.
struct Board {
host: RefCell<FpgaHost>,
/// Number of register accesses by the MCU for each host step, or `None`
/// while no host is running.
period: Cell<Option<u32>>,
accesses: Cell<u32>,
/// When set, `McuBus` clears the operation field of each value that the
/// MCU writes to FL_CONTROL. The host does not know operation 0, so it
/// reports an error.
drop_op: Cell<bool>,
}
impl Board {
fn new(period: Option<u32>) -> Self {
let host = FpgaHost::new();
// Reset values from caliptra_fpga_realtime_regs.rdl.
for is_primary in [true, false] {
let regs = host.flash_ctrl_regs(is_primary);
regs.page_size.set(256);
regs.ctrl_regwen.set(1);
regs.flash_size.set(0x0100_0000);
for word in &regs.buffer {
word.set(0xffff_ffff);
}
}
Self {
host: RefCell::new(host),
period: Cell::new(period),
accesses: Cell::new(0),
drop_op: Cell::new(false),
}
}
/// Returns the MCU's access to the registers of the controller at `addr`
/// on the AXI bus.
fn mcu(&self, addr: usize) -> McuBus<'_> {
let offset = addr.checked_sub(WRAPPER_ADDR).unwrap();
assert!(offset + size_of::<FlashCtrlRegs>() <= WRAPPER_SIZE);
let wrapper = self.host.borrow().wrapper.ptr.cast::<u8>();
let base = wrapper.wrapping_add(offset).expose_provenance();
McuBus {
// SAFETY: `base` is the address of a controller's registers in the
// wrapper's storage, which is allocated for as long as `self` is.
// Nothing else accesses them as the MCU. The host and the tests
// access them on this thread.
regs: unsafe { FpgaMmioBlock::new(base) },
board: self,
}
}
/// Returns the flash of the controller at `addr`, built in the same way as
/// the on-device test in `target/veer/tests/flash` builds it.
fn flash(&self, addr: usize) -> impl Flash<Error = util_error::ErrorCode> + '_ {
BlockingFlash {
driver: SoftFlash::new(FpgaFlashCtrl::new(self.mcu(addr))),
blocking: NoWait,
}
}
/// Called before each register access by the MCU. Runs one host step on
/// every `period`-th call.
fn tick(&self) {
let Some(period) = self.period.get() else {
return;
};
let accesses = self.accesses.get() + 1;
if accesses < period {
self.accesses.set(accesses);
} else {
self.accesses.set(0);
self.host.borrow_mut().step();
}
}
}
/// Register access from the MCU to one controller.
struct McuBus<'a> {
regs: FpgaMmioBlock,
board: &'a Board,
}
impl Mmio for McuBus<'_> {
fn read(&self, reg: Reg) -> u32 {
self.board.tick();
self.regs.read(reg)
}
fn write(&mut self, reg: Reg, mut value: u32) {
self.board.tick();
if self.board.drop_op.get() && reg == Reg::FlControl {
value &= !(FlashControl::OP.mask << FlashControl::OP.shift);
}
self.regs.write(reg, value);
}
}
impl FpgaMmio for McuBus<'_> {
fn read_buf(&self, word: BufWord) -> u32 {
self.board.tick();
self.regs.read_buf(word)
}
fn write_buf(&mut self, word: BufWord, value: u32) {
self.board.tick();
self.regs.write_buf(word, value);
}
}
fn addr(offset: usize) -> FlashAddress {
FlashAddress::new(offset as u32)
}
fn block() -> PowerOf2Usize {
PowerOf2Usize::new(ERASE_SIZE).unwrap()
}
/// Returns one byte for each offset in `offsets`. The bytes differ from page
/// to page.
fn pattern(offsets: Range<usize>) -> Vec<u8> {
offsets.map(|i| (i % 251) as u8).collect()
}
#[test]
fn round_trip_with_fast_and_slow_hosts() {
// With a period of 1, the host runs before every register access by the
// MCU. With larger periods, the MCU polls several times before the host
// responds.
for period in [1, 2, 3, 5, 8, 13] {
let board = Board::new(Some(period));
let mut flash = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
let (size, page_size, erase_sizes) = flash.geometry().unwrap();
{
let host = board.host.borrow();
assert_eq!(size.get(), host.primary_flash.len());
assert_eq!(
size.get() as u32,
host.flash_ctrl_regs(true).flash_size.get()
);
}
assert_eq!(page_size, block());
assert_eq!(erase_sizes, ERASE_SIZE as u32);
// The flash is initially erased, so fill three blocks with zeros before
// erasing the middle one.
board.host.borrow_mut().primary_flash[..3 * ERASE_SIZE].fill(0);
flash.erase(addr(ERASE_SIZE), block()).unwrap();
{
let stored = &board.host.borrow().primary_flash;
assert_eq!(stored[..ERASE_SIZE], [0; ERASE_SIZE]);
assert_eq!(stored[ERASE_SIZE..2 * ERASE_SIZE], [0xff; ERASE_SIZE]);
assert_eq!(stored[2 * ERASE_SIZE..3 * ERASE_SIZE], [0; ERASE_SIZE]);
}
// The data starts and ends in the middle of a word, and spans four
// pages.
let start = ERASE_SIZE + 0x1b3;
let data = pattern(0..700);
flash.program(addr(start), &data).unwrap();
// Programming can only clear bits.
flash.program(addr(start), &[0x0f; 5]).unwrap();
let mut expected = data;
expected[..5].iter_mut().for_each(|byte| *byte &= 0x0f);
{
let stored = &board.host.borrow().primary_flash;
assert_eq!(stored[ERASE_SIZE..start], [0xff; 0x1b3]);
assert_eq!(stored[start..start + 700], expected);
assert_eq!(stored[start + 700..start + 800], [0xff; 100]);
}
let mut buf = [0; 700];
flash.read(addr(start), &mut buf).unwrap();
assert_eq!(buf[..], expected);
}
}
#[test]
fn each_controller_has_its_own_flash() {
let board = Board::new(Some(3));
let mut primary = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
let mut secondary = board.flash(FPGA_SECONDARY_FLASH_CTRL_ADDR);
primary.program(addr(0x10), b"primary").unwrap();
secondary.program(addr(0x10), b"secondary").unwrap();
{
let host = board.host.borrow();
assert_eq!(host.primary_flash[0x10..0x19], *b"primary\xff\xff");
assert_eq!(host.secondary_flash[0x10..0x19], *b"secondary");
}
let mut buf = [0; 9];
primary.read(addr(0x10), &mut buf).unwrap();
assert_eq!(buf, *b"primary\xff\xff");
secondary.read(addr(0x10), &mut buf).unwrap();
assert_eq!(buf, *b"secondary");
}
#[test]
fn accesses_the_last_page_and_rejects_out_of_bounds() {
let board = Board::new(Some(2));
let mut flash = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
let size = DEFAULT_FLASH_SIZE;
let data = pattern(0..PAGE_SIZE);
flash.program(addr(size - PAGE_SIZE), &data).unwrap();
assert_eq!(board.host.borrow().primary_flash[size - PAGE_SIZE..], data);
let mut buf = [0; PAGE_SIZE];
flash.read(addr(size - PAGE_SIZE), &mut buf).unwrap();
assert_eq!(buf[..], data);
flash.erase(addr(size - ERASE_SIZE), block()).unwrap();
assert_eq!(
board.host.borrow().primary_flash[size - ERASE_SIZE..],
[0xff; ERASE_SIZE]
);
// The host extends its storage to fit any page number, so the driver must
// reject accesses past the end of the flash.
let out_of_bounds = Err(FLASH_GENERIC_ADDR_OUT_OF_BOUNDS);
assert_eq!(flash.read(addr(size - 1), &mut [0; 2]), out_of_bounds);
assert_eq!(flash.program(addr(size), &[0]), out_of_bounds);
assert_eq!(flash.erase(addr(size), block()), out_of_bounds);
assert_eq!(board.host.borrow().primary_flash.len(), size);
}
#[test]
fn page_buffer_rejects_ranges_outside_the_page() {
let board = Board::new(Some(1));
let mut controller = FpgaFlashCtrl::new(board.mcu(FPGA_PRIMARY_FLASH_CTRL_ADDR));
let out_of_bounds = Err(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);
}
#[test]
fn ignores_stale_status() {
let board = Board::new(Some(5));
board.host.borrow_mut().primary_flash[..ERASE_SIZE].copy_from_slice(&pattern(0..ERASE_SIZE));
let mut flash = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
// Set DONE, as it would be if the host completed an operation just after
// the driver timed out.
let host = board.host.borrow();
host.flash_ctrl_regs(true)
.op_status
.write(FlashOpStatus::DONE::SET);
drop(host);
let mut buf = [0; 8];
flash.read(addr(0x300), &mut buf).unwrap();
assert_eq!(buf[..], pattern(0x300..0x308));
}
#[test]
fn reports_host_errors() {
let board = Board::new(Some(3));
board.host.borrow_mut().primary_flash[..ERASE_SIZE].copy_from_slice(&pattern(0..ERASE_SIZE));
let mut flash = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
// The host reports an error only for an unknown operation.
board.drop_op.set(true);
let failed = Err(FLASH_VEER_OP_FAILED);
assert_eq!(flash.read(addr(0), &mut [0; 4]), failed);
assert_eq!(flash.program(addr(0), &[0; 4]), failed);
assert_eq!(flash.erase(addr(0), block()), failed);
// The next operation succeeds after a failure.
board.drop_op.set(false);
let mut buf = [0; 4];
assert_eq!(flash.read(addr(0), &mut buf), Ok(()));
assert_eq!(buf[..], pattern(0..4));
}
#[test]
fn times_out_without_a_host() {
let board = Board::new(None);
board.host.borrow_mut().primary_flash[..ERASE_SIZE].copy_from_slice(&pattern(0..ERASE_SIZE));
let mut flash = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
assert_eq!(flash.erase(addr(0), block()), Err(FLASH_VEER_TIMEOUT));
// Start the host. It must not run the erase that timed out.
board.period.set(Some(1));
let mut buf = [0; ERASE_SIZE];
assert_eq!(flash.read(addr(0), &mut buf), Ok(()));
assert_eq!(buf[..], pattern(0..ERASE_SIZE));
}
#[test]
fn disables_interrupts() {
let board = Board::new(Some(1));
// Enable both interrupts, as earlier code could have left them.
let host = board.host.borrow();
host.flash_ctrl_regs(true).fl_interrupt_enable.set(3);
drop(host);
let _flash = board.flash(FPGA_PRIMARY_FLASH_CTRL_ADDR);
let host = board.host.borrow();
assert_eq!(host.flash_ctrl_regs(true).fl_interrupt_enable.get(), 0);
}