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