1# Phosphor State Manager Documentation 2 3This repository contains the software responsible for tracking and controlling 4the state of different objects within OpenBMC. This currently includes the BMC, 5Chassis, Host, and Hypervisor. The most critical feature of 6phosphor-state-manager (PSM) software is its support for requests to power on 7and off the system by the user. 8 9This software also enforces any restore policy (i.e. auto power on system after 10a system power event or bmc reset) and ensures its states are updated correctly 11in situations where the BMC is rebooted and the chassis or host are in 12on/running states. 13 14This repository also provides a command line tool, obmcutil, which provides 15basic command line support to query and control phosphor-state-manager 16applications running within an OpenBMC system. This tool itself runs within an 17OpenBMC system and utilizes D-Bus APIs. These D-Bus APIs are used for 18development and debug and are not intended for end users. 19 20As with all OpenBMC applications, interfaces and properties within 21phosphor-state-manager are D-Bus interfaces. These interfaces are then used by 22external interface protocols, such as Redfish and IPMI, to report and control 23state to/by the end user. 24 25## State Tracking and Control 26 27phosphor-state-manager makes extensive use of systemd. There is a writeup 28[here][1] with an overview of systemd and its use by OpenBMC. 29 30phosphor-state-manager monitors for systemd targets to complete as a trigger to 31updating the its corresponding D-Bus property. When using PSM, a user must 32ensure all generic services installed within the PSM targets complete 33successfully in order to have PSM properly report states. 34 35phosphor-state-manager follows some basics design guidelines in its 36implementation and use of systemd: 37 38- Keep the different objects as independent as possible (host, chassis, bmc) 39- Use systemd targets for everything and keep the code within PSM minimal 40- Ensure it can support required external interfaces, but don't necessarily 41 create 1x1 mappings otherwise every external interface will end up with its 42 own special chassis or host state request 43- If something like a hard power off can be done by just turning off the 44 chassis, don't provide a command in the host to do the same thing 45 46phosphor-state-manager implements states and state requests as defined in 47phosphor-dbus-interfaces for each object it supports. 48 49- [bmc][2]: The BMC has very minimal states. It is `NotReady` when first started 50 and `Ready` once all services within the default.target have executed. It is 51 `Quiesced` when a critical service has entered the failed state. The only 52 state change request you can make of the BMC is for it to reboot itself. 53 - CurrentBMCState: NotReady, Ready, Quiesced 54 - RequestedBMCTransition: Reboot 55 - Monitored systemd targets: multi-user.target and 56 obmc-bmc-service-quiesce\@.target 57- [chassis][3]: The chassis represents the physical hardware in which the system 58 is contained. It usually has the power supplies, fans, and other hardware 59 associated with it. It can be either `On`, `Off`, or in a fail state. A 60 `BrownOut` state indicates there is not enough chassis power to fully power on 61 and `UninterruptiblePowerSupply` indicates the chassis is running on a UPS. 62 - CurrentPowerState: On, Off, BrownOut, UninterruptiblePowerSupply 63 - RequestedPowerTransition: On, Off 64 - Monitored systemd targets: obmc-chassis-poweron\@.target, 65 obmc-chassis-poweroff\@.target 66- [host][4]: The host represents the software running on the system. In most 67 cases this is an operating system of some sort. The host can be `Off`, 68 `Running`, `TransitioningToRunning`, `TransitioningToOff`, `Quiesced`(error 69 condition), or in `DiagnosticMode`(collecting diagnostic data for a failure) 70 - CurrentHostState: Off, Running, TransitioningToRunning, TransitioningToOff, 71 Quiesced, DiagnosticMode 72 - RequestedHostTransition: Off, On, Reboot, GracefulWarmReboot, 73 ForceWarmReboot 74 - Monitored systemd targets: obmc-host-startmin\@.target, 75 obmc-host-stop\@.target, obmc-host-quiesce\@.target, 76 obmc-host-diagnostic-mode\@.target 77- [hypervisor][4]: The hypervisor is an optional package systems can install 78 which tracks the state of the hypervisor on the system. This state manager 79 object implements a limited subset of the host D-Bus interface. 80 - CurrentHostState: Standby, TransitionToRunning, Running, Off, Quiesced 81 - RequestedHostTransition: On 82 83As noted above, PSM provides a command line tool, [obmcutil][5], which takes a 84`state` parameter. This will use D-Bus commands to retrieve the above states and 85present them to the user. It also provides other commands which will send the 86appropriate D-Bus commands to the above properties to power on/off the chassis 87and host (see `obmcutil --help` within an OpenBMC system). 88 89The above objects also implement other D-Bus objects like power on hours, boot 90progress, reboot attempts, and operating system status. These D-Bus objects are 91also defined out in the phosphor-dbus-interfaces repository. 92 93## Restore Policy on Power Events 94 95The [RestorePolicy][6] defines the behavior the user wants when the BMC is 96reset. If the chassis or host is on/running then this service will not run. If 97they are off then the `RestorePolicy` will be read and executed by PSM code. 98 99The `PowerRestoreDelay` property within the interface defines a maximum time the 100service will wait for the BMC to enter the `Ready` state before issuing the 101power on request, this allows host to be powered on as early as the BMC is 102ready. 103 104## Only Allow System Boot When BMC Ready 105 106There is an optional `only-allow-boot-when-bmc-ready` feature which can be 107enabled within PSM that will not allow chassis or host operations (other then 108`Off` requests) if the BMC is not in a `Ready` state. Care should be taken to 109ensure `PowerRestoreDelay` is set to a suitable value to ensure the BMC reaches 110`Ready` before the power restore function requests the power on. 111 112## BMC Reset with Host and/or Chassis On 113 114In situations where the BMC is reset and the chassis and host are on and 115running, its critical that the BMC software do two things: 116 117- Never impact the state of the system (causing a power off of a running system 118 is very bad) 119- Ensure the BMC, Chassis, and Host states accurately represent the state of the 120 system. 121 122Note that some of this logic is provided via service files in system-specific 123meta layers. That is because the logic to determine if the chassis is on or if 124the host is running can vary from system to system. The requirement to create 125the files defined below and ensure the common targets go active is a must for 126anyone wishing to enable this feature. 127 128phosphor-state-manager discovers state vs. trying to cache and save states. This 129ensure it's always getting the most accurate state information. It discovers the 130chassis state by checking the `pgood` value from the power application. If it 131determines that power is on then it will do the following: 132 133- Create a file called /run/openbmc/chassis@0-on 134 - The presence of this file tells the services to alter their behavior because 135 the chassis is already powered on 136- Start the obmc-chassis-poweron\@0.target 137 - The majority of services in this target will "fake start" due to the file 138 being present. They will report to systemd that they started and ran 139 successfully but they actually do nothing. This is what you would want in 140 this case. Power is already on so you don't want to run the services to turn 141 power on. You do want to get the obmc-chassis-poweron\@0.target in the 142 Active state though so that the chassis object within PSM will correctly 143 report that the chassis is `On` 144- Start a service to check if the host is on 145 146The chassis@0-on file is removed once the obmc-chassis-poweron\@0.target becomes 147active (i.e. all service have been successfully started which are wanted or 148required by this target). 149 150The logic to check if the host is on sends a command to the host, and if a 151response is received then similar logic to chassis is done: 152 153- Create a file called /run/openbmc/host@0-on 154- Start the obmc-host-start\@0.target 155 - Similar to above, most services will not run due to the file being created 156 and their service files implementing a 157 "ConditionPathExists=!/run/openbmc/host@0-request" 158 159The host@0-on file is removed once the obmc-host-start\@0.target and 160obmc-host-startmin\@0.target become active (i.e. all service have been 161successfully started which are wanted or required by these targets). 162 163## Building the Code 164 165To build this package, do the following steps: 166 1671. `meson setup build` 1682. `ninja -C build` 169 170To clean the repository again run `rm -rf build`. 171 172[1]: https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md 173[2]: 174 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml 175[3]: 176 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Chassis.interface.yaml 177[4]: 178 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Host.interface.yaml 179[5]: https://github.com/openbmc/phosphor-state-manager/blob/master/obmcutil 180[6]: 181 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Power/RestorePolicy.interface.yaml 182