services/pldm/src/firmware_device.rs - third_party/github/OpenPRoT/openprot - Git at Google

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

 //! PLDM Firmware Device (FD) service.
 //!
 //! [`FirmwareDevice`] owns the PLDM firmware-update state machine and the
 //! platform-specific flash operations.  It talks to the Update Agent (UA)
 //! directly over MCTP via two [`MctpPldmTransport`] instances:
 //!
 //! * **`responder_transport`** – listens for inbound PLDM FW-update commands
 //!   from the UA and replies in place.
 //! * **`requester_transport`** – forwards FD-initiated PLDM requests (e.g.
 //!   `RequestFirmwareData`) to the UA at `remote_eid` and receives the
 //!   response.
 //!
 //! This lets a single process own the whole FD state machine and its MCTP
 //! I/O, without needing to bridge to separate responder/requester processes
 //! over platform-specific IPC.
 //!
 //! ## Buffer layout
 //!
 //! Both transports carry the same flat buffer convention used throughout this
 //! crate:
 //!
 //! ```text
 //! buf[0]          : MCTP message-type (0x01)
 //! buf[1..]        : PLDM message (header + data)
 //! ```
 //!
 //! ## Main loop
 //!
 //! Each iteration of [`FirmwareDevice::run_terminus`] performs two interleaved
 //! phases:
 //!
 //! 1. **Initiator (outbound)** – while the FD is in update mode, generate the
 //!    next FD-initiated request via [`CmdInterface::generate_initiator_request`],
 //!    send it to the UA through `requester_transport`, and feed the response
 //!    back via [`CmdInterface::process_initiator_response`].
 //! 2. **Responder (inbound)** – poll `responder_transport` for an inbound UA
 //!    command and reply via [`CmdInterface::handle_responder_msg`]. Polling
 //!    every iteration keeps the responder path live during a transfer so the
 //!    Update Agent can send `CancelUpdate` at any time.

 use openprot_mctp_api::stack::StackListener;
 use openprot_mctp_api::MctpClient;
 use pldm_interface::cmd_interface::CmdInterface;
 use pldm_interface::control_context::ProtocolCapability;
 use pldm_interface::firmware_device::fd_context::FirmwareDeviceContext;
 use pldm_interface::firmware_device::fd_ops::FdOps;

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

 /// Maximum PLDM-over-MCTP message size (MCTP-type byte + PLDM payload).
 pub const FD_MAX_MSG: usize = 1024;

 /// Poll timeout (milliseconds) used for the inbound responder listener while
 /// an initiator (FD-to-UA) request is active.
 ///
 /// A short, non-zero timeout lets [`FirmwareDevice::run_terminus`] check for
 /// an inbound Update Agent command (e.g. `CancelUpdate`) between successive
 /// outbound requests without blocking the transfer; a lack of a message
 /// within this window is expected and is not treated as an error.
 const RESPONDER_POLL_TIMEOUT_MILLIS: u32 = 1;

 /// Update-lifecycle notification out of the PLDM FD state machine, one per
 /// state-machine edge.
 ///
 /// Every variant payload is `Copy` and lifetime-free by design. Anything
 /// buffer-shaped (image chunks, package data, version strings) lands in
 /// flash or an `FdOps`-owned buffer; an event carries at most the small
 /// fixed-size values that name or qualify the edge.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FdEvent {
     /// The Update Agent's `RequestUpdate` was accepted: the FD moved out of
     /// `Idle` (into `LearnComponents`) and the success response has already
     /// been sent. Emitted exactly once per accepted `RequestUpdate`;
     /// rejected ones (`ALREADY_IN_UPDATE_MODE`, bad transfer size) never
     /// reach here because they leave the FD state unchanged.
     UpdateRequested,
 }

 /// Receiver for [`FdEvent`] notifications out of the PLDM FD state machine.
 ///
 /// [`FirmwareDevice::run_terminus`] owns the PLDM state machine but has no
 /// knowledge of the platform's update orchestration; this trait is the seam
 /// between the two. It is deliberately PLDM-flavored (no orchestrator
 /// types) so that depending on this crate never pulls in the orchestrator
 /// stack; the mapping to an orchestrator event lives in an adapter crate,
 /// following the same rule as the orchestrator's HAL adapters.
 ///
 /// [`FdEvent`] is `#[non_exhaustive]`: implementors match the variants they
 /// care about and ignore the rest, so new FD lifecycle events do not break
 /// existing sinks.
 pub trait FdEventSink {
     /// Receive one FD lifecycle event.
     fn notify(&mut self, event: FdEvent);
 }

 /// Drop update notifications, for callers with no orchestration to notify.
 impl FdEventSink for () {
     fn notify(&mut self, _event: FdEvent) {}
 }

 /// Outcome of [`FirmwareDevice::run_terminus`]/[`FirmwareDevice::run_until`].
 pub enum RunTerminusResult {
     /// The loop exited without an error. Reachable via
     /// [`run_until`](FirmwareDevice::run_until) once its stop condition
     /// returns `false` — which says nothing about protocol state, only that
     /// the caller chose to stop. Unreachable via
     /// [`run_terminus`](FirmwareDevice::run_terminus), whose stop condition
     /// never fires; a well-defined *protocol* completion condition remains
     /// open work there.
     Completed,
     /// The loop was stopped by an unrecoverable error.
     StoppedByError(PldmServiceError),
 }

 /// PLDM Firmware Device service.
 ///
 /// Owns the PLDM firmware-update state machine ([`CmdInterface`]) and drives
 /// it via [`run_terminus`](FirmwareDevice::run_terminus), talking directly to
 /// the Update Agent over MCTP through `responder_transport` (inbound UA
 /// commands) and `requester_transport` (outbound FD-initiated requests).
 pub struct FirmwareDevice<'a, O: FdOps, Cr: MctpClient, Cq: MctpClient> {
     cmd_interface: CmdInterface<'a, O>,
     responder_transport: MctpPldmTransport<Cr>,
     requester_transport: MctpPldmTransport<Cq>,
 }

 impl<'a, O: FdOps, Cr: MctpClient, Cq: MctpClient> FirmwareDevice<'a, O, Cr, Cq> {
     /// Create a new [`FirmwareDevice`] with the given protocol capabilities
     /// and MCTP transports.
     ///
     /// `protocol_capabilities` should advertise at least
     /// [`PldmSupportedType::FwUpdate`] so that the [`CmdInterface`] accepts
     /// and routes firmware-update commands correctly. `responder_transport`
     /// answers inbound UA commands; `requester_transport` forwards
     /// FD-initiated requests to the UA.
     ///
     /// [`PldmSupportedType::FwUpdate`]: pldm_common::protocol::base::PldmSupportedType::FwUpdate
     pub fn init(
         fdops: &'a O,
         protocol_capabilities: &'a [ProtocolCapability<'a>],
         responder_transport: MctpPldmTransport<Cr>,
         requester_transport: MctpPldmTransport<Cq>,
     ) -> Self {
         FirmwareDevice {
             cmd_interface: CmdInterface::new(
                 protocol_capabilities,
                 FirmwareDeviceContext::new(fdops),
             ),
             responder_transport,
             requester_transport,
         }
     }

     /// The step body, taking each field it needs directly rather than
     /// `&mut self`.
     ///
     /// This has to be a free-standing function, not a method: `run_until`
     /// holds `listener`, which borrows `responder_transport` for the whole
     /// session, alongside this step's need for `&mut cmd_interface`. A
     /// method taking `&mut self` claims all of `self` at once — including
     /// `responder_transport` — which the borrow checker sees as conflicting
     /// with `listener`'s outstanding borrow even though the two never
     /// actually touch the same data at the same time. Passing the fields
     /// this needs individually, instead of through `self`, lets the borrow
     /// checker see they are disjoint.
     #[allow(clippy::too_many_arguments)]
     fn run_once_inner(
         cmd_interface: &mut CmdInterface<'_, O>,
         requester_transport: &MctpPldmTransport<Cq>,
         responder_transport: &MctpPldmTransport<Cr>,
         listener: &mut StackListener<'_, Cr>,
         fw_buf: &mut [u8; FD_MAX_MSG],
         buf: &mut [u8],
         remote_eid: u8,
         timeout_millis: u32,
         requester_timeout_millis: u32,
         sink: &mut impl FdEventSink,
     ) -> Result<(), PldmServiceError> {
         // Phase 1: while in initiator mode, issue at most ONE outbound
         // request this step. We deliberately fall through to the responder
         // poll below (no early return) so an Update Agent command such as
         // CancelUpdate is serviced between every RequestFirmwareData.
         let initiator_active = cmd_interface.fd_ctx.should_start_initiator_mode();
         if initiator_active
             && let Some(pldm_len) = cmd_interface
                 .generate_initiator_request(fw_buf)
                 .map_err(PldmServiceError::MsgHandler)?
         {
             let resp_len = requester_transport.send_request(
                 remote_eid,
                 pldm_len,
                 fw_buf,
                 requester_timeout_millis,
             )?;
             let resp_total_len = resp_len
                 .checked_add(1)
                 .ok_or(PldmServiceError::PldmMem(PldmMemError::OverflowMaxSize))?;
             let resp = fw_buf
                 .get_mut(..resp_total_len)
                 .ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;
             cmd_interface
                 .process_initiator_response(resp)
                 .map_err(PldmServiceError::MsgHandler)?;
         }

         // Phase 2: poll for an inbound command so the responder path stays
         // live during a transfer and the Update Agent can cancel at any
         // time. `handle_responder_msg` receives the *whole* buffer because
         // responses may be larger than the request they answer (e.g. GetTid:
         // 4-byte request, 5-byte response). Commands from any EID other than
         // `remote_eid` are dropped without a response.
         let poll_timeout = if initiator_active {
             RESPONDER_POLL_TIMEOUT_MILLIS
         } else {
             timeout_millis
         };
         listener.set_timeout(poll_timeout);
         // Sampled around the responder poll: `RequestUpdate` is the only
         // command that takes the FD out of `Idle`, so the false→true edge
         // of `is_update_mode()` identifies exactly one accepted
         // `RequestUpdate` (the initiator phase above never leaves `Idle`).
         let was_update_mode = cmd_interface.fd_ctx.is_update_mode();
         match responder_transport.respond_once(
             listener,
             buf,
             |framed_buf, _req_total_len, source_eid| {
                 // Only act on commands from the UA this instance serves;
                 // silently drop anything else (e.g. a rogue endpoint).
                 if source_eid != remote_eid {
                     return Ok(0);
                 }
                 cmd_interface
                     .handle_responder_msg(framed_buf)
                     .map_err(PldmServiceError::MsgHandler)
             },
         ) {
             Ok(()) => {
                 if !was_update_mode && cmd_interface.fd_ctx.is_update_mode() {
                     sink.notify(FdEvent::UpdateRequested);
                 }
                 Ok(())
             }
             // A short poll timeout while an initiator request is active
             // just means no UA command arrived in that window; keep going
             // so the transfer can continue.
             Err(PldmServiceError::Mctp(e)) if initiator_active && e.is_timeout() => Ok(()),
             Err(e) => Err(e),
         }
     }

     /// Run the firmware-device service loop, stopping as soon as
     /// `should_continue` returns `false` — even if the session is not
     /// otherwise over.
     ///
     /// Each step performs the same two interleaved phases documented on
     /// [`run_terminus`](Self::run_terminus):
     ///
     /// 1. **Initiator** — while the FD is in update mode
     ///    ([`should_start_initiator_mode`]), generate at most one outbound
     ///    request (e.g. `RequestFirmwareData`) via
     ///    [`CmdInterface::generate_initiator_request`], send it to `remote_eid`
     ///    through `requester_transport`, and feed the response back into the
     ///    state machine via [`CmdInterface::process_initiator_response`].
     /// 2. **Responder** — poll for an inbound Update Agent command and reply
     ///    via [`CmdInterface::handle_responder_msg`]. While an initiator
     ///    request is active, this poll uses a short timeout so the transfer
     ///    keeps making progress; a lack of a message within that window is
     ///    expected and does not end the session. When idle, the poll blocks
     ///    for the caller-supplied `timeout_millis`.
     ///
     /// `should_continue` is checked once per step, before the step runs. A
     /// caller that wants to interleave other work on this thread does it
     /// from inside `should_continue` (returning `true` to keep going) rather
     /// than being handed control back directly between steps: the responder
     /// listener has to stay registered for the entire session — the
     /// underlying MCTP stack requires an active registration to accept an
     /// inbound request of a given message type, so a caller-visible gap
     /// between steps (dropping the listener, doing other work, re-arming it)
     /// would silently drop any Update Agent command arriving in that window.
     /// Threading the listener through a public step-by-step API without that
     /// gap would need `StackListener` to stop borrowing `responder_transport`
     /// (it currently also implements `Drop`, which rules out storing it as a
     /// `FirmwareDevice` field too) — a change to `services/mctp/api`, not
     /// this crate.
     ///
     /// A `timeout_millis` of `0` blocks indefinitely while idle.
     ///
     /// `requester_timeout_millis` bounds how long each `send_request` call
     /// (Phase 1) is allowed to wait for the UA's response to an FD-initiated
     /// request. It is intentionally a separate value from `timeout_millis`:
     /// reusing `timeout_millis` here would let a `0` (block indefinitely)
     /// idle-timeout also apply to the wait for the UA's response, which could
     /// block this call — and therefore Phase 2's responder poll — forever if
     /// the UA never replies. A `requester_timeout_millis` of `0` still blocks
     /// indefinitely if that behavior is desired; callers that want the
     /// responder path to stay live even during a stalled FD-initiated
     /// request should pass a bounded value instead.
     ///
     /// `sink` receives [`FdEvent::UpdateRequested`] once per
     /// accepted `RequestUpdate` (the FD's only `Idle` → non-`Idle`
     /// transition), after the success response has been sent. Callers with
     /// nothing to notify pass `&mut ()`.
     ///
     /// Returns [`StoppedByError`](RunTerminusResult::StoppedByError) if a
     /// step fails, or [`Completed`](RunTerminusResult::Completed) once
     /// `should_continue` returns `false` — the latter says nothing about
     /// protocol state; it only means the caller chose to stop here. A
     /// well-defined *protocol* completion condition is still open work.
     ///
     /// [`should_start_initiator_mode`]: pldm_interface::firmware_device::fd_context::FirmwareDeviceContext
     pub fn run_until(
         &mut self,
         remote_eid: u8,
         buf: &mut [u8],
         timeout_millis: u32,
         requester_timeout_millis: u32,
         sink: &mut impl FdEventSink,
         mut should_continue: impl FnMut() -> bool,
     ) -> RunTerminusResult {
         let mut listener = match self.responder_transport.responder_listener(timeout_millis) {
             Ok(listener) => listener,
             Err(e) => return RunTerminusResult::StoppedByError(e),
         };
         // Scratch buffer for FD-initiated (outbound) requests, reused across
         // steps rather than re-zeroed on every one.
         let mut fw_buf = [0u8; FD_MAX_MSG];
         while should_continue() {
             // Field-by-field, not `&mut self` — see `run_once_inner`'s doc.
             if let Err(e) = Self::run_once_inner(
                 &mut self.cmd_interface,
                 &self.requester_transport,
                 &self.responder_transport,
                 &mut listener,
                 &mut fw_buf,
                 buf,
                 remote_eid,
                 timeout_millis,
                 requester_timeout_millis,
                 sink,
             ) {
                 return RunTerminusResult::StoppedByError(e);
             }
         }
         RunTerminusResult::Completed
     }

     /// Run the firmware-device service loop to completion, blocking the
     /// calling thread.
     ///
     /// A thin wrapper over [`run_until`](Self::run_until) with a
     /// stop condition that never fires — see `run_until` for the full
     /// behavior. This method loops indefinitely and returns only on error.
     /// A `timeout_millis` of `0` blocks indefinitely while idle.
     pub fn run_terminus(
         &mut self,
         remote_eid: u8,
         buf: &mut [u8],
         timeout_millis: u32,
         requester_timeout_millis: u32,
         sink: &mut impl FdEventSink,
     ) -> RunTerminusResult {
         self.run_until(
             remote_eid,
             buf,
             timeout_millis,
             requester_timeout_millis,
             sink,
             || true,
         )
     }
 }
	// Licensed under the Apache-2.0 license
	// SPDX-License-Identifier: Apache-2.0

	//! PLDM Firmware Device (FD) service.
	//!
	//! [`FirmwareDevice`] owns the PLDM firmware-update state machine and the
	//! platform-specific flash operations. It talks to the Update Agent (UA)
	//! directly over MCTP via two [`MctpPldmTransport`] instances:
	//!
	//! * `responder_transport` – listens for inbound PLDM FW-update commands
	//! from the UA and replies in place.
	//! * `requester_transport` – forwards FD-initiated PLDM requests (e.g.
	//! `RequestFirmwareData`) to the UA at `remote_eid` and receives the
	//! response.
	//!
	//! This lets a single process own the whole FD state machine and its MCTP
	//! I/O, without needing to bridge to separate responder/requester processes
	//! over platform-specific IPC.
	//!
	//! ## Buffer layout
	//!
	//! Both transports carry the same flat buffer convention used throughout this
	//! crate:
	//!
	//! ```text
	//! buf[0] : MCTP message-type (0x01)
	//! buf[1..] : PLDM message (header + data)
	//! ```
	//!
	//! ## Main loop
	//!
	//! Each iteration of [`FirmwareDevice::run_terminus`] performs two interleaved
	//! phases:
	//!
	//! 1. Initiator (outbound) – while the FD is in update mode, generate the
	//! next FD-initiated request via [`CmdInterface::generate_initiator_request`],
	//! send it to the UA through `requester_transport`, and feed the response
	//! back via [`CmdInterface::process_initiator_response`].
	//! 2. Responder (inbound) – poll `responder_transport` for an inbound UA
	//! command and reply via [`CmdInterface::handle_responder_msg`]. Polling
	//! every iteration keeps the responder path live during a transfer so the
	//! Update Agent can send `CancelUpdate` at any time.

	use openprot_mctp_api::stack::StackListener;
	use openprot_mctp_api::MctpClient;
	use pldm_interface::cmd_interface::CmdInterface;
	use pldm_interface::control_context::ProtocolCapability;
	use pldm_interface::firmware_device::fd_context::FirmwareDeviceContext;
	use pldm_interface::firmware_device::fd_ops::FdOps;

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

	/// Maximum PLDM-over-MCTP message size (MCTP-type byte + PLDM payload).
	pub const FD_MAX_MSG: usize = 1024;

	/// Poll timeout (milliseconds) used for the inbound responder listener while
	/// an initiator (FD-to-UA) request is active.
	///
	/// A short, non-zero timeout lets [`FirmwareDevice::run_terminus`] check for
	/// an inbound Update Agent command (e.g. `CancelUpdate`) between successive
	/// outbound requests without blocking the transfer; a lack of a message
	/// within this window is expected and is not treated as an error.
	const RESPONDER_POLL_TIMEOUT_MILLIS: u32 = 1;

	/// Update-lifecycle notification out of the PLDM FD state machine, one per
	/// state-machine edge.
	///
	/// Every variant payload is `Copy` and lifetime-free by design. Anything
	/// buffer-shaped (image chunks, package data, version strings) lands in
	/// flash or an `FdOps`-owned buffer; an event carries at most the small
	/// fixed-size values that name or qualify the edge.
	#[non_exhaustive]
	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
	pub enum FdEvent {
	/// The Update Agent's `RequestUpdate` was accepted: the FD moved out of
	/// `Idle` (into `LearnComponents`) and the success response has already
	/// been sent. Emitted exactly once per accepted `RequestUpdate`;
	/// rejected ones (`ALREADY_IN_UPDATE_MODE`, bad transfer size) never
	/// reach here because they leave the FD state unchanged.
	UpdateRequested,
	}

	/// Receiver for [`FdEvent`] notifications out of the PLDM FD state machine.
	///
	/// [`FirmwareDevice::run_terminus`] owns the PLDM state machine but has no
	/// knowledge of the platform's update orchestration; this trait is the seam
	/// between the two. It is deliberately PLDM-flavored (no orchestrator
	/// types) so that depending on this crate never pulls in the orchestrator
	/// stack; the mapping to an orchestrator event lives in an adapter crate,
	/// following the same rule as the orchestrator's HAL adapters.
	///
	/// [`FdEvent`] is `#[non_exhaustive]`: implementors match the variants they
	/// care about and ignore the rest, so new FD lifecycle events do not break
	/// existing sinks.
	pub trait FdEventSink {
	/// Receive one FD lifecycle event.
	fn notify(&mut self, event: FdEvent);
	}

	/// Drop update notifications, for callers with no orchestration to notify.
	impl FdEventSink for () {
	fn notify(&mut self, _event: FdEvent) {}
	}

	/// Outcome of [`FirmwareDevice::run_terminus`]/[`FirmwareDevice::run_until`].
	pub enum RunTerminusResult {
	/// The loop exited without an error. Reachable via
	/// [`run_until`](FirmwareDevice::run_until) once its stop condition
	/// returns `false` — which says nothing about protocol state, only that
	/// the caller chose to stop. Unreachable via
	/// [`run_terminus`](FirmwareDevice::run_terminus), whose stop condition
	/// never fires; a well-defined protocol completion condition remains
	/// open work there.
	Completed,
	/// The loop was stopped by an unrecoverable error.
	StoppedByError(PldmServiceError),
	}

	/// PLDM Firmware Device service.
	///
	/// Owns the PLDM firmware-update state machine ([`CmdInterface`]) and drives
	/// it via [`run_terminus`](FirmwareDevice::run_terminus), talking directly to
	/// the Update Agent over MCTP through `responder_transport` (inbound UA
	/// commands) and `requester_transport` (outbound FD-initiated requests).
	pub struct FirmwareDevice<'a, O: FdOps, Cr: MctpClient, Cq: MctpClient> {
	cmd_interface: CmdInterface<'a, O>,
	responder_transport: MctpPldmTransport<Cr>,
	requester_transport: MctpPldmTransport<Cq>,
	}

	impl<'a, O: FdOps, Cr: MctpClient, Cq: MctpClient> FirmwareDevice<'a, O, Cr, Cq> {
	/// Create a new [`FirmwareDevice`] with the given protocol capabilities
	/// and MCTP transports.
	///
	/// `protocol_capabilities` should advertise at least
	/// [`PldmSupportedType::FwUpdate`] so that the [`CmdInterface`] accepts
	/// and routes firmware-update commands correctly. `responder_transport`
	/// answers inbound UA commands; `requester_transport` forwards
	/// FD-initiated requests to the UA.
	///
	/// [`PldmSupportedType::FwUpdate`]: pldm_common::protocol::base::PldmSupportedType::FwUpdate
	pub fn init(
	fdops: &'a O,
	protocol_capabilities: &'a [ProtocolCapability<'a>],
	responder_transport: MctpPldmTransport<Cr>,
	requester_transport: MctpPldmTransport<Cq>,
	) -> Self {
	FirmwareDevice {
	cmd_interface: CmdInterface::new(
	protocol_capabilities,
	FirmwareDeviceContext::new(fdops),
	),
	responder_transport,
	requester_transport,
	}
	}

	/// The step body, taking each field it needs directly rather than
	/// `&mut self`.
	///
	/// This has to be a free-standing function, not a method: `run_until`
	/// holds `listener`, which borrows `responder_transport` for the whole
	/// session, alongside this step's need for `&mut cmd_interface`. A
	/// method taking `&mut self` claims all of `self` at once — including
	/// `responder_transport` — which the borrow checker sees as conflicting
	/// with `listener`'s outstanding borrow even though the two never
	/// actually touch the same data at the same time. Passing the fields
	/// this needs individually, instead of through `self`, lets the borrow
	/// checker see they are disjoint.
	#[allow(clippy::too_many_arguments)]
	fn run_once_inner(
	cmd_interface: &mut CmdInterface<'_, O>,
	requester_transport: &MctpPldmTransport<Cq>,
	responder_transport: &MctpPldmTransport<Cr>,
	listener: &mut StackListener<'_, Cr>,
	fw_buf: &mut [u8; FD_MAX_MSG],
	buf: &mut [u8],
	remote_eid: u8,
	timeout_millis: u32,
	requester_timeout_millis: u32,
	sink: &mut impl FdEventSink,
	) -> Result<(), PldmServiceError> {
	// Phase 1: while in initiator mode, issue at most ONE outbound
	// request this step. We deliberately fall through to the responder
	// poll below (no early return) so an Update Agent command such as
	// CancelUpdate is serviced between every RequestFirmwareData.
	let initiator_active = cmd_interface.fd_ctx.should_start_initiator_mode();
	if initiator_active
	&& let Some(pldm_len) = cmd_interface
	.generate_initiator_request(fw_buf)
	.map_err(PldmServiceError::MsgHandler)?
	{
	let resp_len = requester_transport.send_request(
	remote_eid,
	pldm_len,
	fw_buf,
	requester_timeout_millis,
	)?;
	let resp_total_len = resp_len
	.checked_add(1)
	.ok_or(PldmServiceError::PldmMem(PldmMemError::OverflowMaxSize))?;
	let resp = fw_buf
	.get_mut(..resp_total_len)
	.ok_or(PldmServiceError::PldmMem(PldmMemError::BufferTooSmall))?;
	cmd_interface
	.process_initiator_response(resp)
	.map_err(PldmServiceError::MsgHandler)?;
	}

	// Phase 2: poll for an inbound command so the responder path stays
	// live during a transfer and the Update Agent can cancel at any
	// time. `handle_responder_msg` receives the whole buffer because
	// responses may be larger than the request they answer (e.g. GetTid:
	// 4-byte request, 5-byte response). Commands from any EID other than
	// `remote_eid` are dropped without a response.
	let poll_timeout = if initiator_active {
	RESPONDER_POLL_TIMEOUT_MILLIS
	} else {
	timeout_millis
	};
	listener.set_timeout(poll_timeout);
	// Sampled around the responder poll: `RequestUpdate` is the only
	// command that takes the FD out of `Idle`, so the false→true edge
	// of `is_update_mode()` identifies exactly one accepted
	// `RequestUpdate` (the initiator phase above never leaves `Idle`).
	let was_update_mode = cmd_interface.fd_ctx.is_update_mode();
	match responder_transport.respond_once(
	listener,
	buf,
	\|framed_buf, _req_total_len, source_eid\| {
	// Only act on commands from the UA this instance serves;
	// silently drop anything else (e.g. a rogue endpoint).
	if source_eid != remote_eid {
	return Ok(0);
	}
	cmd_interface
	.handle_responder_msg(framed_buf)
	.map_err(PldmServiceError::MsgHandler)
	},
	) {
	Ok(()) => {
	if !was_update_mode && cmd_interface.fd_ctx.is_update_mode() {
	sink.notify(FdEvent::UpdateRequested);
	}
	Ok(())
	}
	// A short poll timeout while an initiator request is active
	// just means no UA command arrived in that window; keep going
	// so the transfer can continue.
	Err(PldmServiceError::Mctp(e)) if initiator_active && e.is_timeout() => Ok(()),
	Err(e) => Err(e),
	}
	}

	/// Run the firmware-device service loop, stopping as soon as
	/// `should_continue` returns `false` — even if the session is not
	/// otherwise over.
	///
	/// Each step performs the same two interleaved phases documented on
	/// [`run_terminus`](Self::run_terminus):
	///
	/// 1. Initiator — while the FD is in update mode
	/// ([`should_start_initiator_mode`]), generate at most one outbound
	/// request (e.g. `RequestFirmwareData`) via
	/// [`CmdInterface::generate_initiator_request`], send it to `remote_eid`
	/// through `requester_transport`, and feed the response back into the
	/// state machine via [`CmdInterface::process_initiator_response`].
	/// 2. Responder — poll for an inbound Update Agent command and reply
	/// via [`CmdInterface::handle_responder_msg`]. While an initiator
	/// request is active, this poll uses a short timeout so the transfer
	/// keeps making progress; a lack of a message within that window is
	/// expected and does not end the session. When idle, the poll blocks
	/// for the caller-supplied `timeout_millis`.
	///
	/// `should_continue` is checked once per step, before the step runs. A
	/// caller that wants to interleave other work on this thread does it
	/// from inside `should_continue` (returning `true` to keep going) rather
	/// than being handed control back directly between steps: the responder
	/// listener has to stay registered for the entire session — the
	/// underlying MCTP stack requires an active registration to accept an
	/// inbound request of a given message type, so a caller-visible gap
	/// between steps (dropping the listener, doing other work, re-arming it)
	/// would silently drop any Update Agent command arriving in that window.
	/// Threading the listener through a public step-by-step API without that
	/// gap would need `StackListener` to stop borrowing `responder_transport`
	/// (it currently also implements `Drop`, which rules out storing it as a
	/// `FirmwareDevice` field too) — a change to `services/mctp/api`, not
	/// this crate.
	///
	/// A `timeout_millis` of `0` blocks indefinitely while idle.
	///
	/// `requester_timeout_millis` bounds how long each `send_request` call
	/// (Phase 1) is allowed to wait for the UA's response to an FD-initiated
	/// request. It is intentionally a separate value from `timeout_millis`:
	/// reusing `timeout_millis` here would let a `0` (block indefinitely)
	/// idle-timeout also apply to the wait for the UA's response, which could
	/// block this call — and therefore Phase 2's responder poll — forever if
	/// the UA never replies. A `requester_timeout_millis` of `0` still blocks
	/// indefinitely if that behavior is desired; callers that want the
	/// responder path to stay live even during a stalled FD-initiated
	/// request should pass a bounded value instead.
	///
	/// `sink` receives [`FdEvent::UpdateRequested`] once per
	/// accepted `RequestUpdate` (the FD's only `Idle` → non-`Idle`
	/// transition), after the success response has been sent. Callers with
	/// nothing to notify pass `&mut ()`.
	///
	/// Returns [`StoppedByError`](RunTerminusResult::StoppedByError) if a
	/// step fails, or [`Completed`](RunTerminusResult::Completed) once
	/// `should_continue` returns `false` — the latter says nothing about
	/// protocol state; it only means the caller chose to stop here. A
	/// well-defined protocol completion condition is still open work.
	///
	/// [`should_start_initiator_mode`]: pldm_interface::firmware_device::fd_context::FirmwareDeviceContext
	pub fn run_until(
	&mut self,
	remote_eid: u8,
	buf: &mut [u8],
	timeout_millis: u32,
	requester_timeout_millis: u32,
	sink: &mut impl FdEventSink,
	mut should_continue: impl FnMut() -> bool,
	) -> RunTerminusResult {
	let mut listener = match self.responder_transport.responder_listener(timeout_millis) {
	Ok(listener) => listener,
	Err(e) => return RunTerminusResult::StoppedByError(e),
	};
	// Scratch buffer for FD-initiated (outbound) requests, reused across
	// steps rather than re-zeroed on every one.
	let mut fw_buf = [0u8; FD_MAX_MSG];
	while should_continue() {
	// Field-by-field, not `&mut self` — see `run_once_inner`'s doc.
	if let Err(e) = Self::run_once_inner(
	&mut self.cmd_interface,
	&self.requester_transport,
	&self.responder_transport,
	&mut listener,
	&mut fw_buf,
	buf,
	remote_eid,
	timeout_millis,
	requester_timeout_millis,
	sink,
	) {
	return RunTerminusResult::StoppedByError(e);
	}
	}
	RunTerminusResult::Completed
	}

	/// Run the firmware-device service loop to completion, blocking the
	/// calling thread.
	///
	/// A thin wrapper over [`run_until`](Self::run_until) with a
	/// stop condition that never fires — see `run_until` for the full
	/// behavior. This method loops indefinitely and returns only on error.
	/// A `timeout_millis` of `0` blocks indefinitely while idle.
	pub fn run_terminus(
	&mut self,
	remote_eid: u8,
	buf: &mut [u8],
	timeout_millis: u32,
	requester_timeout_millis: u32,
	sink: &mut impl FdEventSink,
	) -> RunTerminusResult {
	self.run_until(
	remote_eid,
	buf,
	timeout_millis,
	requester_timeout_millis,
	sink,
	\|\| true,
	)
	}
	}