About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hwmon / sysfs-interface




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:03 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-*]_input Temperature input value.
331			Unit: millidegree Celsius
332			RO
333	
334	temp[1-*]_crit	Temperature critical max value, typically greater than
335			corresponding temp_max values.
336			Unit: millidegree Celsius
337			RW
338	
339	temp[1-*]_crit_hyst
340			Temperature hysteresis value for critical limit.
341			Unit: millidegree Celsius
342			Must be reported as an absolute temperature, NOT a delta
343			from the critical value.
344			RW
345	
346	temp[1-*]_emergency
347			Temperature emergency max value, for chips supporting more than
348			two upper temperature limits. Must be equal or greater than
349			corresponding temp_crit values.
350			Unit: millidegree Celsius
351			RW
352	
353	temp[1-*]_emergency_hyst
354			Temperature hysteresis value for emergency limit.
355			Unit: millidegree Celsius
356			Must be reported as an absolute temperature, NOT a delta
357			from the emergency value.
358			RW
359	
360	temp[1-*]_lcrit	Temperature critical min value, typically lower than
361			corresponding temp_min values.
362			Unit: millidegree Celsius
363			RW
364	
365	temp[1-*]_offset
366			Temperature offset which is added to the temperature reading
367			by the chip.
368			Unit: millidegree Celsius
369			Read/Write value.
370	
371	temp[1-*]_label	Suggested temperature channel label.
372			Text string
373			Should only be created if the driver has hints about what
374			this temperature channel is being used for, and user-space
375			doesn't. In all other cases, the label is provided by
376			user-space.
377			RO
378	
379	temp[1-*]_lowest
380			Historical minimum temperature
381			Unit: millidegree Celsius
382			RO
383	
384	temp[1-*]_highest
385			Historical maximum temperature
386			Unit: millidegree Celsius
387			RO
388	
389	temp[1-*]_reset_history
390			Reset temp_lowest and temp_highest
391			WO
392	
393	temp_reset_history
394			Reset temp_lowest and temp_highest for all sensors
395			WO
396	
397	Some chips measure temperature using external thermistors and an ADC, and
398	report the temperature measurement as a voltage. Converting this voltage
399	back to a temperature (or the other way around for limits) requires
400	mathematical functions not available in the kernel, so the conversion
401	must occur in user space. For these chips, all temp* files described
402	above should contain values expressed in millivolt instead of millidegree
403	Celsius. In other words, such temperature channels are handled as voltage
404	channels by the driver.
405	
406	Also see the Alarms section for status flags associated with temperatures.
407	
408	
409	************
410	* Currents *
411	************
412	
413	curr[1-*]_max	Current max value
414			Unit: milliampere
415			RW
416	
417	curr[1-*]_min	Current min value.
418			Unit: milliampere
419			RW
420	
421	curr[1-*]_lcrit	Current critical low value
422			Unit: milliampere
423			RW
424	
425	curr[1-*]_crit	Current critical high value.
426			Unit: milliampere
427			RW
428	
429	curr[1-*]_input	Current input value
430			Unit: milliampere
431			RO
432	
433	curr[1-*]_average
434			Average current use
435			Unit: milliampere
436			RO
437	
438	curr[1-*]_lowest
439			Historical minimum current
440			Unit: milliampere
441			RO
442	
443	curr[1-*]_highest
444			Historical maximum current
445			Unit: milliampere
446			RO
447	
448	curr[1-*]_reset_history
449			Reset currX_lowest and currX_highest
450			WO
451	
452	curr_reset_history
453			Reset currX_lowest and currX_highest for all sensors
454			WO
455	
456	Also see the Alarms section for status flags associated with currents.
457	
458	*********
459	* Power *
460	*********
461	
462	power[1-*]_average		Average power use
463					Unit: microWatt
464					RO
465	
466	power[1-*]_average_interval	Power use averaging interval.  A poll
467					notification is sent to this file if the
468					hardware changes the averaging interval.
469					Unit: milliseconds
470					RW
471	
472	power[1-*]_average_interval_max	Maximum power use averaging interval
473					Unit: milliseconds
474					RO
475	
476	power[1-*]_average_interval_min	Minimum power use averaging interval
477					Unit: milliseconds
478					RO
479	
480	power[1-*]_average_highest	Historical average maximum power use
481					Unit: microWatt
482					RO
483	
484	power[1-*]_average_lowest	Historical average minimum power use
485					Unit: microWatt
486					RO
487	
488	power[1-*]_average_max		A poll notification is sent to
489					power[1-*]_average when power use
490					rises above this value.
491					Unit: microWatt
492					RW
493	
494	power[1-*]_average_min		A poll notification is sent to
495					power[1-*]_average when power use
496					sinks below this value.
497					Unit: microWatt
498					RW
499	
500	power[1-*]_input		Instantaneous power use
501					Unit: microWatt
502					RO
503	
504	power[1-*]_input_highest	Historical maximum power use
505					Unit: microWatt
506					RO
507	
508	power[1-*]_input_lowest		Historical minimum power use
509					Unit: microWatt
510					RO
511	
512	power[1-*]_reset_history	Reset input_highest, input_lowest,
513					average_highest and average_lowest.
514					WO
515	
516	power[1-*]_accuracy		Accuracy of the power meter.
517					Unit: Percent
518					RO
519	
520	power[1-*]_cap			If power use rises above this limit, the
521					system should take action to reduce power use.
522					A poll notification is sent to this file if the
523					cap is changed by the hardware.  The *_cap
524					files only appear if the cap is known to be
525					enforced by hardware.
526					Unit: microWatt
527					RW
528	
529	power[1-*]_cap_hyst		Margin of hysteresis built around capping and
530					notification.
531					Unit: microWatt
532					RW
533	
534	power[1-*]_cap_max		Maximum cap that can be set.
535					Unit: microWatt
536					RO
537	
538	power[1-*]_cap_min		Minimum cap that can be set.
539					Unit: microWatt
540					RO
541	
542	power[1-*]_max			Maximum power.
543					Unit: microWatt
544					RW
545	
546	power[1-*]_crit			Critical maximum power.
547					If power rises to or above this limit, the
548					system is expected take drastic action to reduce
549					power consumption, such as a system shutdown or
550					a forced powerdown of some devices.
551					Unit: microWatt
552					RW
553	
554	Also see the Alarms section for status flags associated with power readings.
555	
556	**********
557	* Energy *
558	**********
559	
560	energy[1-*]_input		Cumulative energy use
561					Unit: microJoule
562					RO
563	
564	
565	************
566	* Humidity *
567	************
568	
569	humidity[1-*]_input		Humidity
570					Unit: milli-percent (per cent mille, pcm)
571					RO
572	
573	
574	**********
575	* Alarms *
576	**********
577	
578	Each channel or limit may have an associated alarm file, containing a
579	boolean value. 1 means than an alarm condition exists, 0 means no alarm.
580	
581	Usually a given chip will either use channel-related alarms, or
582	limit-related alarms, not both. The driver should just reflect the hardware
583	implementation.
584	
585	in[0-*]_alarm
586	curr[1-*]_alarm
587	power[1-*]_alarm
588	fan[1-*]_alarm
589	temp[1-*]_alarm
590			Channel alarm
591			0: no alarm
592			1: alarm
593			RO
594	
595	OR
596	
597	in[0-*]_min_alarm
598	in[0-*]_max_alarm
599	in[0-*]_lcrit_alarm
600	in[0-*]_crit_alarm
601	curr[1-*]_min_alarm
602	curr[1-*]_max_alarm
603	curr[1-*]_lcrit_alarm
604	curr[1-*]_crit_alarm
605	power[1-*]_cap_alarm
606	power[1-*]_max_alarm
607	power[1-*]_crit_alarm
608	fan[1-*]_min_alarm
609	fan[1-*]_max_alarm
610	temp[1-*]_min_alarm
611	temp[1-*]_max_alarm
612	temp[1-*]_lcrit_alarm
613	temp[1-*]_crit_alarm
614	temp[1-*]_emergency_alarm
615			Limit alarm
616			0: no alarm
617			1: alarm
618			RO
619	
620	Each input channel may have an associated fault file. This can be used
621	to notify open diodes, unconnected fans etc. where the hardware
622	supports it. When this boolean has value 1, the measurement for that
623	channel should not be trusted.
624	
625	fan[1-*]_fault
626	temp[1-*]_fault
627			Input fault condition
628			0: no fault occurred
629			1: fault condition
630			RO
631	
632	Some chips also offer the possibility to get beeped when an alarm occurs:
633	
634	beep_enable	Master beep enable
635			0: no beeps
636			1: beeps
637			RW
638	
639	in[0-*]_beep
640	curr[1-*]_beep
641	fan[1-*]_beep
642	temp[1-*]_beep
643			Channel beep
644			0: disable
645			1: enable
646			RW
647	
648	In theory, a chip could provide per-limit beep masking, but no such chip
649	was seen so far.
650	
651	Old drivers provided a different, non-standard interface to alarms and
652	beeps. These interface files are deprecated, but will be kept around
653	for compatibility reasons:
654	
655	alarms		Alarm bitmask.
656			RO
657			Integer representation of one to four bytes.
658			A '1' bit means an alarm.
659			Chips should be programmed for 'comparator' mode so that
660			the alarm will 'come back' after you read the register
661			if it is still valid.
662			Generally a direct representation of a chip's internal
663			alarm registers; there is no standard for the position
664			of individual bits. For this reason, the use of this
665			interface file for new drivers is discouraged. Use
666			individual *_alarm and *_fault files instead.
667			Bits are defined in kernel/include/sensors.h.
668	
669	beep_mask	Bitmask for beep.
670			Same format as 'alarms' with the same bit locations,
671			use discouraged for the same reason. Use individual
672			*_beep files instead.
673			RW
674	
675	
676	***********************
677	* Intrusion detection *
678	***********************
679	
680	intrusion[0-*]_alarm
681			Chassis intrusion detection
682			0: OK
683			1: intrusion detected
684			RW
685			Contrary to regular alarm flags which clear themselves
686			automatically when read, this one sticks until cleared by
687			the user. This is done by writing 0 to the file. Writing
688			other values is unsupported.
689	
690	intrusion[0-*]_beep
691			Chassis intrusion beep
692			0: disable
693			1: enable
694			RW
695	
696	
697	sysfs attribute writes interpretation
698	-------------------------------------
699	
700	hwmon sysfs attributes always contain numbers, so the first thing to do is to
701	convert the input to a number, there are 2 ways todo this depending whether
702	the number can be negative or not:
703	unsigned long u = simple_strtoul(buf, NULL, 10);
704	long s = simple_strtol(buf, NULL, 10);
705	
706	With buf being the buffer with the user input being passed by the kernel.
707	Notice that we do not use the second argument of strto[u]l, and thus cannot
708	tell when 0 is returned, if this was really 0 or is caused by invalid input.
709	This is done deliberately as checking this everywhere would add a lot of
710	code to the kernel.
711	
712	Notice that it is important to always store the converted value in an
713	unsigned long or long, so that no wrap around can happen before any further
714	checking.
715	
716	After the input string is converted to an (unsigned) long, the value should be
717	checked if its acceptable. Be careful with further conversions on the value
718	before checking it for validity, as these conversions could still cause a wrap
719	around before the check. For example do not multiply the result, and only
720	add/subtract if it has been divided before the add/subtract.
721	
722	What to do if a value is found to be invalid, depends on the type of the
723	sysfs attribute that is being set. If it is a continuous setting like a
724	tempX_max or inX_max attribute, then the value should be clamped to its
725	limits using clamp_val(value, min_limit, max_limit). If it is not continuous
726	like for example a tempX_type, then when an invalid value is written,
727	-EINVAL should be returned.
728	
729	Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
730	
731		long v = simple_strtol(buf, NULL, 10) / 1000;
732		v = clamp_val(v, -128, 127);
733		/* write v to register */
734	
735	Example2, fan divider setting, valid values 2, 4 and 8:
736	
737		unsigned long v = simple_strtoul(buf, NULL, 10);
738	
739		switch (v) {
740		case 2: v = 1; break;
741		case 4: v = 2; break;
742		case 8: v = 3; break;
743		default:
744			return -EINVAL;
745		}
746		/* 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.