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