blob: 226f491be57d115952cc6b68cf4e0e785eeb4620 [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
Ratan Gupta40e0db42017-10-13 20:20:43 +0530102- 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
Brad Bishop0df00be2017-05-25 23:38:37 -0400119- name: example method callback
120 description: >
Gunnar Mills2df09e22017-07-31 13:30:22 -0500121 'The method callback invokes the specified D-Bus method.'
Brad Bishop0df00be2017-05-25 23:38:37 -0400122 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
Matt Spinlerf7a6a462017-11-01 10:51:19 -0500134- 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
Brad Bishop49e66172017-05-23 19:16:21 -0400150- 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
Brad Bishop3539db62017-05-30 14:21:12 -0400160 group composed of multiple journal callbacks.'
Brad Bishop49e66172017-05-23 19:16:21 -0400161
Brad Bishop49e66172017-05-23 19:16:21 -0400162 class: callback
163 callback: group
164 members:
165 - example journal callback
Brad Bishop3539db62017-05-30 14:21:12 -0400166 - example deferred condition
Gunnar Millsacac6022017-08-14 16:24:55 -0500167 - example elog callback
Brad Bishop4041d722017-05-21 10:06:07 -0400168
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
Gunnar Mills2df09e22017-07-31 13:30:22 -0500175 the condition evaluates.
Brad Bishop4041d722017-05-21 10:06:07 -0400176
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
Brad Bishop3539db62017-05-30 14:21:12 -0400195
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