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