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