About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hwmon / sysfs-interface


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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog