blob: ec0a611bfc0efc851a267456217c635bbb20e300 [file] [log] [blame]
Brad Bishop870c3fc2017-05-22 23:23:13 -04001# Example PDM configuration file.
Brad Bishop0e7df132017-05-23 17:58:12 -04002
3- name: example path group
4 description: >
Gunnar Mills2df09e22017-07-31 13:30:22 -05005 'A path group is a named collection of D-Bus object
Brad Bishop0e7df132017-05-23 17:58:12 -04006 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:
Brad Bishopbabf3b72017-05-31 19:44:53 -040021 - meta: PATH
Brad Bishop0e7df132017-05-23 17:58:12 -040022 path: /xyz/openbmc_project/testing/inst1
Brad Bishopbabf3b72017-05-31 19:44:53 -040023 - meta: PATH
Brad Bishop0e7df132017-05-23 17:58:12 -040024 path: /xyz/openbmc_project/testing/inst2
Brad Bishopbabf3b72017-05-31 19:44:53 -040025 - meta: PATH
Brad Bishop0e7df132017-05-23 17:58:12 -040026 path: /xyz/openbmc_project/testing/inst3
Brad Bishopbabf3b72017-05-31 19:44:53 -040027 - meta: PATH
Brad Bishop0e7df132017-05-23 17:58:12 -040028 path: /xyz/openbmc_project/testing/inst4
Brad Bishope73b2c32017-05-23 18:01:54 -040029
30- name: example property group
31 description: >
32 'Like path groups, a property group is a named collection
Gunnar Mills2df09e22017-07-31 13:30:22 -050033 of D-Bus property names and associated metadata.
Brad Bishope73b2c32017-05-23 18:01:54 -040034
Gunnar Mills2df09e22017-07-31 13:30:22 -050035 Properties in a group must all have the same D-Bus type signature
Brad Bishope73b2c32017-05-23 18:01:54 -040036 and must be explicitly declared.'
37 class: group
38 group: property
39 type: uint32
40 members:
41 - interface: xyz.openbmc_project.Sensor.Value
Brad Bishopbabf3b72017-05-31 19:44:53 -040042 meta: PROPERTY
Brad Bishope73b2c32017-05-23 18:01:54 -040043 property: ValueA
44 - interface: xyz.openbmc_project.Sensor.Value
Brad Bishopbabf3b72017-05-31 19:44:53 -040045 meta: PROPERTY
Brad Bishope73b2c32017-05-23 18:01:54 -040046 property: ValueB
Brad Bishop4b916f12017-05-23 18:06:38 -040047
48- name: example property watch
49 description: >
50 'A property watch instructs PDM to maintain a cache of the state
Gunnar Mills2df09e22017-07-31 13:30:22 -050051 of the specified properties on the specified D-Bus objects.
Brad Bishopfccdc392017-05-22 21:11:09 -040052
53 An optional callback can be triggered when property values change.'
Brad Bishop4b916f12017-05-23 18:06:38 -040054 class: watch
55 watch: property
56 paths: example path group
57 properties: example property group
Brad Bishopfccdc392017-05-22 21:11:09 -040058 callback: example count condition
Brad Bishopc1283ae2017-05-20 21:42:38 -040059
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!
Brad Bishop49e66172017-05-23 19:16:21 -040080
Gunnar Millsacac6022017-08-14 16:24:55 -050081- 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
Matt Spinler3c5318d2018-02-19 14:03:05 -0600102- 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
Ratan Gupta40e0db42017-10-13 20:20:43 +0530126- 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
Brad Bishop0df00be2017-05-25 23:38:37 -0400143- name: example method callback
144 description: >
Gunnar Mills2df09e22017-07-31 13:30:22 -0500145 'The method callback invokes the specified D-Bus method.'
Brad Bishop0df00be2017-05-25 23:38:37 -0400146 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
Matt Spinlerf7a6a462017-11-01 10:51:19 -0500158- 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
Brad Bishop49e66172017-05-23 19:16:21 -0400174- 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
Brad Bishop3539db62017-05-30 14:21:12 -0400184 group composed of multiple journal callbacks.'
Brad Bishop49e66172017-05-23 19:16:21 -0400185
Brad Bishop49e66172017-05-23 19:16:21 -0400186 class: callback
187 callback: group
188 members:
189 - example journal callback
Brad Bishop3539db62017-05-30 14:21:12 -0400190 - example deferred condition
Gunnar Millsacac6022017-08-14 16:24:55 -0500191 - example elog callback
Brad Bishop4041d722017-05-21 10:06:07 -0400192
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
Gunnar Mills2df09e22017-07-31 13:30:22 -0500199 the condition evaluates.
Brad Bishop4041d722017-05-21 10:06:07 -0400200
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
Matt Spinlerc458dee2018-02-19 13:09:10 -0600208 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.'
Brad Bishop4041d722017-05-21 10:06:07 -0400214
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
Matt Spinlerc458dee2018-02-19 13:09:10 -0600224 oneshot: true
Brad Bishop3539db62017-05-30 14:21:12 -0400225
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