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 213In the case where different systems that require different associations reside 214in the same flash image, multiple JSON files must be used. These files must be 215in the same directory as the default associations file would go, but it does 216not matter what they are named as long as the name ends in '.json'. Each file 217then contains a 'condition' entry that specifies an inventory path, interface, 218property, and list of values. If the actual value of that property is in the 219list of values, then the condition is met and those associations are activated. 220 221If a file with a conditions section is found, then the default associations 222file is ignored. The end result is that associations are only ever loaded from 223one file, either the default file if there aren't any files with conditions in 224them, or the first file that had a condition that matched. 225 226An example is: 227 228``` 229{ 230 "condition": 231 { 232 "path": "system/chassis/motherboard", 233 "interface": "xyz.openbmc_project.Inventory.Decorator.Asset", 234 "property": "Model", 235 "values": [ 236 "ModelA", 237 "ModelB" 238 ] 239 }, 240 "associations": 241 [ 242 { 243 "path": "system/chassis/motherboard/cpu0/core1", 244 "endpoints": 245 [ 246 { 247 "types": 248 { 249 "fType": "sensors", 250 "rType": "inventory" 251 }, 252 "paths": 253 [ 254 "/xyz/openbmc_project/sensors/temperature/p0_core0_temp" 255 ] 256 } 257 ] 258 } 259 ] 260} 261``` 262 263This states that these associations are valid if the system/chassis/motherboard 264inventory object has a Model property with a value of either ModelA or 265ModelB. 266 267The values field supports the same types as in the inventory, so either a 'bool' 268(true/false), 'int64\_t,' 'string', or 'std::vector<uint8_t>'([1, 2]). 269 270---- 271## Building 272After running pimgen.py, build PIM using the following steps: 273 274``` 275 ./bootstrap.sh 276 ./configure ${CONFIGURE_FLAGS} 277 make 278``` 279 280To clean the repository run: 281 282``` 283 ./bootstrap.sh clean 284``` 285[1]: https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations 286