blob: 61087807e34a8905eec28b6d224699f07b3be204 [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
Brad Bishop0df00be2017-05-25 23:38:37 -040081- name: example method callback
82 description: >
Gunnar Mills2df09e22017-07-31 13:30:22 -050083 'The method callback invokes the specified D-Bus method.'
Brad Bishop0df00be2017-05-25 23:38:37 -040084 class: callback
85 callback: method
86 service: org.freedesktop.systemd1
87 path: /org/freedesktop/systemd1
88 interface: org.freedesktop.systemd1.Manager
89 method: StartUnit
90 args:
91 - value: foo.unit
92 type: string
93 - value: replace
94 type: string
95
Brad Bishop49e66172017-05-23 19:16:21 -040096- name: example callback group
97 description: >
98 'Callbacks groups are simply named collections of other callbacks.
99 Configuration file directives can only refer to a single callback.
100 Through use of a group, these configuration file directives can
101 refer to more than one callback.
102
103 For example for a given event, one may wish to trace multiple
104 messages to the systemd journal. The journal callback does not
105 support tracing multiple messages. To do that, define a callback
Brad Bishop3539db62017-05-30 14:21:12 -0400106 group composed of multiple journal callbacks.'
Brad Bishop49e66172017-05-23 19:16:21 -0400107
Brad Bishop49e66172017-05-23 19:16:21 -0400108 class: callback
109 callback: group
110 members:
111 - example journal callback
Brad Bishop3539db62017-05-30 14:21:12 -0400112 - example deferred condition
Brad Bishop4041d722017-05-21 10:06:07 -0400113
114- name: example count condition
115 description: >
116 'Conditions or conditional callbacks apply a test prior to invoking
117 the callback function.
118
119 All conditional callbacks must specify the callback to issue if
Gunnar Mills2df09e22017-07-31 13:30:22 -0500120 the condition evaluates.
Brad Bishop4041d722017-05-21 10:06:07 -0400121
122 The count condition applies the op comparison operator to the value of each
123 property in the specified groups. It then counts the number of properties
124 that pass the comparison, and applies another comparison on the result
125 against the specified bound.
126
127 For example, a callback that requires at least three temperature sensors
128 in the group to be higher than 115 degrees might use a count condition
129 with an op of >, a count op of >=, a bound of 115, and a countbound of 3.'
130
131 class: condition
132 condition: count
133 paths: example path group
134 properties: example property group
135 callback: example callback group
136 countop: '>='
137 countbound: 3
138 op: '>='
139 bound: 115
Brad Bishop3539db62017-05-30 14:21:12 -0400140
141- name: example deferred condition
142 description: >
143 'Deferred conditions operate in the same fashion as conditional callbacks
144 with the added behavior that when the condition is tested and is met,
145 invocation of the callback is deferred by the interval specified.
146
147 When the configured time has elapsed, if the condition has not been reevaluated
148 the callback is invoked.
149
150 Any condition type can be deferred in this way by setting the defer attribute.'
151
152 class: condition
153 condition: count
154 paths: example path group
155 properties: example property group
156 defer: 1000us
157 callback: example callback group
158 countop: '>='
159 countbound: 3
160 op: '>='
161 bound: 115