blob: c6559f15358933cb2ab74a49d70a34ce90e34e91 [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
Jean Delvare125ff802008-02-23 10:57:53 +01005through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
6completely chip-independent. It assumes that all the kernel drivers
7implement the standard sysfs interface described in this document.
8This makes adding or updating support for any given chip very easy, as
9libsensors, and applications using it, do not need to be modified.
10This is a major improvement compared to lm-sensors 2.
Linus Torvalds1da177e2005-04-16 15:20:36 -070011
12Note that motherboards vary widely in the connections to sensor chips.
13There is no standard that ensures, for example, that the second
14temperature sensor is connected to the CPU, or that the second fan is on
15the CPU. Also, some values reported by the chips need some computation
16before they make full sense. For example, most chips can only measure
17voltages between 0 and +4V. Other voltages are scaled back into that
18range using external resistors. Since the values of these resistors
19can change from motherboard to motherboard, the conversions cannot be
20hard coded into the driver and have to be done in user space.
21
Jean Delvare740e06a2006-06-05 20:31:20 +020022For this reason, even if we aim at a chip-independent libsensors, it will
Linus Torvalds1da177e2005-04-16 15:20:36 -070023still require a configuration file (e.g. /etc/sensors.conf) for proper
24values conversion, labeling of inputs and hiding of unused inputs.
25
26An alternative method that some programs use is to access the sysfs
27files directly. This document briefly describes the standards that the
28drivers follow, so that an application program can scan for entries and
29access this data in a simple and consistent way. That said, such programs
30will have to implement conversion, labeling and hiding of inputs. For
31this reason, it is still not recommended to bypass the library.
32
Linus Torvalds1da177e2005-04-16 15:20:36 -070033Each chip gets its own directory in the sysfs /sys/devices tree. To
Jean Delvare740e06a2006-06-05 20:31:20 +020034find all sensor chips, it is easier to follow the device symlinks from
35/sys/class/hwmon/hwmon*.
Linus Torvalds1da177e2005-04-16 15:20:36 -070036
Jean Delvare125ff802008-02-23 10:57:53 +010037Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
38in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
39in the hwmon "class" device directory are also supported. Complex drivers
40(e.g. drivers for multifunction chips) may want to use this possibility to
41avoid namespace pollution. The only drawback will be that older versions of
42libsensors won't support the driver in question.
43
Jean Delvare740e06a2006-06-05 20:31:20 +020044All sysfs values are fixed point numbers.
Linus Torvalds1da177e2005-04-16 15:20:36 -070045
46There is only one value per file, unlike the older /proc specification.
47The common scheme for files naming is: <type><number>_<item>. Usual
48types for sensor chips are "in" (voltage), "temp" (temperature) and
49"fan" (fan). Usual items are "input" (measured value), "max" (high
50threshold, "min" (low threshold). Numbering usually starts from 1,
51except for voltages which start from 0 (because most data sheets use
52this). A number is always used for elements that can be present more
53than once, even if there is a single element of the given type on the
54specific chip. Other files do not refer to a specific element, so
55they have a simple name, and no number.
56
57Alarms are direct indications read from the chips. The drivers do NOT
58make comparisons of readings to thresholds. This allows violations
59between readings to be caught and alarmed. The exact definition of an
60alarm (for example, whether a threshold must be met or must be exceeded
61to cause an alarm) is chip-dependent.
62
Hans de Goede2ed42632007-09-21 17:03:32 +020063When setting values of hwmon sysfs attributes, the string representation of
64the desired value must be written, note that strings which are not a number
65are 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -070067
68-------------------------------------------------------------------------
69
Rudolf Marek057bc352006-06-04 20:03:39 +020070[0-*] denotes any positive number starting from 0
71[1-*] denotes any positive number starting from 1
72RO read only value
Andre Prendelcd4e96c2009-06-15 18:39:49 +020073WO write only value
Rudolf Marek057bc352006-06-04 20:03:39 +020074RW read/write value
75
76Read/write values may be read-only for some chips, depending on the
77hardware implementation.
78
Jean Delvare176544d2007-08-20 16:44:44 +020079All entries (except name) are optional, and should only be created in a
80given driver if the chip has the feature.
81
82
Ira W. Snyderd2b847d2010-05-27 19:58:45 +020083*********************
84* Global attributes *
85*********************
Jean Delvare176544d2007-08-20 16:44:44 +020086
87name 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
Guenter Roecka51b9942010-09-17 17:24:14 +020094update_interval The interval at which the chip will update readings.
Ira W. Snyderd2b847d2010-05-27 19:58:45 +020095 Unit: millisecond
96 RW
Guenter Roecka51b9942010-09-17 17:24:14 +020097 Some devices have a variable update rate or interval.
98 This attribute can be used to change it to the desired value.
Ira W. Snyderd2b847d2010-05-27 19:58:45 +020099
Jean Delvare740e06a2006-06-05 20:31:20 +0200100
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101************
102* Voltages *
103************
104
Rudolf Marek057bc352006-06-04 20:03:39 +0200105in[0-*]_min Voltage min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700106 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200107 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700108
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200109in[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
Rudolf Marek057bc352006-06-04 20:03:39 +0200116in[0-*]_max Voltage max value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700117 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200118 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700119
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200120in[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
Rudolf Marek057bc352006-06-04 20:03:39 +0200127in[0-*]_input Voltage input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700128 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200129 RO
130 Voltage measured on the chip pin.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700131 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)
Rudolf Marek057bc352006-06-04 20:03:39 +0200137 do scale, because of internal resistors built into a chip.
Jean Delvare176544d2007-08-20 16:44:44 +0200138 These drivers will output the actual voltage. Rule of
139 thumb: drivers should report the voltage values at the
140 "pins" of the chip.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141
Jean Delvare176544d2007-08-20 16:44:44 +0200142in[0-*]_label Suggested voltage channel label.
143 Text string
144 Should only be created if the driver has hints about what
145 this voltage channel is being used for, and user-space
146 doesn't. In all other cases, the label is provided by
147 user-space.
148 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149
Rudolf Marek057bc352006-06-04 20:03:39 +0200150cpu[0-*]_vid CPU core reference voltage.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700151 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200152 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700153 Not always correct.
154
155vrm Voltage Regulator Module version number.
Rudolf Marek057bc352006-06-04 20:03:39 +0200156 RW (but changing it should no more be necessary)
157 Originally the VRM standard version multiplied by 10, but now
158 an arbitrary number, as not all standards have a version
159 number.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700160 Affects the way the driver calculates the CPU core reference
161 voltage from the vid pins.
162
Rudolf Marek057bc352006-06-04 20:03:39 +0200163Also see the Alarms section for status flags associated with voltages.
164
Linus Torvalds1da177e2005-04-16 15:20:36 -0700165
166********
167* Fans *
168********
169
Rudolf Marek057bc352006-06-04 20:03:39 +0200170fan[1-*]_min Fan minimum value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700171 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200172 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700173
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200174fan[1-*]_max Fan maximum value
175 Unit: revolution/min (RPM)
176 Only rarely supported by the hardware.
177 RW
178
Rudolf Marek057bc352006-06-04 20:03:39 +0200179fan[1-*]_input Fan input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700180 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200181 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700182
Rudolf Marek057bc352006-06-04 20:03:39 +0200183fan[1-*]_div Fan divisor.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700184 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
Rudolf Marek057bc352006-06-04 20:03:39 +0200185 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700186 Some chips only support values 1, 2, 4 and 8.
187 Note that this is actually an internal clock divisor, which
188 affects the measurable speed range, not the read value.
189
Jean Delvare2dbc5142007-05-08 17:22:00 +0200190fan[1-*]_target
191 Desired fan speed
192 Unit: revolution/min (RPM)
193 RW
194 Only makes sense if the chip supports closed-loop fan speed
195 control based on the measured fan speed.
196
Jean Delvare176544d2007-08-20 16:44:44 +0200197fan[1-*]_label Suggested fan channel label.
198 Text string
199 Should only be created if the driver has hints about what
200 this fan channel is being used for, and user-space doesn't.
201 In all other cases, the label is provided by user-space.
202 RO
203
Rudolf Marek057bc352006-06-04 20:03:39 +0200204Also see the Alarms section for status flags associated with fans.
205
206
Linus Torvalds1da177e2005-04-16 15:20:36 -0700207*******
208* PWM *
209*******
210
Rudolf Marek057bc352006-06-04 20:03:39 +0200211pwm[1-*] Pulse width modulation fan control.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700212 Integer value in the range 0 to 255
Rudolf Marek057bc352006-06-04 20:03:39 +0200213 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700214 255 is max or 100%.
215
Rudolf Marek057bc352006-06-04 20:03:39 +0200216pwm[1-*]_enable
Jean Delvare875f25d2007-06-27 21:26:08 +0200217 Fan speed control method:
218 0: no fan speed control (i.e. fan at full speed)
219 1: manual fan speed control enabled (using pwm[1-*])
220 2+: automatic fan speed control enabled
Jean Delvaref8d0c192007-02-14 21:15:02 +0100221 Check individual chip documentation files for automatic mode
222 details.
Rudolf Marek057bc352006-06-04 20:03:39 +0200223 RW
224
Jean Delvaref8d0c192007-02-14 21:15:02 +0100225pwm[1-*]_mode 0: DC mode (direct current)
226 1: PWM mode (pulse-width modulation)
227 RW
228
229pwm[1-*]_freq Base PWM frequency in Hz.
230 Only possibly available when pwmN_mode is PWM, but not always
231 present even then.
Rudolf Marek057bc352006-06-04 20:03:39 +0200232 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700233
234pwm[1-*]_auto_channels_temp
235 Select which temperature channels affect this PWM output in
236 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
237 Which values are possible depend on the chip used.
Rudolf Marek057bc352006-06-04 20:03:39 +0200238 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700239
240pwm[1-*]_auto_point[1-*]_pwm
241pwm[1-*]_auto_point[1-*]_temp
242pwm[1-*]_auto_point[1-*]_temp_hyst
243 Define the PWM vs temperature curve. Number of trip points is
244 chip-dependent. Use this for chips which associate trip points
245 to PWM output channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200246 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700247
Linus Torvalds1da177e2005-04-16 15:20:36 -0700248temp[1-*]_auto_point[1-*]_pwm
249temp[1-*]_auto_point[1-*]_temp
250temp[1-*]_auto_point[1-*]_temp_hyst
251 Define the PWM vs temperature curve. Number of trip points is
252 chip-dependent. Use this for chips which associate trip points
253 to temperature channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200254 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700255
Jean Delvaref7290e22009-12-09 20:35:47 +0100256There is a third case where trip points are associated to both PWM output
257channels and temperature channels: the PWM values are associated to PWM
258output channels while the temperature values are associated to temperature
259channels. In that case, the result is determined by the mapping between
260temperature inputs and PWM outputs. When several temperature inputs are
261mapped to a given PWM output, this leads to several candidate PWM values.
262The actual result is up to the chip, but in general the highest candidate
263value (fastest fan speed) wins.
264
Linus Torvalds1da177e2005-04-16 15:20:36 -0700265
266****************
267* Temperatures *
268****************
269
Rudolf Marek057bc352006-06-04 20:03:39 +0200270temp[1-*]_type Sensor type selection.
Jean Delvareb26f9332007-08-16 14:30:01 +0200271 Integers 1 to 6
Rudolf Marek057bc352006-06-04 20:03:39 +0200272 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273 1: PII/Celeron Diode
274 2: 3904 transistor
275 3: thermal diode
Jean Delvareb26f9332007-08-16 14:30:01 +0200276 4: thermistor
Rudolf Marek61db0112006-12-12 18:18:30 +0100277 5: AMD AMDSI
278 6: Intel PECI
Linus Torvalds1da177e2005-04-16 15:20:36 -0700279 Not all types are supported by all chips
280
Rudolf Marek057bc352006-06-04 20:03:39 +0200281temp[1-*]_max Temperature max value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200282 Unit: millidegree Celsius (or millivolt, see below)
Rudolf Marek057bc352006-06-04 20:03:39 +0200283 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700284
Rudolf Marek057bc352006-06-04 20:03:39 +0200285temp[1-*]_min Temperature min value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200286 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200287 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700288
Rudolf Marek057bc352006-06-04 20:03:39 +0200289temp[1-*]_max_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700290 Temperature hysteresis value for max limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200291 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700292 Must be reported as an absolute temperature, NOT a delta
293 from the max value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200294 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700295
Rudolf Marek057bc352006-06-04 20:03:39 +0200296temp[1-*]_input Temperature input value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200297 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200298 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700299
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200300temp[1-*]_crit Temperature critical max value, typically greater than
Linus Torvalds1da177e2005-04-16 15:20:36 -0700301 corresponding temp_max values.
Jean Delvare740e06a2006-06-05 20:31:20 +0200302 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200303 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700304
Rudolf Marek057bc352006-06-04 20:03:39 +0200305temp[1-*]_crit_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700306 Temperature hysteresis value for critical limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200307 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700308 Must be reported as an absolute temperature, NOT a delta
309 from the critical value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200310 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700311
Guenter Roeck28e7438f2010-10-28 20:31:42 +0200312temp[1-*]_emergency
313 Temperature emergency max value, for chips supporting more than
314 two upper temperature limits. Must be equal or greater than
315 corresponding temp_crit values.
316 Unit: millidegree Celsius
317 RW
318
319temp[1-*]_emergency_hyst
320 Temperature hysteresis value for emergency limit.
321 Unit: millidegree Celsius
322 Must be reported as an absolute temperature, NOT a delta
323 from the emergency value.
324 RW
325
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200326temp[1-*]_lcrit Temperature critical min value, typically lower than
327 corresponding temp_min values.
328 Unit: millidegree Celsius
329 RW
330
Jean Delvare176544d2007-08-20 16:44:44 +0200331temp[1-*]_offset
Hartmut Rick59ac8362006-03-23 16:37:23 +0100332 Temperature offset which is added to the temperature reading
333 by the chip.
334 Unit: millidegree Celsius
335 Read/Write value.
336
Jean Delvare176544d2007-08-20 16:44:44 +0200337temp[1-*]_label Suggested temperature channel label.
338 Text string
339 Should only be created if the driver has hints about what
340 this temperature channel is being used for, and user-space
341 doesn't. In all other cases, the label is provided by
342 user-space.
343 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700344
Andre Prendelcd4e96c2009-06-15 18:39:49 +0200345temp[1-*]_lowest
346 Historical minimum temperature
347 Unit: millidegree Celsius
348 RO
349
350temp[1-*]_highest
351 Historical maximum temperature
352 Unit: millidegree Celsius
353 RO
354
355temp[1-*]_reset_history
356 Reset temp_lowest and temp_highest
357 WO
358
359temp_reset_history
360 Reset temp_lowest and temp_highest for all sensors
361 WO
362
Jean Delvare740e06a2006-06-05 20:31:20 +0200363Some chips measure temperature using external thermistors and an ADC, and
364report the temperature measurement as a voltage. Converting this voltage
365back to a temperature (or the other way around for limits) requires
366mathematical functions not available in the kernel, so the conversion
367must occur in user space. For these chips, all temp* files described
368above should contain values expressed in millivolt instead of millidegree
369Celsius. In other words, such temperature channels are handled as voltage
370channels by the driver.
371
Rudolf Marek057bc352006-06-04 20:03:39 +0200372Also see the Alarms section for status flags associated with temperatures.
373
Linus Torvalds1da177e2005-04-16 15:20:36 -0700374
375************
376* Currents *
377************
378
Rudolf Marek057bc352006-06-04 20:03:39 +0200379curr[1-*]_max Current max value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700380 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200381 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700382
Rudolf Marek057bc352006-06-04 20:03:39 +0200383curr[1-*]_min Current min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700384 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200385 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700386
Guenter Roeck581693b2010-06-28 13:22:27 -0700387curr[1-*]_lcrit Current critical low value
388 Unit: milliampere
389 RW
390
391curr[1-*]_crit Current critical high value.
392 Unit: milliampere
393 RW
394
Rudolf Marek057bc352006-06-04 20:03:39 +0200395curr[1-*]_input Current input value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700396 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200397 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700398
Guenter Roeck581693b2010-06-28 13:22:27 -0700399Also see the Alarms section for status flags associated with currents.
400
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700401*********
402* Power *
403*********
404
405power[1-*]_average Average power use
406 Unit: microWatt
407 RO
408
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700409power[1-*]_average_interval Power use averaging interval. A poll
410 notification is sent to this file if the
411 hardware changes the averaging interval.
Darrick J. Wongddedc652008-10-09 15:33:58 +0200412 Unit: milliseconds
413 RW
414
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700415power[1-*]_average_interval_max Maximum power use averaging interval
416 Unit: milliseconds
417 RO
418
419power[1-*]_average_interval_min Minimum power use averaging interval
420 Unit: milliseconds
421 RO
422
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700423power[1-*]_average_highest Historical average maximum power use
424 Unit: microWatt
425 RO
426
427power[1-*]_average_lowest Historical average minimum power use
428 Unit: microWatt
429 RO
430
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700431power[1-*]_average_max A poll notification is sent to
432 power[1-*]_average when power use
433 rises above this value.
434 Unit: microWatt
435 RW
436
437power[1-*]_average_min A poll notification is sent to
438 power[1-*]_average when power use
439 sinks below this value.
440 Unit: microWatt
441 RW
442
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700443power[1-*]_input Instantaneous power use
444 Unit: microWatt
445 RO
446
447power[1-*]_input_highest Historical maximum power use
448 Unit: microWatt
449 RO
450
451power[1-*]_input_lowest Historical minimum power use
452 Unit: microWatt
453 RO
454
455power[1-*]_reset_history Reset input_highest, input_lowest,
456 average_highest and average_lowest.
457 WO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700458
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700459power[1-*]_accuracy Accuracy of the power meter.
460 Unit: Percent
461 RO
462
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700463power[1-*]_cap If power use rises above this limit, the
464 system should take action to reduce power use.
465 A poll notification is sent to this file if the
466 cap is changed by the hardware. The *_cap
467 files only appear if the cap is known to be
468 enforced by hardware.
469 Unit: microWatt
470 RW
471
472power[1-*]_cap_hyst Margin of hysteresis built around capping and
473 notification.
474 Unit: microWatt
475 RW
476
477power[1-*]_cap_max Maximum cap that can be set.
478 Unit: microWatt
479 RO
480
481power[1-*]_cap_min Minimum cap that can be set.
482 Unit: microWatt
483 RO
484
Guenter Roeck581693b2010-06-28 13:22:27 -0700485power[1-*]_max Maximum power.
486 Unit: microWatt
487 RW
488
489power[1-*]_crit Critical maximum power.
490 If power rises to or above this limit, the
491 system is expected take drastic action to reduce
492 power consumption, such as a system shutdown or
493 a forced powerdown of some devices.
494 Unit: microWatt
495 RW
496
497Also see the Alarms section for status flags associated with power readings.
498
Jean Delvare400b48e2006-03-23 16:46:47 +0100499**********
Darrick J. Wongddedc652008-10-09 15:33:58 +0200500* Energy *
501**********
502
503energy[1-*]_input Cumulative energy use
504 Unit: microJoule
505 RO
506
Jean Delvareec199202009-03-30 21:46:44 +0200507
Guenter Roeckc6c2c162011-01-06 07:52:03 -0800508************
509* Humidity *
510************
511
512humidity[1-*]_input Humidity
513 Unit: milli-percent (per cent mille, pcm)
514 RO
515
516
Darrick J. Wongddedc652008-10-09 15:33:58 +0200517**********
Jean Delvare400b48e2006-03-23 16:46:47 +0100518* Alarms *
519**********
520
521Each channel or limit may have an associated alarm file, containing a
522boolean value. 1 means than an alarm condition exists, 0 means no alarm.
523
524Usually a given chip will either use channel-related alarms, or
525limit-related alarms, not both. The driver should just reflect the hardware
526implementation.
527
Rudolf Marek057bc352006-06-04 20:03:39 +0200528in[0-*]_alarm
Guenter Roecke04a7152010-08-14 21:08:53 +0200529curr[1-*]_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700530power[1-*]_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200531fan[1-*]_alarm
532temp[1-*]_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100533 Channel alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200534 0: no alarm
535 1: alarm
536 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100537
538OR
539
Rudolf Marek057bc352006-06-04 20:03:39 +0200540in[0-*]_min_alarm
541in[0-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700542in[0-*]_lcrit_alarm
543in[0-*]_crit_alarm
Guenter Roecke04a7152010-08-14 21:08:53 +0200544curr[1-*]_min_alarm
545curr[1-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700546curr[1-*]_lcrit_alarm
547curr[1-*]_crit_alarm
548power[1-*]_cap_alarm
549power[1-*]_max_alarm
550power[1-*]_crit_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200551fan[1-*]_min_alarm
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200552fan[1-*]_max_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200553temp[1-*]_min_alarm
554temp[1-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700555temp[1-*]_lcrit_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200556temp[1-*]_crit_alarm
Guenter Roeck28e7438f2010-10-28 20:31:42 +0200557temp[1-*]_emergency_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100558 Limit alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200559 0: no alarm
560 1: alarm
561 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100562
563Each input channel may have an associated fault file. This can be used
564to notify open diodes, unconnected fans etc. where the hardware
565supports it. When this boolean has value 1, the measurement for that
566channel should not be trusted.
567
Jean Delvare7817a392007-06-09 10:11:16 -0400568fan[1-*]_fault
569temp[1-*]_fault
Jean Delvare400b48e2006-03-23 16:46:47 +0100570 Input fault condition
Rudolf Marek057bc352006-06-04 20:03:39 +0200571 0: no fault occured
572 1: fault condition
573 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100574
575Some chips also offer the possibility to get beeped when an alarm occurs:
576
577beep_enable Master beep enable
Rudolf Marek057bc352006-06-04 20:03:39 +0200578 0: no beeps
579 1: beeps
580 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100581
Rudolf Marek057bc352006-06-04 20:03:39 +0200582in[0-*]_beep
Guenter Roecke04a7152010-08-14 21:08:53 +0200583curr[1-*]_beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200584fan[1-*]_beep
585temp[1-*]_beep
Jean Delvare400b48e2006-03-23 16:46:47 +0100586 Channel beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200587 0: disable
588 1: enable
589 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100590
591In theory, a chip could provide per-limit beep masking, but no such chip
592was seen so far.
593
594Old drivers provided a different, non-standard interface to alarms and
595beeps. These interface files are deprecated, but will be kept around
596for compatibility reasons:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700597
598alarms Alarm bitmask.
Rudolf Marek057bc352006-06-04 20:03:39 +0200599 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700600 Integer representation of one to four bytes.
601 A '1' bit means an alarm.
602 Chips should be programmed for 'comparator' mode so that
603 the alarm will 'come back' after you read the register
604 if it is still valid.
605 Generally a direct representation of a chip's internal
606 alarm registers; there is no standard for the position
Jean Delvare400b48e2006-03-23 16:46:47 +0100607 of individual bits. For this reason, the use of this
608 interface file for new drivers is discouraged. Use
609 individual *_alarm and *_fault files instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700610 Bits are defined in kernel/include/sensors.h.
611
Linus Torvalds1da177e2005-04-16 15:20:36 -0700612beep_mask Bitmask for beep.
Jean Delvare400b48e2006-03-23 16:46:47 +0100613 Same format as 'alarms' with the same bit locations,
614 use discouraged for the same reason. Use individual
615 *_beep files instead.
Rudolf Marek057bc352006-06-04 20:03:39 +0200616 RW
Hans de Goede2ed42632007-09-21 17:03:32 +0200617
618
Jean Delvareec199202009-03-30 21:46:44 +0200619***********************
620* Intrusion detection *
621***********************
622
623intrusion[0-*]_alarm
624 Chassis intrusion detection
625 0: OK
626 1: intrusion detected
627 RW
628 Contrary to regular alarm flags which clear themselves
629 automatically when read, this one sticks until cleared by
630 the user. This is done by writing 0 to the file. Writing
631 other values is unsupported.
632
633intrusion[0-*]_beep
634 Chassis intrusion beep
635 0: disable
636 1: enable
637 RW
638
639
Hans de Goede2ed42632007-09-21 17:03:32 +0200640sysfs attribute writes interpretation
641-------------------------------------
642
643hwmon sysfs attributes always contain numbers, so the first thing to do is to
644convert the input to a number, there are 2 ways todo this depending whether
645the number can be negative or not:
646unsigned long u = simple_strtoul(buf, NULL, 10);
647long s = simple_strtol(buf, NULL, 10);
648
649With buf being the buffer with the user input being passed by the kernel.
650Notice that we do not use the second argument of strto[u]l, and thus cannot
651tell when 0 is returned, if this was really 0 or is caused by invalid input.
652This is done deliberately as checking this everywhere would add a lot of
653code to the kernel.
654
655Notice that it is important to always store the converted value in an
656unsigned long or long, so that no wrap around can happen before any further
657checking.
658
659After the input string is converted to an (unsigned) long, the value should be
660checked if its acceptable. Be careful with further conversions on the value
661before checking it for validity, as these conversions could still cause a wrap
662around before the check. For example do not multiply the result, and only
663add/subtract if it has been divided before the add/subtract.
664
665What to do if a value is found to be invalid, depends on the type of the
666sysfs attribute that is being set. If it is a continuous setting like a
667tempX_max or inX_max attribute, then the value should be clamped to its
668limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
669continuous like for example a tempX_type, then when an invalid value is
670written, -EINVAL should be returned.
671
672Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
Jean Delvare5fbea512007-10-07 22:44:33 +0200673
674 long v = simple_strtol(buf, NULL, 10) / 1000;
675 v = SENSORS_LIMIT(v, -128, 127);
676 /* write v to register */
Hans de Goede2ed42632007-09-21 17:03:32 +0200677
678Example2, fan divider setting, valid values 2, 4 and 8:
Hans de Goede2ed42632007-09-21 17:03:32 +0200679
Jean Delvare5fbea512007-10-07 22:44:33 +0200680 unsigned long v = simple_strtoul(buf, NULL, 10);
681
682 switch (v) {
683 case 2: v = 1; break;
684 case 4: v = 2; break;
685 case 8: v = 3; break;
686 default:
687 return -EINVAL;
688 }
689 /* write v to register */