1# phosphor-psu-code-mgmt
2
3phosphor-psu-code-mgmt is a service to provide management for PSU code,
4including:
5
6* PSU code version
7* PSU code update
8
9
10## Building
11
12```
13meson build/ && ninja -C build
14```
15
16## Unit test
17
18* Run it in OpenBMC CI, refer to [local-ci-build.md][1]
19* Run it in [OE SDK][2], run below commands in a x86-64 SDK env:
20   ```
21   meson -Doe-sdk=enabled -Dtests=enabled build/
22   ninja -C build/ test  # Meson skips running the case due to it thinks it's cross compiling
23   # Manually run the tests
24   for t in `find build/test/ -maxdepth 1 -name "test_*"`; do ./$t || break ; done
25   ```
26
27## Vendor-specific tools
28
29This repo contains generic code to handle the PSU versions and
30updates. It depends on vendor-specific tools to provide the below
31functions on the real PSU hardware:
32* Get PSU firmware version
33* Compare the firmware version
34* Update the PSU firmware
35
36It provides configure options for vendor-specific tools for the above functions:
37* `PSU_VERSION_UTIL`: It shall be defined as a command-line tool that
38accepts the PSU inventory path as input, and outputs the PSU version
39string to stdout.
40* `PSU_VERSION_COMPARE_UTIL`: It shall be defined as a command-line
41tool that accepts one or more PSU version strings, and outputs the
42latest version string to stdout.
43* `PSU_UPDATE_SERVICE`: It shall be defined as a systemd service that
44accepts two arguments:
45   * The PSU inventory DBus object;
46   * The path of the PSU image(s).
47
48For example:
49```
50meson -Dtests=disabled \
51    '-DPSU_VERSION_UTIL=/usr/bin/psutils --raw --get-version' \
52    '-DPSU_VERSION_COMPARE_UTIL=/usr/bin/psutils --raw --compare' \
53    '-DPSU_UPDATE_SERVICE=psu-update@.service' \
54    build
55```
56
57The above configures the vendor-specific tools to use `psutils` from
58[phosphor-power][3] to get and compare the PSU versions, and use
59`psu-update@.service` to perform the PSU firmware update, where
60internally it invokes `psutils` as well.
61
62
63## Usage
64
65### PSU version
66
67When the service starts, it queries the inventory to get all the PSU inventory
68paths, invokes the vendor-specific tool to get the versions, and creates
69version objects under `/xyz/openbmc_project/software` that are associated with
70the PSU inventory path.
71If multiple PSUs are using the same version, multiple PSU inventory paths are
72associated.
73
74E.g.
75* Example of system with two PSUs that have different versions:
76   ```
77    "/xyz/openbmc_project/software/02572429": {
78      "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
79      "Associations": [
80        [
81          "inventory",
82          "activation",
83          "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
84        ]
85      ],
86      "ExtendedVersion": "",
87      "Path": "",
88      "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
89      "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
90      "Version": "01120114"
91    },
92    "/xyz/openbmc_project/software/7094f612": {
93      "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
94      "Associations": [
95        [
96          "inventory",
97          "activation",
98          "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
99        ]
100      ],
101      "ExtendedVersion": "",
102      "Path": "",
103      "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
104      "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
105      "Version": "00000110"
106    },
107   ```
108* Example of system with two PSUs that have the same version:
109   ```
110    "/xyz/openbmc_project/software/9463c2ad": {
111      "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
112      "Associations": [
113        [
114          "inventory",
115          "activation",
116          "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
117        ],
118        [
119          "inventory",
120          "activation",
121          "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
122        ]
123      ],
124      "ExtendedVersion": "",
125      "Path": "",
126      "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
127      "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
128      "Version": "01100110"
129    },
130   ```
131
132### PSU update
133
1341. Generate a tarball of PSU firmware image by [generate-psu-tar tool][4].
135   ```
136   ./generate-psu-tar -i <psu-image> -v <version> -model <model> -mf \
137   <manufacture> -o <psu.tar> -s
138   ```
1392. To update the PSU firmware, follow the same steps as described in
140   [code-update.md][5]:
141   * Upload a PSU image tarball and get the version ID;
142   * Set the RequestedActivation state of the uploaded image's version ID.
143   * Check the state and wait for the activation to be completed.
1443. After a successful update, the PSU image and the manifest is stored
145   in BMC's persistent storage defined by `IMG_DIR_PERSIST`. When a PSU
146   is replaced, the PSU's firmware version will be checked and updated if
147   it's older than the one stored in BMC.
1484. It is possible to put a PSU image and MANIFEST in the built-bin
149   OpenBMC image in BMC's read-only filesystem defined by
150   `IMG_DIR_BUILTIN`. When the service starts, it will compare the
151   versions of the built-in image, the stored image (after PSU update),
152   and the existing PSUs, if there is any PSU that has an older firmware,
153   it will be updated to the newest one.
154
155
156[1]: https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md
157[2]: https://github.com/openbmc/docs/blob/master/cheatsheet.md#building-the-openbmc-sdk
158[3]: https://github.com/openbmc/phosphor-power/tree/master/tools/power-utils
159[4]: https://github.com/openbmc/phosphor-psu-code-mgmt/blob/master/tools/generate-psu-tar
160[5]: https://github.com/openbmc/docs/blob/master/code-update/code-update.md
161