From 4ba423a09f217709735031fd79dc38ee134a3f15 Mon Sep 17 00:00:00 2001 From: Jeremy Kerr Date: Mon, 9 Jun 2025 14:59:16 +0800 Subject: [PATCH] pldm-fw, pldm-fw-cli: Split README content into library and cli components The `pldm-fw` binary used to live in the `pldm-fw` crate. This has since been split into library and binary crates, but the README remained in the library crate. Since `pldm-fw-cli` is more end-user visible, split the cli details out into the crate README. Signed-off-by: Jeremy Kerr --- pldm-fw-cli/README.md | 56 +++++++++++++++++++++++++++++++++++++++++++ pldm-fw/README.md | 38 +++++------------------------ 2 files changed, 62 insertions(+), 32 deletions(-) create mode 100644 pldm-fw-cli/README.md diff --git a/pldm-fw-cli/README.md b/pldm-fw-cli/README.md new file mode 100644 index 0000000..ec3f776 --- /dev/null +++ b/pldm-fw-cli/README.md @@ -0,0 +1,56 @@ +PLDM for Firmware Update command-line Update Agent +-------------------------------------------------- + +This crate contains the `pldm-fw` command-line utility: a PLDM for Firmware +Update ("PLDM type 5") Update Agent (UA). This can be used to interact with +devices that implement the PLDM type 5 for their firmware management functions +("firmware devices", or FD), and PLDM firmware package files. + +This utility is a small wrapper around the [`pldm-fw`](../pldm-fw) crate, which +implements the actual update and package-handling logic. + +Usage +===== + +`pldm-fw` has a subcommand-style interface, to invoke one of the query or +update functions of the utility. + +``` +$ pldm-fw --help +Usage: pldm-fw [] + +PLDM update utility + +Options: + --help display usage information + +Commands: + inventory Query FD inventory + update Update FD from a package file + cancel Cancel ongoing update + pkg-info Query package contents + version Print pldm-fw version + extract Extract package contents +``` + +Each command provides its own usage information. For example, for the +`inventory` command: + +``` +$ pldm-fw inventory --help +Usage: pldm-fw inventory + +Query FD inventory + +Positional Arguments: + addr MCTP net/EID of device + +Options: + --help display usage information +``` + +Operations that interact with a FD (`inventory`, `update` and `cancel`) will +require an argument that specifies the MCTP address of the device; this is in +`,` format, representing the MCTP network ID, and MCTP endpoint ID. +The `,` portion is optional; if not specified, the system default network +will be used. diff --git a/pldm-fw/README.md b/pldm-fw/README.md index 9faf35e..d7ae415 100644 --- a/pldm-fw/README.md +++ b/pldm-fw/README.md @@ -2,42 +2,16 @@ PLDM for Firmware Update library and utilities ---------------------------------------------- This crate provides a PLDM for Firmware Update ("PLDM type 5") implementation -in Rust, both as a library and a small command-line utility. +in Rust, as a library. This uses the common [`mctp` traits](../mctp) crate for +communication, and is intended for use in both embedded and standard +environments. PLDM type 5 is defined by DMTF DSP0267. This crate supports v1.1.0 and v1.2.0 of that specification. -The library ------------ - The `pldm-fw` library provides type definitions and serialisation implementations for type-5 communication. The `pkg` module provides support for -reading PLDM package files, which can then be used for updates - -The `pldm-fw` utility ---------------------- - -The `pldm-fw` utility uses the library to implement a fairly basic firmware -updater. `pldm-fw` provides a few subcommands for querying a device's firmware -inventory, printing the contents of an update package, and applying an -update package to a device. - -``` -$ pldm-fw --help -Usage: pldm-fw [] - -PLDM update utility - -Options: - --help display usage information - -Commands: - inventory Query FD inventory - update Update FD from a package file - cancel Cancel ongoing update - pkg-info Query package contents - version Print pldm-fw version - extract Extract package contents -``` - +reading PLDM package files, which can then be used for updates. +The related [`pldm-fw-cli`](../pldm-fw-cli) crate uses this crate to implement a +small firmware update agent (UA) as a Linux command-line utility.