object-mapper: Add doc on AssociatedById handlers
This updates the documentation on the following new methods.
- GetAssociatedSubTreeById
- GetAssociatedSubTreePathsById
The handler is being implemented in
https://gerrit.openbmc.org/c/openbmc/phosphor-objmgr/+/70699
Change-Id: Iee98fb0da2a8bf1bde663ffc2502aa106e0ecf2f
Signed-off-by: Myung Bae <myungbae@us.ibm.com>
diff --git a/architecture/object-mapper.md b/architecture/object-mapper.md
index 2faec47..a0c7273 100644
--- a/architecture/object-mapper.md
+++ b/architecture/object-mapper.md
@@ -188,6 +188,88 @@
Find all object paths and services that implement a specific interface and
endpoint of the input associationPath.
+### GetAssociatedSubTreeById
+
+Use this method to find the objects, services, and interfaces in the specified
+subtree that implement certain interfaces and endpoints that end by input `id`.
+If no interfaces are passed in, then all objects/services/interfaces in the
+subtree and associated endpoint are returned. If interfaces are passed in, then
+only those interfaces are returned in the output.
+
+Inputs:
+
+- param: id - The leaf name of the dbus path, uniquely identifying a specific
+ component or entity within the system.
+- param: objectPath - The object path for which the result should be fetched.
+- param: subtreeInterfaces - a list of interfaces to constrain the search to
+- param: association - The endpoint association.
+- param: endpointInterfaces - An array of interfaces used to filter associated
+ endpoint paths.
+
+Output:
+
+- Map of object paths to a map of service names to their interfaces that are in
+ the associated endpoints that end with `id`
+
+```text
+ID="chassis"
+ASSOCIATION="powered_by"
+dbus-send --system --print-reply \
+--dest=xyz.openbmc_project.ObjectMapper \
+/xyz/openbmc_project/object_mapper \
+xyz.openbmc_project.ObjectMapper.GetAssociatedSubTreeById \
+string:"${ID}" string:"/xyz/openbmc_project/inventory" \
+array:string:"xyz.openbmc_project.Inventory.Item.Chassis" \
+string:"${ASSOCIATION}" \
+array:string:"xyz.openbmc_project.Inventory.Item.PowerSupply"
+
+ array [
+ dict entry(
+ string "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
+ array [
+ dict entry(
+ string "xyz.openbmc_project.Inventory.Manager"
+ array [
+ ...
+ string "xyz.openbmc_project.Inventory.Item"
+ string "xyz.openbmc_project.Inventory.Item.PowerSupply"
+ ...
+ ]
+ )
+ ]
+ )
+ dict entry(
+ string "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
+ array [
+ dict entry(
+ string "xyz.openbmc_project.Inventory.Manager"
+ array [
+ ...
+ string "xyz.openbmc_project.Inventory.Item"
+ string "xyz.openbmc_project.Inventory.Item.PowerSupply"
+ ...
+ ]
+ )
+ ]
+ )
+ ....
+...
+
+# All output must be in the association endpoints that ends with the given `id`
+CHASSIS_PATH=/xyz/openbmc_project/inventory/system/chassis
+busctl get-property xyz.openbmc_project.ObjectMapper \
+ /xyz/openbmc_project/inventory/system/chassis/${ASSOCIATION} \
+ xyz.openbmc_project.Association endpoints
+as N "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0" \
+"/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1" \
+ ...
+```
+
+#### Example Use Case
+
+Find all object paths and services that implement a specific interface and
+endpoint of the input associationPath.
+
### GetSubTreePaths
This is the same as GetSubTree, but only returns object paths
@@ -267,6 +349,59 @@
Find all object paths that implement a specific interface and endpoint of the
input associationPath.
+### GetAssociatedSubTreePathsById
+
+This is the same as GetAssociatedSubTreePathsById, but only returns object paths
+
+Inputs:
+
+- param: id - The leaf name of the dbus path, uniquely identifying a specific
+ component or entity within the system.
+- param: objectPath - The object path for which the result should be fetched.
+- param: subtreeInterfaces - a list of interfaces to constrain the search to
+- param: association - The endpoint association.
+- param: endpointInterfaces - An array of interfaces used to filter associated
+ endpoint paths.
+
+Output:
+
+- Map of object paths to a map of service names to their interfaces that are in
+ the associated endpoints that ends with `id`
+
+```text
+ID="chassis"
+ASSOCIATION="powered_by"
+dbus-send --system --print-reply \
+--dest=xyz.openbmc_project.ObjectMapper \
+/xyz/openbmc_project/object_mapper \
+xyz.openbmc_project.ObjectMapper.GetAssociatedSubTreePathsById \
+string:"${ID}" string:"/xyz/openbmc_project/inventory" \
+array:string:"xyz.openbmc_project.Inventory.Item.Chassis" \
+string:"${ASSOCIATION}" \
+array:string:"xyz.openbmc_project.Inventory.Item.PowerSupply"
+
+ array [
+ string "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0"
+ string "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1"
+ ...
+ ]
+...
+
+# All output must be in the association endpoints that ends with the given `id`
+CHASSIS_PATH=/xyz/openbmc_project/inventory/system/chassis
+busctl get-property xyz.openbmc_project.ObjectMapper \
+ /xyz/openbmc_project/inventory/system/chassis/${ASSOCIATION} \
+ xyz.openbmc_project.Association endpoints
+as N "/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply0" \
+"/xyz/openbmc_project/inventory/system/chassis/motherboard/powersupply1" \
+ ...
+```
+
+#### Example Use Case
+
+Find all object paths that implement a specific interface and endpoint of the
+input associationPath.
+
### GetAncestors
Use this method to find all ancestors of an object that implement a specific