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## Building
10
11```
12meson build/ && ninja -C build
13```
14
15## Unit test
16
17- Run it in OpenBMC CI, refer to [local-ci-build.md][1]
18- Run it in [OE SDK][2], run below commands in a x86-64 SDK env:
19  ```
20  meson -Doe-sdk=enabled -Dtests=enabled build/
21  ninja -C build/ test  # Meson skips running the case due to it thinks it's cross compiling
22  # Manually run the tests
23  for t in `find build/test/ -maxdepth 1 -name "test_*"`; do ./$t || break ; done
24  ```
25
26## Vendor-specific tools
27
28This repo contains generic code to handle the PSU versions and updates. It
29depends on vendor-specific tools to provide the below functions on the real PSU
30hardware:
31
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
38- `PSU_VERSION_UTIL`: It shall be defined as a command-line tool that accepts
39  the PSU inventory path as input, and outputs the PSU version string to stdout.
40- `PSU_VERSION_COMPARE_UTIL`: It shall be defined as a command-line tool that
41  accepts one or more PSU version strings, and outputs the latest version string
42  to stdout.
43- `PSU_UPDATE_SERVICE`: It shall be defined as a systemd service that accepts
44  two arguments:
45  - The PSU inventory DBus object;
46  - The path of the PSU image(s).
47
48For example:
49
50```
51meson -Dtests=disabled \
52    '-DPSU_VERSION_UTIL=/usr/bin/psutils --raw --get-version' \
53    '-DPSU_VERSION_COMPARE_UTIL=/usr/bin/psutils --raw --compare' \
54    '-DPSU_UPDATE_SERVICE=psu-update@.service' \
55    build
56```
57
58The above configures the vendor-specific tools to use `psutils` from
59[phosphor-power][3] to get and compare the PSU versions, and use
60`psu-update@.service` to perform the PSU firmware update, where internally it
61invokes `psutils` as well.
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 version
69objects under `/xyz/openbmc_project/software` that are associated with the PSU
70inventory path. If multiple PSUs are using the same version, multiple PSU
71inventory paths are associated.
72
73E.g.
74
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 --image <psu-image> --version <version> --model <model> --manufacturer \
137   <manufacturer> --machineName <machineName> --outfile <psu.tar> --sign
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 in BMC's
145   persistent storage defined by `IMG_DIR_PERSIST`. When a PSU is replaced, the
146   PSU's firmware version will be checked and updated if it's older than the one
147   stored in BMC.
1484. It is possible to put a PSU image and MANIFEST in the built-bin OpenBMC image
149   in BMC's read-only filesystem defined by `IMG_DIR_BUILTIN`. When the service
150   starts, it will compare the versions of the built-in image, the stored image
151   (after PSU update), and the existing PSUs, if there is any PSU that has an
152   older firmware, it will be updated to the newest one.
153
154[1]: https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md
155[2]:
156  https://github.com/openbmc/docs/blob/master/cheatsheet.md#building-the-openbmc-sdk
157[3]: https://github.com/openbmc/phosphor-power/tree/master/tools/power-utils
158[4]:
159  https://github.com/openbmc/phosphor-psu-code-mgmt/blob/master/tools/generate-psu-tar
160[5]:
161  https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md
162