blob: 62093d701543f6081a05a94cbc8e717189c1f9f5 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! MCTP control protocol responder (message type `0x00`).
//!
//! This crate holds no transport. The caller registers the listener, receives
//! each request, calls [`ControlResponder::handle`], and sends the bytes
//! `handle` wrote when it returns `Ok`.
//!
//! Clause, table, and figure numbers in this crate refer to DSP0236 1.3.1.
//!
//! # Examples
//!
//! ```
//! use mctp_lib::config;
//! use openprot_mctp_api::{MctpClient, MctpError, Stack};
//! use openprot_mctp_control::{
//! ControlConfig, ControlResponder, MAX_RESPONSE_LEN,
//! MCTP_MSG_TYPE_CONTROL,
//! };
//!
//! fn serve<C: MctpClient>(stack: &Stack<C>) -> Result<(), MctpError> {
//! use openprot_mctp_api::{MctpListener, MctpRespChannel};
//!
//! let responder = ControlResponder::try_new(ControlConfig::simple_endpoint(&[]))
//! .expect("an empty type list and the 1.3.1 tables fit");
//! let mut listener = stack.listener(MCTP_MSG_TYPE_CONTROL, 0)?;
//! let mut request_buf = [0u8; config::MAX_PAYLOAD];
//! let mut response_buf = [0u8; MAX_RESPONSE_LEN];
//!
//! loop {
//! let (_meta, request, mut reply) = listener.recv(&mut request_buf)?;
//! let handled = responder.handle(stack, request, &mut response_buf);
//! // `Ok(None)` and an error each leave no reply to send.
//! if let Ok(Some(len)) = handled {
//! reply.send(&response_buf[..len])?;
//! }
//! }
//! }
//! ```
#![no_std]
#![deny(missing_docs)]
use mctp::Eid;
use mctp_lib::mctp_control::{
CommandCode, CompletionCode, EidAllocationStatus, EidAssignmentStatus, EidType, EndpointType,
GetEndpointIDResponse, GetMCTPVersionSupportResponse, GetMctpMessageTypeSupportResponse,
MctpCodec, MctpControlHeader, MctpMessageType, SetEndpointIdResponse,
};
use openprot_mctp_api::{MctpClient, Stack};
use pw_status::Error;
use util_error::{ErrorCode, ErrorModule};
/// The MCTP message type that carries the control protocol (DSP0236, Table 3).
pub const MCTP_MSG_TYPE_CONTROL: u8 = 0x00;
/// The MCTP control responder error module.
pub const MCTP_CONTROL: ErrorModule = ErrorModule::new(0x4d43); // ascii `MC`
/// The request is too short to carry a control header.
pub const MCTP_CONTROL_MALFORMED: ErrorCode = MCTP_CONTROL.from_pw(1, Error::InvalidArgument);
/// The response buffer cannot hold the reply; see [`MAX_RESPONSE_LEN`].
pub const MCTP_CONTROL_RESPONSE_TOO_SHORT: ErrorCode =
MCTP_CONTROL.from_pw(2, Error::ResourceExhausted);
/// A version table is not whole 4-byte codes or holds more than
/// [`MAX_VERSION_CODES`].
pub const MCTP_CONTROL_BAD_VERSION_TABLE: ErrorCode =
MCTP_CONTROL.from_pw(3, Error::InvalidArgument);
/// The message type list holds more than [`MAX_MSG_TYPES`] entries.
pub const MCTP_CONTROL_TOO_MANY_MSG_TYPES: ErrorCode =
MCTP_CONTROL.from_pw(4, Error::InvalidArgument);
/// The static EID is one no endpoint may hold (DSP0236, Table 14).
pub const MCTP_CONTROL_ILLEGAL_EID: ErrorCode = MCTP_CONTROL.from_pw(5, Error::InvalidArgument);
/// The stack refused to take the static EID.
pub const MCTP_CONTROL_SET_EID_FAILED: ErrorCode = MCTP_CONTROL.from_pw(6, Error::Unavailable);
/// A message type entry is control itself, past 7 bits, or listed twice.
pub const MCTP_CONTROL_BAD_MSG_TYPE: ErrorCode = MCTP_CONTROL.from_pw(7, Error::InvalidArgument);
/// Byte length of one 32-bit version code (DSP0236, clause 12.6.1).
pub const VERSION_CODE_LEN: usize = 4;
/// Response buffer size that fits every reply a valid [`ControlConfig`] draws.
///
/// The longest reply is Get Message Type Support for [`MAX_MSG_TYPES`] types.
pub const MAX_RESPONSE_LEN: usize = 2 + 2 + MAX_MSG_TYPES;
/// Largest message type count Get Message Type Support can report.
///
/// Clause 11.4 limits a control message to one packet whose payload fits the
/// 64-byte baseline transmission unit. The message type byte, the two-byte
/// control header, the completion code, and the count leave 59 bytes.
pub const MAX_MSG_TYPES: usize = 64 - 5;
/// Largest version-code count a requester using `mctp-lib` can decode.
///
/// Both constructors refuse a longer table.
pub const MAX_VERSION_CODES: usize = 8;
/// Version codes for MCTP base specification 1.3.1 (DSP0236, clause 12.6.2).
pub const BASE_VERSIONS_1_3_1: [u8; 16] = [
0xf1, 0xf0, 0xff, 0x00, // 1.0, any update, no alpha
0xf1, 0xf1, 0xff, 0x00, // 1.1, any update, no alpha
0xf1, 0xf2, 0xff, 0x00, // 1.2, any update, no alpha
0xf1, 0xf3, 0xf1, 0x00, // 1.3.1, no alpha
];
/// Version codes for the MCTP control protocol (DSP0236, clause 12.6.3).
pub const CONTROL_VERSIONS_1_3_1: [u8; 16] = BASE_VERSIONS_1_3_1;
/// One message type this endpoint answers, with its binding versions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MsgTypeVersions<'a> {
/// The message type number (DSP0236, Table 3).
pub msg_type: u8,
/// Version codes Get MCTP Version Support reports for this type, 4 bytes
/// per entry, lowest first.
///
/// Table 18 reports the binding specification's version where the type
/// has one, as DSP0241 for PLDM, rather than the protocol's own.
pub versions: &'a [u8],
}
/// What one endpoint reports about itself.
///
/// The binary's `main` fills this in, since only it knows the image's
/// message types and endpoint role.
#[derive(Debug, Clone, Copy)]
pub struct ControlConfig<'a> {
/// Message types this endpoint answers besides control.
///
/// Get Message Type Support lists each `msg_type` (DSP0236, Table 19), and
/// Get MCTP Version Support answers each with its `versions`, so listing a
/// type commits the image to answering both for it.
pub msg_types: &'a [MsgTypeVersions<'a>],
/// Version codes for the MCTP base specification, 4 bytes per entry.
pub base_versions: &'a [u8],
/// Version codes for the control protocol, 4 bytes per entry.
pub control_versions: &'a [u8],
/// Endpoint role Get Endpoint ID reports (DSP0236, Table 15).
pub endpoint_type: EndpointType,
/// Medium-specific byte Get Endpoint ID returns (DSP0236, Table 15).
///
/// Table 15 requires `0x00` unless the transport binding defines a value.
/// On SMBus/I2C, DSP0237 1.2.0 Table 4 defines bit 0 as fairness
/// arbitration support, and [`Self::simple_endpoint`] sets `0` because
/// this stack does not implement fairness arbitration.
pub transport_specific: u8,
}
impl<'a> ControlConfig<'a> {
/// Build a configuration for a simple endpoint reporting MCTP 1.3.1.
///
/// The [`ControlResponder`] constructor decides whether the EID is static
/// or dynamic.
pub const fn simple_endpoint(msg_types: &'a [MsgTypeVersions<'a>]) -> Self {
Self {
msg_types,
base_versions: &BASE_VERSIONS_1_3_1,
control_versions: &CONTROL_VERSIONS_1_3_1,
endpoint_type: EndpointType::SimpleEndpoint,
transport_specific: 0,
}
}
}
/// The Set Endpoint ID operation a request selected (DSP0236, Table 14).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SetEidOperation {
/// Assign the given EID (operation `00b`).
SetEid(u8),
/// Assign the given EID regardless of the tracked bus (operation `01b`).
ForceEid(u8),
/// Restore the statically configured EID (operation `10b`).
ResetEid,
/// Set the discovered flag and leave the EID alone (operation `11b`).
SetDiscoveredFlag,
}
/// Answers MCTP control requests for one endpoint.
///
/// The endpoint's current EID lives in the MCTP stack rather than here, so the
/// two cannot drift.
#[derive(Debug, Clone, Copy)]
pub struct ControlResponder<'a> {
config: ControlConfig<'a>,
static_eid: Option<u8>,
}
impl<'a> ControlResponder<'a> {
/// Create a responder for a dynamic endpoint, holding no configured EID.
///
/// # Errors
///
/// Returns [`MCTP_CONTROL_BAD_VERSION_TABLE`],
/// [`MCTP_CONTROL_TOO_MANY_MSG_TYPES`], or [`MCTP_CONTROL_BAD_MSG_TYPE`]
/// for a `config` whose replies `mctp-lib` cannot encode or decode, or
/// that no packet can carry.
pub const fn try_new(config: ControlConfig<'a>) -> Result<Self, ErrorCode> {
if let Err(e) = check_config(&config) {
return Err(e);
}
Ok(Self {
config,
static_eid: None,
})
}
/// Create a responder for an endpoint configured with a static EID.
///
/// The constructor writes that EID to the stack. DSP0236 clause 12.3 makes
/// the configured value the endpoint's initial default, so the stack must
/// hold it before the first request arrives. Reset EID restores it.
///
/// # Errors
///
/// Returns the error [`Self::try_new`] returns for `config`,
/// [`MCTP_CONTROL_ILLEGAL_EID`] for an EID no endpoint may hold, or
/// [`MCTP_CONTROL_SET_EID_FAILED`] where the stack refuses the write.
pub fn try_new_with_static_eid<C: MctpClient>(
stack: &Stack<C>,
config: ControlConfig<'a>,
static_eid: u8,
) -> Result<Self, ErrorCode> {
check_config(&config)?;
if !is_legal_eid(static_eid) {
return Err(MCTP_CONTROL_ILLEGAL_EID);
}
stack
.set_eid(static_eid)
.map_err(|_| MCTP_CONTROL_SET_EID_FAILED)?;
Ok(Self {
config,
static_eid: Some(static_eid),
})
}
/// Answer one control request.
///
/// `request` is the payload a receive call produced and `response` takes
/// the reply, both including the control header. Returns the reply length,
/// or `None` for a response or a datagram, which draws no reply (DSP0236,
/// clause 11.5).
///
/// # Errors
///
/// Returns [`MCTP_CONTROL_MALFORMED`] or
/// [`MCTP_CONTROL_RESPONSE_TOO_SHORT`]. Either means `response` holds no
/// reply to send, so the caller sends nothing. An unsupported command is
/// not an error: it answers `ERROR_UNSUPPORTED_CMD`.
pub fn handle<C: MctpClient>(
&self,
stack: &Stack<C>,
request: &[u8],
response: &mut [u8],
) -> Result<Option<usize>, ErrorCode> {
let header = MctpControlHeader::decode(request).map_err(|_| MCTP_CONTROL_MALFORMED)?;
let body = request
.get(MctpControlHeader::MCTP_CODEC_MIN_SIZE..)
.ok_or(MCTP_CONTROL_MALFORMED)?;
// No requester waits for a reply here.
if !header.request || header.datagram {
return Ok(None);
}
let reply_header = MctpControlHeader::new(
/* request= */ false,
/* datagram= */ false,
header.instance_id,
header.command_code,
);
let header_len = reply_header
.encode(response)
.map_err(|_| MCTP_CONTROL_RESPONSE_TOO_SHORT)?;
let body_buf = response
.get_mut(header_len..)
.ok_or(MCTP_CONTROL_RESPONSE_TOO_SHORT)?;
let body_len = self.encode_body(stack, header.command_code, body, body_buf)?;
Ok(Some(header_len + body_len))
}
fn encode_body<C: MctpClient>(
&self,
stack: &Stack<C>,
command: CommandCode,
body: &[u8],
out: &mut [u8],
) -> Result<usize, ErrorCode> {
match command {
CommandCode::SetEndpointID => self.set_endpoint_id(stack, body, out),
CommandCode::GetEndpointID => self.get_endpoint_id(stack, body, out),
CommandCode::GetMCTPVersionSupport => self.version_support(body, out),
CommandCode::GetMessageTypeSupport => self.message_type_support(body, out),
_ => encode_error(CompletionCode::ErrorUnsupportedCmd, out),
}
}
fn set_endpoint_id<C: MctpClient>(
&self,
stack: &Stack<C>,
body: &[u8],
out: &mut [u8],
) -> Result<usize, ErrorCode> {
let Some(operation) = decode_set_eid(body) else {
return encode_error(CompletionCode::ErrorInvalidLength, out);
};
let eid = match operation {
// DSP0236 Table 14 makes Force EID equivalent to Set EID on an
// endpoint reached through one bus.
SetEidOperation::SetEid(eid) | SetEidOperation::ForceEid(eid) if is_legal_eid(eid) => {
eid
}
SetEidOperation::SetEid(_) | SetEidOperation::ForceEid(_) => {
return encode_error(CompletionCode::ErrorInvalidData, out);
}
SetEidOperation::ResetEid => match self.static_eid {
Some(configured) => configured,
None => return encode_error(CompletionCode::ErrorInvalidData, out),
},
// The discovered flag serves some transport bindings only, and
// this crate keeps no such flag.
SetEidOperation::SetDiscoveredFlag => {
return encode_error(CompletionCode::ErrorInvalidData, out);
}
};
// The reply is encoded first, so a buffer too short for it fails
// before the stack moves. The write then lands before `handle`
// returns, so the reply leaves from the address just assigned.
let len = SetEndpointIdResponse::new(
CompletionCode::Success,
EidAssignmentStatus::Accepted,
EidAllocationStatus::NoEidPoolUsed,
Eid(eid),
0,
)
.encode(out)
.map_err(|_| MCTP_CONTROL_RESPONSE_TOO_SHORT)?;
// The EID passed `is_legal_eid`, so a refusal is this endpoint's own
// failure, which DSP0236 Table 13 answers with the generic ERROR.
if stack.set_eid(eid).is_err() {
return encode_error(CompletionCode::Error, out);
}
Ok(len)
}
fn get_endpoint_id<C: MctpClient>(
&self,
stack: &Stack<C>,
body: &[u8],
out: &mut [u8],
) -> Result<usize, ErrorCode> {
// DSP0236 Table 15's request carries no data.
if !body.is_empty() {
return encode_error(CompletionCode::ErrorInvalidLength, out);
}
let current = stack.get_eid();
let response = GetEndpointIDResponse::new(
CompletionCode::Success,
Eid(current),
self.config.endpoint_type,
self.eid_type(current),
self.config.transport_specific,
);
response
.encode(out)
.map_err(|_| MCTP_CONTROL_RESPONSE_TOO_SHORT)
}
/// Which Endpoint ID Type value [`Self::get_endpoint_id`] reports.
///
/// DSP0236 Table 15 recommends the matches-or-differs pair wherever an
/// endpoint supports Reset EID, and a static endpoint here supports it.
fn eid_type(&self, current: u8) -> EidType {
match self.static_eid {
None => EidType::DynamicEid,
Some(configured) if configured == current => EidType::StaticEidConfigured,
Some(_) => EidType::StaticEidAvailable,
}
}
fn version_support(&self, body: &[u8], out: &mut [u8]) -> Result<usize, ErrorCode> {
// DSP0236 Table 18's request carries exactly one byte.
let &[raw] = body else {
return encode_error(CompletionCode::ErrorInvalidLength, out);
};
let codes = match MctpMessageType::from(raw) {
MctpMessageType::Mctp => self.config.base_versions,
MctpMessageType::Control => self.config.control_versions,
_ => match self.msg_type_versions(raw) {
Some(versions) => versions,
// 0x80 is Table 18's "message type number not supported".
None => return encode_error(CompletionCode::CommandSpecific(0x80), out),
},
};
let response = GetMCTPVersionSupportResponse::new(CompletionCode::Success, codes);
response
.encode(out)
.map_err(|_| MCTP_CONTROL_RESPONSE_TOO_SHORT)
}
fn msg_type_versions(&self, msg_type: u8) -> Option<&'a [u8]> {
let entries = self.config.msg_types;
entries
.iter()
.find(|entry| entry.msg_type == msg_type)
.map(|entry| entry.versions)
}
fn message_type_support(&self, body: &[u8], out: &mut [u8]) -> Result<usize, ErrorCode> {
// DSP0236 Table 19's request carries no data.
if !body.is_empty() {
return encode_error(CompletionCode::ErrorInvalidLength, out);
}
// `mctp-lib` encodes the list from a byte slice. `check_config`
// bounds the entry count by MAX_MSG_TYPES.
let mut types = [0u8; MAX_MSG_TYPES];
for (slot, entry) in types.iter_mut().zip(self.config.msg_types) {
*slot = entry.msg_type;
}
let response = GetMctpMessageTypeSupportResponse::new(
CompletionCode::Success,
&types[..self.config.msg_types.len()],
);
response
.encode(out)
.map_err(|_| MCTP_CONTROL_RESPONSE_TOO_SHORT)
}
}
/// Whether an EID may be assigned to an endpoint.
///
/// DSP0236 Table 14 marks the null EID `0x00` and the broadcast EID `0xff`
/// illegal for assignment, and clause 8.2 reserves 1 through 7.
const fn is_legal_eid(eid: u8) -> bool {
eid > 7 && eid != 0xff
}
/// Refuse a [`ControlConfig`] whose replies `mctp-lib` cannot encode or
/// decode, or that no packet can carry.
///
/// A partial version code would panic in `mctp-lib`'s encoders, and a table
/// past [`MAX_VERSION_CODES`] would draw a reply its decoder refuses.
const fn check_config(config: &ControlConfig<'_>) -> Result<(), ErrorCode> {
if !version_table_fits(config.base_versions) || !version_table_fits(config.control_versions) {
return Err(MCTP_CONTROL_BAD_VERSION_TABLE);
}
let msg_types = config.msg_types;
if msg_types.len() > MAX_MSG_TYPES {
return Err(MCTP_CONTROL_TOO_MANY_MSG_TYPES);
}
// `while` rather than `for`, since a `const fn` cannot drive an iterator.
// One bit per 7-bit type, so a type listed twice finds its bit set.
let mut seen: u128 = 0;
let mut i = 0;
while i < msg_types.len() {
let entry = &msg_types[i];
// Table 3 numbers message types in 7 bits, and control answers from
// `control_versions` alone. The 7-bit check also keeps the shift
// below under 128.
if entry.msg_type == MCTP_MSG_TYPE_CONTROL || entry.msg_type > 0x7f {
return Err(MCTP_CONTROL_BAD_MSG_TYPE);
}
if entry.versions.is_empty() || !version_table_fits(entry.versions) {
return Err(MCTP_CONTROL_BAD_VERSION_TABLE);
}
let bit = 1u128 << entry.msg_type;
if seen & bit != 0 {
return Err(MCTP_CONTROL_BAD_MSG_TYPE);
}
seen |= bit;
i += 1;
}
Ok(())
}
const fn version_table_fits(codes: &[u8]) -> bool {
codes.len() % VERSION_CODE_LEN == 0 && codes.len() <= MAX_VERSION_CODES * VERSION_CODE_LEN
}
/// Decode a Set Endpoint ID request body (DSP0236, Table 14).
///
/// Reads the operation from byte 1 before the EID in byte 2, which Reset EID
/// and Set Discovered Flag ignore. This crate decodes the body itself because
/// `mctp-lib`'s decoder validates byte 2 first and so rejects either request
/// when byte 2 is absent or not a valid EID.
///
/// Returns `None` for a body of the wrong length: an empty body, a body past
/// 2 bytes, or a Set EID or Force EID without byte 2.
fn decode_set_eid(body: &[u8]) -> Option<SetEidOperation> {
if body.len() > 2 {
return None;
}
let operation = body.first()? & 0b0000_0011;
match operation {
0x00 => Some(SetEidOperation::SetEid(*body.get(1)?)),
0x01 => Some(SetEidOperation::ForceEid(*body.get(1)?)),
0x02 => Some(SetEidOperation::ResetEid),
0x03 => Some(SetEidOperation::SetDiscoveredFlag),
_ => None,
}
}
fn encode_error(code: CompletionCode, out: &mut [u8]) -> Result<usize, ErrorCode> {
*out.first_mut().ok_or(MCTP_CONTROL_RESPONSE_TOO_SHORT)? = code.into();
Ok(1)
}