xref: /openbmc/entity-manager/docs/associations.md (revision 0671d3cebc799ea5f20208b033daefe53e54092f) 
1# Associations
2
3Entity Manager will create [associations][1] between entities in certain cases.
4The associations are needed as part of [2].
5
6## Configuring Associations between Entities
7
8The configuration record has `Name` field which is used to connect 2 ports for
9an association definition.
10
11If a matching element with `Name` is not found, that is not an error, it simply
12means the component we want to associate to is not present.
13
14The `PortType` describes which association to create. This is limited to
15pre-defined values. It also defines the direction of the association.
16
17### containing Association
18
19Baseboard configuration.
20
21```json
22{
23  "Exposes": [
24    {
25      "Name": "ContainingPort",
26      "PortType": "contained_by"
27      "Type": "Port"
28    }
29  ],
30  "Name": "Tyan S8030 Baseboard"
31}
32```
33
34Chassis configuration.
35
36```json
37{
38  "Exposes": [
39    {
40      "Name": "ContainingPort",
41      "PortType": "containing"
42      "Type": "Port"
43    }
44  ],
45  "Name": "MBX Chassis"
46}
47```
48
49### powering Association
50
51Baseboard configuration. This baseboard accepts one of several generic PSUs.
52
53```json
54{
55  "Exposes": [
56    {
57      "Name": "GenericPowerPort",
58      "PortType": "powered_by"
59      "Type": "Port"
60    }
61  ],
62  "Name": "Tyan S8030 Baseboard"
63}
64```
65
66PSU configuration. This example PSU is generic and can be used on different
67servers.
68
69```json
70{
71  "Exposes": [
72    {
73      "Name": "GenericPowerPort",
74      "PortType": "powering"
75      "Type": "Port"
76    }
77  ],
78  "Name": "Generic Supermicro PSU"
79}
80```
81
82### probing Association
83
84The probing association matches an entry in the inventory to a probed path and
85depends on the 'Probe' statement of an EM configuration. If the 'Probe'
86statement matches properties to a path, this path is set as the probed path in
87the inventory item.
88
89For example 'yosemite4.json':
90
91```json
92{
93    "Exposes": [
94        ...
95    ],
96    "Name": "Yosemite 4 Management Board",
97    "Probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME': 'Management Board wBMC', 'PRODUCT_PRODUCT_NAME': 'Yosemite V4'})",
98    "Type": "Board",
99    ...
100}
101```
102
103This configuration queries the object mapper to find an FruDevice interface with
104with the stated property values (BOARD_PRODUCT_NAME, PRODUCT_NAME). The path
105`/xyz/openbmc_project/FruDevice/Management_Board_wBMC` is found, which means EM
106loads the configuration. The found path is the probed path and is placed as the
107probing/probed_by association property in the inventory item of the
108configuration.
109
110[1]:
111  https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
112[2]: https://github.com/openbmc/docs/blob/master/designs/physical-topology.md
113