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