1# Entity-Manager HW ID: VPD Discovery via Device-Tree Properties 2 3Author: Christopher Sides (citysides) 4 5Other contributors: 6 7Created: September 14, 2023 8 9## Problem Description 10 11BMC needs a process to identify and handle HPE GXP baseboards that provide HW ID 12data via non-I2C channels and in a proprietary format that is not covered by 13Entity-Manager's 'fru-device' daemon that most platforms rely on. 14 15This proposal describes a method of handling for hardware where HW ID data is 16gathered from device tree file paths for Entity-Manager consumption. 17 18## Background and References 19 20Typical platforms provide HW ID data - often referred to as 'vital product data' 21(VPD) - for the baseboard as a FRU storage blob held in a physical EEPROM. 22 23[As described in Entity-Manager documentation](https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md), 24this blob is discovered and read over I2C, then is decoded before the data is 25copied to D-Bus as properties of the `xyz.openbmc_project.FruDevice` interface 26by Entity-Manager's fru-device daemon. The current FRU-device daemon is able to 27decode IPMI-FRU storage formatted blobs, as well as the Tyan data format. 28 29Additionally, a separate daemon for handling OpenPower format VPD is hosted in 30the 'openpower-vpd-parser' subproject. This daemon is relied on for the 31identification of certain IBM-supported hardware. 32 33HPE hardware uses different channels and data formats from the above, relying on 34modifications to the device-tree to output properties as one file handle per 35attribute. 36 37Once VPD is made available on D-Bus, it can be referenced by the Entity-Manager 38configuration 'probe' statements that are used as hardware/configuration 39detection triggers. 40 41HPE platforms provide the following properties for baseboard VPD: 42 43- server_id (platform model id) 44- pca_part_number (baseboard part no) 45- pca_serial_number (baseboard serial no) 46- part_number (platform product no, set at assembly by factory) 47- serial_number (system serial no, assigned at assembly by factory) 48- mac0 (if present: MAC address for dedicated BMC network interface) 49- mac1 (if present: MAC address for secondary network interface that may or may 50 not be shared with host) 51 52HPE platforms in Gen 10 and earlier provided VPD through a standard 53I2C-accessible EEPROM (but still in a proprietary data format). That avenue is 54no longer available on newer HPE systems. 55 56For GXP-based Gen 11 HPE platforms, proprietary HPE-controlled bootblock 57firmware communicates with a secure element to provide necessary VPD. This 58process uses a driver whose implementation is strictly license-controlled and 59cannot be publicly released. The open source portions of the boot chain must 60adapt to the bootblock's reserved memory application binary interface (ABI) for 61providing VPD from the secure element. 62 63Early in the boot process, an HPE-proprietary bootblock is validated, then an 64HPE-specific bootloader in the block fetches the VPD blob from the secure 65element via third party driver. From here, the data blob is copied to a 66predetermined location in RAM, where it is retrieved and parsed by HPE-specific 67code in u-Boot (open-sourced, and available at 68https://github.com/HewlettPackard/gxp-uboot). In the future, we'll be aiming to 69upstream as much 'HPE-critical' u-boot code as needed so that an HPE-specific 70u-boot fork will not be needed to boot HPE hardware. 71 72Additionally, code in u-Boot gathers MAC addresses for the BMC's network 73interfaces, along with retrieving a 'server_id' value from an embedded 74CPLD-based memory device. This value is unique to each model of HPE platform, 75and will be used for platform-wide identification. In comparison, the data in 76the aforementioned blob may be used for recognizing finer details like specific 77board revisions for a given platform. 78 79The HPE process described above relies on shared memory instead of u-boot env 80variables because the HPE bootloader does not know that u-boot will run next, 81and does not know where the u-boot variable store is, if it exists at all -- 82since a customer could decide to use something other than u-boot, or to store 83their environmental variables in a different place or format. 84 85After that, u-Boot makes relevant data available to Linux via modifications to 86the flattened device tree, setting the values for ['/model' and 87'/serial-number,' which both have well-known paths in the device tree 88root][dt-spec-chap3-root-node], along with ['local-mac-address,' a property 89provided by the network binding][dt-spec-chap4-device-bindings]. 90 91[dt-spec-chap3-root-node]: 92 https://github.com/devicetree-org/devicetree-specification/blob/main/source/chapter3-devicenodes.rst#root-node 93[dt-spec-chap4-device-bindings]: 94 https://github.com/devicetree-org/devicetree-specification/blob/main/source/chapter4-device-bindings.rst#local-mac-address-property 95 96From there, the GXP product data must be published to D-Bus, or there will be no 97way for Entity-Manager to reference it during the probe evaluations used in 98detecting supported hardware configurations. The contents of 'device-tree/model' 99being made available on D-Bus will be enough to enable basic Entity-Manager 100identification of HPE baseboard hardware. 101 102In the future, HPE's behind-the-scenes reliance on u-Boot for this process may 103be reduced or removed entirely, but but those implementation details should not 104affect how a service would collect data from the device-tree passed to the 105kernel from u-Boot. One alternative to modifying the flat device-tree would be 106to have values like 'model' set in the platform's device-tree source at image 107build time. 108 109This document discusses leveraging a 'device-tree -> D-Bus' daemon in 110Entity-Manager to enable BMC detection and handling of HPE Gen 11 hardware (and 111potentially for other hardware as well). 112 113## Requirements 114 115- Vital product data must be parsed and published to D-Bus 116 117- D-Bus properties for interface(s) at path `xyz/openbmc_project/MachineContext` 118 may be populated using retrieved VPD values as appropriate to offer a D-Bus 119 path for common specific model identifying details. 120 121- Vital product data properties should be referenced in Entity-Manager config 122 'probe' statement(s) in order to key configuration enablement off them. 123 124## Proposed Design 125 126High Level Flow: 127 128- At boot, a proprietary HPE bootblock is validated, then HPE GXP-bootloader 129 code (proprietary) included in the block retrieves data from a secure element. 130 Specific hardware identifying information is transferred into a pre-determined 131 memory location in RAM for pickup. 132 133- u-Boot code (via an 134 [open source, but HPE-specific process](https://github.com/HewlettPackard/gxp-uboot)) 135 gathers MAC addresses and moves product data from the RAM location, plus a 136 CPLD-based memory device, and exposes it in Linux under /proc/device-tree/ 137 138- A daemon in DeviceTree-VPD-Parser retrieves product data from known device 139 tree paths, then parses and publishes to D-Bus 140 141- Entity-Manager probes that reference properties from the 142 `xyz.openbmc_project.Inventory.Decorator.Asset` (.Model & .SerialNumber 143 properties) interface on D-Bus can key off GXP hardware data and react 144 accordingly. 145 146## Alternatives Considered 147 148### Entity-Manager probes are extended to handle reading data from arbitrary<br/>device-tree nodes 149 150#### Pros: 151 1521. No new daemon required 153 154#### Cons: 155 1561. May encourage undesired device-tree exploitation 157 158### A reserved-memory node in device-tree is used for transport of<br/>'serial-number' and 'model' ID data 159 160#### Pros: 161 1621. Reserved-memory is commonly used for passing data from firmware 163 164#### Cons: 165 1661. Has no well-known handles for common properties like /model or /serial-number 167 like device-tree does; makes more sense for keeping arbitrary data instead of 168 'well-known' properties 1692. The critical identifier HPE wants to rely on for platform identification 170 (/model) comes from a different behind-the-scenes source vs. the rest of the 171 data planned for output through reserved-memory. Using reserved-memory for 172 'model' instead of the well known device-tree /model handle would add 173 additional complexity. 1743. Since /model is well described in device-tree documentation, there is 175 potential for non-HPE platform to make easy use of it. Relying on 'model' as 176 an arbitrary property in reserved-memory has less potential to be useful 177 outside of HPE-specific applications. 178 179### All VPD is exposed as devicetree attributes under /chosen/ 180 181#### Pros: 182 1831. Is a well-established device-tree node 1842. Is not being used by other BMC platforms, so easy to enable/disable service 185 based on whether or not 'chosen' path exists 1863. Values can be set from u-Boot via modifications to the flattened device tree 187 available to it (applicable to arbitrary device-tree paths) 188 189#### Cons: 190 1911. Not a 'usual' location for passing this kind HW-tied data. Unlikely to ever 192 be used for moving product data by other entities, so such a daemon would be 193 defacto HPE-specific code. 1942. Presenting HW-specific data here appears to go against the intended use of 195 'chosen' node 196 197### Vital product data is published to u-Boot environment variables, then<br/>transferred to D-Bus 198 199#### Pros: 200 2011. Would increase code reuse and testing 202 203#### Cons: 204 2051. Potential issues with limited writes to memory where u-boot env variables are 206 stored in memory. 2072. HPE component that retrieves VPD from HPE's secure element has no 208 knowledge/ability to alter u-boot environmental variables 209 210### Use an HPE-specific daemon instead of a generalized'[channel]-> D-Bus'<br/>daemon 211 212#### Pros: 213 2141. Simpler (slightly?) code 2152. Would only fire for HPE platforms 2163. Better abstraction 217 218#### Cons: 219 2201. Doesn't save much effort compared to a generalized non-HPE-specific solution 2212. Harder to leverage code for potential future cases 222 223### Service is hosted in Entity-Manager [ACCEPTED after TOF re-examination] 224 225#### Pros: 226 2271. Would operate in parallel to existing Fru_Device daemon 228 229#### Cons: 230 2311. Community doesn't want to host VPD -> DBus daemons in Entity-Manager repo 232 233Follow-up: A Technical Oversight Forum discussion has reached consensus that it 234would be better to host this device-tree VPD daemon in Entity-Manager alongside 235the existing fru-device daemon rather than to create a dedicated repo for a 236daemon as simple as this one, or to force into another even less-related repo. 237 238https://github.com/openbmc/technical-oversight-forum/issues/38 239 240### Service is hosted in Phosphor-u-boot-env-mgr 241 242#### Pros: 243 2441. Repo is already associated with u-boot operations 245 246#### Cons: 247 2481. Current repo maintainer feels the service doesn't fit this repo because the 249 purpose is explicitly to deal with manipulation of u-boot env variables, 250 which this service is not involved with. 251 252 https://gerrit.openbmc.org/c/openbmc/phosphor-u-boot-env-mgr/+/71512 253 254### Addendum: Rejected D-Bus interfaces for pending device-tree -> D-Bus<br/>daemon 255 256#### Existing interfaces (rejected): 257 2581. Proposal: xyz.openbmc_project.Decorator.\* 259 260 Rejection: "doesn't represent anything about the physical board" -Ed Tanous 261 262 Followup: Phosphor-dbus-interfaces maintenance (Patrick Williams) has 263 rejected hosting an interface with properties like 'Model' and 'SerialNumber' 264 that already exist as part of other interfaces, and has specifically 265 suggested relying on xyz.openbmc_project.Inventory.Decorator.Asset (for 266 .model and .serialnumber properties) along with 267 xyz.openbmc_project.Inventory.Item.NetworkInterface (for .MACAddress 268 property). 269 270 Discussion @ 271 https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/ 272 273 Follow-up 2: Sticking with Inventory.Decorator.Asset, but removing MAC 274 address properties to reduce unneeded complexity. 275 2762. Proposal: xyz.openbmc_project.FRUDevice 277 278 Rejection: The data is not coming from a FRU device 279 280#### Proposed interfaces (rejected): 281 2821. Proposal: xyz.openbmc_project.DeviceTree 2832. Proposal: xyz.openbmc_project.uBootHWID 2843. Proposal: xyz.openbmc_project.GXPFRU 285 286 Rejection: Above interfaces do not reflect underlying hardware 287 2884. Proposal: xyz.openbmc_project.BMCPrebootContext 289 290 Rejection: Arguably doesn't represent a hardware concept. 291 2925. Proposal: xyz.openbmc_project.UbootDeviceModel 293 294 Rejection: There are ongoing efforts to enable dynamic device-tree 295 modifications post-u-boot. The nodes this daemon reads are unlikely to be 296 affected, but there's no guarantee of that. 297 2986. Proposal: xyz.openbmc_project.Platform 299 300 Rejection: Some attributes like serial-number or MAC don't apply across a 301 given platform 302 3037. Proposal: xyz.openbmc_project.Machine 304 305 Rejection: Promising, but the name seems vague re: its purpose. 306 xyz.openbmc_project.MachineContext has been offered as an alternative. 307 3088. Proposal: xyz.openbmc_project.MachineContext 309 310 Rejection: "We have all this stuff [.Model, .SerialNumber, ect. properties] defined 311 already. I'm not going to accept a new "bunch of random properties HPe thinks 312 are important [today] globbed into a new interface" interface" 313 314 - Patrick Williams, Phosphor-dbus-interfaces maintainer. 315 316 Counter-proposal: "Reuse the existing dbus interfaces and put them at a 317 well-defined location? Inventory.Decorator.[Asset] = Model 318 Inventory.Decorator.Asset = SerialNumber Inventory.Item.NetworkInterace = 319 MACAddress.." - Patrick Williams 320 321 Discussion @ 322 https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/ 323 324 Follow-up: Landed on interface: xyz.openbmc_project.Inventory.Decorator.Asset 325 @ path xyz/openbmc_project/MachineContext 326 327## Impacts 328 329The above-described process is only intended to scan selected paths -if they 330exist- once during initial service startup. 331 332If the path(s) in question do not exist (device-tree/model or 333device-tree/serial-number), no further work will be done, so there is expected 334to be no noticeable performance or functional impact to platforms that don't 335rely on this service for Entity-Manager HW/config detection. 336 337## Organizational: 338 339### Does this design require a new repository? 340 341No. After some discussion, a Technical Oversight Forum consensus was reached to 342have the device-tree VPD parser daemon hosted in the Entity-Manager repo 343alongside the existing fru-device daemon. 344 345### Which repositories are expected to be modified to execute this design? 346 347Technical Oversight Forums consensus has been reached that this device-tree VPD 348daemon will be hosted in Entity-Manager alongside the existing FRU-device VPD 349daemon. 350 351Entity-Manager will also have configuration files added for HPE hardware that 352make use of the new interface properties via probe statements. 353 354## Testing 355 356Any platform that has a device-tree 'model' or 'serial-number' node populated in 357Device-Tree (this can be done by hardcoding a value into the DTS file before 358building an image, if desired) can be checked by confirming the contents of the 359device-tree/model and/or serial-number node matches the contents of 'model' and 360'serial-number' properties of D-Bus interface at D-Bus path 361'xyz/openbmc_project/MachineContext' 362 363Practically, the whole of the service stack (including Entity-Manager probe 364validation) of the new D-Bus path can be validated on an HPE system by setting 365an Entity-Manager config's probe to trigger on match with a known HPE-HW 366identifying property, then by confirming 367`busctl tree xyz.openbmc_project.EntityManager` shows a listing of objects that 368matches what's described in the modified EM config file. 369 370At this time, HPE hardware requires forked (publicly available) OBMC components 371to fully boot, so automated testing of HPE hardware against 'mainstream' OBMC 372images is not yet a viable option. Enabling this type of testing is a longer 373term goal. 374