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