services/pldm/src/transport.rs

// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0

//! MCTP transport adapter for PLDM messages.
//!
//! [`MctpPldmTransport`] wraps a [`Stack`] (backed by any [`MctpClient`]) and
//! provides PLDM-specific send/receive helpers that manage the MCTP framing
//! byte automatically.
//!
//! ## Buffer layout
//!
//! All methods in this module use the same flat-buffer convention as the rest
//! of this crate:
//!
//! ```text
//! buf[0]          : MCTP message-type (0x01) – written/verified by this layer
//! buf[1..]        : PLDM message (header + data)
//! ```
//!
//! Callers only deal with PLDM bytes; the framing byte is inserted or stripped
//! transparently.

use openprot_mctp_api::stack::StackListener;
use openprot_mctp_api::{MctpClient, MctpListener, MctpReqChannel, MctpRespChannel, Stack};
use pldm_common::util::mctp_transport::MCTP_PLDM_MSG_TYPE;

use crate::error::{PldmMemError, PldmServiceError};

/// MCTP transport adapter for PLDM messages.
///
/// Wraps a [`Stack`] backed by any [`MctpClient`] implementation and provides
/// PLDM-specific send/receive helpers that manage the MCTP framing byte
/// (`buf[0]` = `0x01`) automatically.
///
/// # Example
///
/// ```rust,ignore
/// use openprot_pldm_service::transport::MctpPldmTransport;
/// use openprot_mctp_client::IpcMctpClient;
///
/// let transport = MctpPldmTransport::new(IpcMctpClient::new(handle::MCTP));
///
/// // Use the underlying stack directly if needed.
/// transport.stack().set_eid(8).unwrap();
///
/// // Send a PLDM request; the caller fills buf[1..1+pldm_len] first.
/// let pldm_resp_len = transport
///     .send_request(remote_eid, pldm_len, &mut buf, 5_000)
///     .unwrap();
///
/// // Receive and respond to one inbound PLDM request via a handler closure.
/// transport
///     .recv_and_respond(&mut buf, 5_000, |framed_buf, _req_total_len, _source_eid| {
///         // framed_buf[0] == 0x01, framed_buf[1..] is the PLDM payload.
///         // Process and write the response in-place; return total bytes.
///         my_cmd_interface.handle_responder_msg(framed_buf)
///             .map_err(PldmServiceError::MsgHandler)
///     })
///     .unwrap();
/// ```
pub struct MctpPldmTransport<C: MctpClient> {
    stack: Stack<C>,
}

impl<C: MctpClient> MctpPldmTransport<C> {
    /// Create a new PLDM transport wrapping the given [`MctpClient`].
    pub fn new(client: C) -> Self {
        MctpPldmTransport {
            stack: Stack::new(client),
        }
    }

    /// Get a reference to the underlying MCTP [`Stack`].
    ///
    /// Useful when the raw stack is needed (e.g. to set the local EID).
    pub fn stack(&self) -> &Stack<C> {
        &self.stack
    }

    /// Send a PLDM request to `remote_eid` and receive the response.
    ///
    /// The caller must place the PLDM request bytes in `buf[1..1+pldm_len]`
    /// before calling this method.  `buf[0]` is overwritten with the MCTP
    /// PLDM message-type byte (`0x01`).
    ///
    /// On success, the PLDM response bytes are written into `buf[1..]` and
    /// the number of response bytes is returned.
    ///
    /// A `timeout_millis` of `0` blocks indefinitely.
    ///
    /// # Errors
    ///
    /// Returns [`PldmServiceError::PldmMem`] if `buf` is too small to hold
    /// the request or if an arithmetic overflow would occur.
    /// Returns [`PldmServiceError::Mctp`] on any MCTP transport error.
    pub fn send_request(
        &self,
        remote_eid: u8,
        pldm_len: usize,
        buf: &mut [u8],
        timeout_millis: u32,
    ) -> Result<usize, PldmServiceError> {
        // Stamp the framing byte even though the MCTP layer manages it; this
        // keeps buf consistent for callers that inspect buf[0] afterward.
        match buf.first_mut() {
            Some(b) => *b = MCTP_PLDM_MSG_TYPE,
            None => return Err(PldmServiceError::PldmMem(PldmMemError::MalformedBuffer)),
        }

        // Open an outbound request channel.
        let mut req_channel = self
            .stack
            .req(remote_eid, timeout_millis)
            .map_err(PldmServiceError::Mctp)?;

        // Send the PLDM payload (buf[1..1+pldm_len]).  The MCTP layer adds
        // its own framing, so we exclude buf[0].
        let req_end = pldm_len
            .checked_add(1)
            .ok_or(PldmServiceError::PldmMem(PldmMemError::OverflowMaxSize))?;
        let req_payload = buf
            .get(1..req_end)
            .ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;
        req_channel
            .send(MCTP_PLDM_MSG_TYPE, req_payload)
            .map_err(PldmServiceError::Mctp)?;

        // Receive the PLDM response into buf[1..].
        let recv_buf = buf
            .get_mut(1..)
            .ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;
        let (meta, _) = req_channel.recv(recv_buf).map_err(PldmServiceError::Mctp)?;

        Ok(meta.payload_size)
    }

    /// Receive one incoming PLDM request, frame it in `buf`, and invoke
    /// `handler` to produce a response.
    ///
    /// The PLDM payload is received into `buf[1..]`; `buf[0]` is set to the
    /// MCTP PLDM type byte (`0x01`).  `handler` receives the entire `buf`
    /// (with the request framed at `buf[..1+payload_size]`) so it has room to
    /// write a response that is larger than the request, processing it in
    /// place. `handler` is called with the full framed buffer, the total
    /// request length (including `buf[0]`), and the source EID of the
    /// request (`RecvMetadata::remote_eid`), so callers can filter requests
    /// by sender. It must return the total number of bytes written for the
    /// response (including the type byte at `buf[0]`), or `0` to indicate no
    /// response should be sent (e.g. the request came from an unexpected
    /// EID). Bytes `buf[1..resp_total_len]` are sent back to the requester.
    ///
    /// A `timeout_millis` of `0` blocks indefinitely.
    ///
    /// This registers and drops a fresh listener on every call. A caller that
    /// invokes this repeatedly in a tight loop with no other MCTP traffic in
    /// between is unaffected, but a caller that interleaves other MCTP
    /// activity on the same endpoint between calls (e.g.
    /// [`FirmwareDevice::run_terminus`](crate::firmware_device::FirmwareDevice::run_terminus),
    /// which interleaves FD-initiated requests) should use
    /// [`responder_listener`](Self::responder_listener) and
    /// [`respond_once`](Self::respond_once) instead, to avoid a window with no
    /// listener registered in which an inbound request could be dropped by
    /// the underlying MCTP stack.
    ///
    /// # Errors
    ///
    /// Returns [`PldmServiceError::PldmMem(PldmMemError::BufferTooSmall)`] if `buf` is too small.
    /// Returns [`PldmServiceError::Mctp`] on any MCTP transport error.
    /// Propagates any error returned by `handler`.
    pub fn recv_and_respond<F>(
        &self,
        buf: &mut [u8],
        timeout_millis: u32,
        handler: F,
    ) -> Result<(), PldmServiceError>
    where
        F: FnOnce(&mut [u8], usize, u8) -> Result<usize, PldmServiceError>,
    {
        let mut listener = self.responder_listener(timeout_millis)?;
        self.respond_once(&mut listener, buf, handler)
    }

    /// Register a persistent listener for inbound PLDM requests.
    ///
    /// Unlike [`recv_and_respond`](Self::recv_and_respond), which registers
    /// and drops a listener handle on every call, the returned listener can
    /// be reused across many [`respond_once`](Self::respond_once) calls
    /// (adjusting its timeout with [`StackListener::set_timeout`] as needed).
    /// This matters because the underlying MCTP stack requires an active
    /// listener registration to accept an inbound request of a given
    /// message type; a caller that interleaves other MCTP traffic (e.g.
    /// FD-initiated requests) between polls would otherwise have a window
    /// with no listener registered in which an inbound UA command could be
    /// silently dropped.
    ///
    /// A `timeout_millis` of `0` blocks indefinitely.
    pub fn responder_listener(
        &self,
        timeout_millis: u32,
    ) -> Result<StackListener<'_, C>, PldmServiceError> {
        self.stack
            .listener(MCTP_PLDM_MSG_TYPE, timeout_millis)
            .map_err(PldmServiceError::Mctp)
    }

    /// Receive one incoming PLDM request on an already-registered `listener`
    /// (obtained via [`responder_listener`](Self::responder_listener)), frame
    /// it in `buf`, and invoke `handler` to produce a response.
    ///
    /// See [`recv_and_respond`](Self::recv_and_respond) for the buffer and
    /// handler contract; this method has the same semantics but reuses an
    /// existing listener instead of registering a new one.
    ///
    /// # Errors
    ///
    /// Returns [`PldmServiceError::PldmMem(PldmMemError::BufferTooSmall)`] if `buf` is too small.
    /// Returns [`PldmServiceError::Mctp`] on any MCTP transport error.
    /// Propagates any error returned by `handler`.
    pub fn respond_once<F>(
        &self,
        listener: &mut StackListener<'_, C>,
        buf: &mut [u8],
        handler: F,
    ) -> Result<(), PldmServiceError>
    where
        F: FnOnce(&mut [u8], usize, u8) -> Result<usize, PldmServiceError>,
    {
        // Receive into buf[1..]; discard the payload sub-slice to end the
        // mutable borrow before we touch buf[0].
        let recv_buf = buf
            .get_mut(1..)
            .ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;
        let (meta, mut resp_channel) = listener
            .recv(recv_buf)
            .map(|(m, _, r)| (m, r))
            .map_err(PldmServiceError::Mctp)?;

        let payload_size = meta.payload_size;

        // Stamp the framing byte.
        match buf.first_mut() {
            Some(b) => *b = MCTP_PLDM_MSG_TYPE,
            None => return Err(PldmServiceError::PldmMem(PldmMemError::MalformedBuffer)),
        }

        // Ensure the buffer is at least large enough to hold the framed
        // request before handing it off.
        let req_total_len = payload_size
            .checked_add(1)
            .filter(|&total_len| total_len <= buf.len())
            .ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;

        // Invoke the handler to process the request in-place.  The handler is
        // given the whole buffer so the response may exceed the request size.
        let resp_total_len = handler(buf, req_total_len, meta.remote_eid)?;

        // A handler returning 0 means it deliberately chose not to respond
        // (e.g. the request came from an EID it does not serve).
        if resp_total_len == 0 {
            return Ok(());
        }

        // Send the response, excluding the MCTP type byte that the transport
        // layer manages separately.
        let resp_payload = buf
            .get(1..resp_total_len)
            .ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;
        resp_channel
            .send(resp_payload)
            .map_err(PldmServiceError::Mctp)
    }
}