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