Author: Benjamin Fair
Other contributors: Ed Tanous
Created: June 1, 2022
Complex systems may contain many inventory objects (such as chassis, power supplies, cables, fans, etc.) with different types of relationships among these objects. For instance, one chassis can contain another, be powered by a set of power supplies, connect to cables, and be cooled by fans. OpenBMC does not currently have a standard way to represent these types of relationships.
This builds on a prior proposal, but specifies using Associations for all relationships (Proposal II) rather than path hierarchies (Proposal I).
The main driver of this design is Redfish, particularly the Links section of the Chassis schema.
Changes to phosphor-dbus-interfaces documenting new Associations have been proposed but not yet merged until consensus can be reached on the design.
This design was initially discussed in Discord, where some initial consensus was reached.
The design affects three layers of the OpenBMC architecture: phosphor-dbus-interfaces, inventory managers, and inventory consumers such as bmcweb.
In the interface definition for Chassis inventory items, we add an association definition for each of the relationship types listed above and corresponding association definitions for the other item types linking back to a Chassis item.
phosphor-inventory-manager already has support for exporting custom Associations, so no changes are needed here.
For entity-manager, we add new Exposes stanzas for the upstream and downstream ports in the JSON configurations. The upstream port has a connector type (such as a backplane connector, power input, etc). The downstream port has type DownstreamPort and a ConnectsToType property that refers to the upstream port based on its type.
New code in entity-manager matches these properties and exposes associations on D-Bus based on the types of the inventory objects involved. Two Chassis objects will have chassisContains and chassisContainedBy, a Chassis and PowerSupply will have poweredBy and powers respectively, etc.
Example JSON configurations:
superchassis.json
{
"Exposes": [
{
"Name": "MyConnector",
"Type": "BackplaneConnector"
}
],
"Name": "Superchassis",
"Probe": "TRUE",
"Type": "Chassis"
}
subchassis.json:
{
"Exposes": [
{
"ConnectsToType": "BackplaneConnector",
"Name": "MyDownstreamPort",
"Type": "DownstreamPort"
}
],
"Name": "Subchassis",
"Probe": "TRUE",
"Type": "Chassis"
}
If there are other daemons on the system exporting inventory objects, they can choose to include the same Associations that phosphor-inventory-manager and entity-manager use.
When a daemon such as bmcweb wants to determine what other inventory items have a relationship to a specific item, it makes a query to the object mapper which returns a list of all associated items and the relationship types between them.
Example busctl calls:
$ busctl get-property xyz.openbmc_project.ObjectMapper \ /xyz/openbmc_project/inventory/system/chassis/Superchassis/chassisContains \ xyz.openbmc_project.Association endpoints as 1 "/xyz/openbmc_project/inventory/system/chassis/Subchassis" $ busctl get-property xyz.openbmc_project.ObjectMapper \ /xyz/openbmc_project/inventory/system/chassis/Subchassis/chassisContainedBy \ xyz.openbmc_project.Association endpoints as 1 "/xyz/openbmc_project/inventory/system/chassis/Superchassis"
An alternative proposal involves encoding the topological relationships between inventory items using D-Bus path names. As an example, a chassis object underneath another would be contained by that parent chassis. This works for simple relationships which fit into a tree structure, but breaks down when more complicated relationships are introduced such as cables or fans and power supplies shared by multiple objects or soldered CPUs which are "part of" instead of "contained by" a chassis. Introducing separate trays with their own topology further complicates the path hierarchy approach.
A potential compromise would be allowing a combination of path hierarchies and associations to communicate topology, but this significantly increases the complexity of consumers of this information since they would have to support both approaches and figure out a way to resolve conflicting information.
Associations are the only approach that fits all use cases, so we should start with this method. If the additional complexity of path hierarchies is needed in the future, it can be added as a separate design in the future.
To improve usability for humans inspecting a system, there could also be a dedicated tool to query for Associations of a specific type and present a hierarchical view of the current topology. Additionally, phosphor-inventory-manager configurations can organize their D-Bus objects in whatever way makes sense to the author of those configurations, but the Association properties would still need to be present in order for inventory consumers to understand the topology.
This new API will be documented in phosphor-dbus-interfaces as described above. If no topology information is added to configuration files for entity-manager or phosphor-inventory-manager, then the D-Bus interfaces exported by them will not change. If consumers of inventory data such as bmcweb do not find the new associations, then their output such as Redfish will not change either.
Does this repository require a new repository? No - all changes will go in existing repositories.
All new code in entity-manager and bmcweb will be unit tested using existing frameworks and infrastructure. We will add new end-to-end tests in openbmc-test-automation to ensure the Redfish output is correct.