1description: >
2    Implement to provide DBus service lookup features.
3
4    Any OpenBMC implementation must provide exactly one implementation of
5    xyz.openbmc_project.ObjectMapper on /xyz/openbmc_project/ObjectMapper.
6
7methods:
8    - name: GetObject
9      description: >
10          Obtain a dictionary of service -> implemented interface(s) for the
11          given path.
12      parameters:
13          - name: path
14            type: string
15            description: >
16                The object path for which the result should be fetched.
17          - name: interfaces
18            type: array[string]
19            description: >
20                An array of result set constraining interfaces.
21      returns:
22          - name: services
23            type: dict[string,array[string]]
24            description: >
25                A dictionary of service -> implemented interface(s).
26      errors:
27          - xyz.openbmc_project.Common.Error.ResourceNotFound
28    - name: GetAncestors
29      description: >
30          Obtain a dictionary of ancestor -> services where ancestor is an
31          ancestor of path and services is of the type returned by the GetObject
32          method.
33      parameters:
34          - name: path
35            type: string
36            description: >
37                The path for which the result should be fetched.
38          - name: interfaces
39            type: array[string]
40            description: >
41                An array of result set constraining interfaces.
42      returns:
43          - name: ancestors
44            type: dict[string,dict[string,array[string]]]
45            description: >
46                A dictionary of ancestor -> services.
47      errors:
48          - xyz.openbmc_project.Common.Error.ResourceNotFound
49    - name: GetSubTree
50      description: >
51          Obtain a dictionary of path -> services where path is in sutbtree and
52          services is of the type returned by the GetObject method.
53      parameters:
54          - name: subtree
55            type: string
56            description: >
57                The subtree path for which the result should be fetched.
58          - name: depth
59            type: int32
60            description: >
61                The maximum subtree depth for which results should be fetched.
62                For unconstrained fetches use a depth of zero.
63          - name: interfaces
64            type: array[string]
65            description: >
66                An array of result set constraining interfaces.
67      returns:
68          - name: objects
69            type: dict[string,dict[string,array[string]]]
70            description: >
71                A dictionary of path -> services.
72      errors:
73          - xyz.openbmc_project.Common.Error.ResourceNotFound
74    - name: GetSubTreePaths
75      description: >
76          Obtain an array of paths where array elements are in subtree.
77      parameters:
78          - name: subtree
79            type: string
80            description: >
81                The subtree path for which the result should be fetched.
82          - name: depth
83            type: int32
84            description: >
85                The maximum subtree depth for which results should be fetched.
86                For unconstrained fetches use a depth of zero.
87          - name: interfaces
88            type: array[string]
89            description: >
90                An array of result set constraining interfaces.
91      returns:
92          - name: paths
93            type: array[string]
94            description: >
95                An array of paths.
96      errors:
97          - xyz.openbmc_project.Common.Error.ResourceNotFound
98    - name: GetAssociatedSubTree
99      description: >
100          Same as GetSubTree, but only return the dbus paths that are an
101          association endpoint on associatedPath
102      parameters:
103          - name: associatedPath
104            type: object_path
105            description: >
106                The path where the associated endpoint is fetched from.
107          - name: subtree
108            type: object_path
109            description: >
110                The subtree path for which the result should be fetched.
111          - name: depth
112            type: int32
113            description: >
114                The maximum subtree depth for which results should be fetched.
115                For unconstrained fetches use a depth of zero.
116          - name: interfaces
117            type: array[string]
118            description: >
119                An array of result set constraining interfaces.
120      returns:
121          - name: objects
122            type: dict[string,dict[string,array[string]]]
123            description: >
124                A dictionary of path -> services.
125      errors:
126          - xyz.openbmc_project.Common.Error.ResourceNotFound
127    - name: GetAssociatedSubTreePaths
128      description: >
129          Same as GetSubTreePaths, but only return the dbus paths that are an
130          association endpoint on associatedPath
131      parameters:
132          - name: associatedPath
133            type: string
134            description: >
135                The path where the associated endpoint is fetched from.
136          - name: subtree
137            type: string
138            description: >
139                The subtree path for which the result should be fetched.
140          - name: depth
141            type: int32
142            description: >
143                The maximum subtree depth for which results should be fetched.
144                For unconstrained fetches use a depth of zero.
145          - name: interfaces
146            type: array[string]
147            description: >
148                An array of result set constraining interfaces.
149      returns:
150          - name: paths
151            type: array[string]
152            description: >
153                An array of paths.
154      errors:
155          - xyz.openbmc_project.Common.Error.ResourceNotFound
156    - name: GetAssociatedSubTreeById
157      description: >
158          Retrieves a dictionary of D-Bus paths -> services of associated
159          endpoints with the provided identifier, filtering based on their
160          association with specified endpoint interfaces.
161
162          Implementation steps:
163
164          1. Retrieve the subtree D-Bus paths that implement the
165             "subtreeInterfaces" and have the path endpoint "id".
166          2. Create an association path by concatenating the subtree path with
167             "/" and "association"
168             associationPath = subtreePath + "/" + "association"
169          3. Call getAssociatedSubTree to get the endpoint path -> services of
170             the associationPath that implements the "endpointInterfaces".
171      parameters:
172          - name: id
173            type: string
174            description: >
175                The leaf name of the dbus path, uniquely identifying a specific
176                component or entity within the system. For example, in the path
177                `/xyz/openbmc_project/inventory/system/{ChassisId}/motherboard/{FanId}`,
178                the identifiers would be {FanId}.
179          - name: objectPath
180            type: string
181            description: >
182                The object path for which the result should be fetched.
183          - name: subtreeInterfaces
184            type: array[string]
185            description: >
186                An array of interfaces used to retrieve dbus paths with the
187                specified identifier.
188          - name: association
189            type: string
190            description: >
191                The endpoint association.
192          - name: endpointInterfaces
193            type: array[string]
194            description: >
195                An array of interfaces used to filter associated endpoint paths.
196      returns:
197          - name: objects
198            type: dict[string,dict[string,array[string]]]
199            description: >
200                A dictionary of path -> services.
201      errors:
202          - xyz.openbmc_project.Common.Error.ResourceNotFound
203    - name: GetAssociatedSubTreePathsById
204      description: >
205          Retrieves the D-Bus paths of associated endpoints with the provided
206          identifier, filtering based on their association with specified
207          endpoint interfaces.
208
209          Implementation steps:
210
211          1. Retrieve the subtree D-Bus paths that implement the
212             "subtreeInterfaces" and have the path endpoint "id".
213          2. Create an association path by concatenating the subtree path with
214             "/" and "association"
215             associationPath = subtreePath + "/" + "association"
216          3. Call getAssociatedSubTreePaths to get the endpoint paths of the
217             associationPath that implements the "endpointInterfaces".
218      parameters:
219          - name: id
220            type: string
221            description: >
222                The leaf name of the dbus path, uniquely identifying a specific
223                component or entity within the system. For example, in the path
224                `/xyz/openbmc_project/inventory/system/{ChassisId}/motherboard/{FanId}`,
225                the identifiers would be {FanId}.
226          - name: objectPath
227            type: string
228            description: >
229                The object path for which the result should be fetched.
230          - name: subtreeInterfaces
231            type: array[string]
232            description: >
233                An array of interfaces used to retrieve dbus paths with the
234                specified identifier.
235          - name: association
236            type: string
237            description: >
238                The endpoint association.
239          - name: endpointInterfaces
240            type: array[string]
241            description: >
242                An array of interfaces used to filter associated endpoint paths.
243      returns:
244          - name: paths
245            type: array[string]
246            description: >
247                An array of paths.
248      errors:
249          - xyz.openbmc_project.Common.Error.ResourceNotFound
250
251service_names:
252    - default: xyz.openbmc_project.ObjectMapper
253
254paths:
255    - instance: /xyz/openbmc_project/object_mapper
256