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