1# Physical Topology for Inventory Items 2 3Author: Benjamin Fair <benjaminfair> 4 5Other contributors: 6 Ed Tanous <edtanous> 7 8Created: June 1, 2022 9 10## Problem Description 11Complex systems may contain many inventory objects (such as chassis, power 12supplies, cables, fans, etc.) with different types of relationships among these 13objects. For instance, one chassis can contain another, be powered by a set of 14power supplies, connect to cables, and be cooled by fans. OpenBMC does not 15currently have a standard way to represent these types of relationships. 16 17## Background and References 18This builds on a [prior 19proposal](https://gerrit.openbmc.org/c/openbmc/docs/+/41468), but specifies 20using Associations for all relationships (Proposal II) rather than path 21hierarchies (Proposal I). 22 23The main driver of this design is Redfish, particularly the Links section of the 24[Chassis schema](https://redfish.dmtf.org/schemas/Chassis.v1_20_0.json). 25 26Changes to phosphor-dbus-interfaces documenting new Associations have been 27[proposed](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/46806) 28but not yet merged until consensus can be reached on the design. 29 30This design was initially discussed in 31[Discord](https://discord.com/channels/775381525260664832/819741065531359263/964321666790477924), 32where some initial consensus was reached. 33 34## Requirements 35* Must represent one-to-many relationships from chassis inventory objects which: 36 * Connect to cables 37 * Contain other chassis and/or are contained by a chassis 38 * Contain storage drives 39 * Are cooled by fans 40 * Are powered by power supplies 41 * Contain processors such as CPUs 42 * Contain memory such as DIMMs 43* Must support relationships which are predefined, detected at runtime, or a 44 combination of both 45 * Runtime detection could include I2C bus scanning, USB enumeration, and/or 46 MCTP discovery 47 48### Optional goals (beyond initial implementation) 49* Non-chassis inventory objects may also need one-to-many relationships 50 * CPUs have CPU cores and associated PCIe slots 51 * CPU cores have threads 52 53## Proposed Design 54The design affects three layers of the OpenBMC architecture: 55phosphor-dbus-interfaces, inventory managers, and inventory consumers such as 56bmcweb. 57 58### phosphor-dbus-interfaces 59In the interface definition for Chassis inventory items, we add an association 60definition for each of the relationship types listed above and corresponding 61association definitions for the other item types linking back to a Chassis item. 62 63### Inventory Managers 64#### phosphor-inventory-manager 65phosphor-inventory-manager already has support for exporting custom 66Associations, so no changes are needed here. 67 68#### entity-manager 69For entity-manager, we add new `Exposes` stanzas for the upstream and downstream 70ports in the JSON configurations. The upstream port has a connector type (such 71as a backplane connector, power input, etc). The downstream port has type 72`DownstreamPort` and a `ConnectsToType` property that refers to the upstream 73port based on its type. 74 75New code in entity-manager matches these properties and exposes associations on 76D-Bus based on the types of the inventory objects involved. Two Chassis objects 77will have `chassisContains` and `chassisContainedBy`, a Chassis and PowerSupply 78will have `poweredBy` and `powers` respectively, etc. 79 80Example JSON configurations: 81 82superchassis.json 83``` 84{ 85 "Exposes": [ 86 { 87 "Name": "MyConnector", 88 "Type": "BackplaneConnector" 89 } 90 ], 91 "Name": "Superchassis", 92 "Probe": "TRUE", 93 "Type": "Chassis" 94} 95``` 96 97subchassis.json: 98``` 99{ 100 "Exposes": [ 101 { 102 "ConnectsToType": "BackplaneConnector", 103 "Name": "MyDownstreamPort", 104 "Type": "DownstreamPort" 105 } 106 ], 107 "Name": "Subchassis", 108 "Probe": "TRUE", 109 "Type": "Chassis" 110} 111``` 112 113#### Other inventory managers 114If there are other daemons on the system exporting inventory objects, they can 115choose to include the same Associations that phosphor-inventory-manager and 116entity-manager use. 117 118### Inventory consumers 119When a daemon such as bmcweb wants to determine what other inventory items have 120a relationship to a specific item, it makes a query to the object mapper which 121returns a list of all associated items and the relationship types between them. 122 123Example `busctl` calls: 124``` 125$ busctl get-property xyz.openbmc_project.ObjectMapper \ 126/xyz/openbmc_project/inventory/system/chassis/Superchassis/chassisContains \ 127xyz.openbmc_project.Association endpoints 128 129as 1 "/xyz/openbmc_project/inventory/system/chassis/Subchassis" 130 131$ busctl get-property xyz.openbmc_project.ObjectMapper \ 132/xyz/openbmc_project/inventory/system/chassis/Subchassis/chassisContainedBy \ 133xyz.openbmc_project.Association endpoints 134 135as 1 "/xyz/openbmc_project/inventory/system/chassis/Superchassis" 136``` 137 138## Alternatives Considered 139### Path hierarchies 140An alternative proposal involves encoding the topological relationships between 141inventory items using D-Bus path names. As an example, a chassis object 142underneath another would be contained by that parent chassis. This works for 143simple relationships which fit into a tree structure, but breaks down when more 144complicated relationships are introduced such as cables or fans and power 145supplies shared by multiple objects or soldered CPUs which are "part of" instead 146of "contained by" a chassis. Introducing separate trays with their own topology 147further complicates the path hierarchy approach. 148 149A potential compromise would be allowing a combination of path hierarchies and 150associations to communicate topology, but this significantly increases the 151complexity of consumers of this information since they would have to support 152both approaches and figure out a way to resolve conflicting information. 153 154Associations are the only approach that fits all use cases, so we should start 155with this method. If the additional complexity of path hierarchies is needed in 156the future, it can be added as a separate design in the future. 157 158To improve usability for humans inspecting a system, there could also be a 159dedicated tool to query for Associations of a specific type and present a 160hierarchical view of the current topology. Additionally, 161phosphor-inventory-manager configurations can organize their D-Bus objects in 162whatever way makes sense to the author of those configurations, but the 163Association properties would still need to be present in order for inventory 164consumers to understand the topology. 165 166## Impacts 167This new API will be documented in phosphor-dbus-interfaces as described above. 168If no topology information is added to configuration files for entity-manager or 169phosphor-inventory-manager, then the D-Bus interfaces exported by them will not 170change. If consumers of inventory data such as bmcweb do not find the new 171associations, then their output such as Redfish will not change either. 172 173### Organizational 174Does this repository require a new repository? No - all changes will go in 175existing repositories. 176 177## Testing 178All new code in entity-manager and bmcweb will be unit tested using existing 179frameworks and infrastructure. We will add new end-to-end tests in 180openbmc-test-automation to ensure the Redfish output is correct. 181