| // Licensed under the Apache-2.0 license | |
| // SPDX-License-Identifier: Apache-2.0 | |
| //! Host-buildable core of the i3c server: the target-owning [`Server`] state | |
| //! and the request [`dispatch`] against the [`I3cTarget`] facade. | |
| //! | |
| //! No syscalls live here, so the request handling and the inbound frame ring | |
| //! are verified in host tests. The kernel-tagged `i3c_server_runtime` | |
| //! wraps this in the Pigweed WaitGroup loop and supplies the IRQ/IPC syscalls. | |
| #![no_std] | |
| pub mod loopback; | |
| pub use loopback::LoopbackTransport; | |
| use i3c_api::{ | |
| decode_request, encode_response, DeviceInfo, I3cOp, I3cStatus, DEVICE_INFO_LEN, HEADER, | |
| MAX_PAYLOAD, MAX_SEND, | |
| }; | |
| use openprot_hal_blocking::i3c_hardware::I3cTarget; | |
| /// Default depth of the inbound frame ring. | |
| /// | |
| /// The ring covers the window between the IRQ latching a frame and the client | |
| /// draining it over IPC (a cross-process round-trip, plus a controller that | |
| /// polls and may resend), and it must hold every frame a consumer expects the | |
| /// controller to send back-to-back before it drains any. That last part belongs | |
| /// to the consumer, not to this crate: a [`Server`] takes its depth as a const | |
| /// parameter (`Server<T, RING>`, [`Server::with_ring`]), and `Server::new` uses | |
| /// this default of 6. Overflow is an error path only (see | |
| /// [`Inbound::DroppedFull`]). | |
| pub const RX_RING: usize = 6; | |
| /// Outcome of draining one inbound frame in [`Server::latch_inbound`]. | |
| #[derive(Debug, Clone, Copy, PartialEq, Eq)] | |
| pub enum Inbound { | |
| /// A frame was read from the target and queued into the ring. | |
| Latched, | |
| /// Nothing was available to latch (empty or a zero-length descriptor). | |
| Empty, | |
| /// A frame was read but dropped because the ring was full — a lost frame | |
| /// (for a fragmenting consumer, a lost fragment). [`RX_RING`] is sized so this should not occur in normal flow; | |
| /// the runtime logs it. | |
| DroppedFull, | |
| } | |
| /// The I3C target the server owns, plus its IPC channel, IRQ handle, the | |
| /// inbound frame ring, and the outbound "response staged, awaiting read" flag. | |
| /// | |
| /// Inbound frames are queued in a [`RX_RING`]-deep FIFO. A consumer is | |
| /// typically request/response, but the client draining a latched frame spans a | |
| /// cross-process round-trip, during which the controller can land the next | |
| /// frame (a resend, or the next fragment); the ring holds those so none is | |
| /// lost. `latch_inbound` pushes the oldest-first; `Recv` pops it. The ring | |
| /// never overwrites an unread frame — on overflow a frame is dropped and logged | |
| /// instead (an error path `RX_RING` is sized to avoid). The bus is never | |
| /// blocked. | |
| /// | |
| /// Outbound allows one staged response at a time. A `Send` stages a response | |
| /// for the controller's next private read and sets | |
| /// [`tx_pending`](Server::tx_pending); the flag clears only when the controller | |
| /// has read it, signalled by [`notify_response_read`](Server::notify_response_read) | |
| /// on a [`TargetEvent::ResponseRead`]. While it is set, `dispatch` answers a | |
| /// further `Send` with [`I3cStatus::Busy`] and stages nothing, so a second | |
| /// response can never be queued over an unread one. The client retries once the | |
| /// controller has read the first. (caliptra-mcu-sw's I3C driver does the same: | |
| /// its `transmit_read` returns `ErrorCode::BUSY` while a transmit is | |
| /// outstanding.) | |
| /// | |
| /// [`TargetEvent::ResponseRead`]: openprot_hal_blocking::i3c_hardware::TargetEvent::ResponseRead | |
| pub struct Server<T, const RING: usize = RX_RING> { | |
| /// IPC channel handle carrying the transport protocol. | |
| pub channel: u32, | |
| /// IRQ handle for the I3C controller. | |
| pub irq: u32, | |
| /// The controller driver implementing the facade. | |
| pub target: T, | |
| /// Inbound frame ring buffers, one `MAX_PAYLOAD` slot per ring entry. | |
| rx: [[u8; MAX_PAYLOAD]; RING], | |
| /// Payload length latched in each ring slot. | |
| rx_len: [usize; RING], | |
| /// Index of the oldest queued frame (the next `Recv` pops this slot). | |
| rx_head: usize, | |
| /// Number of frames currently queued in the ring. | |
| rx_count: usize, | |
| tx_pending: bool, | |
| /// A staged response was discarded unread and no `Send` has reported it yet. | |
| discarded: bool, | |
| /// The dynamic address the staged response was framed for, or `None` if it | |
| /// does not depend on one. A frame whose check covers the address byte (an | |
| /// MCTP-over-I3C PEC) is wrong whenever the controller reads it once the | |
| /// address has moved. | |
| staged_addr: Option<u8>, | |
| } | |
| impl<T> Server<T, RX_RING> { | |
| /// Bind the server to one channel, one IRQ, and one target driver, with the | |
| /// default ring depth ([`RX_RING`]). Use [`with_ring`](Self::with_ring) for | |
| /// another depth. | |
| pub const fn new(channel: u32, irq: u32, target: T) -> Self { | |
| Self::with_ring(channel, irq, target) | |
| } | |
| } | |
| impl<T, const RING: usize> Server<T, RING> { | |
| /// Bind the server to one channel, one IRQ, and one target driver, with a | |
| /// ring that holds `RING` inbound frames. | |
| pub const fn with_ring(channel: u32, irq: u32, target: T) -> Self { | |
| Self { | |
| channel, | |
| irq, | |
| target, | |
| rx: [[0u8; MAX_PAYLOAD]; RING], | |
| rx_len: [0usize; RING], | |
| rx_head: 0, | |
| rx_count: 0, | |
| tx_pending: false, | |
| discarded: false, | |
| staged_addr: None, | |
| } | |
| } | |
| /// Whether any inbound frame is queued and waiting for a `Recv`. | |
| pub fn has_frame(&self) -> bool { | |
| self.rx_count > 0 | |
| } | |
| /// The length of the frame most recently latched into the ring, or 0 if the | |
| /// ring is empty. | |
| pub fn newest_frame_len(&self) -> usize { | |
| if self.rx_count == 0 { | |
| return 0; | |
| } | |
| let newest = (self.rx_head + self.rx_count - 1) % RING; | |
| self.rx_len.get(newest).copied().unwrap_or(0) | |
| } | |
| /// Whether a staged transmit is still awaiting the controller's private | |
| /// read. A further `Send` is answered `Busy` while this is set. | |
| pub fn tx_pending(&self) -> bool { | |
| self.tx_pending | |
| } | |
| /// Clear the outbound flag: the controller has read the staged response, so | |
| /// the next `Send` can be staged. Called by the runtime on | |
| /// [`TargetEvent::ResponseRead`], which is the only thing that clears it. | |
| /// | |
| /// [`TargetEvent::ResponseRead`]: openprot_hal_blocking::i3c_hardware::TargetEvent::ResponseRead | |
| pub fn notify_response_read(&mut self) { | |
| self.tx_pending = false; | |
| } | |
| } | |
| impl<T: I3cTarget, const RING: usize> Server<T, RING> { | |
| /// Give up on a staged response the controller has not read. | |
| /// | |
| /// Discards it in the target ([`I3cTarget::cancel_response`]) and releases | |
| /// the outbound flag, so the next `Send` is accepted. Returns whether | |
| /// anything was cancelled: `false`, with the target untouched, if no | |
| /// response was staged. The runtime calls this once a response has waited | |
| /// [`STAGED_RESPONSE_TIMEOUT_MS`](i3c_api::STAGED_RESPONSE_TIMEOUT_MS). | |
| /// | |
| /// The flag is released even if the target could not really discard the | |
| /// response (see [`I3cTarget::cancel_response`]), and also if it reports an | |
| /// error. Keeping it set would refuse every later `Send` for good, which is | |
| /// the failure this exists to end. | |
| /// | |
| /// # Errors | |
| /// | |
| /// The target's error from `cancel_response`, after the flag is released. | |
| pub fn cancel_staged(&mut self) -> Result<bool, T::Error> { | |
| if !self.tx_pending { | |
| return Ok(false); | |
| } | |
| self.tx_pending = false; | |
| // The message is lost whether or not the target could really discard | |
| // it; the next `Send` reports that, once (`I3cStatus::Discarded`). | |
| self.discarded = true; | |
| self.target.cancel_response().map(|()| true) | |
| } | |
| /// The target's dynamic address, if it has one. | |
| fn current_addr(&self) -> Option<u8> { | |
| self.target.dynamic_address().map(u8::from) | |
| } | |
| /// Give up on the staged response if it was framed for an address the target | |
| /// no longer has. | |
| /// | |
| /// The controller can re-run ENTDAA or send RSTDAA at any time. A response | |
| /// framed for the old address (its PEC covers the address byte) would fail | |
| /// the controller's check, so it is discarded the same way a response left | |
| /// unread is, and the next `Send` reports it as [`I3cStatus::Discarded`]. A | |
| /// response that does not depend on an address is left alone. | |
| /// | |
| /// Reads the address from the target rather than waiting for an event: a | |
| /// target whose address is assigned outside the driver (the Caliptra ROM does | |
| /// it) never reports `AddressAssigned` or `AddressLost`. | |
| /// | |
| /// Returns whether a response was discarded. | |
| /// | |
| /// # Errors | |
| /// | |
| /// The target's error from `cancel_response`, after the flag is released. | |
| pub fn discard_if_address_moved(&mut self) -> Result<bool, T::Error> { | |
| match self.staged_addr { | |
| Some(framed_for) if self.tx_pending && self.current_addr() != Some(framed_for) => { | |
| self.cancel_staged() | |
| } | |
| _ => Ok(false), | |
| } | |
| } | |
| /// The runtime saw the address change (`AddressAssigned` or `AddressLost`): | |
| /// discard the staged response if it was framed for an address. | |
| /// | |
| /// Returns whether a response was discarded. | |
| /// | |
| /// # Errors | |
| /// | |
| /// The target's error from `cancel_response`, after the flag is released. | |
| pub fn address_changed(&mut self) -> Result<bool, T::Error> { | |
| if self.tx_pending && self.staged_addr.is_some() { | |
| return self.cancel_staged(); | |
| } | |
| Ok(false) | |
| } | |
| /// Drain one inbound frame into the ring after a [`TargetEvent::InboundReady`]. | |
| /// | |
| /// Reads one frame from the target and, if the ring has room, queues it at | |
| /// the tail; returns [`Inbound`] describing what happened. The runtime calls | |
| /// this in a loop until it returns [`Inbound::Empty`], so a single IRQ that | |
| /// covers several hardware frames drains them all. | |
| /// | |
| /// A zero-length descriptor is not a real frame: the RX-descriptor interrupt | |
| /// can fire with no payload (seen on the emulator around the controller's | |
| /// write/private-read command traffic), and `read_frame` then reports | |
| /// `Some(0)`. A zero-length inbound carries nothing for a consumer, so it is | |
| /// treated as "nothing arrived" ([`Inbound::Empty`]). | |
| /// | |
| /// When the ring is full the frame is still read out of the hardware (to | |
| /// keep the RX path moving) but dropped — [`Inbound::DroppedFull`]. Dropping | |
| /// the new frame is the lesser evil: overwriting a queued one would lose an | |
| /// earlier fragment. The ring is sized so this does not happen in | |
| /// normal flow. | |
| pub fn latch_inbound(&mut self) -> Result<Inbound, T::Error> { | |
| if self.rx_count >= RING { | |
| let mut scratch = [0u8; MAX_PAYLOAD]; | |
| return Ok(match self.target.read_frame(&mut scratch)? { | |
| Some(n) if n > 0 => Inbound::DroppedFull, | |
| _ => Inbound::Empty, | |
| }); | |
| } | |
| let tail = (self.rx_head + self.rx_count) % RING; | |
| Ok(match self.target.read_frame(&mut self.rx[tail])? { | |
| Some(n) if n > 0 => { | |
| self.rx_len[tail] = n.min(MAX_PAYLOAD); | |
| self.rx_count += 1; | |
| Inbound::Latched | |
| } | |
| _ => Inbound::Empty, | |
| }) | |
| } | |
| } | |
| fn status_only(resp: &mut [u8], status: I3cStatus) -> usize { | |
| match encode_response(status, &[], resp) { | |
| Some(n) => n, | |
| None => match resp.first_mut() { | |
| Some(head) => { | |
| *head = status as u8; | |
| 1 | |
| } | |
| None => 0, | |
| }, | |
| } | |
| } | |
| /// Dispatch one client request against the target, writing the response into | |
| /// `resp` and returning its length. | |
| /// | |
| /// `Recv` consumes the latch. This function performs no syscalls; the runtime | |
| /// manages the `USER` notification around it. | |
| pub fn dispatch<T: I3cTarget, const RING: usize>( | |
| srv: &mut Server<T, RING>, | |
| req: &[u8], | |
| resp: &mut [u8], | |
| ) -> usize { | |
| let Some((op, payload)) = decode_request(req) else { | |
| return status_only(resp, I3cStatus::InvalidOp); | |
| }; | |
| match op { | |
| I3cOp::Send => { | |
| // `[framed_for][frame...]`: see `I3cOp::Send`. | |
| let Some((&framed_for, frame)) = payload.split_first() else { | |
| return status_only(resp, I3cStatus::InvalidOp); | |
| }; | |
| if framed_for > 0x7f { | |
| return status_only(resp, I3cStatus::InvalidOp); | |
| } | |
| // 0 = not tied to an address. | |
| let framed_for = (framed_for != 0).then_some(framed_for); | |
| // Too long for the protocol, or for what this target can stage in one | |
| // response. | |
| if frame.len() > MAX_SEND || frame.len() > srv.target.max_send_len() { | |
| return status_only(resp, I3cStatus::TooLong); | |
| } | |
| // A response framed for an address that has since changed is wrong | |
| // for the controller whenever it reads it: discard it now. The flag | |
| // is released even if the target reports an error. | |
| let _ = srv.discard_if_address_moved(); | |
| // One staged response at a time: staging another over an unread one | |
| // could overrun the target's TX queue. The client retries. | |
| if srv.tx_pending { | |
| return status_only(resp, I3cStatus::Busy); | |
| } | |
| // A response was discarded unread since the last `Send`. Say so, once, | |
| // and stage nothing: a sender part-way through a message has lost a | |
| // fragment and must not go on with the rest. | |
| if srv.discarded { | |
| srv.discarded = false; | |
| return status_only(resp, I3cStatus::Discarded); | |
| } | |
| // The frame was built for an address this target no longer has: stage | |
| // nothing, so the client can rebuild it. Checked here, against the | |
| // live address, so no change can slip in between the client reading | |
| // the address and the frame being staged. | |
| if let Some(addr) = framed_for | |
| && srv.current_addr() != Some(addr) | |
| { | |
| return status_only(resp, I3cStatus::AddressChanged); | |
| } | |
| match srv.target.send(frame) { | |
| Ok(()) => { | |
| // Staged for the controller's next private read; further | |
| // sends are `Busy` until it has been read (cleared by the | |
| // runtime on ResponseRead). | |
| srv.tx_pending = true; | |
| srv.staged_addr = framed_for; | |
| status_only(resp, I3cStatus::Ok) | |
| } | |
| Err(_) => status_only(resp, I3cStatus::Internal), | |
| } | |
| } | |
| I3cOp::Recv => { | |
| if srv.rx_count == 0 { | |
| return status_only(resp, I3cStatus::NoData); | |
| } | |
| let head = srv.rx_head; | |
| let cap = resp.len().saturating_sub(HEADER); | |
| let frame = srv | |
| .rx | |
| .get(head) | |
| .zip(srv.rx_len.get(head)) | |
| .and_then(|(frame, &len)| frame.get(..len.min(cap))) | |
| .unwrap_or(&[]); | |
| let out = encode_response(I3cStatus::Ok, frame, resp); | |
| // Pop the oldest frame whether or not the encode succeeded: a | |
| // response buffer too small to hold it would otherwise wedge the | |
| // ring on the same frame forever. | |
| srv.rx_head = (srv.rx_head + 1) % RING; | |
| srv.rx_count -= 1; | |
| out.unwrap_or_else(|| status_only(resp, I3cStatus::Internal)) | |
| } | |
| I3cOp::DeviceInfo => { | |
| let info = srv.target.device_info(); | |
| // Report what a client can use: never more than the ring slots and | |
| // the wire frame hold, whatever the target says. | |
| let clamp = |n: usize| n.min(MAX_PAYLOAD) as u16; | |
| let clamp_send = |n: usize| n.min(MAX_SEND) as u16; | |
| let wire = DeviceInfo { | |
| dynamic_address: info.dynamic_address.map(u8::from), | |
| static_address: info.static_address.map(u8::from), | |
| max_send_len: clamp_send(info.max_send_len), | |
| max_recv_len: clamp(info.max_recv_len), | |
| }; | |
| let mut body = [0u8; DEVICE_INFO_LEN]; | |
| match wire.encode(&mut body) { | |
| Some(n) => encode_response(I3cStatus::Ok, &body[..n], resp) | |
| .unwrap_or_else(|| status_only(resp, I3cStatus::Internal)), | |
| None => status_only(resp, I3cStatus::Internal), | |
| } | |
| } | |
| I3cOp::DynamicAddress => match srv.target.dynamic_address() { | |
| Some(addr) => encode_response(I3cStatus::Ok, &[u8::from(addr)], resp) | |
| .unwrap_or_else(|| status_only(resp, I3cStatus::Internal)), | |
| None => status_only(resp, I3cStatus::Unassigned), | |
| }, | |
| } | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use super::*; | |
| use i3c_api::{decode_response, encode_request, MAX_FRAME}; | |
| use openprot_hal_blocking::i3c_hardware::{DynamicAddress, TargetEvent}; | |
| /// Capacity of the test target's own inbound queue; larger than `RX_RING` | |
| /// so overflow of the server ring can be exercised (tracks `RX_RING`). | |
| const FAKE_INBOUND: usize = RX_RING + 4; | |
| struct FakeTarget { | |
| addr: Option<u8>, | |
| /// How many times `cancel_response` was called. | |
| cancels: u32, | |
| /// Pending inbound frames, oldest first; `read_frame` pops the front. | |
| frames: [[u8; MAX_PAYLOAD]; FAKE_INBOUND], | |
| frame_lens: [usize; FAKE_INBOUND], | |
| frame_head: usize, | |
| frame_count: usize, | |
| sent: [u8; MAX_PAYLOAD], | |
| sent_len: usize, | |
| /// What the fake reports from `max_send_len`. | |
| send_limit: usize, | |
| /// What the fake reports from `max_recv_len`. | |
| recv_limit: usize, | |
| /// What the fake reports from `static_address`. | |
| static_addr: Option<u8>, | |
| } | |
| impl Default for FakeTarget { | |
| fn default() -> Self { | |
| Self { | |
| addr: None, | |
| cancels: 0, | |
| frames: [[0u8; MAX_PAYLOAD]; FAKE_INBOUND], | |
| frame_lens: [0usize; FAKE_INBOUND], | |
| frame_head: 0, | |
| frame_count: 0, | |
| sent: [0u8; MAX_PAYLOAD], | |
| sent_len: 0, | |
| send_limit: MAX_PAYLOAD, | |
| recv_limit: MAX_PAYLOAD, | |
| static_addr: None, | |
| } | |
| } | |
| } | |
| impl FakeTarget { | |
| /// Queue one inbound frame for a later `read_frame`. | |
| fn push_inbound(&mut self, data: &[u8]) { | |
| assert!( | |
| self.frame_count < FAKE_INBOUND, | |
| "test inbound queue overflow" | |
| ); | |
| let tail = (self.frame_head + self.frame_count) % FAKE_INBOUND; | |
| let n = data.len().min(MAX_PAYLOAD); | |
| self.frames[tail][..n].copy_from_slice(&data[..n]); | |
| self.frame_lens[tail] = n; | |
| self.frame_count += 1; | |
| } | |
| } | |
| #[derive(Debug, PartialEq, Eq)] | |
| struct FakeError; | |
| impl I3cTarget for FakeTarget { | |
| type Error = FakeError; | |
| fn enable(&mut self) -> Result<(), Self::Error> { | |
| Ok(()) | |
| } | |
| fn on_interrupt(&mut self) -> Result<TargetEvent, Self::Error> { | |
| if self.frame_count > 0 { | |
| Ok(TargetEvent::InboundReady) | |
| } else { | |
| Ok(TargetEvent::None) | |
| } | |
| } | |
| fn read_frame(&mut self, buf: &mut [u8]) -> Result<Option<usize>, Self::Error> { | |
| if self.frame_count == 0 { | |
| return Ok(None); | |
| } | |
| let head = self.frame_head; | |
| let n = self.frame_lens[head]; | |
| if n > buf.len() { | |
| return Err(FakeError); | |
| } | |
| buf[..n].copy_from_slice(&self.frames[head][..n]); | |
| self.frame_head = (self.frame_head + 1) % FAKE_INBOUND; | |
| self.frame_count -= 1; | |
| Ok(Some(n)) | |
| } | |
| fn send(&mut self, data: &[u8]) -> Result<(), Self::Error> { | |
| let n = data.len().min(MAX_PAYLOAD); | |
| self.sent[..n].copy_from_slice(&data[..n]); | |
| self.sent_len = n; | |
| Ok(()) | |
| } | |
| fn cancel_response(&mut self) -> Result<(), Self::Error> { | |
| self.cancels += 1; | |
| self.sent_len = 0; | |
| Ok(()) | |
| } | |
| fn dynamic_address(&self) -> Option<DynamicAddress> { | |
| self.addr.and_then(|a| DynamicAddress::try_from(a).ok()) | |
| } | |
| fn max_send_len(&self) -> usize { | |
| self.send_limit | |
| } | |
| fn static_address(&self) -> Option<DynamicAddress> { | |
| self.static_addr | |
| .and_then(|a| DynamicAddress::try_from(a).ok()) | |
| } | |
| fn max_recv_len(&self) -> usize { | |
| self.recv_limit | |
| } | |
| fn disable(&mut self) -> Result<(), Self::Error> { | |
| Ok(()) | |
| } | |
| } | |
| fn srv() -> Server<FakeTarget> { | |
| Server::new(1, 2, FakeTarget::default()) | |
| } | |
| #[test] | |
| fn send_dispatches_to_target() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"pong"), I3cStatus::Ok); | |
| assert_eq!(&s.target.sent[..s.target.sent_len], b"pong"); | |
| } | |
| #[test] | |
| fn cancelling_a_staged_response_accepts_the_next_send() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Busy, "first is unread"); | |
| assert_eq!(s.cancel_staged(), Ok(true)); | |
| assert_eq!(s.target.cancels, 1, "the target discarded it"); | |
| assert!(!s.tx_pending()); | |
| // The loss is reported once, with nothing staged, then sends go through. | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Discarded); | |
| assert_eq!(s.target.sent_len, 0, "nothing was staged"); | |
| assert!(!s.tx_pending()); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Ok); | |
| assert_eq!(&s.target.sent[..s.target.sent_len], b"second"); | |
| s.notify_response_read(); | |
| assert_eq!(send(&mut s, b"third"), I3cStatus::Ok, "reported once only"); | |
| } | |
| #[test] | |
| fn an_address_change_discards_the_unread_response_and_reports_it() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x08); | |
| assert_eq!(send_for(&mut s, 0x08, b"first"), I3cStatus::Ok); | |
| // The controller re-ran ENTDAA while the response was unread. | |
| s.target.addr = Some(0x1d); | |
| assert_eq!(send_for(&mut s, 0x1d, b"second"), I3cStatus::Discarded); | |
| assert_eq!(s.target.cancels, 1, "the stale response was cancelled"); | |
| assert!(!s.tx_pending()); | |
| // Reported once; the next Send is staged under the new address. | |
| assert_eq!(send_for(&mut s, 0x1d, b"second"), I3cStatus::Ok); | |
| assert_eq!(&s.target.sent[..s.target.sent_len], b"second"); | |
| assert_eq!( | |
| send_for(&mut s, 0x1d, b"third"), | |
| I3cStatus::Busy, | |
| "unread, address steady" | |
| ); | |
| } | |
| #[test] | |
| fn losing_the_address_discards_the_unread_response() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x08); | |
| assert_eq!(send_for(&mut s, 0x08, b"first"), I3cStatus::Ok); | |
| s.target.addr = None; // RSTDAA | |
| assert_eq!(send_for(&mut s, 0x08, b"second"), I3cStatus::Discarded); | |
| } | |
| #[test] | |
| fn an_address_change_after_the_response_was_read_is_not_a_discard() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x08); | |
| assert_eq!(send_for(&mut s, 0x08, b"first"), I3cStatus::Ok); | |
| s.notify_response_read(); | |
| s.target.addr = Some(0x1d); | |
| assert_eq!(send_for(&mut s, 0x1d, b"second"), I3cStatus::Ok); | |
| assert_eq!(s.target.cancels, 0); | |
| } | |
| #[test] | |
| fn a_frame_built_for_an_address_the_target_no_longer_has_is_not_staged() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x1d); | |
| // The client framed it for 0x08, read a moment earlier. | |
| assert_eq!(send_for(&mut s, 0x08, b"stale"), I3cStatus::AddressChanged); | |
| assert_eq!(s.target.sent_len, 0, "nothing was staged"); | |
| assert!(!s.tx_pending()); | |
| assert_eq!(s.target.cancels, 0, "there was nothing to cancel"); | |
| // Rebuilt for the current address, it goes through. | |
| assert_eq!(send_for(&mut s, 0x1d, b"fresh"), I3cStatus::Ok); | |
| // With no address at all, no frame can be right. | |
| s.notify_response_read(); | |
| s.target.addr = None; | |
| assert_eq!(send_for(&mut s, 0x1d, b"x"), I3cStatus::AddressChanged); | |
| } | |
| #[test] | |
| fn a_frame_not_tied_to_an_address_is_unaffected_by_address_changes() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x08); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| s.target.addr = Some(0x1d); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Busy, "not discarded"); | |
| assert_eq!(s.target.cancels, 0); | |
| assert_eq!( | |
| s.address_changed(), | |
| Ok(false), | |
| "nothing address-bound staged" | |
| ); | |
| s.notify_response_read(); | |
| s.target.addr = None; | |
| assert_eq!( | |
| send(&mut s, b"third"), | |
| I3cStatus::Ok, | |
| "not even with no address" | |
| ); | |
| } | |
| #[test] | |
| fn the_address_changed_event_discards_a_response_framed_for_an_address() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x08); | |
| assert_eq!(send_for(&mut s, 0x08, b"first"), I3cStatus::Ok); | |
| assert_eq!(s.address_changed(), Ok(true)); | |
| assert_eq!(s.target.cancels, 1); | |
| assert_eq!(send_for(&mut s, 0x08, b"second"), I3cStatus::Discarded); | |
| } | |
| #[test] | |
| fn a_send_with_no_address_byte_or_a_reserved_one_is_invalid() { | |
| let mut s = srv(); | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let rn = dispatch(&mut s, &[I3cOp::Send as u8], &mut resp); | |
| assert_eq!( | |
| decode_response(&resp[..rn]).unwrap().0, | |
| I3cStatus::InvalidOp | |
| ); | |
| assert_eq!(send_for(&mut s, 0x80, b"x"), I3cStatus::InvalidOp); | |
| assert_eq!(s.target.sent_len, 0); | |
| } | |
| #[test] | |
| fn a_response_that_was_read_is_never_reported_discarded() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| s.notify_response_read(); | |
| assert_eq!(s.cancel_staged(), Ok(false)); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Ok); | |
| } | |
| #[test] | |
| fn cancelling_with_nothing_staged_does_not_touch_the_target() { | |
| let mut s = srv(); | |
| assert_eq!(s.cancel_staged(), Ok(false)); | |
| assert_eq!(s.target.cancels, 0); | |
| // A response that was read is not staged any more either. | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| s.notify_response_read(); | |
| assert_eq!(s.cancel_staged(), Ok(false)); | |
| assert_eq!(s.target.cancels, 0); | |
| } | |
| #[test] | |
| fn send_sets_tx_pending_until_response_read() { | |
| let mut s = srv(); | |
| assert!(!s.tx_pending(), "nothing staged yet"); | |
| assert_eq!(send(&mut s, b"pong"), I3cStatus::Ok); | |
| assert!(s.tx_pending(), "a staged response is awaiting the read"); | |
| // The controller reads it; the runtime clears the flag. | |
| s.notify_response_read(); | |
| assert!(!s.tx_pending(), "back-pressure released after the read"); | |
| } | |
| /// `Send` a frame framed for `addr` (0: not tied to an address). | |
| fn send_for(s: &mut Server<FakeTarget>, addr: u8, frame: &[u8]) -> I3cStatus { | |
| let mut payload = [0u8; MAX_PAYLOAD + 1]; | |
| payload[0] = addr; | |
| payload[1..=frame.len()].copy_from_slice(frame); | |
| let mut req = [0u8; MAX_FRAME + 1]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let n = encode_request(I3cOp::Send, &payload[..=frame.len()], &mut req).unwrap(); | |
| let rn = dispatch(s, &req[..n], &mut resp); | |
| decode_response(&resp[..rn]).unwrap().0 | |
| } | |
| /// `Send` a frame that does not depend on the target's address. | |
| fn send(s: &mut Server<FakeTarget>, frame: &[u8]) -> I3cStatus { | |
| send_for(s, 0, frame) | |
| } | |
| #[test] | |
| fn second_send_is_busy_and_stages_nothing() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| // The first is still unread: the second is refused, and the target is | |
| // left holding the first, untouched. | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Busy); | |
| assert_eq!(&s.target.sent[..s.target.sent_len], b"first"); | |
| assert!(s.tx_pending(), "the first is still awaiting its read"); | |
| // Busy again on a retry before the read. | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Busy); | |
| } | |
| #[test] | |
| fn send_is_accepted_again_after_the_response_is_read() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Busy); | |
| s.notify_response_read(); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Ok); | |
| assert_eq!(&s.target.sent[..s.target.sent_len], b"second"); | |
| assert!(s.tx_pending(), "the second is now the unread one"); | |
| } | |
| #[test] | |
| fn an_inbound_frame_does_not_release_a_staged_send() { | |
| // Only the controller reading the response clears it. A new inbound | |
| // frame proves nothing: a controller may write again before it reads. | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| s.target.push_inbound(b"hello"); | |
| assert!(!drain(&mut s), "the frame is latched, not dropped"); | |
| assert!(s.has_frame()); | |
| assert!(s.tx_pending()); | |
| assert_eq!(send(&mut s, b"second"), I3cStatus::Busy); | |
| } | |
| #[test] | |
| fn oversize_send_is_too_long_even_while_busy() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, b"first"), I3cStatus::Ok); | |
| let mut req = [0u8; MAX_FRAME + 8]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| req[0] = I3cOp::Send as u8; | |
| let rn = dispatch(&mut s, &req[..HEADER + MAX_PAYLOAD + 1], &mut resp); | |
| assert_eq!(decode_response(&resp[..rn]).unwrap().0, I3cStatus::TooLong); | |
| } | |
| #[test] | |
| fn send_larger_than_the_targets_limit_is_too_long() { | |
| let mut s = srv(); | |
| s.target.send_limit = 8; | |
| // One byte over what the target can stage: refused before it reaches the | |
| // driver, and nothing is marked pending. | |
| assert_eq!(send(&mut s, &[0u8; 9]), I3cStatus::TooLong); | |
| assert_eq!(s.target.sent_len, 0, "nothing was staged"); | |
| assert!(!s.tx_pending()); | |
| // Exactly the limit is accepted. | |
| assert_eq!(send(&mut s, &[0u8; 8]), I3cStatus::Ok); | |
| assert_eq!(s.target.sent_len, 8); | |
| } | |
| #[test] | |
| fn a_frame_of_the_protocol_ceiling_is_accepted_when_the_target_allows_it() { | |
| let mut s = srv(); | |
| assert_eq!(send(&mut s, &[0xa5u8; MAX_SEND]), I3cStatus::Ok); | |
| assert_eq!(s.target.sent_len, MAX_SEND); | |
| } | |
| fn device_info(s: &mut Server<FakeTarget>) -> DeviceInfo { | |
| let mut req = [0u8; MAX_FRAME]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let n = encode_request(I3cOp::DeviceInfo, &[], &mut req).unwrap(); | |
| let rn = dispatch(s, &req[..n], &mut resp); | |
| let (status, body) = decode_response(&resp[..rn]).unwrap(); | |
| assert_eq!(status, I3cStatus::Ok); | |
| DeviceInfo::decode(body).expect("a device-info payload") | |
| } | |
| #[test] | |
| fn device_info_reports_the_targets_addresses_and_limits() { | |
| let mut s = srv(); | |
| s.target.addr = Some(0x08); | |
| s.target.static_addr = Some(0x30); | |
| s.target.send_limit = 100; | |
| s.target.recv_limit = 64; | |
| assert_eq!( | |
| device_info(&mut s), | |
| DeviceInfo { | |
| dynamic_address: Some(0x08), | |
| static_address: Some(0x30), | |
| max_send_len: 100, | |
| max_recv_len: 64, | |
| } | |
| ); | |
| } | |
| #[test] | |
| fn device_info_for_an_unassigned_target_has_no_addresses() { | |
| let mut s = srv(); | |
| let info = device_info(&mut s); | |
| assert_eq!((info.dynamic_address, info.static_address), (None, None)); | |
| } | |
| #[test] | |
| fn device_info_limits_are_clamped_to_the_frame_ceiling() { | |
| // A target claiming more than the ring slots and the wire frame hold is | |
| // reported at the ceiling, so a client never plans a frame that cannot fit. | |
| let mut s = srv(); | |
| s.target.send_limit = MAX_PAYLOAD + 100; | |
| s.target.recv_limit = usize::MAX; | |
| let info = device_info(&mut s); | |
| assert_eq!(info.max_send_len as usize, MAX_SEND); | |
| assert_eq!(info.max_recv_len as usize, MAX_PAYLOAD); | |
| } | |
| #[test] | |
| fn a_full_size_inbound_frame_arrives_intact() { | |
| // The controller can write up to the protocol ceiling; none of it may be | |
| // cut off on the way to the client. | |
| let mut s = srv(); | |
| let frame: [u8; MAX_PAYLOAD] = core::array::from_fn(|i| i as u8); | |
| s.target.push_inbound(&frame); | |
| assert!(!drain(&mut s), "the frame is latched, not dropped"); | |
| let (status, out, n) = recv_once(&mut s); | |
| assert_eq!(status, I3cStatus::Ok); | |
| assert_eq!(n, MAX_PAYLOAD); | |
| assert_eq!(out[..n], frame[..]); | |
| } | |
| #[test] | |
| fn ring_depth_is_a_parameter() { | |
| // A two-deep ring: the third frame overflows, the first two survive. | |
| let mut s: Server<FakeTarget, 2> = Server::with_ring(1, 2, FakeTarget::default()); | |
| for i in 0..3u8 { | |
| s.target.push_inbound(&[i]); | |
| } | |
| let mut dropped = 0; | |
| loop { | |
| match s.latch_inbound().expect("latch") { | |
| Inbound::Latched => {} | |
| Inbound::DroppedFull => dropped += 1, | |
| Inbound::Empty => break, | |
| } | |
| } | |
| assert_eq!(dropped, 1); | |
| assert!(s.has_frame()); | |
| let mut req = [0u8; MAX_FRAME]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let n = encode_request(I3cOp::Recv, &[], &mut req).unwrap(); | |
| for want in 0..2u8 { | |
| let rn = dispatch(&mut s, &req[..n], &mut resp); | |
| assert_eq!( | |
| decode_response(&resp[..rn]), | |
| Some((I3cStatus::Ok, &[want][..])) | |
| ); | |
| } | |
| assert!(!s.has_frame()); | |
| } | |
| #[test] | |
| fn recv_without_frame_is_nodata() { | |
| let mut s = srv(); | |
| let mut req = [0u8; MAX_FRAME]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let n = encode_request(I3cOp::Recv, &[], &mut req).unwrap(); | |
| let rn = dispatch(&mut s, &req[..n], &mut resp); | |
| assert_eq!( | |
| decode_response(&resp[..rn]), | |
| Some((I3cStatus::NoData, &[][..])) | |
| ); | |
| } | |
| /// Drive the runtime's drain loop against the fake target: latch until | |
| /// `Empty`, returning whether any overflow drop occurred. | |
| fn drain(s: &mut Server<FakeTarget>) -> bool { | |
| let mut dropped = false; | |
| loop { | |
| match s.latch_inbound() { | |
| Ok(Inbound::Latched) => continue, | |
| Ok(Inbound::DroppedFull) => dropped = true, | |
| Ok(Inbound::Empty) => break, | |
| Err(_) => panic!("read_frame failed"), | |
| } | |
| } | |
| dropped | |
| } | |
| fn recv_once(s: &mut Server<FakeTarget>) -> (I3cStatus, [u8; MAX_PAYLOAD], usize) { | |
| let mut req = [0u8; MAX_FRAME]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let n = encode_request(I3cOp::Recv, &[], &mut req).unwrap(); | |
| let rn = dispatch(s, &req[..n], &mut resp); | |
| let (status, body) = decode_response(&resp[..rn]).unwrap(); | |
| let mut out = [0u8; MAX_PAYLOAD]; | |
| out[..body.len()].copy_from_slice(body); | |
| (status, out, body.len()) | |
| } | |
| #[test] | |
| fn latch_then_recv_returns_frame_once() { | |
| let mut s = srv(); | |
| s.target.push_inbound(b"ping"); | |
| // Simulate the IRQ path draining the frame into the ring. | |
| assert_eq!(s.on_interrupt_event(), TargetEvent::InboundReady); | |
| assert_eq!(s.latch_inbound(), Ok(Inbound::Latched)); | |
| assert!(s.has_frame()); | |
| let (status, body, len) = recv_once(&mut s); | |
| assert_eq!((status, &body[..len]), (I3cStatus::Ok, &b"ping"[..])); | |
| assert!(!s.has_frame()); | |
| let (status, _, len) = recv_once(&mut s); | |
| assert_eq!((status, len), (I3cStatus::NoData, 0)); | |
| } | |
| #[test] | |
| fn ring_queues_multiple_frames_fifo() { | |
| let mut s = srv(); | |
| s.target.push_inbound(b"one"); | |
| s.target.push_inbound(b"two"); | |
| s.target.push_inbound(b"three"); | |
| assert!(!drain(&mut s), "three frames fit the ring, no drop"); | |
| assert!(s.has_frame()); | |
| for expect in [&b"one"[..], &b"two"[..], &b"three"[..]] { | |
| let (status, body, len) = recv_once(&mut s); | |
| assert_eq!((status, &body[..len]), (I3cStatus::Ok, expect)); | |
| } | |
| let (status, _, len) = recv_once(&mut s); | |
| assert_eq!((status, len), (I3cStatus::NoData, 0)); | |
| assert!(!s.has_frame()); | |
| } | |
| #[test] | |
| fn ring_full_drops_newest_keeps_queued() { | |
| let mut s = srv(); | |
| // Push two more than the ring holds; each frame's single-byte payload is | |
| // its index. The oldest RX_RING survive in order, the last two overflow. | |
| for i in 0..RX_RING + 2 { | |
| s.target.push_inbound(&[i as u8]); | |
| } | |
| assert!(drain(&mut s), "overflow must be reported as a drop"); | |
| for i in 0..RX_RING { | |
| let (status, body, len) = recv_once(&mut s); | |
| assert_eq!((status, &body[..len]), (I3cStatus::Ok, &[i as u8][..])); | |
| } | |
| let (status, _, len) = recv_once(&mut s); | |
| assert_eq!((status, len), (I3cStatus::NoData, 0)); | |
| } | |
| #[test] | |
| fn ring_wraps_around() { | |
| let mut s = srv(); | |
| // Fill most of the ring, drain some to advance head, then refill so the | |
| // tail wraps past the modulus. | |
| s.target.push_inbound(b"a"); | |
| s.target.push_inbound(b"b"); | |
| assert!(!drain(&mut s)); | |
| let (_, b, l) = recv_once(&mut s); // pop "a", head -> 1 | |
| assert_eq!(&b[..l], b"a"); | |
| s.target.push_inbound(b"c"); | |
| s.target.push_inbound(b"d"); | |
| s.target.push_inbound(b"e"); // tail wraps | |
| assert!(!drain(&mut s)); | |
| for expect in [&b"b"[..], &b"c"[..], &b"d"[..], &b"e"[..]] { | |
| let (status, body, len) = recv_once(&mut s); | |
| assert_eq!((status, &body[..len]), (I3cStatus::Ok, expect)); | |
| } | |
| let (status, _, len) = recv_once(&mut s); | |
| assert_eq!((status, len), (I3cStatus::NoData, 0)); | |
| } | |
| #[test] | |
| fn dynamic_address_reports_assignment() { | |
| let mut s = srv(); | |
| let mut req = [0u8; MAX_FRAME]; | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let n = encode_request(I3cOp::DynamicAddress, &[], &mut req).unwrap(); | |
| let rn = dispatch(&mut s, &req[..n], &mut resp); | |
| assert_eq!( | |
| decode_response(&resp[..rn]), | |
| Some((I3cStatus::Unassigned, &[][..])) | |
| ); | |
| s.target.addr = Some(0x42); | |
| let rn = dispatch(&mut s, &req[..n], &mut resp); | |
| assert_eq!( | |
| decode_response(&resp[..rn]), | |
| Some((I3cStatus::Ok, &[0x42][..])) | |
| ); | |
| } | |
| #[test] | |
| fn unknown_opcode_is_invalid() { | |
| let mut s = srv(); | |
| let mut resp = [0u8; MAX_FRAME]; | |
| let rn = dispatch(&mut s, &[0xFF], &mut resp); | |
| assert_eq!( | |
| decode_response(&resp[..rn]), | |
| Some((I3cStatus::InvalidOp, &[][..])) | |
| ); | |
| } | |
| // Test-only helper mirroring what the runtime reads from `on_interrupt`. | |
| impl Server<FakeTarget> { | |
| fn on_interrupt_event(&mut self) -> TargetEvent { | |
| self.target.on_interrupt().unwrap() | |
| } | |
| } | |
| } |