1# Associations
2
3Entity Manager will create [associations][1] between entities in certain cases.
4
5## `contained_by`, `containing`
6
7Entity Manager can model the [physical topology][2] of how entities plug into
8each other when upstream and downstream ports are added as `Exposes` elements.
9It will then create the 'upstream containing downstream' and 'downstream
10contained_by upstream' associations for the connected entities.
11
12For example, taken from the referenced physical topology design:
13
14superchassis.json:
15
16```json
17{
18  "Exposes": [
19    {
20      "Name": "MyPort",
21      "Type": "BackplanePort"
22    }
23  ],
24  "Name": "Superchassis"
25}
26```
27
28subchassis.json:
29
30```json
31{
32  "Exposes": [
33    {
34      "ConnectsToType": "BackplanePort",
35      "Name": "MyDownstreamPort",
36      "Type": "DownstreamPort"
37    }
38  ],
39  "Name": "Subchassis"
40}
41```
42
43Entity Manager will create the 'Superchassis containing Subchassis' and
44'Subchassis contained_by Superchassis` associations, putting the associations
45definition interface on the downstream entity.
46
47## `powered_by`, `powering`
48
49In addition to the `containing` associations, entity-manager will add
50`powering`/`powered_by` associations between a power supply and its parent when
51its downstream port is marked as a `PowerPort`.
52
53The below example shows two PSU ports on the motherboard, where the `Type`
54fields for those ports match up with the `ConnectsToType` field from the PSUs.
55
56motherboard.json:
57
58```json
59{
60  "Exposes": [
61    {
62      "Name": "PSU 1 Port",
63      "Type": "PSU 1 Port"
64    },
65    {
66      "Name": "PSU 2 Port",
67      "Type": "PSU 2 Port"
68    }
69  ]
70}
71```
72
73psu.json:
74
75```json
76{
77  "Exposes": [
78    {
79      "ConnectsToType": "PSU$ADDRESS % 4 + 1 Port",
80      "Name": "PSU Port",
81      "Type": "DownstreamPort",
82      "PowerPort": true
83    }
84  ]
85}
86```
87
88[1]:
89  https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
90[2]: https://github.com/openbmc/docs/blob/master/designs/physical-topology.md
91