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
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
20 As with all OpenBMC applications, interfaces and properties within
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][1]
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
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
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.
106 There is an optional `only-allow-boot-when-bmc-ready` feature which can be
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
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
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…