services/pldm/README.md

# openprot-pldm-service

Platform-independent PLDM Firmware Device (FD) service, talking PLDM-over-MCTP
directly to a remote Update Agent (UA).

## Overview

This crate bridges [`openprot-mctp-api`](../mctp/api) and
[`pldm-interface`](https://github.com/OpenPRoT/pldm-lib/tree/main/pldm-interface)
so that firmware can run the PLDM firmware-update state machine and exchange
PLDM messages over MCTP without depending on any particular MCTP
implementation or OS.

`FirmwareDevice` owns two [`MctpPldmTransport`] instances and drives both
directions of traffic itself — there is no separate responder/requester
process or platform-specific IPC bridge:

```text
┌──────────────────────────┐
│   Application / Firmware │  constructs FirmwareDevice, calls run_terminus()
└───────────┬──────────────┘
            │
            ▼
┌───────────────────────────────────────────┐
│   openprot-pldm-service                   │◄── this crate
│   FirmwareDevice<'a, O: FdOps, Cr, Cq>    │
│     - cmd_interface: CmdInterface<'a, O>  │  PLDM FW-update state machine
│     - responder_transport: inbound UA→FD  │
│     - requester_transport: outbound FD→UA │
└───────────┬──────────────┬────────────────┘
            │              │ MctpPldmTransport<C: MctpClient>
            ▼              ▼
┌───────────────────────────────────────────┐
│   openprot-mctp-api                       │  Stack<C: MctpClient>
└───────────┬───────────────────────────────┘
            │ IPC / transport
            ▼
┌──────────────────────────┐
│   MCTP Server            │
└──────────────────────────┘
```

## Key types

| Type | Description |
|------|-------------|
| `FirmwareDevice<'a, O: FdOps, Cr: MctpClient, Cq: MctpClient>` | Owns the `CmdInterface` FW-update state machine plus the responder/requester `MctpPldmTransport`s; `run_terminus()` drives both to completion |
| `MctpPldmTransport<C: MctpClient>` | Wraps a `Stack<C>` and manages the MCTP PLDM framing byte (`0x01`) for sends/receives |
| `PldmServiceError` | Union of MCTP transport errors (`Mctp`), PLDM handler errors (`MsgHandler`), buffer/arithmetic overflow, and IPC errors |
| `PLDM_MSG_TYPE` (`pldm_common::util::mctp_transport::MCTP_PLDM_MSG_TYPE`) | MCTP message-type constant for PLDM (`0x01`) |

## Usage

```rust,ignore
use openprot_pldm_service::firmware_device::FirmwareDevice;
use openprot_pldm_service::MctpPldmTransport;
use pldm_interface::config::PLDM_PROTOCOL_CAPABILITIES;

// `fd_ops` implements `FdOps` (platform-specific flash / component logic).
// `responder_client` / `requester_client` are `MctpClient` implementations
// (they may share the same underlying MCTP endpoint).
let responder_transport = MctpPldmTransport::new(responder_client);
let requester_transport = MctpPldmTransport::new(requester_client);

let mut fd = FirmwareDevice::init(
    &fd_ops,
    &PLDM_PROTOCOL_CAPABILITIES,
    responder_transport,
    requester_transport,
);

const UA_EID: u8 = 8;
let mut buf = [0u8; 1024];

// `run_terminus` loops forever, interleaving inbound UA commands with any
// FD-initiated requests (e.g. RequestFirmwareData) once an update begins.
// It returns only on error; a `timeout_millis`/`requester_timeout_millis`
// of `0` blocks indefinitely while idle.
if let Err(e) = fd.run_terminus(UA_EID, &mut buf, 0, 0) {
    // handle or log error
}
```

## Buffer layout

All transport methods (`MctpPldmTransport::send_request`,
`recv_and_respond`, `respond_once`) and `FirmwareDevice::run_terminus` use the
same flat-buffer convention:

```text
buf[0]   : MCTP message-type byte (0x01) — managed by MctpPldmTransport
buf[1..] : PLDM request / response bytes
```

Size the buffer to accommodate the largest PLDM message your application
expects (typically ≤ 1024 bytes; smaller for embedded targets). See
`FD_MAX_MSG` in [`src/firmware_device.rs`](src/firmware_device.rs) for the
scratch-buffer size used internally for FD-initiated requests.

## Build

```
bazel build //services/pldm:pldm_service
```

Run the host-side integration tests:

```
bazel build -c dbg --strip=never //services/pldm:base_host_test
bazel build -c dbg --strip=never //services/pldm:firmware_update_host_test
```

After changing `pldm-common` / `pldm-interface` versions in
`third_party/crates_io/Cargo.toml`, re-pin the lock file. This repo is
bzlmod-only (no `WORKSPACE` file), so use `bazel build` with
`CARGO_BAZEL_REPIN=1`, not `bazel sync` (which errors with "WORKSPACE has to
be enabled"):

```
CARGO_BAZEL_REPIN=1 bazel build //services/pldm:pldm_service
```

## Dependencies

- [`openprot-mctp-api`](../mctp/api) — MCTP stack facade and traits
- [`pldm-interface`](https://github.com/OpenPRoT/pldm-lib/tree/main/pldm-interface) — PLDM command dispatcher (`CmdInterface`, `FdOps`, `FirmwareDeviceContext`)
- [`pldm-common`](https://github.com/OpenPRoT/pldm-lib/tree/main/pldm-common) — PLDM protocol types and MCTP transport helpers