1# Example PDM configuration file. 2 3- name: example path group 4 description: > 5 'A path group is a named collection of D-Bus object 6 paths and associated metadata. These collections 7 serve only to be referenced by other configuration 8 directives. 9 10 The metadata element has different uses depending 11 on the referencing directive. 12 13 Within a single configuration file path group names 14 must be unique. The same name can appear in multiple 15 configuration files; however, the referencing directive 16 will only search for the group in the same configuration 17 file.' 18 class: group 19 group: path 20 members: 21 - meta: PATH 22 path: /xyz/openbmc_project/testing/inst1 23 - meta: PATH 24 path: /xyz/openbmc_project/testing/inst2 25 - meta: PATH 26 path: /xyz/openbmc_project/testing/inst3 27 - meta: PATH 28 path: /xyz/openbmc_project/testing/inst4 29 30- name: example property group 31 description: > 32 'Like path groups, a property group is a named collection 33 of D-Bus property names and associated metadata. 34 35 Properties in a group must all have the same D-Bus type signature 36 and must be explicitly declared.' 37 class: group 38 group: property 39 type: uint32 40 members: 41 - interface: xyz.openbmc_project.Sensor.Value 42 meta: PROPERTY 43 property: ValueA 44 - interface: xyz.openbmc_project.Sensor.Value 45 meta: PROPERTY 46 property: ValueB 47 48- name: example property watch 49 description: > 50 'A property watch instructs PDM to maintain a cache of the state 51 of the specified properties on the specified D-Bus objects. 52 53 An optional callback can be triggered when property values change.' 54 class: watch 55 watch: property 56 paths: example path group 57 properties: example property group 58 callback: example count condition 59 60- name: example journal callback 61 description: > 62 'Callbacks are actions PDM should take when instructed to do so. 63 64 Some callback types refer to a group of paths and group of properties 65 in a similar fashion as the property watch directive. 66 67 The journal callback logs the specified message to the systemd journal 68 with the specified severity. 69 70 Additionally, the journal callback will add to the journal key value 71 pair metadata for each property in the specified property group with 72 the key being the property element metadata and the value being the 73 property value.' 74 class: callback 75 callback: journal 76 paths: example path group 77 properties: example property group 78 severity: INFO 79 message: Hello world from PDM! 80 81- name: example elog callback 82 description: > 83 'Callbacks are actions PDM should take when instructed to do so. 84 85 Some callback types refer to a group of paths and group of properties 86 in a similar fashion as the property watch directive. 87 88 The elog callback logs the elog and elog metadata.' 89 class: callback 90 callback: elog 91 paths: example path group 92 properties: example property group 93 error: xyz::openbmc_project::Common::Error::InvalidArgument 94 metadata: 95 - name: xyz::openbmc_project::Common::InvalidArgument::ARGUMENT_NAME 96 value: testing... 97 type: string 98 - name: xyz::openbmc_project::Common::InvalidArgument::ARGUMENT_VALUE 99 value: testing... 100 type: string 101 102- name: example elog with metadata capture callback 103 description: > 104 'Callbacks are actions pdm should take when instructed to do so. 105 106 This callback creates an elog, and it will capture the values of the 107 properties that passed its condition check in the metadata field 108 (that must be a string type) in the form: 109 110 |path1:property1=value1|path2:property2=value2| 111 112 Note that as this callback depends on the condition that called it to 113 fill in the result of its checks on each property, this callback should 114 use the same properties and paths keywords as the condition that calls it. 115 116 Currently an error log with only 1 metadata entry of type string is 117 supported.' 118 119 class: callback 120 callback: elog_with_metadata 121 paths: example path group 122 properties: example property group 123 error: xyz::openbmc_project::Common::Callout::Error::Inventory 124 metadata: xyz::openbmc_project::Common::Callout::Inventory::CALLOUT_INVENTORY_PATH 125 126- name: example event callback 127 description: > 128 'Callbacks are actions PDM should take when instructed to do so. 129 130 Some callback types refer to a group of paths and group of properties 131 in a similar fashion as the property watch directive. 132 133 The event callback creates the event D-Bus object with the given name 134 and the event message. 135 eg /xyz/openbmc_project/events/test/<id>' 136 class: callback 137 callback: event 138 paths: example path group 139 properties: example property group 140 eventName: test 141 eventMessage: "Test configuration changed." 142 143- name: example method callback 144 description: > 145 'The method callback invokes the specified D-Bus method.' 146 class: callback 147 callback: method 148 service: org.freedesktop.systemd1 149 path: /org/freedesktop/systemd1 150 interface: org.freedesktop.systemd1.Manager 151 method: StartUnit 152 args: 153 - value: foo.unit 154 type: string 155 - value: replace 156 type: string 157 158- name: example resolve callouts callback 159 description: > 160 'The resolve callout callback resolves all error log entries that 161 are associated with the inventory path specified by setting the 162 Resolved property in the entries to true. 163 164 A use case could be to watch the Present property on the inventory 165 item and resolve all errors for it when a new one is plugged in and 166 the property changes to true.' 167 168 class: callback 169 callback: resolve callout 170 paths: example path group 171 properties: example property group 172 callout: /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0 173 174- name: example callback group 175 description: > 176 'Callbacks groups are simply named collections of other callbacks. 177 Configuration file directives can only refer to a single callback. 178 Through use of a group, these configuration file directives can 179 refer to more than one callback. 180 181 For example for a given event, one may wish to trace multiple 182 messages to the systemd journal. The journal callback does not 183 support tracing multiple messages. To do that, define a callback 184 group composed of multiple journal callbacks.' 185 186 class: callback 187 callback: group 188 members: 189 - example journal callback 190 - example deferred condition 191 - example elog callback 192 193- name: example count condition 194 description: > 195 'Conditions or conditional callbacks apply a test prior to invoking 196 the callback function. 197 198 All conditional callbacks must specify the callback to issue if 199 the condition evaluates. 200 201 The count condition applies the op comparison operator to the value of each 202 property in the specified groups. It then counts the number of properties 203 that pass the comparison, and applies another comparison on the result 204 against the specified bound. 205 206 For example, a callback that requires at least three temperature sensors 207 in the group to be higher than 115 degrees might use a count condition 208 with an op of >, a count op of >=, a bound of 115, and a countbound of 3. 209 210 The optional oneshot parameter defaults to false. If it is specified and 211 set to true, then the callback will only be called once for as long as the 212 condition is repeatedly passing. The condition needs to fail at least 213 once to rearm the callback.' 214 215 class: condition 216 condition: count 217 paths: example path group 218 properties: example property group 219 callback: example callback group 220 countop: '>=' 221 countbound: 3 222 op: '>=' 223 bound: 115 224 oneshot: true 225 226- name: example deferred condition 227 description: > 228 'Deferred conditions operate in the same fashion as conditional callbacks 229 with the added behavior that when the condition is tested and is met, 230 invocation of the callback is deferred by the interval specified. 231 232 When the configured time has elapsed, if the condition has not been reevaluated 233 the callback is invoked. 234 235 Any condition type can be deferred in this way by setting the defer attribute.' 236 237 class: condition 238 condition: count 239 paths: example path group 240 properties: example property group 241 defer: 1000us 242 callback: example callback group 243 countop: '>=' 244 countbound: 3 245 op: '>=' 246 bound: 115 247