blob: a3b5a426a8d6d615b2918f681ca662386301a645 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! Flash request handling, independent of the kernel and of IPC.
//!
//! [`Server::handle_frame`] takes one request frame and leaves one response
//! frame in the same buffer. The kernel loop that moves those frames over a
//! channel is `flash_server_runtime`.
use hal_flash::{Flash, FlashAddress};
use openprot_flash_api::*;
use util_error::{self as error, ErrorCode};
use util_types::{Opcode, PowerOf2Usize};
use zerocopy::{FromBytes, IntoBytes};
const OPCODE_LEN: usize = core::mem::size_of::<Opcode>();
const STATUS_LEN: usize = core::mem::size_of::<u32>();
// A reply is built right after the request's opcode, so the status word that
// precedes it in the response has to fit exactly where the opcode was.
const _: () = assert!(OPCODE_LEN == STATUS_LEN);
/// Serves flash requests against a [`Flash`].
///
/// A request is untrusted. Each handler establishes the preconditions the
/// driver documents (erase size in the erasable-size bitmap, erase address
/// aligned to that size, range inside the device) before calling [`Flash`].
/// Read and program may be unaligned; `BlockingFlash` splits those, but does
/// not check that the range stays on the device.
pub struct Server<TFlash: Flash> {
flash: TFlash,
}
impl<TFlash: Flash<Error = ErrorCode>> Server<TFlash> {
/// Creates a new `Server` wrapping the given flash implementation.
pub fn new(flash: TFlash) -> Self {
Self { flash }
}
/// Handles the `IPC_OP_FLASH_GET_INFO` request.
///
/// Writes the flash geometry to the front of `data` and returns its length.
fn handle_geometry(&mut self, data: &mut [u8], reqsz: usize) -> Result<usize, ErrorCode> {
if reqsz != 0 {
return Err(error::IPC_ERROR_BAD_REQ_LEN);
}
let (info, _rest) =
FlashInfo::mut_from_prefix(data).map_err(|_| error::IPC_ERROR_BAD_REQ_LEN)?;
let (total_size, page_size, erasable_sizes_bitmap) = self.flash.geometry()?;
info.page_size = page_size.get() as u32;
info.total_size = total_size.get() as u32;
info.erasable_sizes_bitmap = erasable_sizes_bitmap;
Ok(info.as_bytes().len())
}
/// Device size and erasable-size bitmap, from the flash the server wraps.
fn device_limits(&mut self) -> Result<(usize, u32), ErrorCode> {
let (total, _page, bitmap) = self.flash.geometry()?;
Ok((total.get(), bitmap))
}
/// Handles the `IPC_OP_FLASH_ERASE` request.
///
/// Parses the `EraseOp` from the input data and erases the specified block.
/// The size must be a supported erase size, the address must be aligned to
/// it, and the block must lie inside the device.
fn handle_erase(&mut self, data: &mut [u8], reqsz: usize) -> Result<usize, ErrorCode> {
let req_data = data.get(..reqsz).ok_or(error::IPC_ERROR_BAD_REQ_LEN)?;
let op = EraseOp::read_from_bytes(req_data).map_err(|_| error::IPC_ERROR_BAD_REQ_LEN)?;
let Some(size) = PowerOf2Usize::new(op.size as usize) else {
return Err(error::FLASH_GENERIC_ERASE_INVALID_SIZE);
};
let (total, bitmap) = self.device_limits()?;
erase_size_supported(size, bitmap)?;
erase_address_aligned(op.address, size)?;
region_in_bounds(op.address, size.get(), total)?;
self.flash.erase(op.address, size)?;
Ok(0)
}
/// Handles the `IPC_OP_FLASH_PROGRAM` request.
///
/// Parses the start address and data from the input, rejects a range
/// outside the device, then programs it.
fn handle_program(&mut self, data: &mut [u8], reqsz: usize) -> Result<usize, ErrorCode> {
let req_data = data.get(..reqsz).ok_or(error::IPC_ERROR_BAD_REQ_LEN)?;
let (addr, program_data) =
FlashAddress::read_from_prefix(req_data).map_err(|_| error::IPC_ERROR_BAD_REQ_LEN)?;
let (total, _bitmap) = self.device_limits()?;
region_in_bounds(addr, program_data.len(), total)?;
self.flash.program(addr, program_data)?;
Ok(0)
}
/// Handles the `IPC_OP_FLASH_READ` request.
///
/// Parses the `ReadOp` from the input, rejects a length the reply buffer
/// cannot hold or a range outside the device, then reads to the front of
/// `data` and returns the length.
fn handle_read(&mut self, data: &mut [u8], reqsz: usize) -> Result<usize, ErrorCode> {
let req_data = data.get(..reqsz).ok_or(error::IPC_ERROR_BAD_REQ_LEN)?;
let op = ReadOp::read_from_bytes(req_data).map_err(|_| error::IPC_ERROR_BAD_REQ_LEN)?;
let length = op.length as usize;
let Some(dst) = data.get_mut(..length) else {
return Err(error::FLASH_GENERIC_INVALID_SIZE);
};
let (total, _bitmap) = self.device_limits()?;
region_in_bounds(op.address, length, total)?;
self.flash.read(op.address, dst)?;
Ok(length)
}
/// Handles one request: `data` holds `reqsz` request bytes and receives
/// the reply at its front. Returns the reply length.
fn handle_op(
&mut self,
opcode: Opcode,
data: &mut [u8],
reqsz: usize,
) -> Result<usize, ErrorCode> {
match opcode {
IPC_OP_FLASH_GET_INFO => self.handle_geometry(data, reqsz),
IPC_OP_FLASH_ERASE => self.handle_erase(data, reqsz),
IPC_OP_FLASH_PROGRAM => self.handle_program(data, reqsz),
IPC_OP_FLASH_READ => self.handle_read(data, reqsz),
_ => Err(error::IPC_ERROR_UNKNOWN_OP),
}
}
/// Decodes the request in `buf[..len]`, an opcode then its body, and runs
/// it. The reply is left in `buf` right after the opcode.
fn handle_request(&mut self, buf: &mut [u8], len: usize) -> Result<usize, ErrorCode> {
let body_len = len
.checked_sub(OPCODE_LEN)
.ok_or(error::IPC_ERROR_BAD_REQ_LEN)?;
let (head, body) = buf
.split_at_mut_checked(OPCODE_LEN)
.ok_or(error::IPC_ERROR_BAD_REQ_LEN)?;
let opcode = Opcode::read_from_bytes(head).map_err(|_| error::IPC_ERROR_BAD_REQ_LEN)?;
self.handle_op(opcode, body, body_len)
}
/// Serves the request frame in `buf[..len]` and leaves the response frame
/// at the start of `buf`: a four-byte status, zero for success or an
/// `ErrorCode`, then the reply. Returns the frame length.
///
/// Only the first `len` bytes of `buf` are the request; the rest is stale.
/// The frame is built in place, so `buf` has to hold the larger of the
/// request and the response. Returns 0 if `buf` cannot hold a status.
pub fn handle_frame(&mut self, buf: &mut [u8], len: usize) -> usize {
let (status, reply_len) = match self.handle_request(buf, len) {
Ok(reply_len) => (0, reply_len),
Err(e) => (e.0.get(), 0),
};
let Some(head) = buf.get_mut(..STATUS_LEN) else {
return 0;
};
head.copy_from_slice(status.as_bytes());
STATUS_LEN.saturating_add(reply_len)
}
}
/// `size` must be a bit in `bitmap`: bit `i` means an erase of `2^i` bytes.
fn erase_size_supported(size: PowerOf2Usize, bitmap: u32) -> Result<(), ErrorCode> {
match 1u32.checked_shl(size.get().trailing_zeros()) {
Some(bit) if bitmap & bit != 0 => Ok(()),
_ => Err(error::FLASH_GENERIC_ERASE_INVALID_SIZE),
}
}
/// `BlockingFlash` does not align an erase before `FlashDriver::start_erase`.
fn erase_address_aligned(address: FlashAddress, size: PowerOf2Usize) -> Result<(), ErrorCode> {
let Ok(size) = u32::try_from(size.get()) else {
return Err(error::FLASH_GENERIC_ERASE_INVALID_SIZE);
};
if address.offset() & size.wrapping_sub(1) != 0 {
return Err(error::FLASH_GENERIC_ERASE_INVALID_ADDR);
}
Ok(())
}
/// `[address, address + len)` must lie in `[0, total)`.
fn region_in_bounds(address: FlashAddress, len: usize, total: usize) -> Result<(), ErrorCode> {
let in_bounds = u64::try_from(len)
.ok()
.and_then(|len| u64::from(address.offset()).checked_add(len))
.is_some_and(|end| end <= total as u64);
if in_bounds {
Ok(())
} else {
Err(error::FLASH_GENERIC_ADDR_OUT_OF_BOUNDS)
}
}