blob: b3a9e1b9dbda9458b5d4215f50b3b217284c3b82 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Naming and data format standards for sysfs files
2------------------------------------------------
3
4The libsensors library offers an interface to the raw sensors data
5through the sysfs interface. See libsensors documentation and source for
Jean Delvare740e06a2006-06-05 20:31:20 +02006further information. As of writing this document, libsensors
7(from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating
Linus Torvalds1da177e2005-04-16 15:20:36 -07008support for any given chip requires modifying the library's code.
9This is because libsensors was written for the procfs interface
10older kernel modules were using, which wasn't standardized enough.
11Recent versions of libsensors (from lm_sensors 2.8.2 and later) have
12support for the sysfs interface, though.
13
Jean Delvare740e06a2006-06-05 20:31:20 +020014The new sysfs interface was designed to be as chip-independent as
Linus Torvalds1da177e2005-04-16 15:20:36 -070015possible.
16
17Note that motherboards vary widely in the connections to sensor chips.
18There is no standard that ensures, for example, that the second
19temperature sensor is connected to the CPU, or that the second fan is on
20the CPU. Also, some values reported by the chips need some computation
21before they make full sense. For example, most chips can only measure
22voltages between 0 and +4V. Other voltages are scaled back into that
23range using external resistors. Since the values of these resistors
24can change from motherboard to motherboard, the conversions cannot be
25hard coded into the driver and have to be done in user space.
26
Jean Delvare740e06a2006-06-05 20:31:20 +020027For this reason, even if we aim at a chip-independent libsensors, it will
Linus Torvalds1da177e2005-04-16 15:20:36 -070028still require a configuration file (e.g. /etc/sensors.conf) for proper
29values conversion, labeling of inputs and hiding of unused inputs.
30
31An alternative method that some programs use is to access the sysfs
32files directly. This document briefly describes the standards that the
33drivers follow, so that an application program can scan for entries and
34access this data in a simple and consistent way. That said, such programs
35will have to implement conversion, labeling and hiding of inputs. For
36this reason, it is still not recommended to bypass the library.
37
38If you are developing a userspace application please send us feedback on
39this standard.
40
41Note that this standard isn't completely established yet, so it is subject
Jean Delvare740e06a2006-06-05 20:31:20 +020042to changes. If you are writing a new hardware monitoring driver those
43features can't seem to fit in this interface, please contact us with your
44extension proposal. Keep in mind that backward compatibility must be
45preserved.
Linus Torvalds1da177e2005-04-16 15:20:36 -070046
47Each chip gets its own directory in the sysfs /sys/devices tree. To
Jean Delvare740e06a2006-06-05 20:31:20 +020048find all sensor chips, it is easier to follow the device symlinks from
49/sys/class/hwmon/hwmon*.
Linus Torvalds1da177e2005-04-16 15:20:36 -070050
Jean Delvare740e06a2006-06-05 20:31:20 +020051All sysfs values are fixed point numbers.
Linus Torvalds1da177e2005-04-16 15:20:36 -070052
53There is only one value per file, unlike the older /proc specification.
54The common scheme for files naming is: <type><number>_<item>. Usual
55types for sensor chips are "in" (voltage), "temp" (temperature) and
56"fan" (fan). Usual items are "input" (measured value), "max" (high
57threshold, "min" (low threshold). Numbering usually starts from 1,
58except for voltages which start from 0 (because most data sheets use
59this). A number is always used for elements that can be present more
60than once, even if there is a single element of the given type on the
61specific chip. Other files do not refer to a specific element, so
62they have a simple name, and no number.
63
64Alarms are direct indications read from the chips. The drivers do NOT
65make comparisons of readings to thresholds. This allows violations
66between readings to be caught and alarmed. The exact definition of an
67alarm (for example, whether a threshold must be met or must be exceeded
68to cause an alarm) is chip-dependent.
69
70
71-------------------------------------------------------------------------
72
Rudolf Marek057bc352006-06-04 20:03:39 +020073[0-*] denotes any positive number starting from 0
74[1-*] denotes any positive number starting from 1
75RO read only value
76RW read/write value
77
78Read/write values may be read-only for some chips, depending on the
79hardware implementation.
80
Jean Delvare740e06a2006-06-05 20:31:20 +020081All entries are optional, and should only be created in a given driver
82if the chip has the feature.
83
Linus Torvalds1da177e2005-04-16 15:20:36 -070084************
85* Voltages *
86************
87
Rudolf Marek057bc352006-06-04 20:03:39 +020088in[0-*]_min Voltage min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -070089 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +020090 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -070091
Rudolf Marek057bc352006-06-04 20:03:39 +020092in[0-*]_max Voltage max value.
Linus Torvalds1da177e2005-04-16 15:20:36 -070093 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +020094 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -070095
Rudolf Marek057bc352006-06-04 20:03:39 +020096in[0-*]_input Voltage input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -070097 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +020098 RO
99 Voltage measured on the chip pin.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100 Actual voltage depends on the scaling resistors on the
101 motherboard, as recommended in the chip datasheet.
102 This varies by chip and by motherboard.
103 Because of this variation, values are generally NOT scaled
104 by the chip driver, and must be done by the application.
105 However, some drivers (notably lm87 and via686a)
Rudolf Marek057bc352006-06-04 20:03:39 +0200106 do scale, because of internal resistors built into a chip.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700107 These drivers will output the actual voltage.
108
109 Typical usage:
110 in0_* CPU #1 voltage (not scaled)
111 in1_* CPU #2 voltage (not scaled)
112 in2_* 3.3V nominal (not scaled)
113 in3_* 5.0V nominal (scaled)
114 in4_* 12.0V nominal (scaled)
115 in5_* -12.0V nominal (scaled)
116 in6_* -5.0V nominal (scaled)
117 in7_* varies
118 in8_* varies
119
Rudolf Marek057bc352006-06-04 20:03:39 +0200120cpu[0-*]_vid CPU core reference voltage.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700121 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200122 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700123 Not always correct.
124
125vrm Voltage Regulator Module version number.
Rudolf Marek057bc352006-06-04 20:03:39 +0200126 RW (but changing it should no more be necessary)
127 Originally the VRM standard version multiplied by 10, but now
128 an arbitrary number, as not all standards have a version
129 number.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700130 Affects the way the driver calculates the CPU core reference
131 voltage from the vid pins.
132
Rudolf Marek057bc352006-06-04 20:03:39 +0200133Also see the Alarms section for status flags associated with voltages.
134
Linus Torvalds1da177e2005-04-16 15:20:36 -0700135
136********
137* Fans *
138********
139
Rudolf Marek057bc352006-06-04 20:03:39 +0200140fan[1-*]_min Fan minimum value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200142 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700143
Rudolf Marek057bc352006-06-04 20:03:39 +0200144fan[1-*]_input Fan input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700145 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200146 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700147
Rudolf Marek057bc352006-06-04 20:03:39 +0200148fan[1-*]_div Fan divisor.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
Rudolf Marek057bc352006-06-04 20:03:39 +0200150 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700151 Some chips only support values 1, 2, 4 and 8.
152 Note that this is actually an internal clock divisor, which
153 affects the measurable speed range, not the read value.
154
Jean Delvare2dbc5142007-05-08 17:22:00 +0200155fan[1-*]_target
156 Desired fan speed
157 Unit: revolution/min (RPM)
158 RW
159 Only makes sense if the chip supports closed-loop fan speed
160 control based on the measured fan speed.
161
Rudolf Marek057bc352006-06-04 20:03:39 +0200162Also see the Alarms section for status flags associated with fans.
163
164
Linus Torvalds1da177e2005-04-16 15:20:36 -0700165*******
166* PWM *
167*******
168
Rudolf Marek057bc352006-06-04 20:03:39 +0200169pwm[1-*] Pulse width modulation fan control.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170 Integer value in the range 0 to 255
Rudolf Marek057bc352006-06-04 20:03:39 +0200171 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172 255 is max or 100%.
173
Rudolf Marek057bc352006-06-04 20:03:39 +0200174pwm[1-*]_enable
Jean Delvare875f25d2007-06-27 21:26:08 +0200175 Fan speed control method:
176 0: no fan speed control (i.e. fan at full speed)
177 1: manual fan speed control enabled (using pwm[1-*])
178 2+: automatic fan speed control enabled
Jean Delvaref8d0c192007-02-14 21:15:02 +0100179 Check individual chip documentation files for automatic mode
180 details.
Rudolf Marek057bc352006-06-04 20:03:39 +0200181 RW
182
Jean Delvaref8d0c192007-02-14 21:15:02 +0100183pwm[1-*]_mode 0: DC mode (direct current)
184 1: PWM mode (pulse-width modulation)
185 RW
186
187pwm[1-*]_freq Base PWM frequency in Hz.
188 Only possibly available when pwmN_mode is PWM, but not always
189 present even then.
Rudolf Marek057bc352006-06-04 20:03:39 +0200190 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700191
192pwm[1-*]_auto_channels_temp
193 Select which temperature channels affect this PWM output in
194 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
195 Which values are possible depend on the chip used.
Rudolf Marek057bc352006-06-04 20:03:39 +0200196 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700197
198pwm[1-*]_auto_point[1-*]_pwm
199pwm[1-*]_auto_point[1-*]_temp
200pwm[1-*]_auto_point[1-*]_temp_hyst
201 Define the PWM vs temperature curve. Number of trip points is
202 chip-dependent. Use this for chips which associate trip points
203 to PWM output channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200204 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700205
206OR
207
208temp[1-*]_auto_point[1-*]_pwm
209temp[1-*]_auto_point[1-*]_temp
210temp[1-*]_auto_point[1-*]_temp_hyst
211 Define the PWM vs temperature curve. Number of trip points is
212 chip-dependent. Use this for chips which associate trip points
213 to temperature channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200214 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700215
216
217****************
218* Temperatures *
219****************
220
Rudolf Marek057bc352006-06-04 20:03:39 +0200221temp[1-*]_type Sensor type selection.
Rudolf Marek61db0112006-12-12 18:18:30 +0100222 Integers 1 to 6 or thermistor Beta value (typically 3435)
Rudolf Marek057bc352006-06-04 20:03:39 +0200223 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700224 1: PII/Celeron Diode
225 2: 3904 transistor
226 3: thermal diode
Jean Delvaree53004e2006-01-09 23:26:14 +0100227 4: thermistor (default/unknown Beta)
Rudolf Marek61db0112006-12-12 18:18:30 +0100228 5: AMD AMDSI
229 6: Intel PECI
Linus Torvalds1da177e2005-04-16 15:20:36 -0700230 Not all types are supported by all chips
231
Rudolf Marek057bc352006-06-04 20:03:39 +0200232temp[1-*]_max Temperature max value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200233 Unit: millidegree Celsius (or millivolt, see below)
Rudolf Marek057bc352006-06-04 20:03:39 +0200234 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235
Rudolf Marek057bc352006-06-04 20:03:39 +0200236temp[1-*]_min Temperature min value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200237 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200238 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700239
Rudolf Marek057bc352006-06-04 20:03:39 +0200240temp[1-*]_max_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700241 Temperature hysteresis value for max limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200242 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700243 Must be reported as an absolute temperature, NOT a delta
244 from the max value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200245 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700246
Rudolf Marek057bc352006-06-04 20:03:39 +0200247temp[1-*]_input Temperature input value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200248 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200249 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700250
Rudolf Marek057bc352006-06-04 20:03:39 +0200251temp[1-*]_crit Temperature critical value, typically greater than
Linus Torvalds1da177e2005-04-16 15:20:36 -0700252 corresponding temp_max values.
Jean Delvare740e06a2006-06-05 20:31:20 +0200253 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200254 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700255
Rudolf Marek057bc352006-06-04 20:03:39 +0200256temp[1-*]_crit_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700257 Temperature hysteresis value for critical limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200258 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700259 Must be reported as an absolute temperature, NOT a delta
260 from the critical value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200261 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700262
Hartmut Rick59ac8362006-03-23 16:37:23 +0100263temp[1-4]_offset
264 Temperature offset which is added to the temperature reading
265 by the chip.
266 Unit: millidegree Celsius
267 Read/Write value.
268
Linus Torvalds1da177e2005-04-16 15:20:36 -0700269 If there are multiple temperature sensors, temp1_* is
270 generally the sensor inside the chip itself,
271 reported as "motherboard temperature". temp2_* to
272 temp4_* are generally sensors external to the chip
273 itself, for example the thermal diode inside the CPU or
274 a thermistor nearby.
275
Jean Delvare740e06a2006-06-05 20:31:20 +0200276Some chips measure temperature using external thermistors and an ADC, and
277report the temperature measurement as a voltage. Converting this voltage
278back to a temperature (or the other way around for limits) requires
279mathematical functions not available in the kernel, so the conversion
280must occur in user space. For these chips, all temp* files described
281above should contain values expressed in millivolt instead of millidegree
282Celsius. In other words, such temperature channels are handled as voltage
283channels by the driver.
284
Rudolf Marek057bc352006-06-04 20:03:39 +0200285Also see the Alarms section for status flags associated with temperatures.
286
Linus Torvalds1da177e2005-04-16 15:20:36 -0700287
288************
289* Currents *
290************
291
292Note that no known chip provides current measurements as of writing,
293so this part is theoretical, so to say.
294
Rudolf Marek057bc352006-06-04 20:03:39 +0200295curr[1-*]_max Current max value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700296 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200297 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700298
Rudolf Marek057bc352006-06-04 20:03:39 +0200299curr[1-*]_min Current min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700300 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200301 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700302
Rudolf Marek057bc352006-06-04 20:03:39 +0200303curr[1-*]_input Current input value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700304 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200305 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700306
307
Jean Delvare400b48e2006-03-23 16:46:47 +0100308**********
309* Alarms *
310**********
311
312Each channel or limit may have an associated alarm file, containing a
313boolean value. 1 means than an alarm condition exists, 0 means no alarm.
314
315Usually a given chip will either use channel-related alarms, or
316limit-related alarms, not both. The driver should just reflect the hardware
317implementation.
318
Rudolf Marek057bc352006-06-04 20:03:39 +0200319in[0-*]_alarm
320fan[1-*]_alarm
321temp[1-*]_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100322 Channel alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200323 0: no alarm
324 1: alarm
325 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100326
327OR
328
Rudolf Marek057bc352006-06-04 20:03:39 +0200329in[0-*]_min_alarm
330in[0-*]_max_alarm
331fan[1-*]_min_alarm
332temp[1-*]_min_alarm
333temp[1-*]_max_alarm
334temp[1-*]_crit_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100335 Limit alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200336 0: no alarm
337 1: alarm
338 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100339
340Each input channel may have an associated fault file. This can be used
341to notify open diodes, unconnected fans etc. where the hardware
342supports it. When this boolean has value 1, the measurement for that
343channel should not be trusted.
344
Jean Delvare7817a392007-06-09 10:11:16 -0400345in[0-*]_fault
346fan[1-*]_fault
347temp[1-*]_fault
Jean Delvare400b48e2006-03-23 16:46:47 +0100348 Input fault condition
Rudolf Marek057bc352006-06-04 20:03:39 +0200349 0: no fault occured
350 1: fault condition
351 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100352
353Some chips also offer the possibility to get beeped when an alarm occurs:
354
355beep_enable Master beep enable
Rudolf Marek057bc352006-06-04 20:03:39 +0200356 0: no beeps
357 1: beeps
358 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100359
Rudolf Marek057bc352006-06-04 20:03:39 +0200360in[0-*]_beep
361fan[1-*]_beep
362temp[1-*]_beep
Jean Delvare400b48e2006-03-23 16:46:47 +0100363 Channel beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200364 0: disable
365 1: enable
366 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100367
368In theory, a chip could provide per-limit beep masking, but no such chip
369was seen so far.
370
371Old drivers provided a different, non-standard interface to alarms and
372beeps. These interface files are deprecated, but will be kept around
373for compatibility reasons:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700374
375alarms Alarm bitmask.
Rudolf Marek057bc352006-06-04 20:03:39 +0200376 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700377 Integer representation of one to four bytes.
378 A '1' bit means an alarm.
379 Chips should be programmed for 'comparator' mode so that
380 the alarm will 'come back' after you read the register
381 if it is still valid.
382 Generally a direct representation of a chip's internal
383 alarm registers; there is no standard for the position
Jean Delvare400b48e2006-03-23 16:46:47 +0100384 of individual bits. For this reason, the use of this
385 interface file for new drivers is discouraged. Use
386 individual *_alarm and *_fault files instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700387 Bits are defined in kernel/include/sensors.h.
388
Linus Torvalds1da177e2005-04-16 15:20:36 -0700389beep_mask Bitmask for beep.
Jean Delvare400b48e2006-03-23 16:46:47 +0100390 Same format as 'alarms' with the same bit locations,
391 use discouraged for the same reason. Use individual
392 *_beep files instead.
Rudolf Marek057bc352006-06-04 20:03:39 +0200393 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700394
Jean Delvare400b48e2006-03-23 16:46:47 +0100395
396*********
397* Other *
398*********
399
Linus Torvalds1da177e2005-04-16 15:20:36 -0700400eeprom Raw EEPROM data in binary form.
Rudolf Marek057bc352006-06-04 20:03:39 +0200401 RO
Jean Delvarec3df5802005-10-26 21:39:40 +0200402
403pec Enable or disable PEC (SMBus only)
Rudolf Marek057bc352006-06-04 20:03:39 +0200404 0: disable
405 1: enable
406 RW