docs/designs/state-management-and-external-interfaces.md

1 # OpenBMC State Management and External Interfaces
23 [phoshor-state-manager][2] implements the xyz.openbmc_project.State.\*
24 interfaces. These interfaces control and track the state of the BMC, Chassis,
28 the appropriate xyz.openbmc_project.State.\* D-Bus interface.
30 The goal with this design is to enhance the xyz.openbmc_project.State.\*
35 Currently phosphor-state-manager supports the following:
37 - Chassis: On/Off
38 - Host: On/Off/Reboot
60         "ForceOff": "Turn off the unit immediately (non-graceful shutdown).",
62         "ForceRestart": "Shut down immediately and non-gracefully and restart
65         "GracefulShutdown": "Shut down gracefully and power off.",
84 …------------------------------ | -----------------------------------------------------------------…
85 …system into soft off (S4/S45) state. This is for ‘emergency’ management power down actions. The co…
87 …off interval of at least 1 second following the deassertion of the system’s POWERGOOD status from …
88 …ticular effect and will pulse the system reset signal regardless of power state.                  …
90 | Initiate a soft-shutdown of OS |                                                                 …
94 - Keep legacy support where `xyz.openbmc_project.State.Host.Transition.Reboot`
97 - Support a reboot of the host with chassis power on
98   - Support `GracefulRestart` (where the host is notified of the reboot)
99   - Support `ForceRestart` (where the host is not notified of the reboot)
100 - Map `PowerCycle` to a host or chassis operation depending on the current state
102   - If host is running, then a `PowerCycle` should cycle power to the chassis
104   - If host is not running, then a `PowerCycle` should only cycle power to the
109 Create two new `xyz.openbmc_project.State.Host.Transition` options:
111 - `ForceWarmReboot`, `GracefulWarmReboot`
113 Create a new `xyz.openbmc_project.State.Chassis.Transition` option:
115 - `PowerCycle`
117 The existing bmcweb code uses some additional xyz.openbmc_project.State.\*
118 interfaces that are not defined within phosphor-dbus-interfaces. These are
119 implemented within the x86-power-control repository which is an alternate
120 implementation to phosphor-state-manager. It has the following mapping for these
121 non-phosphor-dbus-interfaces
123 - `ForceRestart` -> `xyz.openbmc_project.State.Chassis.Transition.Reset`
124 - `PowerCycle` -> `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
128 `xyz.openbmc_project.State.Host.Transition.ForceWarmReboot`
131 `xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
133 The `PowerCycle` operation is dependent on the current state of the host. If
134 host is on, it will map to `xyz.openbmc_project.State.Host.Transition.Reboot`
136 `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
138 To summarize the new Redfish to xyz.openbmc_project.State.\* mappings:
140 - `ForceRestart` -> `xyz.openbmc_project.State.Host.Transition.ForceWarmReboot`
141 - `GracefulRestart`->
142   `xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
143 - `PowerCycle`:
144   - If host on: `xyz.openbmc_project.State.Host.Transition.Reboot`
145   - If host off: `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
147 The full mapping of Redfish and IPMI to xyz.openbmc_project.State.\* is as
150 | Redfish               | IPMI        | xyz.openbmc_project.State.Transition |
151 | --------------------- | ----------- | ------------------------------------ |
152 | ForceOff              | power down  | Chassis.Off                          |
156 | GracefulShutdown      | soft off    | Host.Off                             |
159 | PowerCycle (host off) |             | Chassis.PowerCycle                   |
167 Existing interfaces will be kept the same. Some changes in x86-power-control
171 Some changes in phosphor-host-ipmid would be needed to support the new state
176 These new state transitions will be backed by systemd targets. These targets
181 [2]: https://github.com/openbmc/phosphor-state-manager