blob: e55e43663c6df56abfe4c82e7cd15bbc150ea3a7 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! I3C target IPC transport protocol.
//!
//! The wire contract between the i3c server-runtime (which owns the
//! [`I3cTarget`](openprot_hal_blocking::i3c_hardware::I3cTarget) facade) and
//! any client process that speaks to it over a Pigweed channel. A consumer such
//! as an MCTP binding sits on top of the client.
//!
//! Both directions are a single opcode/status byte followed by an optional
//! payload; there is one operation per whole request. This crate is
//! host-buildable and kernel-free: the marshalling is verified in host tests,
//! and the server-runtime and client only supply the syscalls.
//!
//! ```text
//! request : [op: u8][payload …]
//! response: [status: u8][payload …]
//! ```
#![no_std]
// The transport seam is the shared one in //util/transport: one whole serialized
// request in, one whole response out. `I3cClient` (in `i3c-client`) is generic
// over it, so swapping `IpcTransport` (in `i3c-client-ipc`, the cross-process
// path) for `LoopbackTransport` (in `i3c-server`, an in-process call to
// `dispatch`) is a wiring choice, never a code fork.
pub use util_transport::{Transport, TransportError};
/// Largest message payload carried in one request or response: the service's
/// protocol ceiling.
///
/// A frame from the controller is at most 256 bytes on the hardware this was
/// written against (a 64-DWORD FIFO), so the ceiling is 256; it sizes the wire
/// frame, every inbound ring slot, and the client buffers. A target that can
/// stage less reports a smaller limit through `I3cTarget::max_send_len`, which
/// `dispatch` enforces, and an inbound frame must never exceed this ceiling.
pub const MAX_PAYLOAD: usize = 256;
/// Largest frame one `Send` can carry: [`MAX_PAYLOAD`] less the address byte that
/// leads a `Send` payload (see [`I3cOp::Send`]).
pub const MAX_SEND: usize = MAX_PAYLOAD - 1;
/// Size of the one-byte opcode/status header on each frame.
pub const HEADER: usize = 1;
/// Largest whole frame (header + payload) in either direction.
pub const MAX_FRAME: usize = HEADER + MAX_PAYLOAD;
/// How long the service keeps a staged response that the controller has not
/// read, in milliseconds.
///
/// Only one response is staged at a time and a `Send` is `Busy` until it is
/// read. A controller that never reads would block every later `Send`, so after
/// this long the server discards the staged response and accepts `Send` again.
/// The discarded message is lost, and the next `Send` is answered
/// [`I3cStatus::Discarded`] once so the client learns of it. A client that
/// retries on `Busy` has to keep retrying for longer than this to get through
/// after such a stall.
///
/// It is much longer than a controller takes to read after an IBI, and shorter
/// than the MCTP reassembly timeout (about 6 s).
pub const STAGED_RESPONSE_TIMEOUT_MS: u32 = 1000;
/// Operation a client asks the i3c server to perform.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum I3cOp {
/// Transmit a frame to the controller (staged TX + IBI). At most one
/// response is staged at a time: a `Send` while one is still unread by the
/// controller is answered with [`I3cStatus::Busy`].
///
/// The payload is `[framed_for: u8][frame...]`, the frame at most
/// [`MAX_SEND`] bytes. `framed_for` is the 7-bit dynamic address the client
/// built the frame for, or 0 if the frame does not depend on the address
/// (0x00 is reserved on an I3C bus). A frame whose check covers the address
/// byte, as an MCTP-over-I3C PEC does, is wrong once the address moves, so
/// the server stages it only if the target still has that address and
/// answers [`I3cStatus::AddressChanged`] if not. It also discards the staged
/// response if the address moves before the controller reads it.
Send = 0,
/// Return the latched inbound frame, or `NoData` if none is pending.
Recv = 1,
/// Return the assigned 7-bit dynamic address, or `Unassigned`.
DynamicAddress = 2,
/// Return the target's addresses and transfer limits as a [`DeviceInfo`].
DeviceInfo = 3,
}
impl I3cOp {
/// Decode an opcode byte.
pub const fn from_u8(value: u8) -> Option<Self> {
match value {
0 => Some(Self::Send),
1 => Some(Self::Recv),
2 => Some(Self::DynamicAddress),
3 => Some(Self::DeviceInfo),
_ => None,
}
}
}
/// Size of the [`DeviceInfo`] payload.
pub const DEVICE_INFO_LEN: usize = 6;
/// A target's addresses and transfer limits, as `I3cOp::DeviceInfo` returns them.
///
/// The limits are what the target can carry in one transfer, already clamped to
/// the service's frame ceiling ([`MAX_PAYLOAD`]), so a client can size a message
/// from them directly: the most it can `Send`, and the most it will `Recv`. They
/// can change while the target runs (a controller can set them), so ask again
/// when they matter.
///
/// ```text
/// [dynamic: u8][static: u8][max_send: u16 LE][max_recv: u16 LE]
/// ```
///
/// Address 0 means "none": 0x00 is reserved on an I3C bus, so it cannot be a
/// real address.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DeviceInfo {
/// The dynamic address currently assigned, if any.
pub dynamic_address: Option<u8>,
/// The static address the target answers on before assignment, if any.
pub static_address: Option<u8>,
/// The most bytes one `Send` can carry.
pub max_send_len: u16,
/// The most bytes one received frame can carry.
pub max_recv_len: u16,
}
impl DeviceInfo {
/// Encode into `buf`, returning the length ([`DEVICE_INFO_LEN`]), or `None`
/// if `buf` is too small.
pub fn encode(&self, buf: &mut [u8]) -> Option<usize> {
let out = buf.get_mut(..DEVICE_INFO_LEN)?;
out[0] = self.dynamic_address.unwrap_or(0);
out[1] = self.static_address.unwrap_or(0);
out[2..4].copy_from_slice(&self.max_send_len.to_le_bytes());
out[4..6].copy_from_slice(&self.max_recv_len.to_le_bytes());
Some(DEVICE_INFO_LEN)
}
/// Decode a payload of exactly [`DEVICE_INFO_LEN`] bytes.
pub fn decode(payload: &[u8]) -> Option<Self> {
let &[dynamic, stat, send_lo, send_hi, recv_lo, recv_hi] = payload else {
return None;
};
let addr = |a: u8| if a == 0 { None } else { Some(a) };
Some(Self {
dynamic_address: addr(dynamic),
static_address: addr(stat),
max_send_len: u16::from_le_bytes([send_lo, send_hi]),
max_recv_len: u16::from_le_bytes([recv_lo, recv_hi]),
})
}
}
/// Result byte the server returns for a request.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum I3cStatus {
/// Success; any payload follows.
Ok = 0,
/// `Recv` with no inbound frame latched.
NoData = 1,
/// `DynamicAddress` before the controller has assigned one.
Unassigned = 2,
/// A `Send` frame exceeded [`MAX_SEND`], or what the target can stage.
TooLong = 3,
/// The facade reported a hardware error.
Internal = 4,
/// Opcode byte was unknown or the frame was empty.
InvalidOp = 5,
/// `Send` while the previous staged response has not been read by the
/// controller yet. Nothing was staged; retry once the controller has read it.
Busy = 6,
/// `Send` refused, with nothing staged, because the server discarded an
/// earlier staged response the controller never read (see
/// [`STAGED_RESPONSE_TIMEOUT_MS`]). Reported once per discard, to the first
/// `Send` after it, so a sender can tell that a message it was still
/// sending has lost a fragment. Sending again is accepted.
Discarded = 7,
/// `Send` named a `framed_for` address the target no longer has (the
/// controller re-ran ENTDAA, or revoked it). Nothing was staged. The client
/// reads the address again, builds the frame for it, and sends again.
AddressChanged = 8,
}
impl I3cStatus {
/// Decode a status byte.
pub const fn from_u8(value: u8) -> Option<Self> {
match value {
0 => Some(Self::Ok),
1 => Some(Self::NoData),
2 => Some(Self::Unassigned),
3 => Some(Self::TooLong),
4 => Some(Self::Internal),
5 => Some(Self::InvalidOp),
6 => Some(Self::Busy),
7 => Some(Self::Discarded),
8 => Some(Self::AddressChanged),
_ => None,
}
}
}
/// Encode a request into `buf`, returning the frame length.
///
/// Fails if `payload` exceeds [`MAX_PAYLOAD`] or `buf` is too small.
pub fn encode_request(op: I3cOp, payload: &[u8], buf: &mut [u8]) -> Option<usize> {
if payload.len() > MAX_PAYLOAD || buf.len() < HEADER + payload.len() {
return None;
}
let (head, body) = buf.split_first_mut()?;
*head = op as u8;
body.get_mut(..payload.len())?.copy_from_slice(payload);
Some(HEADER + payload.len())
}
/// Decode a request frame into its opcode and payload slice.
pub fn decode_request(frame: &[u8]) -> Option<(I3cOp, &[u8])> {
let (&head, body) = frame.split_first()?;
Some((I3cOp::from_u8(head)?, body))
}
/// Encode a response into `buf`, returning the frame length.
///
/// Fails if `payload` exceeds [`MAX_PAYLOAD`] or `buf` is too small.
pub fn encode_response(status: I3cStatus, payload: &[u8], buf: &mut [u8]) -> Option<usize> {
if payload.len() > MAX_PAYLOAD || buf.len() < HEADER + payload.len() {
return None;
}
let (head, body) = buf.split_first_mut()?;
*head = status as u8;
body.get_mut(..payload.len())?.copy_from_slice(payload);
Some(HEADER + payload.len())
}
/// Decode a response frame into its status and payload slice.
pub fn decode_response(frame: &[u8]) -> Option<(I3cStatus, &[u8])> {
let (&head, body) = frame.split_first()?;
Some((I3cStatus::from_u8(head)?, body))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn op_round_trip() {
for op in [
I3cOp::Send,
I3cOp::Recv,
I3cOp::DynamicAddress,
I3cOp::DeviceInfo,
] {
assert_eq!(I3cOp::from_u8(op as u8), Some(op));
}
assert_eq!(I3cOp::from_u8(4), None);
}
#[test]
fn status_round_trip() {
for st in [
I3cStatus::Ok,
I3cStatus::NoData,
I3cStatus::Unassigned,
I3cStatus::TooLong,
I3cStatus::Internal,
I3cStatus::InvalidOp,
I3cStatus::Busy,
I3cStatus::Discarded,
I3cStatus::AddressChanged,
] {
assert_eq!(I3cStatus::from_u8(st as u8), Some(st));
}
assert_eq!(I3cStatus::from_u8(9), None);
}
#[test]
fn request_encode_decode() {
let mut buf = [0u8; MAX_FRAME];
let n = encode_request(I3cOp::Send, b"ping", &mut buf).unwrap();
assert_eq!(n, HEADER + 4);
assert_eq!(decode_request(&buf[..n]), Some((I3cOp::Send, &b"ping"[..])));
let n = encode_request(I3cOp::Recv, &[], &mut buf).unwrap();
assert_eq!(decode_request(&buf[..n]), Some((I3cOp::Recv, &[][..])));
}
#[test]
fn response_encode_decode() {
let mut buf = [0u8; MAX_FRAME];
let n = encode_response(I3cStatus::Ok, b"pong", &mut buf).unwrap();
assert_eq!(
decode_response(&buf[..n]),
Some((I3cStatus::Ok, &b"pong"[..]))
);
let n = encode_response(I3cStatus::NoData, &[], &mut buf).unwrap();
assert_eq!(
decode_response(&buf[..n]),
Some((I3cStatus::NoData, &[][..]))
);
}
#[test]
fn oversize_payload_rejected() {
let big = [0u8; MAX_PAYLOAD + 1];
let mut buf = [0u8; MAX_FRAME + 8];
assert_eq!(encode_request(I3cOp::Send, &big, &mut buf), None);
assert_eq!(encode_response(I3cStatus::Ok, &big, &mut buf), None);
}
#[test]
fn device_info_round_trips() {
let info = DeviceInfo {
dynamic_address: Some(0x08),
static_address: Some(0x30),
max_send_len: 256,
max_recv_len: 64,
};
let mut buf = [0u8; 8];
assert_eq!(info.encode(&mut buf), Some(DEVICE_INFO_LEN));
assert_eq!(
&buf[..DEVICE_INFO_LEN],
&[0x08, 0x30, 0x00, 0x01, 0x40, 0x00]
);
assert_eq!(DeviceInfo::decode(&buf[..DEVICE_INFO_LEN]), Some(info));
}
#[test]
fn device_info_zero_address_means_none() {
let mut buf = [0u8; DEVICE_INFO_LEN];
let info = DeviceInfo {
dynamic_address: None,
static_address: None,
max_send_len: 1,
max_recv_len: 2,
};
info.encode(&mut buf).unwrap();
assert_eq!(&buf[..2], &[0, 0]);
assert_eq!(DeviceInfo::decode(&buf), Some(info));
}
#[test]
fn device_info_rejects_the_wrong_length() {
let mut small = [0u8; DEVICE_INFO_LEN - 1];
assert_eq!(DeviceInfo::decode(&small), None);
assert_eq!(DeviceInfo::decode(&[0u8; DEVICE_INFO_LEN + 1]), None);
let info = DeviceInfo {
dynamic_address: None,
static_address: None,
max_send_len: 0,
max_recv_len: 0,
};
assert_eq!(info.encode(&mut small), None);
}
#[test]
fn empty_frame_is_none() {
assert_eq!(decode_request(&[]), None);
assert_eq!(decode_response(&[]), None);
}
}