xref: /openbmc/docs/designs/physical-topology.md (revision 33d73e38) 
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 Inventory/Item or the more specific subtypes, we
65add an association definition for each of the relationship types listed above
66and corresponding association definitions linking back to that 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 type ending in `Port`
79(such as a `BackplanePort`, `PowerInputPort`, 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 `containing` and `contained_by`, a Chassis and PowerSupply will have
86`powering` and `powered_by` respectively, etc.
87
88Example JSON configurations:
89
90superchassis.json
91
92```
93{
94    "Exposes": [
95        {
96            "Name": "MyPort",
97            "Type": "BackplanePort"
98        }
99    ],
100    "Name": "Superchassis",
101    "Probe": "TRUE",
102    "Type": "Chassis"
103}
104```
105
106subchassis.json:
107
108```
109{
110    "Exposes": [
111        {
112            "ConnectsToType": "BackplanePort",
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/containing \
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/contained_by \
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
200## Update history
201
202### February 14, 2023
203
204- Update the example port type and name from `Connector` to `Port`
205- Change the association names based on feedback from phosphor-dbus-interfaces
206  maintainers (chassisContains -> containing, chassisContainedBy ->
207  contained_by, etc)
208