flash: remove WouldBlock from wire status and document server-internal retry semantics

Author: rusty1968

drivers/flash/README.md

@@ -0,0 +1,151 @@
+# Flash Driver Model
+
+This document describes the architecture of the layered flash userspace driver
+under drivers/flash and how it integrates with platform server bindings.
+
+## 1. Layer Overview
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Application / Client Task                               │
+│  FlashClient  (drivers/flash/client)                     │
+│  channel_transact(request) -> response                   │
+└────────────────────────┬─────────────────────────────────┘
+                         │  Pigweed IPC channel
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  Server Binary (platform binding)                         │
+│  rust_app wires handles + backend + runtime loop         │
+└────────────────────────┬─────────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  Server Library (platform binding)                       │
+│  dispatch_request: protocol -> backend translation        │
+│  runtime loop: channel_read -> dispatch -> respond        │
+└────────────────────────┬─────────────────────────────────┘
+                         │  FlashBackend trait
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  Platform Backend (platform binding)                      │
+│  PlatformFlashBackend : FlashBackend                     │
+└────────────────────────┬─────────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  Controller Driver (SMC/FMC or equivalent)               │
+│  Raw MMIO or HAL-level flash controller implementation    │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 2. Crate Map
+
+| Bazel target | Crate | Role |
+|---|---|---|
+| //drivers/flash/api:flash_api | flash_api | Wire protocol, error/status model, geometry types, backend trait contract |
+| //drivers/flash/client:flash_client | flash_client | Userspace IPC facade for read/write/erase/discovery |
+
+The API/client layers are target-agnostic within Pigweed kernel userspace
+targets.
+
+## 3. Wire Protocol (flash_api::protocol)
+
+Operations are encoded by FlashOp in FlashRequestHeader (16 bytes,
+repr(C, packed), little-endian), with an optional payload up to
+MAX_PAYLOAD_SIZE (256 bytes).
+
+| Op | Value | Request shape | Response shape |
+|---|---|---|---|
+| Exists | 0x01 | header only | value = 0/1 |
+| GetCapacity | 0x02 | header only | value = capacity bytes |
+| Read | 0x03 | address + length | payload = bytes read, value = byte count |
+| Write | 0x04 | address + length + payload | value = byte count |
+| Erase | 0x05 | address + length | success/error only |
+| GetGeometry | 0x06 | header only | payload = FlashGeometry |
+
+FlashResponseHeader (8 bytes) carries status (FlashError), payload length,
+and an op-specific value word.
+
+## 4. Backend Contract (flash_api::backend)
+
+The server-side backend contract is defined by FlashBackend:
+
+- info(route_key) -> FlashInfo
+- exists(route_key) -> Result<bool, BackendError>
+- read(route_key, address, out) -> Result<usize, BackendError>
+- write(route_key, address, data) -> Result<usize, BackendError>
+- erase(route_key, address, length) -> Result<(), BackendError>
+- enable_interrupts() / disable_interrupts()
+
+Geometry discovery is exposed via FlashGeometryProvider, which can derive a
+default geometry from info() or be overridden by backends that need richer
+semantics.
+
+## 5. Client Library (flash_client)
+
+FlashClient is a synchronous userspace facade that:
+
+- serializes request headers/payloads into caller-provided request buffers,
+- performs channel_transact with optional timeout,
+- parses/validates response headers and payload lengths,
+- maps transport and wire errors into ClientError.
+
+Current client behavior and constraints:
+
+- no_std, blocking IPC calls.
+- single call in flight per client instance (&mut self API).
+- per-call data cap is FlashClient::chunk_size() (MAX_PAYLOAD_SIZE).
+- explicit support for discovery calls: exists, capacity, geometry.
+
+For detailed usage and method-level behavior, see:
+
+- drivers/flash/api/README.md
+- drivers/flash/client/README.md
+
+## 6. Error Surface
+
+Wire-level status is FlashError. Common categories:
+
+- protocol misuse: InvalidOperation, InvalidAddress, InvalidLength
+- runtime contention: Busy, Timeout
+- media/policy failures: IoError, NotPermitted
+- fallback: InternalError
+
+ClientError wraps three classes of failure:
+
+- IpcError(pw_status::Error): transport syscall failure
+- ServerError(FlashError): valid response reporting flash-level failure
+- InvalidResponse: malformed/truncated response frame
+- BufferTooSmall: local request/response buffer constraints
+
+## 7. Integration Model
+
+drivers/flash is split so protocol and client can evolve independently from
+platform backend/server bring-up:
+
+- Keep wire schema and trait contract stable in flash_api.
+- Keep userspace ergonomics and parsing hardening in flash_client.
+- Implement server runtime and concrete backend per target tree.
+
+This separation allows host-side validation of protocol and client logic before
+hardware-specific bindings are ready.
+
+## 8. Extension Points
+
+- New backend: implement FlashBackend (and optionally FlashGeometryProvider)
+  in a platform crate, then bind server channel handles to route keys.
+- New operation: add FlashOp variant, define header/payload semantics, extend
+  backend trait and server dispatch.
+- New geometry flags semantics: preserve wire compatibility by treating flags
+  as opaque at protocol level and documenting interpretation at backend level.
+
+## 9. Testing Focus
+
+Recommended tests by layer:
+
+- flash_api: wire layout, endian correctness, enum/status round-trips,
+  short-buffer decode rejection.
+- flash_client: response validation paths, timeout behavior, chunk-size checks,
+  and retry handling for Busy.
+- platform server/backend: operation dispatch, alignment rules, erase granule
+  correctness, and hardware fault mapping to FlashError.

drivers/flash/api/README.md

@@ -192,14 +192,15 @@ maps channel → backend → `RouteKey`.
 | `BufferTooSmall` | 0x04 | Server-side buffer constraint |
 | `Busy` | 0x05 | Backend busy |
 | `Timeout` | 0x06 | Operation timed out |
-| `WouldBlock` | 0x07 | Could not complete synchronously; retry after IRQ |
-| `IoError` | 0x08 | Media-level failure |
-| `NotPermitted` | 0x09 | Blocked by backend policy/protection |
+| `IoError` | 0x07 | Media-level failure |
+| `NotPermitted` | 0x08 | Blocked by backend policy/protection |
 | `InternalError` | 0xFF | Unclassified server fault |
 
 `BackendError` is the trait-level error backends produce; an `impl
 From<BackendError> for FlashError` provides the canonical mapping for
-the server's response-encoding path.
+the server's response-encoding path. `BackendError::WouldBlock` is
+treated as backend-internal and maps to `FlashError::Busy` at the wire
+boundary.
 
 ## Tests
 

drivers/flash/api/src/backend.rs

@@ -6,7 +6,8 @@
 //! The shape mirrors the `FlashStorage` HIL from caliptra-mcu-sw but is
 //! synchronous and buffer-borrowing rather than callback-based: the
 //! server runtime drives concurrency, so backends only need to expose
-//! a blocking-or-`WouldBlock` surface.
+//! a blocking-or-`WouldBlock` surface. `WouldBlock` is backend-internal
+//! and is not encoded on the wire.
 
 use crate::protocol::{FlashError, FlashGeometry};
 
@@ -18,8 +19,11 @@ pub enum BackendError {
     BufferTooSmall,
     Busy,
     Timeout,
-    /// Backend cannot complete synchronously at this time; the server
-    /// runtime should retry after `OPERATION_COMPLETE` fires.
+    /// Operation cannot complete synchronously now.
+    ///
+    /// This is an internal backend/server scheduling signal. The server
+    /// runtime should defer and retry after a progress signal, typically
+    /// a completion interrupt, rather than exposing it directly on the wire.
     WouldBlock,
     /// Media-level failure (program/erase verify fail, ECC uncorrectable, …).
     IoError,
@@ -37,7 +41,7 @@ impl From<BackendError> for FlashError {
             BackendError::BufferTooSmall => FlashError::BufferTooSmall,
             BackendError::Busy => FlashError::Busy,
             BackendError::Timeout => FlashError::Timeout,
-            BackendError::WouldBlock => FlashError::WouldBlock,
+            BackendError::WouldBlock => FlashError::Busy,
             BackendError::IoError => FlashError::IoError,
             BackendError::NotPermitted => FlashError::NotPermitted,
             BackendError::InternalError => FlashError::InternalError,

drivers/flash/api/src/protocol.rs

@@ -66,14 +66,11 @@ pub enum FlashError {
     BufferTooSmall = 0x04,
     Busy = 0x05,
     Timeout = 0x06,
-    /// Operation cannot complete right now; the server/runtime may defer
-    /// completion until the backend signals progress via interrupt.
-    WouldBlock = 0x07,
     /// Underlying media reported an I/O error (e.g. flash program failure).
-    IoError = 0x08,
+    IoError = 0x07,
     /// Address/length straddles a region the backend refuses to touch
     /// (e.g. write-protected partition).
-    NotPermitted = 0x09,
+    NotPermitted = 0x08,
     InternalError = 0xFF,
 }
 
@@ -87,9 +84,8 @@ impl From<u8> for FlashError {
             0x04 => Self::BufferTooSmall,
             0x05 => Self::Busy,
             0x06 => Self::Timeout,
-            0x07 => Self::WouldBlock,
-            0x08 => Self::IoError,
-            0x09 => Self::NotPermitted,
+            0x07 => Self::IoError,
+            0x08 => Self::NotPermitted,
             _ => Self::InternalError,
         }
     }
@@ -297,9 +293,8 @@ mod tests {
             (0x04, FlashError::BufferTooSmall),
             (0x05, FlashError::Busy),
             (0x06, FlashError::Timeout),
-            (0x07, FlashError::WouldBlock),
-            (0x08, FlashError::IoError),
-            (0x09, FlashError::NotPermitted),
+            (0x07, FlashError::IoError),
+            (0x08, FlashError::NotPermitted),
             (0xFF, FlashError::InternalError),
         ];
         for (byte, err) in cases {
@@ -313,6 +308,7 @@ mod tests {
         for byte in [0x0Au8, 0x10, 0x42, 0x80, 0xFE] {
             assert_eq!(FlashError::from(byte), FlashError::InternalError);
         }
+        assert_eq!(FlashError::from(0x09), FlashError::InternalError);
     }
 
     #[test]
@@ -416,7 +412,6 @@ mod tests {
         for err in [
             FlashError::Success,
             FlashError::InvalidAddress,
-            FlashError::WouldBlock,
             FlashError::NotPermitted,
             FlashError::InternalError,
         ] {

drivers/flash/client/README.md

@@ -144,15 +144,11 @@ pub enum ClientError {
 | `BufferTooSmall` | Server-side buffer constraint |
 | `Busy` | Backend busy |
 | `Timeout` | Operation timed out |
-| `WouldBlock` | Operation could not be completed immediately |
 | `IoError` | Media-level failure |
 | `NotPermitted` | Blocked by backend policy/protection |
 | `InternalError` | Unclassified server fault |
 
-### `Busy` vs `WouldBlock`
-
-- **`Busy`**: The backend is actively performing another operation and cannot accept new requests. Retry the entire call after waiting.
-- **`WouldBlock`**: This specific operation could not be completed immediately due to resource constraints or contention, but is not blocked by global device activity. Callers can implement smarter retry logic or adjust request parameters.
+Client policy should treat `Busy` as the retryable contention signal.
 
 ## Constraints
 

drivers/flash/client/src/lib.rs

@@ -10,7 +10,7 @@ use flash_api::{
 };
 pub use flash_api::MAX_PAYLOAD_SIZE;
 use userspace::syscall;
-use userspace::time::{Duration as KDuration, Instant, SystemClock};
+use userspace::time::{Clock, Duration as KDuration, Instant, SystemClock};
 use zerocopy::FromBytes;
 
 /// Minimum buffer size required for Flash protocol messages.