19b846121SLei YU# phosphor-psu-code-mgmt 29b846121SLei YU 39b846121SLei YUphosphor-psu-code-mgmt is a service to provide management for PSU code, 49b846121SLei YUincluding: 59b846121SLei YU 6*b8f30754SPatrick Williams- PSU code version 7*b8f30754SPatrick Williams- PSU code update 89b846121SLei YU 99b846121SLei YU## Building 109b846121SLei YU 119b846121SLei YU``` 129b846121SLei YUmeson build/ && ninja -C build 139b846121SLei YU``` 149b846121SLei YU 159b846121SLei YU## Unit test 169b846121SLei YU 17*b8f30754SPatrick Williams- Run it in OpenBMC CI, refer to [local-ci-build.md][1] 18*b8f30754SPatrick Williams- Run it in [OE SDK][2], run below commands in a x86-64 SDK env: 199b846121SLei YU ``` 209b846121SLei YU meson -Doe-sdk=enabled -Dtests=enabled build/ 219b846121SLei YU ninja -C build/ test # Meson skips running the case due to it thinks it's cross compiling 229b846121SLei YU # Manually run the tests 239b846121SLei YU for t in `find build/test/ -maxdepth 1 -name "test_*"`; do ./$t || break ; done 249b846121SLei YU ``` 259b846121SLei YU 268ccc653eSLei YU## Vendor-specific tools 278ccc653eSLei YU 28*b8f30754SPatrick WilliamsThis repo contains generic code to handle the PSU versions and updates. It 29*b8f30754SPatrick Williamsdepends on vendor-specific tools to provide the below functions on the real PSU 30*b8f30754SPatrick Williamshardware: 31*b8f30754SPatrick Williams 32*b8f30754SPatrick Williams- Get PSU firmware version 33*b8f30754SPatrick Williams- Compare the firmware version 34*b8f30754SPatrick Williams- Update the PSU firmware 358ccc653eSLei YU 368ccc653eSLei YUIt provides configure options for vendor-specific tools for the above functions: 37*b8f30754SPatrick Williams 38*b8f30754SPatrick Williams- `PSU_VERSION_UTIL`: It shall be defined as a command-line tool that accepts 39*b8f30754SPatrick Williams the PSU inventory path as input, and outputs the PSU version string to stdout. 40*b8f30754SPatrick Williams- `PSU_VERSION_COMPARE_UTIL`: It shall be defined as a command-line tool that 41*b8f30754SPatrick Williams accepts one or more PSU version strings, and outputs the latest version string 42*b8f30754SPatrick Williams to stdout. 43*b8f30754SPatrick Williams- `PSU_UPDATE_SERVICE`: It shall be defined as a systemd service that accepts 44*b8f30754SPatrick Williams two arguments: 45*b8f30754SPatrick Williams - The PSU inventory DBus object; 46*b8f30754SPatrick Williams - The path of the PSU image(s). 478ccc653eSLei YU 488ccc653eSLei YUFor example: 49*b8f30754SPatrick Williams 508ccc653eSLei YU``` 518ccc653eSLei YUmeson -Dtests=disabled \ 528ccc653eSLei YU '-DPSU_VERSION_UTIL=/usr/bin/psutils --raw --get-version' \ 538ccc653eSLei YU '-DPSU_VERSION_COMPARE_UTIL=/usr/bin/psutils --raw --compare' \ 548ccc653eSLei YU '-DPSU_UPDATE_SERVICE=psu-update@.service' \ 558ccc653eSLei YU build 568ccc653eSLei YU``` 578ccc653eSLei YU 588ccc653eSLei YUThe above configures the vendor-specific tools to use `psutils` from 598ccc653eSLei YU[phosphor-power][3] to get and compare the PSU versions, and use 60*b8f30754SPatrick Williams`psu-update@.service` to perform the PSU firmware update, where internally it 61*b8f30754SPatrick Williamsinvokes `psutils` as well. 62c6db1142SLei YU 63c6db1142SLei YU## Usage 64c6db1142SLei YU 65c6db1142SLei YU### PSU version 66c6db1142SLei YU 67c6db1142SLei YUWhen the service starts, it queries the inventory to get all the PSU inventory 68*b8f30754SPatrick Williamspaths, invokes the vendor-specific tool to get the versions, and creates version 69*b8f30754SPatrick Williamsobjects under `/xyz/openbmc_project/software` that are associated with the PSU 70*b8f30754SPatrick Williamsinventory path. If multiple PSUs are using the same version, multiple PSU 71*b8f30754SPatrick Williamsinventory paths are associated. 72c6db1142SLei YU 73c6db1142SLei YUE.g. 74*b8f30754SPatrick Williams 75*b8f30754SPatrick Williams- Example of system with two PSUs that have different versions: 76c6db1142SLei YU ``` 77c6db1142SLei YU "/xyz/openbmc_project/software/02572429": { 78c6db1142SLei YU "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active", 79c6db1142SLei YU "Associations": [ 80c6db1142SLei YU [ 81c6db1142SLei YU "inventory", 82c6db1142SLei YU "activation", 83c6db1142SLei YU "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1" 84c6db1142SLei YU ] 85c6db1142SLei YU ], 86c6db1142SLei YU "ExtendedVersion": "", 87c6db1142SLei YU "Path": "", 88c6db1142SLei YU "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU", 89c6db1142SLei YU "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None", 90c6db1142SLei YU "Version": "01120114" 91c6db1142SLei YU }, 92c6db1142SLei YU "/xyz/openbmc_project/software/7094f612": { 93c6db1142SLei YU "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active", 94c6db1142SLei YU "Associations": [ 95c6db1142SLei YU [ 96c6db1142SLei YU "inventory", 97c6db1142SLei YU "activation", 98c6db1142SLei YU "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0" 99c6db1142SLei YU ] 100c6db1142SLei YU ], 101c6db1142SLei YU "ExtendedVersion": "", 102c6db1142SLei YU "Path": "", 103c6db1142SLei YU "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU", 104c6db1142SLei YU "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None", 105c6db1142SLei YU "Version": "00000110" 106c6db1142SLei YU }, 107c6db1142SLei YU ``` 108*b8f30754SPatrick Williams- Example of system with two PSUs that have the same version: 109c6db1142SLei YU ``` 110c6db1142SLei YU "/xyz/openbmc_project/software/9463c2ad": { 111c6db1142SLei YU "Activation": "xyz.openbmc_project.Software.Activation.Activations.Active", 112c6db1142SLei YU "Associations": [ 113c6db1142SLei YU [ 114c6db1142SLei YU "inventory", 115c6db1142SLei YU "activation", 116c6db1142SLei YU "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0" 117c6db1142SLei YU ], 118c6db1142SLei YU [ 119c6db1142SLei YU "inventory", 120c6db1142SLei YU "activation", 121c6db1142SLei YU "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1" 122c6db1142SLei YU ] 123c6db1142SLei YU ], 124c6db1142SLei YU "ExtendedVersion": "", 125c6db1142SLei YU "Path": "", 126c6db1142SLei YU "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.PSU", 127c6db1142SLei YU "RequestedActivation": "xyz.openbmc_project.Software.Activation.RequestedActivations.None", 128c6db1142SLei YU "Version": "01100110" 129c6db1142SLei YU }, 130c6db1142SLei YU ``` 131c6db1142SLei YU 132c6db1142SLei YU### PSU update 133c6db1142SLei YU 134c6db1142SLei YU1. Generate a tarball of PSU firmware image by [generate-psu-tar tool][4]. 135c6db1142SLei YU ``` 136d48ae5fbSChicago Duan ./generate-psu-tar --image <psu-image> --version <version> --model <model> --manufacture \ 137d48ae5fbSChicago Duan <manufacture> --machineName <machineName> --outfile <psu.tar> --sign 138c6db1142SLei YU ``` 139c6db1142SLei YU2. To update the PSU firmware, follow the same steps as described in 140c6db1142SLei YU [code-update.md][5]: 141*b8f30754SPatrick Williams - Upload a PSU image tarball and get the version ID; 142*b8f30754SPatrick Williams - Set the RequestedActivation state of the uploaded image's version ID. 143*b8f30754SPatrick Williams - Check the state and wait for the activation to be completed. 144*b8f30754SPatrick Williams3. After a successful update, the PSU image and the manifest is stored in BMC's 145*b8f30754SPatrick Williams persistent storage defined by `IMG_DIR_PERSIST`. When a PSU is replaced, the 146*b8f30754SPatrick Williams PSU's firmware version will be checked and updated if it's older than the one 147*b8f30754SPatrick Williams stored in BMC. 148*b8f30754SPatrick Williams4. It is possible to put a PSU image and MANIFEST in the built-bin OpenBMC image 149*b8f30754SPatrick Williams in BMC's read-only filesystem defined by `IMG_DIR_BUILTIN`. When the service 150*b8f30754SPatrick Williams starts, it will compare the versions of the built-in image, the stored image 151*b8f30754SPatrick Williams (after PSU update), and the existing PSUs, if there is any PSU that has an 152*b8f30754SPatrick Williams older firmware, it will be updated to the newest one. 153c6db1142SLei YU 1541799f381SGunnar Mills[1]: https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md 155*b8f30754SPatrick Williams[2]: 156*b8f30754SPatrick Williams https://github.com/openbmc/docs/blob/master/cheatsheet.md#building-the-openbmc-sdk 1578ccc653eSLei YU[3]: https://github.com/openbmc/phosphor-power/tree/master/tools/power-utils 158*b8f30754SPatrick Williams[4]: 159*b8f30754SPatrick Williams https://github.com/openbmc/phosphor-psu-code-mgmt/blob/master/tools/generate-psu-tar 160*b8f30754SPatrick Williams[5]: 161*b8f30754SPatrick Williams https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md 162