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