1e12059abSBenjamin Fair# Physical Topology for Inventory Items 2e12059abSBenjamin Fair 3e12059abSBenjamin FairAuthor: Benjamin Fair <benjaminfair> 4e12059abSBenjamin Fair 5f4febd00SPatrick WilliamsOther contributors: Ed Tanous <edtanous> 6e12059abSBenjamin Fair 7e12059abSBenjamin FairCreated: June 1, 2022 8e12059abSBenjamin Fair 9e12059abSBenjamin Fair## Problem Description 10f4febd00SPatrick Williams 11e12059abSBenjamin FairComplex systems may contain many inventory objects (such as chassis, power 12e12059abSBenjamin Fairsupplies, cables, fans, etc.) with different types of relationships among these 13e12059abSBenjamin Fairobjects. For instance, one chassis can contain another, be powered by a set of 14e12059abSBenjamin Fairpower supplies, connect to cables, and be cooled by fans. OpenBMC does not 15e12059abSBenjamin Faircurrently have a standard way to represent these types of relationships. 16e12059abSBenjamin Fair 17e12059abSBenjamin Fair## Background and References 18f4febd00SPatrick Williams 19f4febd00SPatrick WilliamsThis builds on a 20f4febd00SPatrick Williams[prior proposal](https://gerrit.openbmc.org/c/openbmc/docs/+/41468), but 21f4febd00SPatrick Williamsspecifies using Associations for all relationships (Proposal II) rather than 22f4febd00SPatrick Williamspath hierarchies (Proposal I). 23e12059abSBenjamin Fair 24e12059abSBenjamin FairThe main driver of this design is Redfish, particularly the Links section of the 25e12059abSBenjamin Fair[Chassis schema](https://redfish.dmtf.org/schemas/Chassis.v1_20_0.json). 26e12059abSBenjamin Fair 27e12059abSBenjamin FairChanges to phosphor-dbus-interfaces documenting new Associations have been 28e12059abSBenjamin Fair[proposed](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/46806) 29e12059abSBenjamin Fairbut not yet merged until consensus can be reached on the design. 30e12059abSBenjamin Fair 31e12059abSBenjamin FairThis design was initially discussed in 32e12059abSBenjamin Fair[Discord](https://discord.com/channels/775381525260664832/819741065531359263/964321666790477924), 33e12059abSBenjamin Fairwhere some initial consensus was reached. 34e12059abSBenjamin Fair 35e12059abSBenjamin Fair## Requirements 36f4febd00SPatrick Williams 37f4febd00SPatrick Williams- Must represent one-to-many relationships from chassis inventory objects which: 38f4febd00SPatrick Williams - Connect to cables 39f4febd00SPatrick Williams - Contain other chassis and/or are contained by a chassis 40f4febd00SPatrick Williams - Contain storage drives 41f4febd00SPatrick Williams - Are cooled by fans 42f4febd00SPatrick Williams - Are powered by power supplies 43f4febd00SPatrick Williams - Contain processors such as CPUs 44f4febd00SPatrick Williams - Contain memory such as DIMMs 45f4febd00SPatrick Williams- Must support relationships which are predefined, detected at runtime, or a 46e12059abSBenjamin Fair combination of both 47f4febd00SPatrick Williams - Runtime detection could include I2C bus scanning, USB enumeration, and/or 48e12059abSBenjamin Fair MCTP discovery 49e12059abSBenjamin Fair 50e12059abSBenjamin Fair### Optional goals (beyond initial implementation) 51f4febd00SPatrick Williams 52f4febd00SPatrick Williams- Non-chassis inventory objects may also need one-to-many relationships 53f4febd00SPatrick Williams - CPUs have CPU cores and associated PCIe slots 54f4febd00SPatrick Williams - CPU cores have threads 55e12059abSBenjamin Fair 56e12059abSBenjamin Fair## Proposed Design 57f4febd00SPatrick Williams 58e12059abSBenjamin FairThe design affects three layers of the OpenBMC architecture: 59e12059abSBenjamin Fairphosphor-dbus-interfaces, inventory managers, and inventory consumers such as 60e12059abSBenjamin Fairbmcweb. 61e12059abSBenjamin Fair 62e12059abSBenjamin Fair### phosphor-dbus-interfaces 63f4febd00SPatrick Williams 64*669d6fddSBenjamin FairIn the interface definition for Inventory/Item or the more specific subtypes, we 65*669d6fddSBenjamin Fairadd an association definition for each of the relationship types listed above 66*669d6fddSBenjamin Fairand corresponding association definitions linking back to that item. 67e12059abSBenjamin Fair 68e12059abSBenjamin Fair### Inventory Managers 69f4febd00SPatrick Williams 70e12059abSBenjamin Fair#### phosphor-inventory-manager 71f4febd00SPatrick Williams 72e12059abSBenjamin Fairphosphor-inventory-manager already has support for exporting custom 73e12059abSBenjamin FairAssociations, so no changes are needed here. 74e12059abSBenjamin Fair 75e12059abSBenjamin Fair#### entity-manager 76f4febd00SPatrick Williams 77e12059abSBenjamin FairFor entity-manager, we add new `Exposes` stanzas for the upstream and downstream 78*669d6fddSBenjamin Fairports in the JSON configurations. The upstream port has a type ending in `Port` 79*669d6fddSBenjamin Fair(such as a `BackplanePort`, `PowerInputPort`, etc). The downstream port has type 80e12059abSBenjamin Fair`DownstreamPort` and a `ConnectsToType` property that refers to the upstream 81e12059abSBenjamin Fairport based on its type. 82e12059abSBenjamin Fair 83e12059abSBenjamin FairNew code in entity-manager matches these properties and exposes associations on 84e12059abSBenjamin FairD-Bus based on the types of the inventory objects involved. Two Chassis objects 85*669d6fddSBenjamin Fairwill have `containing` and `contained_by`, a Chassis and PowerSupply will have 86*669d6fddSBenjamin Fair`powering` and `powered_by` respectively, etc. 87e12059abSBenjamin Fair 88e12059abSBenjamin FairExample JSON configurations: 89e12059abSBenjamin Fair 90e12059abSBenjamin Fairsuperchassis.json 91f4febd00SPatrick Williams 92e12059abSBenjamin Fair``` 93e12059abSBenjamin Fair{ 94e12059abSBenjamin Fair "Exposes": [ 95e12059abSBenjamin Fair { 96*669d6fddSBenjamin Fair "Name": "MyPort", 97*669d6fddSBenjamin Fair "Type": "BackplanePort" 98e12059abSBenjamin Fair } 99e12059abSBenjamin Fair ], 100e12059abSBenjamin Fair "Name": "Superchassis", 101e12059abSBenjamin Fair "Probe": "TRUE", 102e12059abSBenjamin Fair "Type": "Chassis" 103e12059abSBenjamin Fair} 104e12059abSBenjamin Fair``` 105e12059abSBenjamin Fair 106e12059abSBenjamin Fairsubchassis.json: 107f4febd00SPatrick Williams 108e12059abSBenjamin Fair``` 109e12059abSBenjamin Fair{ 110e12059abSBenjamin Fair "Exposes": [ 111e12059abSBenjamin Fair { 112*669d6fddSBenjamin Fair "ConnectsToType": "BackplanePort", 113e12059abSBenjamin Fair "Name": "MyDownstreamPort", 114e12059abSBenjamin Fair "Type": "DownstreamPort" 115e12059abSBenjamin Fair } 116e12059abSBenjamin Fair ], 117e12059abSBenjamin Fair "Name": "Subchassis", 118e12059abSBenjamin Fair "Probe": "TRUE", 119e12059abSBenjamin Fair "Type": "Chassis" 120e12059abSBenjamin Fair} 121e12059abSBenjamin Fair``` 122e12059abSBenjamin Fair 123e12059abSBenjamin Fair#### Other inventory managers 124f4febd00SPatrick Williams 125e12059abSBenjamin FairIf there are other daemons on the system exporting inventory objects, they can 126e12059abSBenjamin Fairchoose to include the same Associations that phosphor-inventory-manager and 127e12059abSBenjamin Fairentity-manager use. 128e12059abSBenjamin Fair 129e12059abSBenjamin Fair### Inventory consumers 130f4febd00SPatrick Williams 131e12059abSBenjamin FairWhen a daemon such as bmcweb wants to determine what other inventory items have 132e12059abSBenjamin Faira relationship to a specific item, it makes a query to the object mapper which 133e12059abSBenjamin Fairreturns a list of all associated items and the relationship types between them. 134e12059abSBenjamin Fair 135e12059abSBenjamin FairExample `busctl` calls: 136f4febd00SPatrick Williams 137e12059abSBenjamin Fair``` 138e12059abSBenjamin Fair$ busctl get-property xyz.openbmc_project.ObjectMapper \ 139*669d6fddSBenjamin Fair/xyz/openbmc_project/inventory/system/chassis/Superchassis/containing \ 140e12059abSBenjamin Fairxyz.openbmc_project.Association endpoints 141e12059abSBenjamin Fair 142e12059abSBenjamin Fairas 1 "/xyz/openbmc_project/inventory/system/chassis/Subchassis" 143e12059abSBenjamin Fair 144e12059abSBenjamin Fair$ busctl get-property xyz.openbmc_project.ObjectMapper \ 145*669d6fddSBenjamin Fair/xyz/openbmc_project/inventory/system/chassis/Subchassis/contained_by \ 146e12059abSBenjamin Fairxyz.openbmc_project.Association endpoints 147e12059abSBenjamin Fair 148e12059abSBenjamin Fairas 1 "/xyz/openbmc_project/inventory/system/chassis/Superchassis" 149e12059abSBenjamin Fair``` 150e12059abSBenjamin Fair 151e12059abSBenjamin Fair## Alternatives Considered 152f4febd00SPatrick Williams 153e12059abSBenjamin Fair### Path hierarchies 154f4febd00SPatrick Williams 155e12059abSBenjamin FairAn alternative proposal involves encoding the topological relationships between 156e12059abSBenjamin Fairinventory items using D-Bus path names. As an example, a chassis object 157e12059abSBenjamin Fairunderneath another would be contained by that parent chassis. This works for 158e12059abSBenjamin Fairsimple relationships which fit into a tree structure, but breaks down when more 159e12059abSBenjamin Faircomplicated relationships are introduced such as cables or fans and power 160e12059abSBenjamin Fairsupplies shared by multiple objects or soldered CPUs which are "part of" instead 161e12059abSBenjamin Fairof "contained by" a chassis. Introducing separate trays with their own topology 162e12059abSBenjamin Fairfurther complicates the path hierarchy approach. 163e12059abSBenjamin Fair 164e12059abSBenjamin FairA potential compromise would be allowing a combination of path hierarchies and 165e12059abSBenjamin Fairassociations to communicate topology, but this significantly increases the 166e12059abSBenjamin Faircomplexity of consumers of this information since they would have to support 167e12059abSBenjamin Fairboth approaches and figure out a way to resolve conflicting information. 168e12059abSBenjamin Fair 169e12059abSBenjamin FairAssociations are the only approach that fits all use cases, so we should start 170e12059abSBenjamin Fairwith this method. If the additional complexity of path hierarchies is needed in 171e12059abSBenjamin Fairthe future, it can be added as a separate design in the future. 172e12059abSBenjamin Fair 173e12059abSBenjamin FairTo improve usability for humans inspecting a system, there could also be a 174e12059abSBenjamin Fairdedicated tool to query for Associations of a specific type and present a 175e12059abSBenjamin Fairhierarchical view of the current topology. Additionally, 176e12059abSBenjamin Fairphosphor-inventory-manager configurations can organize their D-Bus objects in 177e12059abSBenjamin Fairwhatever way makes sense to the author of those configurations, but the 178e12059abSBenjamin FairAssociation properties would still need to be present in order for inventory 179e12059abSBenjamin Fairconsumers to understand the topology. 180e12059abSBenjamin Fair 181e12059abSBenjamin Fair## Impacts 182f4febd00SPatrick Williams 183e12059abSBenjamin FairThis new API will be documented in phosphor-dbus-interfaces as described above. 184e12059abSBenjamin FairIf no topology information is added to configuration files for entity-manager or 185e12059abSBenjamin Fairphosphor-inventory-manager, then the D-Bus interfaces exported by them will not 186e12059abSBenjamin Fairchange. If consumers of inventory data such as bmcweb do not find the new 187e12059abSBenjamin Fairassociations, then their output such as Redfish will not change either. 188e12059abSBenjamin Fair 189e12059abSBenjamin Fair### Organizational 190f4febd00SPatrick Williams 191e12059abSBenjamin FairDoes this repository require a new repository? No - all changes will go in 192e12059abSBenjamin Fairexisting repositories. 193e12059abSBenjamin Fair 194e12059abSBenjamin Fair## Testing 195f4febd00SPatrick Williams 196e12059abSBenjamin FairAll new code in entity-manager and bmcweb will be unit tested using existing 197e12059abSBenjamin Fairframeworks and infrastructure. We will add new end-to-end tests in 198e12059abSBenjamin Fairopenbmc-test-automation to ensure the Redfish output is correct. 199*669d6fddSBenjamin Fair 200*669d6fddSBenjamin Fair## Update history 201*669d6fddSBenjamin Fair 202*669d6fddSBenjamin Fair### February 14, 2023 203*669d6fddSBenjamin Fair 204*669d6fddSBenjamin Fair- Update the example port type and name from `Connector` to `Port` 205*669d6fddSBenjamin Fair- Change the association names based on feedback from phosphor-dbus-interfaces 206*669d6fddSBenjamin Fair maintainers (chassisContains -> containing, chassisContainedBy -> 207*669d6fddSBenjamin Fair contained_by, etc) 208