topology: schema rework
Deprecate the old topology schemas since they cannot be extended
anymore without making 'Type' field variable.
'Type' field has to be const/enum for people to be able to find the
schema for a configuration record and for EM to be able to create a PDI
compatible DBus interface name.
The new schema for defining topology association definitions uses
'Name' property to connect the inventory items containing
the topology definitions via association definitions.
Error handling:
If the other port to 'Name' is not present, it is not an
error, the association definition will simply not be created.
This helps to represent optional components.
Power examples:
Simple, 2 fixed component. They can both declare 'Name'
```
component 1 --- PSU 1
```
One component, containing 2 components.
```
/--- PSU 1
component 1
\--- PSU 2
```
One generic PSU config connecting to one of various boards.
There are PSU 2 instances in this example.
The upstream component (baseboard) needs to declare a fixed 'Name' and
the PSU declares `Name`.
```
/--- component 2 (PSU 1)
component 1
\--- component 2 (PSU 2)
component 3 (baseboard, not present)
component 4 (baseboard, not present)
```
Containment examples:
```
Baseboard ---- Chassis variant 1
Chassis variant 2 (not present)
```
All components besides the enclosure chassis need to know their
index/name here.
```
Baseboard 1 --+-- Chassis 1 --+
| |
Baseboard 2 --+-- Chassis 2 --+-- Chassis (Enclosure)
. .
. .
Baseboard N --+-- Chassis N --+
```
Implementation: next patch
Tested: next patch
References:
[1] https://github.com/openbmc/docs/blob/master/designs/physical-topology.md
[2] https://gerrit.openbmc.org/c/openbmc/entity-manager/+/81926 (Olek's
change for containment)
[3] https://gerrit.openbmc.org/c/openbmc/entity-manager/+/82408
(citysides change for cooling/cooled_by)
Change-Id: Iacf0c87dfe118ebe50e9461d519e226f10a059c5
Signed-off-by: Alexander Hansen <alexander.hansen@9elements.com>
diff --git a/docs/associations.md b/docs/associations.md
index 4dcb167..f221270 100644
--- a/docs/associations.md
+++ b/docs/associations.md
@@ -2,6 +2,86 @@
Entity Manager will create [associations][1] between entities in certain cases.
+## Configuring Associations between Entities
+
+The configuration record has `Name` field which is used to connect 2 ports for
+an association definition.
+
+If a matching element with `Name` is not found, that is not an error, it simply
+means the component we want to associate to is not present.
+
+The `PortType` describes which association to create. This is limited to
+pre-defined values. It also defines the direction of the association.
+
+### containing Association
+
+Baseboard configuration.
+
+```json
+{
+ "Exposes": [
+ {
+ "Name": "ContainingPort",
+ "PortType": "contained_by"
+ "Type": "Port"
+ }
+ ],
+ "Name": "Tyan S8030 Baseboard"
+}
+```
+
+Chassis configuration.
+
+```json
+{
+ "Exposes": [
+ {
+ "Name": "ContainingPort",
+ "PortType": "containing"
+ "Type": "Port"
+ }
+ ],
+ "Name": "MBX Chassis"
+}
+```
+
+### powering Association
+
+Baseboard configuration. This baseboard accepts one of several generic PSUs.
+
+```json
+{
+ "Exposes": [
+ {
+ "Name": "GenericPowerPort",
+ "PortType": "powered_by"
+ "Type": "Port"
+ }
+ ],
+ "Name": "Tyan S8030 Baseboard"
+}
+```
+
+PSU configuration. This example PSU is generic and can be used on different
+servers.
+
+```json
+{
+ "Exposes": [
+ {
+ "Name": "GenericPowerPort",
+ "PortType": "powering"
+ "Type": "Port"
+ }
+ ],
+ "Name": "Generic Supermicro PSU"
+}
+```
+
+## Deprecated configuration style
+
+The configuration style described below is deprecated and superseded.
+
## `contained_by`, `containing`
Entity Manager can model the [physical topology][2] of how entities plug into
diff --git a/schemas/exposes_record.json b/schemas/exposes_record.json
index 9196b54..1bad51f 100644
--- a/schemas/exposes_record.json
+++ b/schemas/exposes_record.json
@@ -88,7 +88,10 @@
"$ref": "topology.json#/$defs/Port"
},
{
- "$ref": "topology.json#/$defs/DownstreamPort"
+ "$ref": "topology.json#/$defs/LegacyPort"
+ },
+ {
+ "$ref": "topology.json#/$defs/LegacyDownstreamPort"
},
{
"$ref": "legacy.json#/$defs/PSUPresence"
diff --git a/schemas/topology.json b/schemas/topology.json
index 5b9a968..66c9d59 100644
--- a/schemas/topology.json
+++ b/schemas/topology.json
@@ -8,6 +8,33 @@
"Name": {
"$ref": "#/$defs/Types/Name"
},
+ "PortType": {
+ "description": "This enum may be extended as described in the design",
+ "type": "string",
+ "enum": [
+ "powering",
+ "powered_by",
+ "cooling",
+ "cooled_by",
+ "containing",
+ "contained_by"
+ ]
+ },
+ "Type": {
+ "type": "string",
+ "const": "Port"
+ }
+ },
+ "required": ["Name", "PortType", "Type"],
+ "type": "object"
+ },
+ "LegacyPort": {
+ "description": "deprecated schema. https://github.com/openbmc/docs/blob/master/designs/physical-topology.md",
+ "additionalProperties": false,
+ "properties": {
+ "Name": {
+ "$ref": "#/$defs/Types/Name"
+ },
"Type": {
"description": "This enum may be extended as described in the design",
"type": "string",
@@ -17,8 +44,8 @@
"required": ["Name", "Type"],
"type": "object"
},
- "DownstreamPort": {
- "description": "https://github.com/openbmc/docs/blob/master/designs/physical-topology.md",
+ "LegacyDownstreamPort": {
+ "description": "deprecated schema. https://github.com/openbmc/docs/blob/master/designs/physical-topology.md",
"additionalProperties": false,
"properties": {
"Name": {