1Phosphor Inventory Manager (PIM) is an implementation of the
2xyz.openbmc_project.Inventory.Manager DBus interface, and supporting tools. PIM
3uses a combination of build-time YAML files, run-time calls to the Notify method
4of the Manager interface, and association definition JSON files to provide a
5generalized inventory state management solution.
6
7## YAML
8
9PIM includes a YAML parser (pimgen.py). For PIM to do anything useful, a set of
10YAML files must be provided externally that tell it what to do. Examples can be
11found in the examples directory.
12
13The following top level YAML tags are supported:
14
15- description - An optional description of the file.
16- events - One or more events that PIM should monitor.
17
18---
19
20**events**
21
22Supported event tags are:
23
24- name - A globally unique event name.
25- description - An optional description of the event.
26- type - The event type. Supported types are: _match_ and _startup_.
27- actions - The responses to the event.
28
29Subsequent tags are defined by the event type.
30
31---
32
33**match**
34
35Supported match tags are:
36
37- signatures - A DBus match specification.
38- filters - Filters to apply when a match occurs.
39
40---
41
42**startup**
43
44Supported startup tags are:
45
46- filters - Filters to apply at startup.
47
48---
49
50**filters**
51
52Supported filter tags are:
53
54- name - The filter to use.
55
56Subsequent tags are defined by the filter type.
57
58The available filters provided by PIM are:
59
60- propertyChangedTo - Only match events when the specified property has the
61  specified value.
62- propertyIs - Only match events when the specified property has the specified
63  value.
64
65---
66
67**propertyChangedTo**
68
69The property under test is obtained from an sdbus message generated from an
70org.freedesktop.DBus.Properties.PropertiesChanged signal payload.
71
72Supported arguments for the propertyChangedTo filter are:
73
74- interface - The interface hosting the property to be checked.
75- property - The property to check.
76- value - The value to check.
77
78---
79
80**propertyIs**
81
82The property under test is obtained by invoking org.freedesktop.Properties.Get
83on the specified interface.
84
85Supported arguments for the propertyIs filter are:
86
87- path - The object hosting the property to be checked.
88- interface - The interface hosting the property to be checked.
89- property - The property to check.
90- value - The value to check.
91- service - An optional DBus service name.
92
93The service argument is optional. If provided that service will be called
94explicitly. If omitted, the service will be obtained with an
95xyz.openbmc_project.ObjectMapper lookup.
96
97propertyIs can be used in an action condition context when the action operates
98on a dbus object path.
99
100---
101
102**actions**
103
104Supported action tags are:
105
106- name - The action to perform.
107
108Subsequent tags are defined by the action type.
109
110The available actions provided by PIM are:
111
112- destroyObject - Destroy the specified DBus object.
113- setProperty - Set the specified property on the specified DBus object.
114
115---
116
117**destroyObject**
118
119Supported arguments for the destroyObject action are:
120
121- paths - The paths of the objects to remove from DBus.
122- conditions - An array of conditions.
123
124Conditions are tested and logically ANDed. If the conditions do not pass, the
125object is not destroyed. Any condition that accepts a path parameter is
126supported.
127
128---
129
130**setProperty**
131
132Supported arguments for the setProperty action are:
133
134- interface - The interface hosting the property to be set.
135- property - The property to set.
136- paths - The objects hosting the property to be set.
137- value - The value to set.
138- conditions - An array of conditions.
139
140Conditions are tested and logically ANDed. If the conditions do not pass, the
141property is not set. Any condition that accepts a path parameter is supported.
142
143---
144
145**createObjects**
146
147Supported arguments for the createObjects action are:
148
149- objs - A dictionary of objects to create.
150
151---
152
153## Creating Associations
154
155PIM can create [associations][1] between inventory items and other D-Bus
156objects.
157
158This functionality is optional and is controlled with the
159`--enable-associations` configure option. It defaults to disabled.
160
161To use this, the associations to create should be defined in a JSON file which
162is specified by the `ASSOCIATIONS_FILE_PATH` configure variable, which defaults
163to `/usr/share/phosphor-inventory-manager/associations.json`. This file is
164processed at runtime.
165
166An example of this JSON is:
167
168```
169[
170    {
171        "path": "system/chassis/motherboard/cpu0/core1",
172        "endpoints":
173        [
174            {
175                "types":
176                {
177                    "fType": "sensors",
178                    "rType": "inventory"
179                },
180                "paths":
181                [
182                    "/xyz/openbmc_project/sensors/temperature/p0_core0_temp"
183                ]
184            }
185        ]
186    }
187]
188```
189
190Then, when/if PIM creates the
191`xyz/openbmc_project/system/chassis/motherboard/cpu0/core1` inventory object, it
192will add an `xyz.openbmc_project.Association.Definitions` interface on it such
193that the object mapper creates the 2 association objects:
194
195```
196    /xyz/openbmc_project/inventory/system/chassis/motherboard/cpu0/core1/sensors
197       endpoints property:
198       ['/xyz/openbmc_project/sensors/temperature/p0_core0_temp']
199
200    /xyz/openbmc_project/sensors/temperature/p0_core0_temp/inventory
201       endpoints property:
202       ['/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu0/core1']
203```
204
205The JSON description is:
206
207```
208[
209    {
210        "path": "The relative path of the inventory object to create the
211                 xyz.openbmc_project.Association.Definitions interface on."
212        "endpoints":
213        [
214            {
215                "types":
216                {
217                    "fType": "The forward association type."
218                    "rType": "The reverse association type."
219                },
220                "paths":
221                [
222                    "The list of association endpoints for this inventory path
223                     and association type."
224                ]
225            }
226        ]
227    }
228]
229
230```
231
232In the case where different systems that require different associations reside
233in the same flash image, multiple JSON files must be used. These files must be
234in the same directory as the default associations file would go, but it does not
235matter what they are named as long as the name ends in '.json'. Each file then
236contains a 'condition' entry that specifies an inventory path, interface,
237property, and list of values. If the actual value of that property is in the
238list of values, then the condition is met and those associations are activated.
239
240If a file with a conditions section is found, then the default associations file
241is ignored. The end result is that associations are only ever loaded from one
242file, either the default file if there aren't any files with conditions in them,
243or the first file that had a condition that matched.
244
245An example is:
246
247```
248{
249    "condition":
250    {
251        "path": "system/chassis/motherboard",
252        "interface": "xyz.openbmc_project.Inventory.Decorator.Asset",
253        "property": "Model",
254        "values": [
255            "ModelA",
256            "ModelB"
257        ]
258    },
259    "associations":
260    [
261        {
262            "path": "system/chassis/motherboard/cpu0/core1",
263            "endpoints":
264            [
265                {
266                    "types":
267                    {
268                        "fType": "sensors",
269                        "rType": "inventory"
270                    },
271                    "paths":
272                    [
273                        "/xyz/openbmc_project/sensors/temperature/p0_core0_temp"
274                    ]
275                }
276            ]
277        }
278    ]
279}
280```
281
282This states that these associations are valid if the system/chassis/motherboard
283inventory object has a Model property with a value of either ModelA or ModelB.
284
285The values field supports the same types as in the inventory, so either a 'bool'
286(true/false), 'int64_t,' 'string', or 'std::vector<uint8_t>'([1, 2]).
287
288---
289
290## Building
291
292After running pimgen.py, build PIM using the following steps:
293
294```
295    ./bootstrap.sh
296    ./configure ${CONFIGURE_FLAGS}
297    make
298```
299
300To clean the repository run:
301
302```
303 ./bootstrap.sh clean
304```
305
306[1]:
307  https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
308