docs: Describe which associations are created
Add some documentation that describes which associations EM can
automatically create and how to configure it to do so.
Change-Id: Ibe6128bba37b1849138c8447e63aad187bd96624
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
diff --git a/README.md b/README.md
index e918497..dfffaa8 100644
--- a/README.md
+++ b/README.md
@@ -85,6 +85,11 @@
hot swap backplane daemon, which both reacts to the hot swap being detected, and
also creates detection records of what drives are present.
+### Associations
+
+Entity Manager will automatically create associations between its entities in
+certain cases. For details see [here](docs/associations.md).
+
## Requirements
1. Entity manager shall support the dynamic discovery of hardware at runtime,
diff --git a/docs/associations.md b/docs/associations.md
new file mode 100644
index 0000000..efcbee6
--- /dev/null
+++ b/docs/associations.md
@@ -0,0 +1,64 @@
+# Associations
+
+Entity Manager will create [associations][1] between entities in certain cases.
+
+## `contained_by`, `containing`
+
+Entity Manager can model the [physical topology][2] of how entities plug into
+each other when upstream and downstream ports are added as `Exposes` elements.
+It will then create the 'upstream containing downstream' and 'downstream
+contained_by upstream' associations for the connected entities.
+
+For example, taken from the referenced physical topology design:
+
+superchassis.json:
+
+```json
+{
+ "Exposes": [
+ {
+ "Name": "MyPort",
+ "Type": "BackplanePort"
+ }
+ ],
+ "Name": "Superchassis"
+}
+```
+
+subchassis.json:
+
+```json
+{
+ "Exposes": [
+ {
+ "ConnectsToType": "BackplanePort",
+ "Name": "MyDownstreamPort",
+ "Type": "DownstreamPort"
+ }
+ ],
+ "Name": "Subchassis"
+}
+```
+
+Entity Manager will create the 'Superchassis containing Subchassis' and
+'Subchassis contained_by Superchassis` associations, putting the associations
+definition interface on the downstream entity.
+
+## `powered_by`, `powering`
+
+In addition to the `containing` associations, entity-manager will add
+`powering`/`powered_by` associations between a power supply and its parent when
+its downstream port is marked as a `PowerPort`:
+
+```json
+{
+ "ConnectsToType": "Mobo Upstream Port",
+ "Name": "PSU $BUS Downstream Port",
+ "Type": "DownstreamPort",
+ "PowerPort": true
+}
+```
+
+[1]:
+ https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
+[2]: https://github.com/openbmc/docs/blob/master/designs/physical-topology.md