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```text
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  ```text
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 updates. It
30depends on vendor-specific tools to provide the below functions on the real PSU
31hardware:
32
33- Get PSU firmware version
34- Compare the firmware version
35- Update the PSU firmware
36
37It provides configure options for vendor-specific tools for the above functions:
38
39- `PSU_VERSION_UTIL`: It shall be defined as a command-line tool that accepts
40  the PSU inventory path as input, and outputs the PSU version string to stdout.
41- `PSU_VERSION_COMPARE_UTIL`: It shall be defined as a command-line tool that
42  accepts one or more PSU version strings, and outputs the latest version string
43  to stdout.
44- `PSU_UPDATE_SERVICE`: It shall be defined as a systemd service that accepts
45  two arguments:
46  - The PSU inventory DBus object;
47  - The path of the PSU image(s).
48
49For example:
50
51```text
52meson -Dtests=disabled \
53    '-DPSU_VERSION_UTIL=/usr/bin/psutils --raw --get-version' \
54    '-DPSU_VERSION_COMPARE_UTIL=/usr/bin/psutils --raw --compare' \
55    '-DPSU_UPDATE_SERVICE=psu-update@.service' \
56    build
57```
58
59The above configures the vendor-specific tools to use `psutils` from
60[phosphor-power][3] to get and compare the PSU versions, and use
61`psu-update@.service` to perform the PSU firmware update, where internally it
62invokes `psutils` as well.
63
64## Usage
65
66### PSU version
67
68When the service starts, it queries the inventory to get all the PSU inventory
69paths, invokes the vendor-specific tool to get the versions, and creates version
70objects under `/xyz/openbmc_project/software` that are associated with the PSU
71inventory path. If multiple PSUs are using the same version, multiple PSU
72inventory paths are associated.
73
74E.g.
75
76- Example of system with two PSUs that have different versions:
77
78  ```text
79   "/xyz/openbmc_project/software/02572429": {
80     "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
81     "Associations": [
82       [
83         "inventory",
84         "activation",
85         "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
86       ]
87     ],
88     "ExtendedVersion": "",
89     "Path": "",
90     "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
91     "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
92     "Version": "01120114"
93   },
94   "/xyz/openbmc_project/software/7094f612": {
95     "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
96     "Associations": [
97       [
98         "inventory",
99         "activation",
100         "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
101       ]
102     ],
103     "ExtendedVersion": "",
104     "Path": "",
105     "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
106     "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
107     "Version": "00000110"
108   },
109  ```
110
111- Example of system with two PSUs that have the same version:
112
113  ```text
114   "/xyz/openbmc_project/software/9463c2ad": {
115     "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active",
116     "Associations": [
117       [
118         "inventory",
119         "activation",
120         "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
121       ],
122       [
123         "inventory",
124         "activation",
125         "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
126       ]
127     ],
128     "ExtendedVersion": "",
129     "Path": "",
130     "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU",
131     "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None",
132     "Version": "01100110"
133   },
134  ```
135
136### PSU update
137
1381. Generate a tarball of PSU firmware image by [generate-psu-tar tool][4].
139
140   ```text
141   ./generate-psu-tar --image <psu-image> --version <version> --model <model> --manufacturer \
142   <manufacturer> --machineName <machineName> --outfile <psu.tar> --sign
143   ```
144
1452. To update the PSU firmware, follow the same steps as described in
146   [code-update.md][5]:
147   - Upload a PSU image tarball and get the version ID;
148   - Set the RequestedActivation state of the uploaded image's version ID.
149   - Check the state and wait for the activation to be completed.
1503. After a successful update, the PSU image and the manifest is stored in BMC's
151   persistent storage defined by `IMG_DIR_PERSIST`. When a PSU is replaced, the
152   PSU's firmware version will be checked and updated if it's older than the one
153   stored in BMC.
1544. It is possible to put a PSU image and MANIFEST in the built-bin OpenBMC image
155   in BMC's read-only filesystem defined by `IMG_DIR_BUILTIN`. When the service
156   starts, it will compare the versions of the built-in image, the stored image
157   (after PSU update), and the existing PSUs, if there is any PSU that has an
158   older firmware, it will be updated to the newest one.
159
160[1]: https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md
161[2]:
162  https://github.com/openbmc/docs/blob/master/cheatsheet.md#building-the-openbmc-sdk
163[3]: https://github.com/openbmc/phosphor-power/tree/master/tools/power-utils
164[4]:
165  https://github.com/openbmc/phosphor-psu-code-mgmt/blob/master/tools/generate-psu-tar
166[5]:
167  https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md
168