README: Add description about the usage of this repo
Add the description of several usage of this repo:
* How to generate a PSU image tarball;
* How to update the PSU image;
* How the version is updated when PSU is replaced.
Signed-off-by: Lei YU <mine260309@gmail.com>
Change-Id: I8727a27be138e03e6feecc26205f1c4b0adf8fbe
diff --git a/README.md b/README.md
index ebd479d..e6378bf 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,102 @@
`psu-update@.service` to perform the PSU firmware update, where
internally it invokes `psutils` as well.
+
+## Usage
+
+### PSU version
+
+When the service starts, it queries the inventory to get all the PSU inventory
+paths, invokes the vendor-specific tool to get the versions, and creates
+version objects under `/xyz/openbmc_project/software` that are associated with
+the PSU inventory path.
+If multiple PSUs are using the same version, multiple PSU inventory paths are
+associated.
+
+E.g.
+* Example of system with two PSUs that have different versions:
+ ```
+ "/xyz/openbmc_project/software/02572429": {
+ "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
+ "Associations": [
+ [
+ "inventory",
+ "activation",
+ "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
+ ]
+ ],
+ "ExtendedVersion": "",
+ "Path": "",
+ "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
+ "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
+ "Version": "01120114"
+ },
+ "/xyz/openbmc_project/software/7094f612": {
+ "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
+ "Associations": [
+ [
+ "inventory",
+ "activation",
+ "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
+ ]
+ ],
+ "ExtendedVersion": "",
+ "Path": "",
+ "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
+ "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
+ "Version": "00000110"
+ },
+ ```
+* Example of system with two PSUs that have the same version:
+ ```
+ "/xyz/openbmc_project/software/9463c2ad": {
+ "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
+ "Associations": [
+ [
+ "inventory",
+ "activation",
+ "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
+ ],
+ [
+ "inventory",
+ "activation",
+ "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
+ ]
+ ],
+ "ExtendedVersion": "",
+ "Path": "",
+ "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
+ "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
+ "Version": "01100110"
+ },
+ ```
+
+### PSU update
+
+1. Generate a tarball of PSU firmware image by [generate-psu-tar tool][4].
+ ```
+ ./generate-psu-tar -i <psu-image> -v <version> -model <model> -mf \
+ <manufacture> -o <psu.tar> -s
+ ```
+2. To update the PSU firmware, follow the same steps as described in
+ [code-update.md][5]:
+ * Upload a PSU image tarball and get the version ID;
+ * Set the RequestedActivation state of the uploaded image's version ID.
+ * Check the state and wait for the activation to be completed.
+3. After a successful update, the PSU image and the manifest is stored
+ in BMC's persistent storage defined by `IMG_DIR_PERSIST`. When a PSU
+ is replaced, the PSU's firmware version will be checked and updated if
+ it's older than the one stored in BMC.
+4. It is possible to put a PSU image and MANIFEST in the built-bin
+ OpenBMC image in BMC's read-only filesystem defined by
+ `IMG_DIR_BUILTIN`. When the service starts, it will compare the
+ versions of the built-in image, the stored image (after PSU update),
+ and the existing PSUs, if there is any PSU that has an older firmware,
+ it will be updated to the newest one.
+
+
[1]: https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md
[2]: https://github.com/openbmc/docs/blob/master/cheatsheet.md#building-the-openbmc-sdk
[3]: https://github.com/openbmc/phosphor-power/tree/master/tools/power-utils
+[4]: https://github.com/openbmc/phosphor-psu-code-mgmt/blob/master/tools/generate-psu-tar
+[5]: https://github.com/openbmc/docs/blob/master/code-update/code-update.md