1# System Boot Progress on OpenBMC 2 3Author: Andrew Geissler `geissonator` 4 5Other contributors: None 6 7Created: May 27, 2020 8 9## Problem Description 10 11The boot progress of an OpenBMC managed system is complex. There are a mix of 12phosphor D-Bus properties, IPMI sensors, PLDM sensors, and Redfish properties to 13represent it. The goal of this design document is to highlight these different 14entities and provide a base for system implementors on what to implement. 15 16## Background and References 17 18[phosphor-state-manager][1] implements D-Bus properties which track the state of 19the BMC, Chassis, and Host. This design is primarily focused on the status of 20the Host since it is the most complex. Specifically the goal is to provide 21detailed information on what the host is doing during a boot. 22 23[HostState][2] provides basic `Off`/`Running` type information along with an 24error state (`Quiesced`) and debug state (`DiagnosticMode`). The focus of this 25document is the `Running` state. This simply indicates whether something is 26running on the host processors. 27 28phosphor-state-manager implements some other D-Bus properties that represent the 29host boot progress: 30 31- [xyz.openbmc_project.State.Boot.Progress][3] 32- [xyz.openbmc_project.State.OperatingSystem.Status][4] 33 34These two D-Bus properties are very IPMI-centric. They were defined based on two 35IPMI sensors which are set by the host firmware as it boots the system. 36 37PLDM also has a boot progress sensor. Search for "Boot Progress" in this 38[doc][5]. A subset of this maps fairly well to the IPMI sensors above. This PLDM 39sensor is not implemented yet in OpenBMC code. 40 41Redfish represents system state in a variety of ways. The BMC, Chassis, and 42System all implement a [Status][6] object. This provides a list of generic 43`State` options which are applicable to Redfish objects. OpenBMC has the 44following mapping for phosphor-state-manager to the Redfish System [Status][7]: 45 46- `xyz.openbmc_project.State.Host.HostState.Running` : `Enabled` 47- `xyz.openbmc_project.State.Host.HostState.Quiesced` : `Quiesced` 48- `xyz.openbmc_project.State.Host.HostState.DiagnosticMode` : `InTest` 49 50As of [ComputerSystem.v1_13_0][7], the `BootProgress` object is officially in 51the Redfish ComputerSystem schema. 52 53To summarize, the `LastState` property under this new `BootProgress` object 54tracks the following boot states of the system: 55 56- None 57- PrimaryProcessorInitializationStarted 58- BusInitializationStarted 59- MemoryInitializationStarted 60- SecondaryProcessorInitializationStarted 61- PCIResourceConfigStarted 62- SystemHardwareInitializationComplete 63- OSBootStarted 64- OSRunning 65- OEM 66 67There is also a `LastStateTime` associated with this new BootProgress object 68which should be updated with the date and time the `LastState` was last updated. 69 70In the end, the goal is to be able to map either the IPMI or PLDM boot sensors 71into all or some of the values in this new Redfish property. 72 73Note that this design does not include multi-host computer system concepts but 74it also does not preclude them. The `BootProgress` D-Bus property is associated 75with a `/xyz/openbmc_project/state/host<X>` instance where `<X>` is the host 76instance. Similarly, the Redfish system object is also an instance based object. 77 78## Requirements 79 80- Enhance the existing [BootProgress][3] D-Bus property to cover all supported 81 PLDM boot progress codes 82- Create a new `BootProgressLastUpdate` D-Bus property that will hold the date 83 and time of the last update to `BootProgress` 84- Ensure the `BootProgress` and `BootProgressLastUpdate` properties are updated 85 appropriately in both IPMI and PLDM based stacks 86 - It is the responsibility of the IPMI or PLDM implementation to update the 87 `BootProgress` property on D-Bus 88 - It is the responsibility the phosphor-state-manager to update the 89 `BootProgressLastUpdate` property on D-Bus when it sees `BootProgress` 90 updated 91- Ensure the new Redfish `LastState` and `LastStateTime` properties have the 92 appropriate mappings to the `BootProgress` and `BootProgressLastUpdate D-Bus 93 properties 94 95Different OpenBMC systems could support different boot progress codes, and 96support them in different orders. This document does not try to set any 97requirements on this other than that they must all be defined within the 98`BootProgress` D-Bus property and the ones which have a mapping to the Redfish 99BootProgress object will be shown via the Redfish interface. 100 101## Proposed Design 102 103[BootProgress][3] will be enhanced to support a superset of what is provided by 104IPMI and PLDM. 105 106IPMI code already sets the `BootProgress` D-Bus property based on a config file. 107Look for `fw_boot_sensor` in this [file][8] for an example of how a particular 108IPMI sensor is mapped to this D-Bus property. 109 110PLDM software will do something similar. 111 112bmcweb will then use this `BootProgress` D-Bus interface to respond 113appropriately to Redfish requests. 114 115## Alternatives Considered 116 117A lot of system BIOS's provided some form of a detailed boot progress codes. 118UEFI has POST codes, POWER has istep progress codes. If more fine grained 119details were needed, we could look into using these. Currently though the need 120is just high level boot progress. Note that these POST/istep codes could be 121mapped to the appropriate BootProgress value if desired (or for cases where the 122host does not support an IPMI or PLDM stack that has BootProgress in it). 123 124## Impacts 125 126Each system will need to document which `BootProgress` codes they support and 127the expected order of them when a system is booting. 128 129## Testing 130 131Ensure an IPMI and PLDM based system boot and update the `BootProgress` D-Bus 132property as expected. 133 134[1]: 135 https://github.com/openbmc/phosphor-state-manager#state-tracking-and-control 136[2]: 137 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Host.interface.yaml 138[3]: 139 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Boot/Progress.interface.yaml 140[4]: 141 https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/OperatingSystem/Status.interface.yaml 142[5]: 143 https://www.dmtf.org/sites/default/files/standards/documents/DSP0249_1.0.0.pdf 144[6]: http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/Status 145[7]: https://redfish.dmtf.org/schemas/v1/ComputerSystem.v1_13_0.json 146[8]: 147 https://github.com/openbmc/meta-ibm/blob/master/recipes-phosphor/configuration/acx22-yaml-config/acx22-ipmi-sensors-mrw.yaml 148