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