tree: 5c5f9f5ac2c89f23a2b14f88714a8b1258f65529 [search]
  1. api/
  2. client/
  3. client-ipc/
  4. server/
  5. server-runtime/
  6. tests/
  7. BUILD.bazel
  8. README.md
services/flash/README.md

Flash Service

The Flash Service provides a centralized interface for userspace applications to interact with on-chip and external flash memory. This is achieved via an IPC-based client-server architecture.

Overview

Applications interact with flash through the Flash trait, typically using the FlashIpcClient implementation. All operations are blocking from the perspective of the caller.

Key Features

  • Flexible Erase: Support for multiple erase granularities (e.g., page vs. block) as reported by the hardware.
  • Unified Addressing: A logical FlashAddress system that abstracts hardware-specific bank and page layouts.

Usage

To use the flash service, initialize a FlashIpcClient with a transport over the channel to the flash service:

use hal_flash::{Flash, FlashAddress};
use openprot_flash_client_ipc::{ChannelTransport, FlashIpcClient};
use util_ipc::IpcHandle;

// 1. Connect to the flash service
let transport = ChannelTransport::new(IpcHandle::new(FLASH_SERVICE_HANDLE));
let mut flash = FlashIpcClient::new(transport)?;

// 2. Retrieve device geometry
let (total_size, page_size, erasable_bitmap) = flash.geometry();

// 3. Erase a block (using the default page size)
let addr = FlashAddress::new(0x1000);
flash.erase(addr, page_size)?;

// 4. Program data
flash.program(addr, b"Hello, Flash!")?;

// 5. Read data back
let mut buf = [0u8; 13];
flash.read(addr, &mut buf)?;

The Flash Trait

The primary interface for flash operations:

  • geometry() -> (NonZero<usize>, PowerOf2Usize, u32): Returns the total capacity, the default/smallest page size, and a bitmap of all supported erase block sizes.
  • read(addr, buf): Reads data from the specified address.
  • erase(addr, size): Erases a block of the specified size. The size must be one of the values supported in the erasable_bitmap.
  • program(addr, data): Writes data to the specified address. Flash must be erased before programming.

Understanding erasable_bitmap

The erasable_bitmap is a u32 where each set bit i indicates that an erase block size of 2^i bytes is supported.

  • Bit 11 set (0x800) -> 2048-byte erase supported.
  • Bit 16 set (0x10000) -> 64KB erase supported.

Addressing

Flash memory is addressed using the FlashAddress type, which wraps a single 32-bit offset.

The server treats the offset as a byte position in a flat range from 0 to the size reported by geometry(), and rejects any read, program, or erase that does not fit in it. A target whose offsets carry more than a position, such as a partition selector, needs its own address handling in front of the server.

Implementation Details

The service is built on several layers of abstraction:

Crates

DirectoryCrateRole
api/openprot_flash_apiOpcodes and request layouts shared by client and server.
client/openprot_flash_clientFlashClient, the Flash trait over any FlashTransport. No kernel types.
client-ipc/openprot_flash_client_ipcChannelTransport, which carries requests over a kernel channel, and FlashIpcClient. Kernel only.
server/openprot_flash_serverServer: decodes a request frame, checks it, and builds the response frame. No kernel types.
server-runtime/flash_server_runtimerun: serves one Server per IPC channel, through util_service's loop. Kernel only.

Host tests: bazelisk test //services/flash:flash_host_tests. They include the real client talking to the real server over an in-memory transport.

IPC Layer

  • Server is the trust boundary. Client address, erase size, and length are checked here, before BlockingFlash or the hardware driver is called. The erase size is a bit in the erasable-size bitmap, the erase address is aligned to that size, and every read, program, and erase range stays inside the device. A rejected request never reaches the flash.
  • FlashClient: Implements the Flash trait by proxying calls to the server. It checks the length of each response.

A request is an opcode followed by its body. A response is a four-byte status, zero for success or an ErrorCode, followed by the reply.

Several devices

One flash device is one IPC channel. A controller with several chip selects is served by giving each chip select its own channel and Server, and passing them to run as parallel slices. The channel a request arrives on picks the device, so the wire protocol has no device id, and a process can only reach the devices it was given a channel to. A device a client should not touch is a channel it does not get.

Hardware Abstraction

  • FlashDriver Trait: Defines the low-level, often asynchronous, interface for hardware drivers.
  • BlockingFlash: A wrapper that converts a FlashDriver into a synchronous Flash implementation using a provided blocking mechanism.

Component Diagram

Flash Trait FlashTransport IPC handle_frame() Flash Trait FlashDriver Trait Userspace Application FlashClient ChannelTransport flash_server_runtime Server BlockingFlash e.g., EmbeddedFlash Flash Controller