docs/designs/entity-manager-hw-id-vpd-discover-via-device-tree.md

1 # Entity-Manager HW ID: VPD Discovery via Device-Tree Properties
12 data via non-I2C channels and in a proprietary format that is not covered by
13 Entity-Manager's 'fru-device' daemon that most platforms rely on.
16 gathered from device tree file paths for Entity-Manager consumption.
20 Typical 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.
23 [As described in Entity-Manager documentation](https://github.com/openbmc/entity-manager/blob/maste…
25 copied to D-Bus as properties of the `xyz.openbmc_project.FruDevice` interface
26 by Entity-Manager's fru-device daemon. The current FRU-device daemon is able to
27 decode IPMI-FRU storage formatted blobs, as well as the Tyan data format.
30 the 'openpower-vpd-parser' subproject. This daemon is relied on for the
31 identification of certain IBM-supported hardware.
34 modifications to the device-tree to output properties as one file handle per
37 Once VPD is made available on D-Bus, it can be referenced by the Entity-Manager
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
53 I2C-accessible EEPROM (but still in a proprietary data format). That avenue is
56 For GXP-based Gen 11 HPE platforms, proprietary HPE-controlled bootblock
58 process uses a driver whose implementation is strictly license-controlled and
63 Early in the boot process, an HPE-proprietary bootblock is validated, then an
64 HPE-specific bootloader in the block fetches the VPD blob from the secure
66 predetermined location in RAM, where it is retrieved and parsed by HPE-specific
67 code in u-Boot (open-sourced, and available at
68 <https://github.com/HewlettPackard/gxp-uboot>). In the future, we'll be aiming
69 to upstream as much 'HPE-critical' u-boot code as needed so that an HPE-specific
70 u-boot fork will not be needed to boot HPE hardware.
72 Additionally, code in u-Boot gathers MAC addresses for the BMC's network
74 CPLD-based memory device. This value is unique to each model of HPE platform,
75 and will be used for platform-wide identification. In comparison, the data in
79 The HPE process described above relies on shared memory instead of u-boot env
80 variables because the HPE bootloader does not know that u-boot will run next,
81 and does not know where the u-boot variable store is, if it exists at all --
82 since a customer could decide to use something other than u-boot, or to store
85 After that, u-Boot makes relevant data available to Linux via modifications to
87 '/serial-number,' which both have well-known paths in the device tree
88 root][dt-spec-chap3-root-node], along with ['local-mac-address,' a property
89 provided by the network binding][dt-spec-chap4-device-bindings].
91 [dt-spec-chap3-root-node]:
92 …https://github.com/devicetree-org/devicetree-specification/blob/main/source/chapter3-devicenodes.r…
93 [dt-spec-chap4-device-bindings]:
94 …https://github.com/devicetree-org/devicetree-specification/blob/main/source/chapter4-device-bindin…
96 From there, the GXP product data must be published to D-Bus, or there will be no
97 way for Entity-Manager to reference it during the probe evaluations used in
98 detecting supported hardware configurations. The contents of 'device-tree/model'
99 being made available on D-Bus will be enough to enable basic Entity-Manager
102 In the future, HPE's behind-the-scenes reliance on u-Boot for this process may
104 affect how a service would collect data from the device-tree passed to the
105 kernel from u-Boot. One alternative to modifying the flat device-tree would be
106 to have values like 'model' set in the platform's device-tree source at image
109 This document discusses leveraging a 'device-tree -> D-Bus' daemon in
110 Entity-Manager to enable BMC detection and handling of HPE Gen 11 hardware (and
115 - Vital product data must be parsed and published to D-Bus
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
121 - Vital product data properties should be referenced in Entity-Manager config
128 - At boot, a proprietary HPE bootblock is validated, then HPE GXP-bootloader
130   Specific hardware identifying information is transferred into a pre-determined
133 - u-Boot code (via an
134   [open source, but HPE-specific process](https://github.com/HewlettPackard/gxp-uboot))
136   CPLD-based memory device, and exposes it in Linux under /proc/device-tree/
138 - A daemon in DeviceTree-VPD-Parser retrieves product data from known device
139   tree paths, then parses and publishes to D-Bus
141 - Entity-Manager probes that reference properties from the
143   properties) interface on D-Bus can key off GXP hardware data and react
148 ### Entity-Manager probes are extended to handle reading data from arbitrary device-tree nodes
156 1. May encourage undesired device-tree exploitation
158 ### A reserved-memory node in device-tree is used for transport of 'serial-number' and 'model' ID d…
162 1. Reserved-memory is commonly used for passing data from firmware
166 1. 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
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
174 3. 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.
183 1. Is a well-established device-tree node
186 3. Values can be set from u-Boot via modifications to the flattened device tree
187    available to it (applicable to arbitrary device-tree paths)
191 1. Not a 'usual' location for passing this kind HW-tied data. Unlikely to ever
193    defacto HPE-specific code.
194 2. Presenting HW-specific data here appears to go against the intended use of
197 ### Vital product data is published to u-Boot environment variables, then transferred to D-Bus
205 1. Potential issues with limited writes to memory where u-boot env variables are
208    knowledge/ability to alter u-boot environmental variables
210 ### Use an HPE-specific daemon instead of a generalized'[channel]-> D-Bus' daemon
220 1. Doesn't save much effort compared to a generalized non-HPE-specific solution
223 ### Service is hosted in Entity-Manager [ACCEPTED after TOF re-examination]
231 1. Community doesn't want to host VPD -> DBus daemons in Entity-Manager repo
233 Follow-up: A Technical Oversight Forum discussion has reached consensus that it
234 would be better to host this device-tree VPD daemon in Entity-Manager alongside
235 the existing fru-device daemon rather than to create a dedicated repo for a
236 daemon as simple as this one, or to force into another even less-related repo.
238 <https://github.com/openbmc/technical-oversight-forum/issues/38>
240 ### Service is hosted in Phosphor-u-boot-env-mgr
244 1. Repo is already associated with u-boot operations
249    purpose is explicitly to deal with manipulation of u-boot env variables,
252    <https://gerrit.openbmc.org/c/openbmc/phosphor-u-boot-env-mgr/+/71512>
254 ### Addendum: Rejected D-Bus interfaces for pending device-tree -> D-Bus daemon
260    Rejection: "doesn't represent anything about the physical board" -Ed Tanous
262    Followup: Phosphor-dbus-interfaces maintenance (Patrick Williams) has
271 … <https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/>
273    Follow-up 2: Sticking with Inventory.Decorator.Asset, but removing MAC
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
300    Rejection: Some attributes like serial-number or MAC don't apply across a
313    - Patrick Williams, Phosphor-dbus-interfaces maintainer.
315    Counter-proposal: "Reuse the existing dbus interfaces and put them at a
316    well-defined location? Inventory.Decorator.[Asset] = Model
318    MACAddress.." - Patrick Williams
321 … <https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/>
323    Follow-up: Landed on interface: xyz.openbmc_project.Inventory.Decorator.Asset
328 The above-described process is only intended to scan selected paths -if they
329 exist- once during initial service startup.
331 If the path(s) in question do not exist (device-tree/model or
332 device-tree/serial-number), no further work will be done, so there is expected
334 rely on this service for Entity-Manager HW/config detection.
341 have the device-tree VPD parser daemon hosted in the Entity-Manager repo
342 alongside the existing fru-device daemon.
346 Technical Oversight Forums consensus has been reached that this device-tree VPD
347 daemon will be hosted in Entity-Manager alongside the existing FRU-device VPD
350 Entity-Manager will also have configuration files added for HPE hardware that
355 Any platform that has a device-tree 'model' or 'serial-number' node populated in
356 Device-Tree (this can be done by hardcoding a value into the DTS file before
358 device-tree/model and/or serial-number node matches the contents of 'model' and
359 'serial-number' properties of D-Bus interface at D-Bus path
362 Practically, the whole of the service stack (including Entity-Manager probe
363 validation) of the new D-Bus path can be validated on an HPE system by setting
364 an Entity-Manager config's probe to trigger on match with a known HPE-HW