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 6b8f30754SPatrick Williams- PSU code version 7b8f30754SPatrick 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 17b8f30754SPatrick Williams- Run it in OpenBMC CI, refer to [local-ci-build.md][1] 18b8f30754SPatrick 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 28b8f30754SPatrick WilliamsThis repo contains generic code to handle the PSU versions and updates. It 29b8f30754SPatrick Williamsdepends on vendor-specific tools to provide the below functions on the real PSU 30b8f30754SPatrick Williamshardware: 31b8f30754SPatrick Williams 32b8f30754SPatrick Williams- Get PSU firmware version 33b8f30754SPatrick Williams- Compare the firmware version 34b8f30754SPatrick Williams- Update the PSU firmware 358ccc653eSLei YU 368ccc653eSLei YUIt provides configure options for vendor-specific tools for the above functions: 37b8f30754SPatrick Williams 38b8f30754SPatrick Williams- `PSU_VERSION_UTIL`: It shall be defined as a command-line tool that accepts 39b8f30754SPatrick Williams the PSU inventory path as input, and outputs the PSU version string to stdout. 40b8f30754SPatrick Williams- `PSU_VERSION_COMPARE_UTIL`: It shall be defined as a command-line tool that 41b8f30754SPatrick Williams accepts one or more PSU version strings, and outputs the latest version string 42b8f30754SPatrick Williams to stdout. 43b8f30754SPatrick Williams- `PSU_UPDATE_SERVICE`: It shall be defined as a systemd service that accepts 44b8f30754SPatrick Williams two arguments: 45b8f30754SPatrick Williams - The PSU inventory DBus object; 46b8f30754SPatrick Williams - The path of the PSU image(s). 478ccc653eSLei YU 488ccc653eSLei YUFor example: 49b8f30754SPatrick 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 60b8f30754SPatrick Williams`psu-update@.service` to perform the PSU firmware update, where internally it 61b8f30754SPatrick 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 68b8f30754SPatrick Williamspaths, invokes the vendor-specific tool to get the versions, and creates version 69b8f30754SPatrick Williamsobjects under `/xyz/openbmc_project/software` that are associated with the PSU 70b8f30754SPatrick Williamsinventory path. If multiple PSUs are using the same version, multiple PSU 71b8f30754SPatrick Williamsinventory paths are associated. 72c6db1142SLei YU 73c6db1142SLei YUE.g. 74b8f30754SPatrick Williams 75b8f30754SPatrick 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 ``` 108b8f30754SPatrick 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 ``` 136*4ba2edccSChicago Duan ./generate-psu-tar --image <psu-image> --version <version> --model <model> --manufacturer \ 137*4ba2edccSChicago Duan <manufacturer> --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]: 141b8f30754SPatrick Williams - Upload a PSU image tarball and get the version ID; 142b8f30754SPatrick Williams - Set the RequestedActivation state of the uploaded image's version ID. 143b8f30754SPatrick Williams - Check the state and wait for the activation to be completed. 144b8f30754SPatrick Williams3. After a successful update, the PSU image and the manifest is stored in BMC's 145b8f30754SPatrick Williams persistent storage defined by `IMG_DIR_PERSIST`. When a PSU is replaced, the 146b8f30754SPatrick Williams PSU's firmware version will be checked and updated if it's older than the one 147b8f30754SPatrick Williams stored in BMC. 148b8f30754SPatrick Williams4. It is possible to put a PSU image and MANIFEST in the built-bin OpenBMC image 149b8f30754SPatrick Williams in BMC's read-only filesystem defined by `IMG_DIR_BUILTIN`. When the service 150b8f30754SPatrick Williams starts, it will compare the versions of the built-in image, the stored image 151b8f30754SPatrick Williams (after PSU update), and the existing PSUs, if there is any PSU that has an 152b8f30754SPatrick 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 155b8f30754SPatrick Williams[2]: 156b8f30754SPatrick 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 158b8f30754SPatrick Williams[4]: 159b8f30754SPatrick Williams https://github.com/openbmc/phosphor-psu-code-mgmt/blob/master/tools/generate-psu-tar 160b8f30754SPatrick Williams[5]: 161b8f30754SPatrick Williams https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md 162