xref: /netbsd-src/share/man/man4/envsys.4 (revision 8b0f9554ff8762542c4defc4f70e1eb76fb508fa)
1.\"	$NetBSD: envsys.4,v 1.39 2007/12/02 19:54:32 wiz Exp $
2.\"
3.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Juan Romero Pardines.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd November 13, 2007
38.Dt ENVSYS 4
39.Os
40.Sh NAME
41.Nm envsys
42.Nd Environmental Systems framework (version 2)
43.Sh SYNOPSIS
44.In sys/envsys.h
45.Sh DESCRIPTION
46The
47.Nm
48framework provides support to handle hardware monitor devices.
49Hardware monitoring chips are able to report values from different types of
50sensors.
51.Pp
52The
53.Nm
54framework consists of two parts:
55.Pp
56.Bl -enum -offset indent -compact
57.It
58the userland part, to receive the current sensor data and
59to set some properties on sensors:
60.Xr envstat 8 .
61.It
62The kernel part that is able to talk to the drivers providing sensor
63data:
64.Xr sysmon_envsys 9 .
65.El
66.Pp
67The
68.Nm
69framework uses
70.Xr proplib 3
71for communication between kernel and user space.
72The following
73.Xr ioctl 2
74types are available:
75.Pp
76.Bl -tag -width XX -compact
77.It Dv ENVSYS_GETDICTIONARY Pq prop_dictionary_t
78.Pp
79This
80.Xr ioctl 2
81is used to receive the global dictionary that is being used in
82the kernel by the
83.Xr sysmon_envsys 9
84framework.
85It will contain an array of dictionaries per device
86and one dictionary per sensor plus another special dictionary that
87contains the properties for a device.
88Each sensor dictionary will have their own characteristics and values.
89.Pp
90The following XML property list represents a virtual device
91.Dq device0
92with one sensor
93.Dq sensor0
94and all available properties set on it, plus another sensor for
95the
96.Dq device-properties
97dictionary (which contains specific properties for a device):
98.Pp
99.Bd -literal
100\&\*[Lt]key\&\*[Gt]device0\&\*[Lt]\&/key\&\*[Gt]
101\&\*[Lt]array\&\*[Gt]
102	\&\*[Lt]dict\&\*[Gt]
103		\&\*[Lt]key\&\*[Gt]allow-rfact\&\*[Lt]\&/key\&\*[Gt]
104		\&\*[Lt]true\&/\&\*[Gt]
105		\&\*[Lt]key\&\*[Gt]avg-value\&\*[Lt]\&/key\&\*[Gt]
106		\&\*[Lt]integer\&\*[Gt]36400\&\*[Lt]\&/integer\&\*[Gt]
107		\&\*[Lt]key\&\*[Gt]battery-capacity\&\*[Lt]\&/key\&\*[Gt]
108		\&\*[Lt]string\&\*[Gt]NORMAL\&\*[Lt]\&/string\&\*[Gt]
109		\&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt]
110		\&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt]
111		\&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt]
112		\&\*[Lt]integer\&\*[Gt]343150000\&\*[Lt]\&/integer\&\*[Gt]
113		\&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt]
114		\&\*[Lt]integer\&\*[Gt]288150000\&\*[Lt]\&/integer\&\*[Gt]
115		\&\*[Lt]key\&\*[Gt]cur-value\&\*[Lt]\&/key\&\*[Gt]
116		\&\*[Lt]integer\&\*[Gt]406000\&\*[Lt]\&/integer\&\*[Gt]
117		\&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt]
118		\&\*[Lt]string\&\*[Gt]CPU Temp\&\*[Lt]\&/string\&\*[Gt]
119		\&\*[Lt]string\&\*[Gt]index\&\*[Lt]\&/string\&\*[Gt]
120		\&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt]
121		\&\*[Lt]key\&\*[Gt]max-value\&\*[Lt]\&/key\&\*[Gt]
122		\&\*[Lt]integer\&\*[Gt]3894000\&\*[Lt]\&/integer\&\*[Gt]
123		\&\*[Lt]key\&\*[Gt]min-value\&\*[Lt]\&/key\&\*[Gt]
124		\&\*[Lt]integer\&\*[Gt]2894000\&\*[Lt]\&/integer\&\*[Gt]
125		\&\*[Lt]key\&\*[Gt]monitoring-state-critical\&\*[Lt]\&/key\&\*[Gt]
126		\&\*[Lt]true\&/\&\*[Gt]
127		\&\*[Lt]key\&\*[Gt]monitoring-state-critover\&\*[Lt]\&/key\&\*[Gt]
128		\&\*[Lt]true\&/\&\*[Gt]
129		\&\*[Lt]key\&\*[Gt]monitoring-state-critunder\&\*[Lt]\&/key\&\*[Gt]
130		\&\*[Lt]true\&/\&\*[Gt]
131		\&\*[Lt]key\&\*[Gt]monitoring-state-state-changed\&\*[Lt]\&/key\&\*[Gt]
132		\&\*[Lt]true\&/\&\*[Gt]
133		\&\*[Lt]key\&\*[Gt]monitoring-state-warnover\&\*[Lt]\&/key\&\*[Gt]
134		\&\*[Lt]true\&/\&\*[Gt]
135		\&\*[Lt]key\&\*[Gt]monitoring-state-warnunder\&\*[Lt]\&/key\&\*[Gt]
136		\&\*[Lt]true\&/\&\*[Gt]
137		\&\*[Lt]key\&\*[Gt]monitoring-supported\&\*[Lt]\&/key\&\*[Gt]
138		\&\*[Lt]true\&/\&\*[Gt]
139		\&\*[Lt]key\&\*[Gt]state\&\*[Lt]\&/key\&\*[Gt]
140		\&\*[Lt]string\&\*[Gt]valid\&\*[Lt]\&/string\&\*[Gt]
141		\&\*[Lt]key\&\*[Gt]type\&\*[Lt]\&/key\&\*[Gt]
142		\&\*[Lt]string\&\*[Gt]Ampere hour\&\*[Lt]\&/string\&\*[Gt]
143		\&\*[Lt]key\&\*[Gt]want-percentage\&\*[Lt]\&/key\&\*[Gt]
144		\&\*[Lt]true\&/\&\*[Gt]
145	\&\*[Lt]\&/dict\&\*[Gt]
146	\&\*[Lt]dict\&\*[Gt]
147		\&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt]
148		\&\*[Lt]dict\&\*[Gt]
149			\&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt]
150			\&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt]
151		\&\*[Lt]\&/dict\&\*[Gt]
152	\&\*[Lt]\&/dict\&\*[Gt]
153\&\*[Lt]\&/array\&\*[Gt]
154.Ed
155.Pp
156Let's explain some more about those objects:
157.Bl -tag -width "monitoring-state-critical-overxx"
158.It Fa allow-rfact
159Set to
160.Em true
161mean that the sensor is able to change the resistor factor,
162only used in Voltage sensors.
163.It Fa avg-value
164Current average value in the sensor.
165.It Fa battery-capacity
166Current capacity state for a battery capacity sensor.
167.It Fa critical-capacity
168Critical capacity set previously by the
169.Dv ENVSYS_SETDICTIONARY
170.Xr ioctl 2 .
171Only available on sensors with the
172.Em want-percentage
173object enabled.
174.It Fa critical-max
175Critical max limit set previously by the
176.Dv ENVSYS_SETDICTIONARY
177.Xr ioctl 2 .
178.It Fa critical-min
179Critical min limit set previously by the
180.Dv ENVSYS_SETDICTIONARY
181.Xr ioctl 2 .
182.It Fa cur-value
183Current value in the sensor.
184.It Fa description
185Description of the sensor.
186.It Fa index
187Index position of the sensor.
188.It Fa max-value
189Current max value in the sensor.
190.It Fa min-value
191Current min value in the sensor.
192.It Fa monitoring-state-critical
193If true, the driver has enabled the flag to monitor a critical state.
194.It Fa monitoring-state-critical-over
195If true, the driver has enabled the flag to monitor a critical over state.
196.It Fa monitoring-state-critical-under
197If true, the driver has enabled the flag to monitor a critical under state.
198.It Fa monitoring-state-state-changed
199If true, the driver has enabled the flag to monitor for state changes in
200a drive or Battery state sensor.
201.It Fa monitoring-state-warning-over
202If true, the driver has enabled the flag to monitor a warning over state.
203.It Fa monitoring-state-warning-under
204If true, the driver has enabled the flag to monitor a warning under state.
205.It Fa monitoring-supported
206If true, critical capacity/max/min limits may be set by the
207.Dv ENVSYS_SETDICTIONARY
208.Xr ioctl 2 .
209.It Fa state
210Current state in the sensor.
211.It Fa type
212Type of unit in the sensor.
213.It Fa want-percentage
214If true,
215.Em max-value
216and
217.Em cur-value
218are valid and a percentage may be computed from them.
219.El
220.El
221.Pp
222.Bl -tag -width XX -compact
223.It Dv ENVSYS_REMOVEPROPS Pq prop_dictionary_t
224.Pp
225This
226.Xr ioctl 2
227is used to remove all properties that are currently set via the
228.Dv ENVSYS_SETDICTIONARY
229ioctl.
230The values will be set to defaults, the ones that the driver uses.
231.Pp
232Only one object is allowed on this dictionary:
233.Bd -literal -offset -ident
234	\*[Lt]key\*[Gt]envsys-remove-props\*[Lt]/key\*[Gt]
235	\*[Lt]true/\*[Gt]
236.Ed
237.Pp
238It is a boolean object and must be set to
239.Em true
240to be effective.
241.El
242.Bl -tag -width XX -compact
243.Pp
244.It Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t
245.Pp
246This
247.Xr ioctl 2
248is used to send a dictionary with new properties that should be
249processed by the
250.Nm
251framework.
252Only a set of predefined keywords are recognized by the kernel part.
253The following is the property list representation
254of a dictionary with all recognized and required keywords that
255a sensor understands:
256.Bd -literal
257\&\*[Lt]dict\&\*[Gt]
258	\&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt]
259	\&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt]
260	\&\*[Lt]key\&\*[Gt]rfact\&\*[Lt]\&/key\&\*[Gt]
261	\&\*[Lt]integer\&\*[Gt]56000\&\*[Lt]\&/integer\&\*[Gt]
262	\&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt]
263	\&\*[Lt]integer\&\*[Gt]10\&\*[Lt]\&/integer\&\*[Gt]
264	\&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt]
265	\&\*[Lt]integer\&\*[Gt]3400\&\*[Lt]\&/integer\&\*[Gt]
266	\&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt]
267	\&\*[Lt]integer\&\*[Gt]2800\&\*[Lt]\&/integer\&\*[Gt]
268\&\*[Lt]\&/dict\&\*[Gt]
269.Ed
270.Pp
271Also if some properties in a device need to be changed, the
272.Dq device-properties
273dictionary must be used.
274At this moment only the
275.Dq refresh-timeout
276property is understood.
277This has the following structure:
278.Bd -literal
279\&\*[Lt]dict\&\*[Gt]
280	\&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt]
281	\&\*[Lt]dict\&\*[Gt]
282		\&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt]
283		\&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt]
284	\&\*[Lt]\&/dict\&\*[Gt]
285\&\*[Lt]\&/dict\&\*[Gt]
286.Ed
287.Pp
288A dictionary sent to the kernel with this
289.Xr ioctl 2
290should have the following structure:
291.Bd -literal
292\&\*[Lt]dict\&\*[Gt]
293	\&\*[Lt]key\&\*[Gt]device_name\&\*[Lt]\&/key\&\*[Gt]
294	\&\*[Lt]array\&\*[Gt]
295		\&\*[Lt]dict\&\*[Gt]
296			\&\*[Lt]key\&\*[Gt]index\&\*[Lt]\&/key\&\*[Gt]
297			\&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt]
298			\&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt]
299			\&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt]
300			...
301			Another property for this sensor
302			...
303		\&\*[Lt]\&/dict\&\*[Gt]
304		...
305		Another dictionary for device-properties or sensor
306		...
307	\&\*[Lt]\&/array\&\*[Gt]
308	...
309	Another device as above
310	...
311\&\*[Lt]\&/dict\&\*[Gt]
312.Ed
313.Pp
314The named device will be an array and will contain dictionaries,
315any dictionary needs to have the
316.Em index
317object specifying the sensor that is required for the new properties.
318.Pp
319If an unknown object was sent with the dictionary,
320.Er EINVAL
321will be returned, or if the sensor does not support changing
322rfact (voltage sensors) or critical/capacity limits,
323.Er ENOTSUP
324will be returned.
325.El
326.Sh NOTES
327When setting a critical max or min limit with the
328.Dv ENVSYS_SETDICTIONARY
329.Xr ioctl 2 ,
330the user must be aware that
331.Xr sysmon_envsys 9
332expects to have a proper unit, so the value must be converted.
333Please see
334.Xr sysmon_envsys 9
335for more information.
336.Pp
337Also when setting a critical capacity limit, the formula to send a
338proper value to
339.Xr sysmon_envsys 9
340is the following:
341.Em value = (value / 100) * max value .
342The max value is available in the sensor's dictionary.
343.Sh EXAMPLES
344The following example shows how to change the description
345of
346.Ql sensor0
347in the
348.Ql aiboost0
349device with the
350.Dv ENVSYS_SETDICTIONARY
351.Xr ioctl 2 :
352.Bd -literal
353int
354main(void)
355{
356	prop_dictionary_t global_dict, sensor_dict;
357	prop_array_t;
358	prop_object_t obj;
359	int fd;
360
361	global_dict = prop_dictionary_create();
362	sensor_dict = prop_dictionary_create();
363	array = prop_array_create();
364
365	if (!prop_dictionary_set(global_dict, "aiboost0", array))
366		err(EINVAL, "prop_dictionary_set global");
367
368	obj = prop_string_create_cstring_nocopy("sensor0");
369	if (obj == NULL ||
370	    !prop_dictionary_set(dict, "index", obj))
371		err(EINVAL, "sensor index");
372
373	prop_object_release(obj);
374
375	/* new description */
376	obj = prop_string_create_cstring_nocopy("CPU temp");
377	if (obj == NULL ||
378	    !prop_dictionary_set(dict, "description", obj))
379		err(EINVAL, "new description");
380
381	prop_object_release(obj);
382
383	if (!prop_array_add(array, sensor_dict))
384		err(EINVAL, "prop_array_add");
385
386	if ((fd = open(_DEV_SYSMON, O_RDWR)) == \-1)
387		err(EXIT_FAILURE, "open")
388
389	/* we are done, send the dictionary */
390	error = prop_dictionary_send_ioctl(global_dict,
391					   fd,
392					   ENVSYS_SETDICTIONARY);
393	prop_object_release(array);
394	prop_object_release(global_dict);
395	(void)close(fd);
396	return error;
397}
398.Ed
399.Sh SEE ALSO
400.Xr envstat 8 ,
401.Xr powerd 8 ,
402.Xr sysmon_envsys 9
403.Sh HISTORY
404The first
405.Em envsys
406framework first appeared in
407.Nx 1.5 .
408The
409.Em envsys 2
410framework first appeared in
411.Nx 5.0 .
412.Sh AUTHORS
413The (current)
414.Em envsys 2
415framework was implemented by
416.An Juan Romero Pardines .
417Additional input on the design was provided by many
418.Nx
419developers around the world.
420.Pp
421The first
422.Em envsys
423framework was implemented by Jason R. Thorpe, Tim Rightnour,
424and Bill Squier.
425