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 5BMC, Chassis, and Host. The most critical feature of phosphor-state-manager 6software is its support for requests to power on and off the system by the user. 7 8This software also enforces any restore policy (i.e. auto power on system after 9a system power event or bmc reset) and ensures its states are updated correctly 10in situations where the BMC is rebooted and the chassis or host are in 11on/running states. 12 13This repository also provides a command line tool, obmcutil, which provides 14basic command line support to query and control phosphor-state-manager 15applications running within an OpenBMC system. This tool itself runs within an 16OpenBMC system and utilizes D-Bus APIs. These D-Bus APIs are used for 17development and debug and are not intended for end users. 18 19As with all OpenBMC applications, interfaces and properties within 20phosphor-state-manager are D-Bus interfaces. These interfaces are then used 21by external interface protocols, such as Redfish and IPMI, to report and 22control state to/by the end user. 23 24## State Tracking and Control 25 26phosphor-state-manager makes extensive use of systemd. There is a writeup 27[here][1] with an overview of systemd and its use by OpenBMC. 28 29phosphor-state-manager follows some basics design guidelines in its 30implementation and use of systemd: 31- Keep the different objects as independent as possible (host, chassis, bmc) 32- Use systemd targets for everything and keep the code within 33 phosphor-state-manager minimal 34- Ensure it can support required external interfaces, but don't necessarily 35 create 1x1 mappings otherwise every external interface will end up with its 36 own special chassis or host state request 37- If something like a hard power off can be done by just turning off the 38 chassis, don't provide a command in the host to do the same thing 39 40phosphor-state-manager implements states and state requests as defined in 41phosphor-dbus-interfaces for each object it supports. 42- [bmc][2]: The BMC has very minimal states. It is `Ready` once all services 43 within the default.target have executed. The only state change request you 44 can make of the BMC is for it to reboot itself. 45 - CurrentBMCState: NotReady, Ready 46 - RequestedBMCTransition: Reboot 47- [chassis][3]: The chassis represents the physical hardware in which the system 48 is contained. It usually has the power supplies, fans, and other hardware 49 associated with it. It can be either `On` or `Off`. 50 - CurrentPowerState: On, Off 51 - RequestedPowerTransition: On, Off 52- [host][4]: The host represents the software running on the system. In most 53 cases this is an operating system of some sort. The host can be `Off`, 54 `Running`, or `Quiesced`(error condition) 55 - CurrentHostState: Off, Running, Quiesced 56 - RequestedHostTransition: Off, On, Reboot 57 58As noted above, phosphor-state-manager provides a command line tool, 59[obmcutil][5], which takes a `state` parameter. This will use D-Bus commands to 60retrieve the above states and present them to the user. It also provides other 61commands which will send the appropriate D-Bus commands to the above properties 62to power on/off the chassis and host (see `obmcutil --help` within an OpenBMC 63system). 64 65The above objects also implement other D-Bus objects like power on hours, boot 66progress, reboot attempts, and operating system status. These D-Bus objects are 67also defined out in the phosphor-dbus-interfaces repository. 68 69## Restore Policy on Power Events 70 71The [RestorePolicy][6] defines the behavior the user wants when the BMC is 72reset. If the chassis or host is on/running then this service will not run. 73If they are off then the `RestorePolicy` will be read and executed by 74phosphor-state-manager code. 75 76## BMC Reset with Host and/or Chassis On 77 78In situations where the BMC is reset and the chassis and host are on and 79running, its critical that the BMC software do two things: 80- Never impact the state of the system (causing a power off of a running system 81is very bad) 82- Ensure the BMC, Chassis, and Host states accurately represent the state of the 83system. 84 85Note that some of this logic is provided via service files in system-specific 86meta layers. That is because the logic to determine if the chassis is on or 87if the host is running can vary from system to system. The requirement to 88create the files defined below and ensure the common targets go active is a 89must for anyone wishing to enable this feature. 90 91phosphor-state-manager discovers state vs. trying to cache and save states. This 92ensure it's always getting the most accurate state information. It discovers the 93chassis state by checking the `pgood` value from the power application. If it 94determines that power is on then it will do the following: 95- Create a file called /run/openbmc/chassis@0-on 96 - The presence of this file tells the services to alter their behavior because 97 the chassis is already powered on 98- Start the obmc-chassis-poweron@0.target 99 - The majority of services in this target will "fake start" due to the file 100 being present. They will report to systemd that they started and ran 101 successfully but they actually do nothing. This is what you would want in 102 this case. Power is already on so you don't want to run the services to turn 103 power on. You do want to get the obmc-chassis-poweron@0.target in the Active 104 state though so that the chassis object within phosphor-state-manager will 105 correctly report that the chassis is `On` 106- Start a service to check if the host is on 107 108The chassis@0-on file is removed when power is removed from the chassis. 109 110The logic to check if the host is on sends a command to the host, and if a 111response is received then similar logic to chassis is done: 112- Create a file called /run/openbmc/host@0-on 113- Start the obmc-host-start@0.target 114 - Similar to above, most services will not run due to the file being created 115 and their service files implementing a 116 "ConditionPathExists=!/run/openbmc/host@0-request" 117 118The host@0-on file is removed when the host is stopped. 119 120## Building the Code 121``` 122./bootstrap.sh 123./configure ${CONFIGURE_FLAGS} && make 124``` 125 126[1]: https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md 127[2]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/State/BMC.interface.yaml 128[3]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/State/Chassis.interface.yaml 129[4]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/State/Host.interface.yaml 130[5]: https://github.com/openbmc/phosphor-state-manager/blob/master/obmcutil 131[6]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Control/Power/RestorePolicy.interface.yaml 132