1Phosphor Inventory Manager (PIM) is an implementation of the
2xyz.openbmc_project.Inventory.Manager DBus interface, and supporting tools.
3PIM uses a combination of build-time YAML files, run-time calls to the Notify
4method of the Manager interface, and association definition JSON files to
5provide a generalized inventory state management solution.
6
7## YAML
8PIM includes a YAML parser (pimgen.py).  For PIM to do anything useful, a
9set of YAML files must be provided externally that tell it what to do.
10Examples can be found in the examples directory.
11
12The following top level YAML tags are supported:
13
14* description - An optional description of the file.
15* events - One or more events that PIM should monitor.
16
17----
18**events**
19
20Supported event tags are:
21
22* name - A globally unique event name.
23* description - An optional description of the event.
24* type - The event type.  Supported types are: *match* and *startup*.
25* actions - The responses to the event.
26
27Subsequent tags are defined by the event type.
28
29-----
30**match**
31
32Supported match tags are:
33
34* signatures - A DBus match specification.
35* filters - Filters to apply when a match occurs.
36
37-----
38**startup**
39
40Supported startup tags are:
41
42* filters - Filters to apply at startup.
43
44----
45**filters**
46
47Supported filter tags are:
48
49* name - The filter to use.
50
51Subsequent tags are defined by the filter type.
52
53The available filters provided by PIM are:
54
55* propertyChangedTo - Only match events when the specified property has
56the specified value.
57* propertyIs - Only match events when the specified property has
58the specified value.
59
60----
61**propertyChangedTo**
62
63The property under test is obtained from an sdbus message
64generated from an org.freedesktop.DBus.Properties.PropertiesChanged
65signal payload.
66
67Supported arguments for the propertyChangedTo filter are:
68* interface - The interface hosting the property to be checked.
69* property - The property to check.
70* value - The value to check.
71
72----
73**propertyIs**
74
75The property under test is obtained by invoking
76org.freedesktop.Properties.Get on the specified interface.
77
78Supported arguments for the propertyIs filter are:
79* path - The object hosting the property to be checked.
80* interface - The interface hosting the property to be checked.
81* property - The property to check.
82* value - The value to check.
83* service - An optional DBus service name.
84
85The service argument is optional.  If provided that service will
86be called explicitly.  If omitted, the service will be obtained
87with an xyz.openbmc_project.ObjectMapper lookup.
88
89propertyIs can be used in an action condition context when the
90action operates on a dbus object path.
91
92---
93**actions**
94
95Supported action tags are:
96
97* name - The action to perform.
98
99Subsequent tags are defined by the action type.
100
101The available actions provided by PIM are:
102
103* destroyObject - Destroy the specified DBus object.
104* setProperty - Set the specified property on the specified DBus object.
105
106----
107**destroyObject**
108
109Supported arguments for the destroyObject action are:
110* paths - The paths of the objects to remove from DBus.
111* conditions - An array of conditions.
112
113Conditions are tested and logically ANDed.  If the conditions do not
114pass, the object is not destroyed.  Any condition that accepts a path
115parameter is supported.
116
117----
118**setProperty**
119
120Supported arguments for the setProperty action are:
121* interface - The interface hosting the property to be set.
122* property - The property to set.
123* paths - The objects hosting the property to be set.
124* value - The value to set.
125* conditions - An array of conditions.
126
127Conditions are tested and logically ANDed.  If the conditions do not
128pass, the property is not set.  Any condition that accepts a path
129parameter is supported.
130
131----
132**createObjects**
133
134Supported arguments for the createObjects action are:
135* objs - A dictionary of objects to create.
136
137----
138## Creating Associations
139PIM can create [associations][1] between inventory items and other D-Bus objects.
140
141This functionality is optional and is controlled with the
142`--enable-associations` configure option.  It defaults to disabled.
143
144To use this, the associations to create should be defined in a JSON file which
145is specified by the `ASSOCIATIONS_FILE_PATH` configure variable, which defaults
146to `/usr/share/phosphor-inventory-manager/associations.json`.  This file is
147processed at runtime.
148
149An example of this JSON is:
150```
151[
152    {
153        "path": "system/chassis/motherboard/cpu0/core1",
154        "endpoints":
155        [
156            {
157                "types":
158                {
159                    "fType": "sensors",
160                    "rType": "inventory"
161                },
162                "paths":
163                [
164                    "/xyz/openbmc_project/sensors/temperature/p0_core0_temp"
165                ]
166            }
167        ]
168    }
169]
170```
171
172Then, when/if PIM creates the
173`xyz/openbmc_project/system/chassis/motherboard/cpu0/core1` inventory object,
174it will add an `xyz.openbmc_project.Association.Definitions` interface on it
175such that the object mapper creates the 2 association objects:
176
177```
178    /xyz/openbmc_project/inventory/system/chassis/motherboard/cpu0/core1/sensors
179       endpoints property:
180       ['/xyz/openbmc_project/sensors/temperature/p0_core0_temp']
181
182    /xyz/openbmc_project/sensors/temperature/p0_core0_temp/inventory
183       endpoints property:
184       ['/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu0/core1']
185```
186
187The JSON description is:
188```
189[
190    {
191        "path": "The relative path of the inventory object to create the
192                 xyz.openbmc_project.Association.Definitions interface on."
193        "endpoints":
194        [
195            {
196                "types":
197                {
198                    "fType": "The forward association type."
199                    "rType": "The reverse association type."
200                },
201                "paths":
202                [
203                    "The list of association endpoints for this inventory path
204                     and association type."
205                ]
206            }
207        ]
208    }
209]
210
211```
212
213----
214## Building
215After running pimgen.py, build PIM using the following steps:
216
217```
218    ./bootstrap.sh
219    ./configure ${CONFIGURE_FLAGS}
220    make
221```
222
223To clean the repository run:
224
225```
226 ./bootstrap.sh clean
227```
228[1]: https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
229