xref: /openbmc/phosphor-dbus-monitor/src/example/example.yaml (revision 40e0db468a22cb162d906391ea79ac757ab99d01)
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 event callback
103  description: >
104    'Callbacks are actions PDM should take when instructed to do so.
105
106    Some callback types refer to a group of paths and group of properties
107    in a similar fashion as the property watch directive.
108
109    The event callback creates the event D-Bus object with the given name
110    and the event message.
111    eg /xyz/openbmc_project/events/test/<id>'
112  class: callback
113  callback: event
114  paths: example path group
115  properties: example property group
116  eventName: test
117  eventMessage: "Test configuration changed."
118
119- name: example method callback
120  description: >
121    'The method callback invokes the specified D-Bus method.'
122  class: callback
123  callback: method
124  service: org.freedesktop.systemd1
125  path: /org/freedesktop/systemd1
126  interface: org.freedesktop.systemd1.Manager
127  method: StartUnit
128  args:
129    - value: foo.unit
130      type: string
131    - value: replace
132      type: string
133
134- name: example resolve callouts callback
135  description: >
136    'The resolve callout callback resolves all error log entries that
137    are associated with the inventory path specified by setting the
138    Resolved property in the entries to true.
139
140    A use case could be to watch the Present property on the inventory
141    item and resolve all errors for it when a new one is plugged in and
142    the property changes to true.'
143
144  class: callback
145  callback: resolve callout
146  paths: example path group
147  properties: example property group
148  callout: /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0
149
150- name: example callback group
151  description: >
152    'Callbacks groups are simply named collections of other callbacks.
153    Configuration file directives can only refer to a single callback.
154    Through use of a group, these configuration file directives can
155    refer to more than one callback.
156
157    For example for a given event, one may wish to trace multiple
158    messages to the systemd journal.  The journal callback does not
159    support tracing multiple messages.  To do that, define a callback
160    group composed of multiple journal callbacks.'
161
162  class: callback
163  callback: group
164  members:
165    - example journal callback
166    - example deferred condition
167    - example elog callback
168
169- name: example count condition
170  description: >
171    'Conditions or conditional callbacks apply a test prior to invoking
172    the callback function.
173
174    All conditional callbacks must specify the callback to issue if
175    the condition evaluates.
176
177    The count condition applies the op comparison operator to the value of each
178    property in the specified groups.  It then counts the number of properties
179    that pass the comparison, and applies another comparison on the result
180    against the specified bound.
181
182    For example, a callback that requires at least three temperature sensors
183    in the group to be higher than 115 degrees might use a count condition
184    with an op of >, a count op of >=, a bound of 115, and a countbound of 3.'
185
186  class: condition
187  condition: count
188  paths: example path group
189  properties: example property group
190  callback: example callback group
191  countop: '>='
192  countbound: 3
193  op: '>='
194  bound: 115
195
196- name: example deferred condition
197  description: >
198    'Deferred conditions operate in the same fashion as conditional callbacks
199    with the added behavior that when the condition is tested and is met,
200    invocation of the callback is deferred by the interval specified.
201
202    When the configured time has elapsed, if the condition has not been reevaluated
203    the callback is invoked.
204
205    Any condition type can be deferred in this way by setting the defer attribute.'
206
207  class: condition
208  condition: count
209  paths: example path group
210  properties: example property group
211  defer: 1000us
212  callback: example callback group
213  countop: '>='
214  countbound: 3
215  op: '>='
216  bound: 115
217