About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hwmon / sysfs-interface




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:39 EST.

1	Naming and data format standards for sysfs files
2	------------------------------------------------
3	
4	The libsensors library offers an interface to the raw sensors data
5	through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
6	completely chip-independent. It assumes that all the kernel drivers
7	implement the standard sysfs interface described in this document.
8	This makes adding or updating support for any given chip very easy, as
9	libsensors, and applications using it, do not need to be modified.
10	This is a major improvement compared to lm-sensors 2.
11	
12	Note that motherboards vary widely in the connections to sensor chips.
13	There is no standard that ensures, for example, that the second
14	temperature sensor is connected to the CPU, or that the second fan is on
15	the CPU. Also, some values reported by the chips need some computation
16	before they make full sense. For example, most chips can only measure
17	voltages between 0 and +4V. Other voltages are scaled back into that
18	range using external resistors. Since the values of these resistors
19	can change from motherboard to motherboard, the conversions cannot be
20	hard coded into the driver and have to be done in user space.
21	
22	For this reason, even if we aim at a chip-independent libsensors, it will
23	still require a configuration file (e.g. /etc/sensors.conf) for proper
24	values conversion, labeling of inputs and hiding of unused inputs.
25	
26	An alternative method that some programs use is to access the sysfs
27	files directly. This document briefly describes the standards that the
28	drivers follow, so that an application program can scan for entries and
29	access this data in a simple and consistent way. That said, such programs
30	will have to implement conversion, labeling and hiding of inputs. For
31	this reason, it is still not recommended to bypass the library.
32	
33	Each chip gets its own directory in the sysfs /sys/devices tree.  To
34	find all sensor chips, it is easier to follow the device symlinks from
35	/sys/class/hwmon/hwmon*.
36	
37	Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
38	in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
39	in the hwmon "class" device directory are also supported. Complex drivers
40	(e.g. drivers for multifunction chips) may want to use this possibility to
41	avoid namespace pollution. The only drawback will be that older versions of
42	libsensors won't support the driver in question.
43	
44	All sysfs values are fixed point numbers.
45	
46	There is only one value per file, unlike the older /proc specification.
47	The common scheme for files naming is: <type><number>_<item>. Usual
48	types for sensor chips are "in" (voltage), "temp" (temperature) and
49	"fan" (fan). Usual items are "input" (measured value), "max" (high
50	threshold, "min" (low threshold). Numbering usually starts from 1,
51	except for voltages which start from 0 (because most data sheets use
52	this). A number is always used for elements that can be present more
53	than once, even if there is a single element of the given type on the
54	specific chip. Other files do not refer to a specific element, so
55	they have a simple name, and no number.
56	
57	Alarms are direct indications read from the chips. The drivers do NOT
58	make comparisons of readings to thresholds. This allows violations
59	between readings to be caught and alarmed. The exact definition of an
60	alarm (for example, whether a threshold must be met or must be exceeded
61	to cause an alarm) is chip-dependent.
62	
63	When setting values of hwmon sysfs attributes, the string representation of
64	the desired value must be written, note that strings which are not a number
65	are interpreted as 0! For more on how written strings are interpreted see the
66	"sysfs attribute writes interpretation" section at the end of this file.
67	
68	-------------------------------------------------------------------------
69	
70	[0-*]	denotes any positive number starting from 0
71	[1-*]	denotes any positive number starting from 1
72	RO	read only value
73	WO	write only value
74	RW	read/write value
75	
76	Read/write values may be read-only for some chips, depending on the
77	hardware implementation.
78	
79	All entries (except name) are optional, and should only be created in a
80	given driver if the chip has the feature.
81	
82	
83	*********************
84	* Global attributes *
85	*********************
86	
87	name		The chip name.
88			This should be a short, lowercase string, not containing
89			spaces nor dashes, representing the chip name. This is
90			the only mandatory attribute.
91			I2C devices get this attribute created automatically.
92			RO
93	
94	update_interval	The interval at which the chip will update readings.
95			Unit: millisecond
96			RW
97			Some devices have a variable update rate or interval.
98			This attribute can be used to change it to the desired value.
99	
100	
101	************
102	* Voltages *
103	************
104	
105	in[0-*]_min	Voltage min value.
106			Unit: millivolt
107			RW
108			
109	in[0-*]_lcrit	Voltage critical min value.
110			Unit: millivolt
111			RW
112			If voltage drops to or below this limit, the system may
113			take drastic action such as power down or reset. At the very
114			least, it should report a fault.
115	
116	in[0-*]_max	Voltage max value.
117			Unit: millivolt
118			RW
119			
120	in[0-*]_crit	Voltage critical max value.
121			Unit: millivolt
122			RW
123			If voltage reaches or exceeds this limit, the system may
124			take drastic action such as power down or reset. At the very
125			least, it should report a fault.
126	
127	in[0-*]_input	Voltage input value.
128			Unit: millivolt
129			RO
130			Voltage measured on the chip pin.
131			Actual voltage depends on the scaling resistors on the
132			motherboard, as recommended in the chip datasheet.
133			This varies by chip and by motherboard.
134			Because of this variation, values are generally NOT scaled
135			by the chip driver, and must be done by the application.
136			However, some drivers (notably lm87 and via686a)
137			do scale, because of internal resistors built into a chip.
138			These drivers will output the actual voltage. Rule of
139			thumb: drivers should report the voltage values at the
140			"pins" of the chip.
141	
142	in[0-*]_average
143			Average voltage
144			Unit: millivolt
145			RO
146	
147	in[0-*]_lowest
148			Historical minimum voltage
149			Unit: millivolt
150			RO
151	
152	in[0-*]_highest
153			Historical maximum voltage
154			Unit: millivolt
155			RO
156	
157	in[0-*]_reset_history
158			Reset inX_lowest and inX_highest
159			WO
160	
161	in_reset_history
162			Reset inX_lowest and inX_highest for all sensors
163			WO
164	
165	in[0-*]_label	Suggested voltage channel label.
166			Text string
167			Should only be created if the driver has hints about what
168			this voltage channel is being used for, and user-space
169			doesn't. In all other cases, the label is provided by
170			user-space.
171			RO
172	
173	cpu[0-*]_vid	CPU core reference voltage.
174			Unit: millivolt
175			RO
176			Not always correct.
177	
178	vrm		Voltage Regulator Module version number. 
179			RW (but changing it should no more be necessary)
180			Originally the VRM standard version multiplied by 10, but now
181			an arbitrary number, as not all standards have a version
182			number.
183			Affects the way the driver calculates the CPU core reference
184			voltage from the vid pins.
185	
186	Also see the Alarms section for status flags associated with voltages.
187	
188	
189	********
190	* Fans *
191	********
192	
193	fan[1-*]_min	Fan minimum value
194			Unit: revolution/min (RPM)
195			RW
196	
197	fan[1-*]_max	Fan maximum value
198			Unit: revolution/min (RPM)
199			Only rarely supported by the hardware.
200			RW
201	
202	fan[1-*]_input	Fan input value.
203			Unit: revolution/min (RPM)
204			RO
205	
206	fan[1-*]_div	Fan divisor.
207			Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
208			RW
209			Some chips only support values 1, 2, 4 and 8.
210			Note that this is actually an internal clock divisor, which
211			affects the measurable speed range, not the read value.
212	
213	fan[1-*]_pulses	Number of tachometer pulses per fan revolution.
214			Integer value, typically between 1 and 4.
215			RW
216			This value is a characteristic of the fan connected to the
217			device's input, so it has to be set in accordance with the fan
218			model.
219			Should only be created if the chip has a register to configure
220			the number of pulses. In the absence of such a register (and
221			thus attribute) the value assumed by all devices is 2 pulses
222			per fan revolution.
223	
224	fan[1-*]_target
225			Desired fan speed
226			Unit: revolution/min (RPM)
227			RW
228			Only makes sense if the chip supports closed-loop fan speed
229			control based on the measured fan speed.
230	
231	fan[1-*]_label	Suggested fan channel label.
232			Text string
233			Should only be created if the driver has hints about what
234			this fan channel is being used for, and user-space doesn't.
235			In all other cases, the label is provided by user-space.
236			RO
237	
238	Also see the Alarms section for status flags associated with fans.
239	
240	
241	*******
242	* PWM *
243	*******
244	
245	pwm[1-*]	Pulse width modulation fan control.
246			Integer value in the range 0 to 255
247			RW
248			255 is max or 100%.
249	
250	pwm[1-*]_enable
251			Fan speed control method:
252			0: no fan speed control (i.e. fan at full speed)
253			1: manual fan speed control enabled (using pwm[1-*])
254			2+: automatic fan speed control enabled
255			Check individual chip documentation files for automatic mode
256			details.
257			RW
258	
259	pwm[1-*]_mode	0: DC mode (direct current)
260			1: PWM mode (pulse-width modulation)
261			RW
262	
263	pwm[1-*]_freq	Base PWM frequency in Hz.
264			Only possibly available when pwmN_mode is PWM, but not always
265			present even then.
266			RW
267	
268	pwm[1-*]_auto_channels_temp
269			Select which temperature channels affect this PWM output in
270			auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
271			Which values are possible depend on the chip used.
272			RW
273	
274	pwm[1-*]_auto_point[1-*]_pwm
275	pwm[1-*]_auto_point[1-*]_temp
276	pwm[1-*]_auto_point[1-*]_temp_hyst
277			Define the PWM vs temperature curve. Number of trip points is
278			chip-dependent. Use this for chips which associate trip points
279			to PWM output channels.
280			RW
281	
282	temp[1-*]_auto_point[1-*]_pwm
283	temp[1-*]_auto_point[1-*]_temp
284	temp[1-*]_auto_point[1-*]_temp_hyst
285			Define the PWM vs temperature curve. Number of trip points is
286			chip-dependent. Use this for chips which associate trip points
287			to temperature channels.
288			RW
289	
290	There is a third case where trip points are associated to both PWM output
291	channels and temperature channels: the PWM values are associated to PWM
292	output channels while the temperature values are associated to temperature
293	channels. In that case, the result is determined by the mapping between
294	temperature inputs and PWM outputs. When several temperature inputs are
295	mapped to a given PWM output, this leads to several candidate PWM values.
296	The actual result is up to the chip, but in general the highest candidate
297	value (fastest fan speed) wins.
298	
299	
300	****************
301	* Temperatures *
302	****************
303	
304	temp[1-*]_type	Sensor type selection.
305			Integers 1 to 6
306			RW
307			1: CPU embedded diode
308			2: 3904 transistor
309			3: thermal diode
310			4: thermistor
311			5: AMD AMDSI
312			6: Intel PECI
313			Not all types are supported by all chips
314	
315	temp[1-*]_max	Temperature max value.
316			Unit: millidegree Celsius (or millivolt, see below)
317			RW
318	
319	temp[1-*]_min	Temperature min value.
320			Unit: millidegree Celsius
321			RW
322	
323	temp[1-*]_max_hyst
324			Temperature hysteresis value for max limit.
325			Unit: millidegree Celsius
326			Must be reported as an absolute temperature, NOT a delta
327			from the max value.
328			RW
329	
330	temp[1-*]_min_hyst
331			Temperature hysteresis value for min limit.
332			Unit: millidegree Celsius
333			Must be reported as an absolute temperature, NOT a delta
334			from the min value.
335			RW
336	
337	temp[1-*]_input Temperature input value.
338			Unit: millidegree Celsius
339			RO
340	
341	temp[1-*]_crit	Temperature critical max value, typically greater than
342			corresponding temp_max values.
343			Unit: millidegree Celsius
344			RW
345	
346	temp[1-*]_crit_hyst
347			Temperature hysteresis value for critical limit.
348			Unit: millidegree Celsius
349			Must be reported as an absolute temperature, NOT a delta
350			from the critical value.
351			RW
352	
353	temp[1-*]_emergency
354			Temperature emergency max value, for chips supporting more than
355			two upper temperature limits. Must be equal or greater than
356			corresponding temp_crit values.
357			Unit: millidegree Celsius
358			RW
359	
360	temp[1-*]_emergency_hyst
361			Temperature hysteresis value for emergency limit.
362			Unit: millidegree Celsius
363			Must be reported as an absolute temperature, NOT a delta
364			from the emergency value.
365			RW
366	
367	temp[1-*]_lcrit	Temperature critical min value, typically lower than
368			corresponding temp_min values.
369			Unit: millidegree Celsius
370			RW
371	
372	temp[1-*]_lcrit_hyst
373			Temperature hysteresis value for critical min limit.
374			Unit: millidegree Celsius
375			Must be reported as an absolute temperature, NOT a delta
376			from the critical min value.
377			RW
378	
379	temp[1-*]_offset
380			Temperature offset which is added to the temperature reading
381			by the chip.
382			Unit: millidegree Celsius
383			Read/Write value.
384	
385	temp[1-*]_label	Suggested temperature channel label.
386			Text string
387			Should only be created if the driver has hints about what
388			this temperature channel is being used for, and user-space
389			doesn't. In all other cases, the label is provided by
390			user-space.
391			RO
392	
393	temp[1-*]_lowest
394			Historical minimum temperature
395			Unit: millidegree Celsius
396			RO
397	
398	temp[1-*]_highest
399			Historical maximum temperature
400			Unit: millidegree Celsius
401			RO
402	
403	temp[1-*]_reset_history
404			Reset temp_lowest and temp_highest
405			WO
406	
407	temp_reset_history
408			Reset temp_lowest and temp_highest for all sensors
409			WO
410	
411	Some chips measure temperature using external thermistors and an ADC, and
412	report the temperature measurement as a voltage. Converting this voltage
413	back to a temperature (or the other way around for limits) requires
414	mathematical functions not available in the kernel, so the conversion
415	must occur in user space. For these chips, all temp* files described
416	above should contain values expressed in millivolt instead of millidegree
417	Celsius. In other words, such temperature channels are handled as voltage
418	channels by the driver.
419	
420	Also see the Alarms section for status flags associated with temperatures.
421	
422	
423	************
424	* Currents *
425	************
426	
427	curr[1-*]_max	Current max value
428			Unit: milliampere
429			RW
430	
431	curr[1-*]_min	Current min value.
432			Unit: milliampere
433			RW
434	
435	curr[1-*]_lcrit	Current critical low value
436			Unit: milliampere
437			RW
438	
439	curr[1-*]_crit	Current critical high value.
440			Unit: milliampere
441			RW
442	
443	curr[1-*]_input	Current input value
444			Unit: milliampere
445			RO
446	
447	curr[1-*]_average
448			Average current use
449			Unit: milliampere
450			RO
451	
452	curr[1-*]_lowest
453			Historical minimum current
454			Unit: milliampere
455			RO
456	
457	curr[1-*]_highest
458			Historical maximum current
459			Unit: milliampere
460			RO
461	
462	curr[1-*]_reset_history
463			Reset currX_lowest and currX_highest
464			WO
465	
466	curr_reset_history
467			Reset currX_lowest and currX_highest for all sensors
468			WO
469	
470	Also see the Alarms section for status flags associated with currents.
471	
472	*********
473	* Power *
474	*********
475	
476	power[1-*]_average		Average power use
477					Unit: microWatt
478					RO
479	
480	power[1-*]_average_interval	Power use averaging interval.  A poll
481					notification is sent to this file if the
482					hardware changes the averaging interval.
483					Unit: milliseconds
484					RW
485	
486	power[1-*]_average_interval_max	Maximum power use averaging interval
487					Unit: milliseconds
488					RO
489	
490	power[1-*]_average_interval_min	Minimum power use averaging interval
491					Unit: milliseconds
492					RO
493	
494	power[1-*]_average_highest	Historical average maximum power use
495					Unit: microWatt
496					RO
497	
498	power[1-*]_average_lowest	Historical average minimum power use
499					Unit: microWatt
500					RO
501	
502	power[1-*]_average_max		A poll notification is sent to
503					power[1-*]_average when power use
504					rises above this value.
505					Unit: microWatt
506					RW
507	
508	power[1-*]_average_min		A poll notification is sent to
509					power[1-*]_average when power use
510					sinks below this value.
511					Unit: microWatt
512					RW
513	
514	power[1-*]_input		Instantaneous power use
515					Unit: microWatt
516					RO
517	
518	power[1-*]_input_highest	Historical maximum power use
519					Unit: microWatt
520					RO
521	
522	power[1-*]_input_lowest		Historical minimum power use
523					Unit: microWatt
524					RO
525	
526	power[1-*]_reset_history	Reset input_highest, input_lowest,
527					average_highest and average_lowest.
528					WO
529	
530	power[1-*]_accuracy		Accuracy of the power meter.
531					Unit: Percent
532					RO
533	
534	power[1-*]_cap			If power use rises above this limit, the
535					system should take action to reduce power use.
536					A poll notification is sent to this file if the
537					cap is changed by the hardware.  The *_cap
538					files only appear if the cap is known to be
539					enforced by hardware.
540					Unit: microWatt
541					RW
542	
543	power[1-*]_cap_hyst		Margin of hysteresis built around capping and
544					notification.
545					Unit: microWatt
546					RW
547	
548	power[1-*]_cap_max		Maximum cap that can be set.
549					Unit: microWatt
550					RO
551	
552	power[1-*]_cap_min		Minimum cap that can be set.
553					Unit: microWatt
554					RO
555	
556	power[1-*]_max			Maximum power.
557					Unit: microWatt
558					RW
559	
560	power[1-*]_crit			Critical maximum power.
561					If power rises to or above this limit, the
562					system is expected take drastic action to reduce
563					power consumption, such as a system shutdown or
564					a forced powerdown of some devices.
565					Unit: microWatt
566					RW
567	
568	Also see the Alarms section for status flags associated with power readings.
569	
570	**********
571	* Energy *
572	**********
573	
574	energy[1-*]_input		Cumulative energy use
575					Unit: microJoule
576					RO
577	
578	
579	************
580	* Humidity *
581	************
582	
583	humidity[1-*]_input		Humidity
584					Unit: milli-percent (per cent mille, pcm)
585					RO
586	
587	
588	**********
589	* Alarms *
590	**********
591	
592	Each channel or limit may have an associated alarm file, containing a
593	boolean value. 1 means than an alarm condition exists, 0 means no alarm.
594	
595	Usually a given chip will either use channel-related alarms, or
596	limit-related alarms, not both. The driver should just reflect the hardware
597	implementation.
598	
599	in[0-*]_alarm
600	curr[1-*]_alarm
601	power[1-*]_alarm
602	fan[1-*]_alarm
603	temp[1-*]_alarm
604			Channel alarm
605			0: no alarm
606			1: alarm
607			RO
608	
609	OR
610	
611	in[0-*]_min_alarm
612	in[0-*]_max_alarm
613	in[0-*]_lcrit_alarm
614	in[0-*]_crit_alarm
615	curr[1-*]_min_alarm
616	curr[1-*]_max_alarm
617	curr[1-*]_lcrit_alarm
618	curr[1-*]_crit_alarm
619	power[1-*]_cap_alarm
620	power[1-*]_max_alarm
621	power[1-*]_crit_alarm
622	fan[1-*]_min_alarm
623	fan[1-*]_max_alarm
624	temp[1-*]_min_alarm
625	temp[1-*]_max_alarm
626	temp[1-*]_lcrit_alarm
627	temp[1-*]_crit_alarm
628	temp[1-*]_emergency_alarm
629			Limit alarm
630			0: no alarm
631			1: alarm
632			RO
633	
634	Each input channel may have an associated fault file. This can be used
635	to notify open diodes, unconnected fans etc. where the hardware
636	supports it. When this boolean has value 1, the measurement for that
637	channel should not be trusted.
638	
639	fan[1-*]_fault
640	temp[1-*]_fault
641			Input fault condition
642			0: no fault occurred
643			1: fault condition
644			RO
645	
646	Some chips also offer the possibility to get beeped when an alarm occurs:
647	
648	beep_enable	Master beep enable
649			0: no beeps
650			1: beeps
651			RW
652	
653	in[0-*]_beep
654	curr[1-*]_beep
655	fan[1-*]_beep
656	temp[1-*]_beep
657			Channel beep
658			0: disable
659			1: enable
660			RW
661	
662	In theory, a chip could provide per-limit beep masking, but no such chip
663	was seen so far.
664	
665	Old drivers provided a different, non-standard interface to alarms and
666	beeps. These interface files are deprecated, but will be kept around
667	for compatibility reasons:
668	
669	alarms		Alarm bitmask.
670			RO
671			Integer representation of one to four bytes.
672			A '1' bit means an alarm.
673			Chips should be programmed for 'comparator' mode so that
674			the alarm will 'come back' after you read the register
675			if it is still valid.
676			Generally a direct representation of a chip's internal
677			alarm registers; there is no standard for the position
678			of individual bits. For this reason, the use of this
679			interface file for new drivers is discouraged. Use
680			individual *_alarm and *_fault files instead.
681			Bits are defined in kernel/include/sensors.h.
682	
683	beep_mask	Bitmask for beep.
684			Same format as 'alarms' with the same bit locations,
685			use discouraged for the same reason. Use individual
686			*_beep files instead.
687			RW
688	
689	
690	***********************
691	* Intrusion detection *
692	***********************
693	
694	intrusion[0-*]_alarm
695			Chassis intrusion detection
696			0: OK
697			1: intrusion detected
698			RW
699			Contrary to regular alarm flags which clear themselves
700			automatically when read, this one sticks until cleared by
701			the user. This is done by writing 0 to the file. Writing
702			other values is unsupported.
703	
704	intrusion[0-*]_beep
705			Chassis intrusion beep
706			0: disable
707			1: enable
708			RW
709	
710	
711	sysfs attribute writes interpretation
712	-------------------------------------
713	
714	hwmon sysfs attributes always contain numbers, so the first thing to do is to
715	convert the input to a number, there are 2 ways todo this depending whether
716	the number can be negative or not:
717	unsigned long u = simple_strtoul(buf, NULL, 10);
718	long s = simple_strtol(buf, NULL, 10);
719	
720	With buf being the buffer with the user input being passed by the kernel.
721	Notice that we do not use the second argument of strto[u]l, and thus cannot
722	tell when 0 is returned, if this was really 0 or is caused by invalid input.
723	This is done deliberately as checking this everywhere would add a lot of
724	code to the kernel.
725	
726	Notice that it is important to always store the converted value in an
727	unsigned long or long, so that no wrap around can happen before any further
728	checking.
729	
730	After the input string is converted to an (unsigned) long, the value should be
731	checked if its acceptable. Be careful with further conversions on the value
732	before checking it for validity, as these conversions could still cause a wrap
733	around before the check. For example do not multiply the result, and only
734	add/subtract if it has been divided before the add/subtract.
735	
736	What to do if a value is found to be invalid, depends on the type of the
737	sysfs attribute that is being set. If it is a continuous setting like a
738	tempX_max or inX_max attribute, then the value should be clamped to its
739	limits using clamp_val(value, min_limit, max_limit). If it is not continuous
740	like for example a tempX_type, then when an invalid value is written,
741	-EINVAL should be returned.
742	
743	Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
744	
745		long v = simple_strtol(buf, NULL, 10) / 1000;
746		v = clamp_val(v, -128, 127);
747		/* write v to register */
748	
749	Example2, fan divider setting, valid values 2, 4 and 8:
750	
751		unsigned long v = simple_strtoul(buf, NULL, 10);
752	
753		switch (v) {
754		case 2: v = 1; break;
755		case 4: v = 2; break;
756		case 8: v = 3; break;
757		default:
758			return -EINVAL;
759		}
760		/* write v to register */
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.