1# OpenBMC State Management and External Interfaces
2
3Author: Andrew Geissler (geissonator)
4
5Other contributors:
6  Jason Bills (jmbills)
7
8Created: Jan 22, 2020
9
10## Problem Description
11
12As OpenBMC moves to fully supporting the Redfish protocol, it's important to
13have the appropriate support within OpenBMC for the [ResetType][1] within the
14Resource schema. OpenBMC currently has limited support and the goal with this
15design is to get that support more complete.
16
17Please note that the focus of this document is on the following `ResetType`
18instance: `redfish/v1/Systems/system/Actions/ComputerSystem.Reset`
19
20This support will also map to the existing IPMI Chassis Control command.
21
22## Background and References
23
24[phoshor-state-manager][2] implements the xyz.openbmc_project.State.\*
25interfaces. These interfaces control and track the state of the BMC, Chassis,
26and Host within an OpenBMC managed system. The README within the repository
27can provide some further background information. [bmcweb][3], OpenBMC's web
28server and front end Redfish interface, then maps commands to the ResetType
29object to the appropriate xyz.openbmc_project.State.* D-Bus interface.
30
31The goal with this design is to enhance the xyz.openbmc_project.State.*
32interfaces to support more of the Redfish ResetType. Specifically this design
33is looking to support the capability to reboot an operating system on a system
34without cycling power to the chassis.
35
36Currently phosphor-state-manager supports the following:
37  - Chassis: On/Off
38  - Host: On/Off/Reboot
39
40The `Reboot` to the host currently causes a power cycle to the chassis.
41
42### Redfish
43
44The Redfish [ResetType][1] has the following operations associated with it:
45```
46"ResetType": {
47    "enum": [
48        "On",
49        "ForceOff",
50        "GracefulShutdown",
51        "GracefulRestart",
52        "ForceRestart",
53        "Nmi",
54        "ForceOn",
55        "PushPowerButton",
56        "PowerCycle"
57    ],
58    "enumDescriptions": {
59        "ForceOff": "Turn off the unit immediately (non-graceful shutdown).",
60        "ForceOn": "Turn on the unit immediately.",
61        "ForceRestart": "Shut down immediately and non-gracefully and restart
62          the system.",
63        "GracefulRestart": "Shut down gracefully and restart the system.",
64        "GracefulShutdown": "Shut down gracefully and power off.",
65        "Nmi": "Generate a diagnostic interrupt, which is usually an NMI on x86
66          systems, to stop normal operations, complete diagnostic actions, and,
67          typically, halt the system.",
68        "On": "Turn on the unit.",
69        "PowerCycle": "Power cycle the unit.",
70        "PushPowerButton": "Simulate the pressing of the physical power button
71          on this unit."
72    },
73    "type": "string"
74},
75```
76
77### IPMI
78
79The IPMI specification defines a Chassis Control Command with a chassis
80control parameter as follows:
81
82| Option | Description |
83| --- | --- |
84| power down | Force system into soft off (S4/S45) state. This is for ‘emergency’ management power down actions. The command does not initiate a clean shut-down of the operating system prior to powering down the system. |
85| power up |  |
86| power cycle | This command provides a power off interval of at least 1 second following the deassertion of the system’s POWERGOOD status from the main power subsystem. It is recommended that no action occur if system power is off (S4/S5) when this action is selected, and that a D5h “Request parameter(s) not supported in present state.” error completion code be returned. |
87| hard reset | In some implementations, the BMC may not know whether a reset will cause any particular effect and will pulse the system reset signal regardless of power state. |
88| pulse Diagnostic Interrupt | Pulse a version of a diagnostic interrupt that goes directly to the processor(s). This is typically used to cause the operating system to do a diagnostic dump (OS dependent). |
89| Initiate a soft-shutdown of OS |  |
90
91## Requirements
92
93- Keep legacy support where `xyz.openbmc_project.State.Host.Transition.Reboot`
94  causes a graceful shutdown of the host, a power cycle of the chassis, and
95  a starting of the host.
96- Support a reboot of the host with chassis power on
97  - Support `GracefulRestart` (where the host is notified of the reboot)
98  - Support `ForceRestart` (where the host is not notified of the reboot)
99- Map `PowerCycle` to a host or chassis operation depending on the current state
100  of the system.
101  - If host is running, then a `PowerCycle` should cycle power to the chassis
102    and boot the host.
103  - If host is not running, then a `PowerCycle` should only cycle power to the
104    chassis.
105
106## Proposed Design
107
108Create two new `xyz.openbmc_project.State.Host.Transition` options:
109- `ForceWarmReboot`, `GracefulWarmReboot`
110
111Create a new `xyz.openbmc_project.State.Chassis.Transition` option:
112- `PowerCycle`
113
114The existing bmcweb code uses some additional xyz.openbmc_project.State.*
115interfaces that are not defined within phosphor-dbus-interfaces. These are
116implemented within the x86-power-control repository which is an alternate
117implementation to phosphor-state-manager. It has the following mapping for
118these non-phosphor-dbus-interfaces
119- `ForceRestart` -> `xyz.openbmc_project.State.Chassis.Transition.Reset`
120- `PowerCycle` -> `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
121
122A `ForceRestart` should restart the host, not the chassis. The proposal is to
123change the current bmcweb mapping for `ForceRestart` to a new host transition:
124`xyz.openbmc_project.State.Host.Transition.ForceWarmReboot`
125
126A `GracefulRestart` will map to our new host transition:
127`xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
128
129The `PowerCycle` operation is dependent on the current state of the host.
130If host is on, it will map to `xyz.openbmc_project.State.Host.Transition.Reboot`
131otherwise it will map to
132`xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
133
134To summarize the new Redfish to xyz.openbmc_project.State.* mappings:
135- `ForceRestart` -> `xyz.openbmc_project.State.Host.Transition.ForceWarmReboot`
136- `GracefulRestart`-> `xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
137- `PowerCycle`:
138  - If host on: `xyz.openbmc_project.State.Host.Transition.Reboot`
139  - If host off: `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
140
141The full mapping of Redfish and IPMI to xyz.openbmc_project.State.* is as
142follows:
143
144| Redfish | IPMI | xyz.openbmc_project.State.Transition |
145| --- | --- | --- |
146| ForceOff | power down | Chassis.Off |
147| ForceOn | power up | Host.On |
148| ForceRestart | hard reset | Host.ForceWarmReboot |
149| GracefulRestart |  | Host.GracefulWarmReboot |
150| GracefulShutdown | soft off | Host.Off |
151| On | power up | Host.On |
152| PowerCycle (host on) | power cycle | Host.Reboot |
153| PowerCycle (host off) |  | Chassis.PowerCycle |
154
155## Alternatives Considered
156
157No other alternatives considered.
158
159## Impacts
160
161Existing interfaces will be kept the same. Some changes in x86-power-control
162would be needed to ensure the bmcweb mappings work as expected with the new
163interfaces.
164
165Some changes in phosphor-host-ipmid would be needed to support the new state
166transitions.
167
168## Testing
169
170These new state transitions will be backed by systemd targets. These targets
171will be thoroughly tested. OpenBMC test team will be approached to ensure these
172are tested in automation.
173
174[1]: http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/ResetType
175[2]: https://github.com/openbmc/phosphor-state-manager
176[3]: https://github.com/openbmc/bmcweb
177[4]: https://gerrit.openbmc.org/c/openbmc/docs/+/22358
178