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