xref: /openbmc/entity-manager/docs/associations.md (revision f850ecad00900a9d338950e28506c04af42b8883) 
1# Associations
2
3Entity Manager will create [associations][1] between entities in certain cases.
4
5## Configuring Associations between Entities
6
7The configuration record has `Name` field which is used to connect 2 ports for
8an association definition.
9
10If a matching element with `Name` is not found, that is not an error, it simply
11means the component we want to associate to is not present.
12
13The `PortType` describes which association to create. This is limited to
14pre-defined values. It also defines the direction of the association.
15
16### containing Association
17
18Baseboard configuration.
19
20```json
21{
22  "Exposes": [
23    {
24      "Name": "ContainingPort",
25      "PortType": "contained_by"
26      "Type": "Port"
27    }
28  ],
29  "Name": "Tyan S8030 Baseboard"
30}
31```
32
33Chassis configuration.
34
35```json
36{
37  "Exposes": [
38    {
39      "Name": "ContainingPort",
40      "PortType": "containing"
41      "Type": "Port"
42    }
43  ],
44  "Name": "MBX Chassis"
45}
46```
47
48### powering Association
49
50Baseboard configuration. This baseboard accepts one of several generic PSUs.
51
52```json
53{
54  "Exposes": [
55    {
56      "Name": "GenericPowerPort",
57      "PortType": "powered_by"
58      "Type": "Port"
59    }
60  ],
61  "Name": "Tyan S8030 Baseboard"
62}
63```
64
65PSU configuration. This example PSU is generic and can be used on different
66servers.
67
68```json
69{
70  "Exposes": [
71    {
72      "Name": "GenericPowerPort",
73      "PortType": "powering"
74      "Type": "Port"
75    }
76  ],
77  "Name": "Generic Supermicro PSU"
78}
79```
80
81## Deprecated configuration style
82
83The configuration style described below is deprecated and superseded.
84
85## `contained_by`, `containing`
86
87Entity Manager can model the [physical topology][2] of how entities plug into
88each other when upstream and downstream ports are added as `Exposes` elements.
89It will then create the 'upstream containing downstream' and 'downstream
90contained_by upstream' associations for the connected entities.
91
92For example, taken from the referenced physical topology design:
93
94superchassis.json:
95
96```json
97{
98  "Exposes": [
99    {
100      "Name": "MyPort",
101      "Type": "BackplanePort"
102    }
103  ],
104  "Name": "Superchassis"
105}
106```
107
108subchassis.json:
109
110```json
111{
112  "Exposes": [
113    {
114      "ConnectsToType": "BackplanePort",
115      "Name": "MyDownstreamPort",
116      "Type": "DownstreamPort"
117    }
118  ],
119  "Name": "Subchassis"
120}
121```
122
123Entity Manager will create the 'Superchassis containing Subchassis' and
124'Subchassis contained_by Superchassis` associations, putting the associations
125definition interface on the downstream entity.
126
127## `powered_by`, `powering`
128
129In addition to the `containing` associations, entity-manager will add
130`powering`/`powered_by` associations between a power supply and its parent when
131its downstream port is marked as a `PowerPort`.
132
133The below example shows two PSU ports on the motherboard, where the `Type`
134fields for those ports match up with the `ConnectsToType` field from the PSUs.
135
136motherboard.json:
137
138```json
139{
140  "Exposes": [
141    {
142      "Name": "PSU 1 Port",
143      "Type": "PSU 1 Port"
144    },
145    {
146      "Name": "PSU 2 Port",
147      "Type": "PSU 2 Port"
148    }
149  ]
150}
151```
152
153psu.json:
154
155```json
156{
157  "Exposes": [
158    {
159      "ConnectsToType": "PSU$ADDRESS % 4 + 1 Port",
160      "Name": "PSU Port",
161      "Type": "DownstreamPort",
162      "PowerPort": true
163    }
164  ]
165}
166```
167
168[1]:
169  https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
170[2]: https://github.com/openbmc/docs/blob/master/designs/physical-topology.md
171