blob: 0fab76d9143da1b0c08a1bf27f89aacab8e5d37f [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! Pigweed server-runtime for an I3C target.
//!
//! Wraps the host-buildable [`i3c_server`] (target-owning `Server` + request
//! dispatch) in a `util_service::ServiceLoop`. A single IPC channel carries the
//! transport protocol ([`i3c_api`]); the I3C hardware IRQ is added to the loop
//! as a wake source, so a frame arriving on the bus and a client request are
//! both just events. The WaitGroup belongs to `util_service`; what a request
//! means belongs to the `Server`.
//!
//! ## Hot path
//!
//! - **IRQ** — the loop returns the I3C interrupt source; `on_interrupt` decodes
//! it. On `InboundReady` the runtime drains every available frame into the
//! server's ring, `interrupt_ack`s, and raises `USER` on the client channel so
//! a parked client wakes. On `ResponseRead` the staged transmit was consumed
//! by the controller, so the runtime lets the next `Send` through.
//! - **IPC** — the loop returns a request, already read; the runtime dispatches
//! it and replies. A `Recv` that consumes a frame also updates `USER`: it stays
//! asserted while frames remain and clears when the ring is empty; the IRQ path
//! re-raises it when the next frame lands.
//!
//! ## Outbound back-pressure
//!
//! A `Send` stages a response for the controller's next private read. Only one
//! can be staged at a time: a `Send` while the previous one is still unread is
//! answered `Busy` by `i3c_server::dispatch` and nothing is staged. The client
//! retries after the controller has read it. The only thing that releases the
//! next `Send` is `ResponseRead`, which the i3c target derives from the hardware
//! `TxDescComplete` interrupt. A new inbound frame does **not** release it: a
//! controller may write again before it reads. This is also how caliptra-mcu-sw's
//! I3C driver gates outbound data (`ErrorCode::BUSY`).
//!
//! A controller that never reads would leave `Busy` set for good. So the runtime
//! gives each staged response [`STAGED_RESPONSE_TIMEOUT_MS`](i3c_api::STAGED_RESPONSE_TIMEOUT_MS):
//! when that passes without a `ResponseRead` it discards the response in the
//! target ([`Server::cancel_staged`]), logs it, and accepts `Send` again. The
//! discarded message is lost, and the next `Send` is answered `Discarded` so the
//! client learns of it.
//!
//! A staged response is also discarded when the dynamic address changes, since
//! the client framed it (its PEC) for the old one: on an `AddressAssigned` or
//! `AddressLost` event here, and in `dispatch` for a target that never reports
//! them ([`Server::discard_if_address_moved`]).
//!
//! The **only** kernel-tagged crate in the i3c server path.
#![no_std]
use i3c_api::{decode_request, I3cOp, MAX_FRAME, STAGED_RESPONSE_TIMEOUT_MS};
use i3c_server::{dispatch, Inbound, Server};
use openprot_hal_blocking::i3c_hardware::{I3cTarget, TargetEvent};
use pw_status::Result;
use userspace::syscall::{self, Signals};
use userspace::time::{Clock, Duration, Instant, SystemClock};
use util_service::{Event, ServiceLoop};
pub use util_service::Channel;
/// How long a staged response may go unread. See
/// [`STAGED_RESPONSE_TIMEOUT_MS`].
const STAGED_TIMEOUT: Duration = Duration::from_millis(STAGED_RESPONSE_TIMEOUT_MS as u64);
/// What one entry of the [`Trace`] records.
mod kind {
/// The interrupt object woke the loop.
pub const IRQ: u8 = 1;
/// `on_interrupt` reported an inbound frame.
pub const INBOUND_READY: u8 = 2;
/// `on_interrupt` reported that the controller read the staged response.
pub const RESPONSE_READ: u8 = 3;
/// `on_interrupt` reported anything else.
pub const OTHER_EVENT: u8 = 4;
/// A frame was drained from the hardware into the ring; the argument is its length.
pub const LATCHED: u8 = 5;
/// A frame was drained and dropped because the ring was full.
pub const DROPPED: u8 = 6;
/// A client `Send` request; the argument is the request length.
pub const SEND: u8 = 7;
/// A client `Recv` request.
pub const RECV: u8 = 8;
/// Any other client request.
pub const OTHER_REQUEST: u8 = 9;
/// The staged-response deadline woke the loop.
pub const DEADLINE: u8 = 10;
}
/// How many events the [`Trace`] keeps.
const TRACE_LEN: usize = 24;
/// The last few things the server did, with the time of each, kept in memory and
/// printed only when the hardware reports a damaged frame.
///
/// A frame the core could not fit arrives cut short, and the question is when the
/// frame before it was drained. Logging each event as it happens would slow the
/// drain path being watched, so the events wait here until there is something to
/// explain.
struct Trace {
/// (clock ticks, kind, argument), as a ring.
events: [(u64, u8, u16); TRACE_LEN],
/// Where the next event goes.
next: usize,
/// How many of `events` are in use.
count: usize,
}
impl Trace {
const fn new() -> Self {
Self {
events: [(0, 0, 0); TRACE_LEN],
next: 0,
count: 0,
}
}
fn record(&mut self, kind: u8, arg: usize) {
let now = SystemClock::now().ticks();
if let Some(slot) = self.events.get_mut(self.next) {
*slot = (now, kind, u16::try_from(arg).unwrap_or(u16::MAX));
}
self.next = (self.next + 1) % TRACE_LEN;
self.count = (self.count + 1).min(TRACE_LEN);
}
/// Print the events, oldest first, each as clock ticks before now (20 ticks
/// are a microsecond on the FPGA), with the damaged frame's descriptor.
fn dump(&self, desc: u32) {
let now = SystemClock::now().ticks();
pw_log::error!(
"i3c rx error: desc=0x{:08x}; events, ticks before now, kind, arg;",
desc as u32
);
let start = (self.next + TRACE_LEN - self.count) % TRACE_LEN;
for i in 0..self.count {
if let Some(&(at, kind, arg)) = self.events.get((start + i) % TRACE_LEN) {
pw_log::error!(
" -{} k={} a={};",
now.wrapping_sub(at) as u32,
kind as u32,
arg as u32
);
}
}
}
}
/// Discard the staged response if its time is up. `deadline` is when the staged
/// response runs out of time to be read, and is cleared when it does.
fn discard_if_expired<T: I3cTarget, const RING: usize>(
srv: &mut Server<T, RING>,
deadline: &mut Option<Instant>,
) {
let Some(due) = *deadline else { return };
if SystemClock::now() < due {
return;
}
*deadline = None;
match srv.cancel_staged() {
Ok(true) => pw_log::error!("i3c staged response not read in time; discarded"),
Ok(false) => {}
Err(_) => pw_log::error!("i3c cancel_response failed"),
}
}
/// Run the I3C server loop until a fatal error.
///
/// Serves the one IPC channel `srv.channel` and wakes on `irq_signals` of
/// `srv.irq`.
///
/// # Errors
///
/// Only setup and WaitGroup failures return; anything that goes wrong with one
/// request or one interrupt is logged and the loop carries on.
pub fn run<T: I3cTarget, const RING: usize>(
wg: u32,
irq_signals: Signals,
srv: &mut Server<T, RING>,
) -> Result<()> {
if srv.target.enable().is_err() {
pw_log::error!("i3c target enable failed");
}
// The only thing that releases the next `Send` is `ResponseRead`, so the
// target must report it.
if srv.target.enable_response_read_events().is_err() {
pw_log::error!("i3c response-read events enable failed");
}
let mut channels = [Channel::new(srv.channel)];
let mut service = ServiceLoop::new(wg, &mut channels)?;
service.add_source(srv.irq, irq_signals)?;
let mut request_buf = [0u8; MAX_FRAME];
let mut response_buf = [0u8; MAX_FRAME];
// When the staged response, if any, runs out of time to be read.
let mut staged_deadline: Option<Instant> = None;
let mut trace = Trace::new();
loop {
// Check the clock here and not only through `next`'s deadline: `next`
// returns `Deadline` only when nothing else is ready, and a client
// retrying `Busy` faster than the scheduler tick always has a request
// ready, so the deadline would never be seen and the staged response
// never discarded.
discard_if_expired(srv, &mut staged_deadline);
match service.next(staged_deadline.unwrap_or(Instant::MAX), &mut request_buf)? {
// The staged response was not read in time: give up on it so the
// next `Send` is not refused for good.
Event::Deadline => {
trace.record(kind::DEADLINE, 0);
discard_if_expired(srv, &mut staged_deadline);
}
// ---- I3C hardware IRQ: decode, latch an inbound frame, wake client ----
Event::Source(_) => {
trace.record(kind::IRQ, 0);
match srv.target.on_interrupt() {
Ok(TargetEvent::InboundReady) => {
trace.record(kind::INBOUND_READY, 0);
// Drain every frame the IRQ covers into the ring; a single
// RX-descriptor interrupt can stand for more than one
// hardware frame. Stop on Empty.
let mut dropped = false;
loop {
match srv.latch_inbound() {
Ok(Inbound::Latched) => {
trace.record(kind::LATCHED, srv.newest_frame_len());
if let Some(desc) = srv.target.take_rx_error() {
trace.dump(desc);
}
continue;
}
Ok(Inbound::DroppedFull) => {
trace.record(kind::DROPPED, 0);
dropped = true;
continue;
}
Ok(Inbound::Empty) => break,
Err(_) => {
pw_log::error!("i3c read_frame failed");
break;
}
}
}
if dropped {
pw_log::error!("i3c inbound ring full; frame(s) dropped");
}
}
Ok(TargetEvent::ResponseRead) => {
trace.record(kind::RESPONSE_READ, 0);
// The controller read the staged response: the next
// `Send` can be staged.
srv.notify_response_read();
staged_deadline = None;
}
// A response framed for the old address would fail the
// controller's PEC check, so drop it. The next `Send` is
// told (`Discarded`).
Ok(TargetEvent::AddressAssigned(_) | TargetEvent::AddressLost) => {
match srv.address_changed() {
Ok(true) => {
pw_log::error!("i3c address changed; staged response discarded");
staged_deadline = None;
}
Ok(false) => {}
Err(_) => pw_log::error!("i3c cancel_response failed"),
}
}
Ok(_) => trace.record(kind::OTHER_EVENT, 0),
Err(_) => pw_log::error!("i3c on_interrupt failed"),
}
// The loop does not acknowledge a source, and the IRQ is level
// triggered, so ack it or `next` returns it again at once.
if syscall::interrupt_ack(srv.irq, irq_signals).is_err() {
pw_log::error!("interrupt_ack failed");
}
if srv.has_frame() {
// ORs USER onto the client channel without disturbing READABLE.
if syscall::object_set_peer_user_signal(srv.channel, true).is_err() {
pw_log::error!("object_set_peer_user_signal failed");
}
}
}
// ---- client IPC request ----
Event::Request { channel, len } => {
let request = request_buf.get(..len).unwrap_or(&[]);
let op = decode_request(request).map(|(op, _)| op);
let is_recv = op == Some(I3cOp::Recv);
trace.record(
match op {
Some(I3cOp::Send) => kind::SEND,
Some(I3cOp::Recv) => kind::RECV,
_ => kind::OTHER_REQUEST,
},
len,
);
let was_pending = srv.tx_pending();
let resp_len = dispatch(srv, request, &mut response_buf);
if !was_pending && srv.tx_pending() {
// This request staged a response: start its clock.
staged_deadline = Some(
SystemClock::now()
.checked_add_duration(STAGED_TIMEOUT)
.unwrap_or(Instant::MAX),
);
}
// A Recv pops one frame from the ring. Keep USER asserted while
// frames remain so the client drains the rest; clear it only when
// the ring is empty (the IRQ path re-raises it when the next frame
// arrives). A blind clear here would park the client with frames
// still queued.
if is_recv
&& syscall::object_set_peer_user_signal(srv.channel, srv.has_frame()).is_err()
{
pw_log::error!("object_set_peer_user_signal update failed");
}
if service
.reply(channel, response_buf.get(..resp_len).unwrap_or(&[]))
.is_err()
{
pw_log::error!("channel_respond failed");
}
}
}
}
}