openbmc/phosphor-state-manager/README.md

1 # Phosphor State Manager Documentation
6 phosphor-state-manager (PSM) software is its support for requests to power on
9 This software also enforces any restore policy (i.e. auto power on system after
10 a system power event or bmc reset) and ensures its states are updated correctly
15 basic command line support to query and control phosphor-state-manager
17 OpenBMC system and utilizes D-Bus APIs. These D-Bus APIs are used for
21 phosphor-state-manager are D-Bus interfaces. These interfaces are then used by
27 phosphor-state-manager makes extensive use of systemd. There is a writeup
30 phosphor-state-manager monitors for systemd targets to complete as a trigger to
31 updating the its corresponding D-Bus property. When using PSM, a user must
35 phosphor-state-manager follows some basics design guidelines in its
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
43 - If something like a hard power off can be done by just turning off the
46 phosphor-state-manager implements states and state requests as defined in
47 phosphor-dbus-interfaces for each object it supports.
49 - [bmc][2]: The BMC has very minimal states. It is `NotReady` when first started
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
60   `BrownOut` state indicates there is not enough chassis power to fully power on
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
70   - CurrentHostState: Off, Running, TransitioningToRunning, TransitioningToOff,
72   - RequestedHostTransition: Off, On, Reboot, GracefulWarmReboot,
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
84 `state` parameter. This will use D-Bus commands to retrieve the above states and
86 appropriate D-Bus commands to the above properties to power on/off the chassis
87 and host (see `obmcutil --help` within an OpenBMC system).
89 The above objects also implement other D-Bus objects like power on hours, boot
90 progress, reboot attempts, and operating system status. These D-Bus objects are
91 also defined out in the phosphor-dbus-interfaces repository.
93 ## Restore Policy on Power Events
101 power on request, this allows host to be powered on as early as the BMC is
106 There is an optional `only-allow-boot-when-bmc-ready` feature which can be
110 `Ready` before the power restore function requests the power on.
117 - Never impact the state of the system (causing a power off of a running system
119 - Ensure the BMC, Chassis, and Host states accurately represent the state of the
122 Note that some of this logic is provided via service files in system-specific
128 phosphor-state-manager discovers state vs. trying to cache and save states. This
130 chassis state by checking the `pgood` value from the power application. If it
131 determines that power is on then it will do the following:
133 - Create a file called /run/openbmc/chassis@0-on
134   - The presence of this file tells the services to alter their behavior because
136 - Start the obmc-chassis-poweron\@0.target
137   - The majority of services in this target will "fake start" due to the file
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
144 - Start a service to check if the host is on
146 The chassis@0-on file is removed once the obmc-chassis-poweron\@0.target becomes
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
157     "ConditionPathExists=!/run/openbmc/host@0-request"
159 The host@0-on file is removed once the obmc-host-start\@0.target and
160 obmc-host-startmin\@0.target become active (i.e. all service have been
168 2. `ninja -C build`
170 To clean the repository again run `rm -rf build`.
172 [1]: https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md
174 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC…
176 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Cha…
178 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Hos…
179 [5]: https://github.com/openbmc/phosphor-state-manager/blob/master/obmcutil
181 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/P…