xref: /openbmc/entity-manager/docs/associations.md (revision 9a5eec91664d61ed47630a616c2e187c7c6a69bc) 
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### probing Association
82
83The probing association matches an entry in the inventory to a probed path and
84depends on the 'Probe' statement of an EM configuration. If the 'Probe'
85statement matches properties to a path, this path is set as the probed path in
86the inventory item.
87
88For example 'yosemite4.json':
89
90```json
91{
92    "Exposes": [
93        ...
94    ],
95    "Name": "Yosemite 4 Management Board",
96    "Probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME': 'Management Board wBMC', 'PRODUCT_PRODUCT_NAME': 'Yosemite V4'})",
97    "Type": "Board",
98    ...
99}
100```
101
102This configuration queries the object mapper to find an FruDevice interface with
103with the stated property values (BOARD_PRODUCT_NAME, PRODUCT_NAME). The path
104`/xyz/openbmc_project/FruDevice/Management_Board_wBMC` is found, which means EM
105loads the configuration. The found path is the probed path and is placed as the
106probing/probed_by association property in the inventory item of the
107configuration.
108
109## Deprecated configuration style
110
111The configuration style described below is deprecated and superseded.
112
113## `contained_by`, `containing`
114
115Entity Manager can model the [physical topology][2] of how entities plug into
116each other when upstream and downstream ports are added as `Exposes` elements.
117It will then create the 'upstream containing downstream' and 'downstream
118contained_by upstream' associations for the connected entities.
119
120For example, taken from the referenced physical topology design:
121
122superchassis.json:
123
124```json
125{
126  "Exposes": [
127    {
128      "Name": "MyPort",
129      "Type": "BackplanePort"
130    }
131  ],
132  "Name": "Superchassis"
133}
134```
135
136subchassis.json:
137
138```json
139{
140  "Exposes": [
141    {
142      "ConnectsToType": "BackplanePort",
143      "Name": "MyDownstreamPort",
144      "Type": "DownstreamPort"
145    }
146  ],
147  "Name": "Subchassis"
148}
149```
150
151Entity Manager will create the 'Superchassis containing Subchassis' and
152'Subchassis contained_by Superchassis` associations, putting the associations
153definition interface on the downstream entity.
154
155## `powered_by`, `powering`
156
157In addition to the `containing` associations, entity-manager will add
158`powering`/`powered_by` associations between a power supply and its parent when
159its downstream port is marked as a `PowerPort`.
160
161The below example shows two PSU ports on the motherboard, where the `Type`
162fields for those ports match up with the `ConnectsToType` field from the PSUs.
163
164motherboard.json:
165
166```json
167{
168  "Exposes": [
169    {
170      "Name": "PSU 1 Port",
171      "Type": "PSU 1 Port"
172    },
173    {
174      "Name": "PSU 2 Port",
175      "Type": "PSU 2 Port"
176    }
177  ]
178}
179```
180
181psu.json:
182
183```json
184{
185  "Exposes": [
186    {
187      "ConnectsToType": "PSU$ADDRESS % 4 + 1 Port",
188      "Name": "PSU Port",
189      "Type": "DownstreamPort",
190      "PowerPort": true
191    }
192  ]
193}
194```
195
196[1]:
197  https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
198[2]: https://github.com/openbmc/docs/blob/master/designs/physical-topology.md
199