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