1# BMC, Host, and Chassis State Management
2
3## Overview
4
5The goal of the phosphor-state-manager repository is to control and track the
6states of the different software entities in a system.  All users will usually
7implement the BMC state interfaces, and some, when creating servers will do the
8Host and Chassis state interfaces.  These interfaces will be the mechanism by
9which you determine the state of their corresponding instances, as well as
10reboot the BMC and hosts, and turn on and off power to the chassis.  The
11interfaces are designed in a way to support a many to many mappings of each
12interface.
13
14There are three states to track and control on a BMC based server.  The states
15below in () represent the actual parameter name as found in
16`/xyz/openbmc_project/state/`+`/bmcX,/hostY,/chassisZ` where X,Y,Z are the
17instances (in most cases 0).  For all three states, the software tracks a
18current state, and a requested transition.
19
201. *BMC* : The BMC has either started all required systemd services and reached
21it's required target (Ready) or it's on it's way there (NotReady).  Users can
22request a (Reboot).
23
242. *Host* : The host is either (Off), (Running), or it's (Quiesced).
25Running simply implies that the processors are executing instructions.  Users
26can request the host be in a (Off), (On), or (Reboot) state.  More details on
27different Reboot options below.
28Quiesced means the host OS is in a quiesce state and the system should be
29checked for errors. For more information refer to
30[Error Handling of systemd](https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md#error-handling-of-systemd)
31
323. *Chassis* : The chassis is either (Off) or (On)
33This represents the state of power to the chassis.  The Chassis being on
34is a pre-req to the Host being running.  Users can request for the chassis to be
35(Off) or (On).  A transition to one or the other is implied by the transition
36not matching the current state.
37
38A simple system design would be to include a single *BMC*, *Host*, and
39*Chassis*.
40
41Details of the properties and their valid settings can be found in the state
42manager dbus interface [specification](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/)
43
44### BMC
45
46The *BMC* would provide interfaces at
47`/xyz/openbmc_project/state/bmc<instance>`
48
49### *Host*
50
51The *Host* would provide interfaces at
52`/xyz/openbmc_project/state/host<instance>`
53
54### *Chassis*
55
56The *Chassis* would provide interfaces at
57`/xyz/openbmc_project/state/chassis<instance>`
58
59### *Chassis System*
60This is an instance under *Chassis* and provide interface at
61`/xyz/openbmc_project/state/chassis_system<instance>`
62
63Instance 0 (chassis_system0) will be treated as a complete chassis system
64which will include BMC, host and chassis. This will support hard power
65cycle of complete system.
66
67In multi-host or multi-chassis system, instance number can be used from
681-N, as 0 is reserved for complete system. In multi chassis system this
69can be named as chassis_system1 to chassis_systemN
70
71## BMC to Host to Chassis Mapping
72
73In the future, OpenBMC will provide an association API, which allows one
74to programmatically work out the mapping between BMCs, Chassis and Hosts.
75
76In order to not introduce subtle bugs with existing API users, `bmc0`,
77`chassis0` and `host0` are special. If they exist, they are guaranteed to talk
78to the system as a whole as if it was a system with one BMC, one chassis and
79one host. If there are multiple hosts, then bmc0/chassis0/host0
80will *not* exist. In the event of multiple BMCs or Chassis, bmc0 and chassis0
81will act on all entities as if they are one (if at all possible).
82
83This behaviour means that existing code will continue to work, or error out
84if the request would be ambiguous and probably not what the user wanted.
85
86For example, if a system has two chassis, only powering off the first chassis
87(while leaving the second chassis on) is certainly *not* what the API user had
88in mind as they likely desired to hard power off the system. In such a
89multi-chassis system, starting counting from 1 rather than 0 would avoid this
90problem, while allowing an API user to *intentionally* only power off one
91chassis. With chassis0 being special, it would allow existing code to continue
92to function on this multi-chassis system.
93
94For example, a system with multiple hosts would have BMCs, Chassis and Hosts
95*all* start numbering from 1 rather than 0. This is because multiple hosts
96could be in the same chassis, or controlled by the same BMC, so taking action
97against them would *not* be what the API user intended.
98
99It is safe to continue to write code referencing bmc0, host0 and
100chassis0 and that code will continue to function, or error out rather than
101doing something undesirable.
102
103## Hard vs. Soft Power Off
104
105A hard power off is where you simply cut power to a chassis.  You don't give
106the software running on that chassis any chance to cleanly shut down.
107A soft power off is where you send a notification to the host that is running
108on that chassis that a shutdown is requested, and wait for that host firmware
109to indicate it has shut itself down.  Once complete, power is then removed
110from the chassis. By default, a host off or reboot request does the soft
111power off.  If a user desires a cold reboot then they should simply issue a
112power off transition request to the chassis, and then issue an on transition
113request to the host.
114
115## Operating System State and Boot Progress Properties
116
117[OperatingSystemState](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/OperatingSystem/Status.interface.yaml)
118property is used to track different progress states of the OS or the hypervisor
119boot, while the [BootProgress](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/Boot/Progress.interface.yaml)
120property is used mainly for indicating system firmware boot progress.
121The enumerations used in both the cases are influenced by standard interfaces
122like IPMI 2.0 (Section 42.2, Sensor Type Codes and Data, Table 42, Base OS
123boot status) and PLDM state spec (DSP0249, Section 6.3, State Sets Tables,
124Table 7 – Boot-Related State Sets, Set ID - 196 Boot Progress).
125
126