blob: 084dc045c80bbfa4391cbf37e8564f071c6a9f54 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! Client for the i3c target service.
//!
//! `I3cClient<T>` turns the byte-oriented `i3c_api` frames into typed calls —
//! [`send`](I3cClient::send), [`recv`](I3cClient::recv) and
//! [`dynamic_address`](I3cClient::dynamic_address). All wire marshalling lives
//! here and is generic over [`Transport`]: the *same* encode/decode code runs
//! in production (`IpcTransport`, cross-process) and in host tests
//! (`LoopbackTransport`, in-process against a mock target).
//!
//! This crate has **no kernel/IPC dependency** and builds on the host — that
//! is what makes the encoders/decoders testable without a kernel.
#![no_std]
#![deny(missing_docs)]
use i3c_api::{
decode_response, encode_request, DeviceInfo, I3cOp, I3cStatus, Transport, TransportError,
MAX_FRAME, MAX_PAYLOAD, MAX_SEND,
};
/// Why a client call failed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ClientError {
/// The transport round-trip itself failed.
Transport(TransportError),
/// The previous response is still staged: the controller has not read it, so
/// nothing was staged for this `Send`. Try again later. Only `send` returns
/// this.
Busy,
/// An earlier staged response was discarded unread, so a message in
/// progress has lost a fragment. Nothing was staged for this `Send`; it is
/// reported once, and the next `send` is accepted. Only `send` returns this.
Discarded,
/// The target no longer has the address the frame was built for, so nothing
/// was staged: read the address again, rebuild the frame, send again. Only
/// `send_for` returns this.
AddressChanged,
/// The server returned a status this call does not treat as success.
///
/// `NoData`, `Unassigned` and `Busy` are *not* reported here — they are expected
/// outcomes and surface as `Ok(None)` from the calls that can see them.
Server(I3cStatus),
/// The response was empty, truncated, or carried an unknown status byte.
InvalidResponse,
/// The payload exceeds [`MAX_PAYLOAD`], or the caller's buffer is too
/// small for the response. One call is one frame; nothing is fragmented.
BufferTooSmall,
}
impl core::fmt::Display for ClientError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::Transport(e) => write!(f, "i3c transport error: {e}"),
Self::Busy => f.write_str("i3c server busy: the previous response is unread"),
Self::Discarded => f.write_str("i3c server discarded an unread response"),
Self::AddressChanged => f.write_str("i3c address changed since the frame was built"),
Self::Server(s) => write!(f, "i3c server error: {s:?}"),
Self::InvalidResponse => f.write_str("malformed i3c response"),
Self::BufferTooSmall => f.write_str("i3c frame exceeds one round-trip buffer"),
}
}
}
impl core::error::Error for ClientError {
fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
match self {
Self::Transport(e) => Some(e),
_ => None,
}
}
}
impl From<TransportError> for ClientError {
fn from(e: TransportError) -> Self {
Self::Transport(e)
}
}
/// Typed client for the i3c target service, generic over the transport.
pub struct I3cClient<T> {
transport: T,
}
impl<T: Transport> I3cClient<T> {
/// Bind the client to one transport (one i3c target).
pub const fn new(transport: T) -> Self {
Self { transport }
}
/// Borrow the underlying transport.
pub fn transport(&mut self) -> &mut T {
&mut self.transport
}
/// Perform one request/response round-trip, returning the status and the
/// decoded response body borrowed from `resp`.
///
/// The transport's mutable borrow of `resp` ends when it returns, so the
/// body can be handed back as an immutable slice with no copy.
fn transact<'r>(
&mut self,
op: I3cOp,
payload: &[u8],
resp: &'r mut [u8; MAX_FRAME],
) -> Result<(I3cStatus, &'r [u8]), ClientError> {
let mut req = [0u8; MAX_FRAME];
let req_len = encode_request(op, payload, &mut req).ok_or(ClientError::BufferTooSmall)?;
let req = req.get(..req_len).ok_or(ClientError::BufferTooSmall)?;
let resp_len = self.transport.transact(req, resp)?;
match resp
.get(..resp_len)
.and_then(decode_response)
.ok_or(ClientError::InvalidResponse)?
{
(I3cStatus::Busy, _) => Err(ClientError::Busy),
decoded => Ok(decoded),
}
}
/// Stage a frame that does not depend on the target's address.
///
/// See [`send_for`](Self::send_for), which this is with no address.
pub fn send(&mut self, frame: &[u8]) -> Result<(), ClientError> {
self.send_with(0, frame)
}
/// Stage a frame built for the dynamic address `addr`.
///
/// For a frame whose check covers the address byte, as an MCTP-over-I3C PEC
/// does. The server stages it only if the target still has `addr`, and
/// discards it if the address moves before the controller reads it. If the
/// address has already moved this returns `Err(ClientError::AddressChanged)`
/// with nothing staged: read the address again and rebuild the frame.
///
/// The target cannot initiate a transfer, so this stages a TX and raises an
/// IBI; the controller collects it with a private read. A frame over
/// [`MAX_SEND`] cannot be sent and returns [`ClientError::BufferTooSmall`].
///
/// Only one response is staged at a time. While the previous one has not
/// been read by the controller, nothing is staged and this returns
/// `Err(ClientError::Busy)`: retry later. If the server gave up on an unread
/// response in the meantime, the next call returns
/// `Err(ClientError::Discarded)` once, with nothing staged.
pub fn send_for(&mut self, addr: u8, frame: &[u8]) -> Result<(), ClientError> {
if addr == 0 {
// 0 means "no address" on the wire, so it cannot name one.
return Err(ClientError::Server(I3cStatus::InvalidOp));
}
self.send_with(addr, frame)
}
fn send_with(&mut self, addr: u8, frame: &[u8]) -> Result<(), ClientError> {
if frame.len() > MAX_SEND {
return Err(ClientError::BufferTooSmall);
}
let mut payload = [0u8; MAX_PAYLOAD];
let (head, body) = payload
.split_first_mut()
.ok_or(ClientError::BufferTooSmall)?;
*head = addr;
body.get_mut(..frame.len())
.ok_or(ClientError::BufferTooSmall)?
.copy_from_slice(frame);
let len = 1 + frame.len();
let mut resp = [0u8; MAX_FRAME];
let sent = payload.get(..len).ok_or(ClientError::BufferTooSmall)?;
match self.transact(I3cOp::Send, sent, &mut resp)? {
(I3cStatus::Ok, _) => Ok(()),
(I3cStatus::Discarded, _) => Err(ClientError::Discarded),
(I3cStatus::AddressChanged, _) => Err(ClientError::AddressChanged),
(status, _) => Err(ClientError::Server(status)),
}
}
/// Take the latched inbound frame, copying it into `buf`.
///
/// Returns `Ok(None)` when no frame is latched — the ordinary outcome of
/// polling an idle bus, not an error. A successful read consumes the frame.
///
/// `buf` must be at least [`MAX_PAYLOAD`] bytes. The server pops the frame
/// from its queue the instant it answers `Recv`, so a buffer too small to
/// hold it would lose it with no way to re-read; this is rejected *before*
/// the round-trip rather than after, leaving the frame queued.
pub fn recv(&mut self, buf: &mut [u8]) -> Result<Option<usize>, ClientError> {
if buf.len() < MAX_PAYLOAD {
return Err(ClientError::BufferTooSmall);
}
let mut resp = [0u8; MAX_FRAME];
match self.transact(I3cOp::Recv, &[], &mut resp)? {
(I3cStatus::NoData, _) => Ok(None),
(I3cStatus::Ok, body) => {
let n = body.len();
buf.get_mut(..n)
.ok_or(ClientError::BufferTooSmall)?
.copy_from_slice(body);
Ok(Some(n))
}
(status, _) => Err(ClientError::Server(status)),
}
}
/// Read back the 7-bit dynamic address the controller assigned.
///
/// Returns `Ok(None)` before ENTDAA has run. The address is assigned at
/// runtime and changes across a bus reset, so callers that embed it in a
/// wire header must re-read it rather than cache it indefinitely.
pub fn dynamic_address(&mut self) -> Result<Option<u8>, ClientError> {
let mut resp = [0u8; MAX_FRAME];
match self.transact(I3cOp::DynamicAddress, &[], &mut resp)? {
(I3cStatus::Unassigned, _) => Ok(None),
(I3cStatus::Ok, [addr]) => Ok(Some(*addr)),
(I3cStatus::Ok, _) => Err(ClientError::InvalidResponse),
(status, _) => Err(ClientError::Server(status)),
}
}
/// Read the target's addresses and transfer limits.
///
/// The limits are what one `send` and one received frame can carry; size
/// messages from them rather than assuming a number. They can change while
/// the target runs (a controller can set them), so ask again when they matter.
pub fn device_info(&mut self) -> Result<DeviceInfo, ClientError> {
let mut resp = [0u8; MAX_FRAME];
match self.transact(I3cOp::DeviceInfo, &[], &mut resp)? {
(I3cStatus::Ok, body) => DeviceInfo::decode(body).ok_or(ClientError::InvalidResponse),
(status, _) => Err(ClientError::Server(status)),
}
}
}