blob: a4aa8f600e09643beb6a2b505c9c08d00f28166a [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
Guenter Roeck0084e9f2011-07-09 10:32:11 -0700142in[0-*]_average
143 Average voltage
144 Unit: millivolt
145 RO
146
147in[0-*]_lowest
148 Historical minimum voltage
149 Unit: millivolt
150 RO
151
152in[0-*]_highest
153 Historical maximum voltage
154 Unit: millivolt
155 RO
156
157in[0-*]_reset_history
158 Reset inX_lowest and inX_highest
159 WO
160
161in_reset_history
162 Reset inX_lowest and inX_highest for all sensors
163 WO
164
Jean Delvare176544d2007-08-20 16:44:44 +0200165in[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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172
Rudolf Marek057bc352006-06-04 20:03:39 +0200173cpu[0-*]_vid CPU core reference voltage.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700174 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200175 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700176 Not always correct.
177
178vrm Voltage Regulator Module version number.
Rudolf Marek057bc352006-06-04 20:03:39 +0200179 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700183 Affects the way the driver calculates the CPU core reference
184 voltage from the vid pins.
185
Rudolf Marek057bc352006-06-04 20:03:39 +0200186Also see the Alarms section for status flags associated with voltages.
187
Linus Torvalds1da177e2005-04-16 15:20:36 -0700188
189********
190* Fans *
191********
192
Rudolf Marek057bc352006-06-04 20:03:39 +0200193fan[1-*]_min Fan minimum value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700194 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200195 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700196
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200197fan[1-*]_max Fan maximum value
198 Unit: revolution/min (RPM)
199 Only rarely supported by the hardware.
200 RW
201
Rudolf Marek057bc352006-06-04 20:03:39 +0200202fan[1-*]_input Fan input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700203 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200204 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700205
Rudolf Marek057bc352006-06-04 20:03:39 +0200206fan[1-*]_div Fan divisor.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700207 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
Rudolf Marek057bc352006-06-04 20:03:39 +0200208 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700209 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
Guenter Roeck2d2e1482011-03-02 15:19:35 -0800213fan[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
Jean Delvare2dbc5142007-05-08 17:22:00 +0200224fan[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
Jean Delvare176544d2007-08-20 16:44:44 +0200231fan[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
Rudolf Marek057bc352006-06-04 20:03:39 +0200238Also see the Alarms section for status flags associated with fans.
239
240
Linus Torvalds1da177e2005-04-16 15:20:36 -0700241*******
242* PWM *
243*******
244
Rudolf Marek057bc352006-06-04 20:03:39 +0200245pwm[1-*] Pulse width modulation fan control.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700246 Integer value in the range 0 to 255
Rudolf Marek057bc352006-06-04 20:03:39 +0200247 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700248 255 is max or 100%.
249
Rudolf Marek057bc352006-06-04 20:03:39 +0200250pwm[1-*]_enable
Jean Delvare875f25d2007-06-27 21:26:08 +0200251 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
Jean Delvaref8d0c192007-02-14 21:15:02 +0100255 Check individual chip documentation files for automatic mode
256 details.
Rudolf Marek057bc352006-06-04 20:03:39 +0200257 RW
258
Jean Delvaref8d0c192007-02-14 21:15:02 +0100259pwm[1-*]_mode 0: DC mode (direct current)
260 1: PWM mode (pulse-width modulation)
261 RW
262
263pwm[1-*]_freq Base PWM frequency in Hz.
264 Only possibly available when pwmN_mode is PWM, but not always
265 present even then.
Rudolf Marek057bc352006-06-04 20:03:39 +0200266 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700267
268pwm[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.
Rudolf Marek057bc352006-06-04 20:03:39 +0200272 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273
274pwm[1-*]_auto_point[1-*]_pwm
275pwm[1-*]_auto_point[1-*]_temp
276pwm[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.
Rudolf Marek057bc352006-06-04 20:03:39 +0200280 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700281
Linus Torvalds1da177e2005-04-16 15:20:36 -0700282temp[1-*]_auto_point[1-*]_pwm
283temp[1-*]_auto_point[1-*]_temp
284temp[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.
Rudolf Marek057bc352006-06-04 20:03:39 +0200288 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700289
Jean Delvaref7290e22009-12-09 20:35:47 +0100290There is a third case where trip points are associated to both PWM output
291channels and temperature channels: the PWM values are associated to PWM
292output channels while the temperature values are associated to temperature
293channels. In that case, the result is determined by the mapping between
294temperature inputs and PWM outputs. When several temperature inputs are
295mapped to a given PWM output, this leads to several candidate PWM values.
296The actual result is up to the chip, but in general the highest candidate
297value (fastest fan speed) wins.
298
Linus Torvalds1da177e2005-04-16 15:20:36 -0700299
300****************
301* Temperatures *
302****************
303
Rudolf Marek057bc352006-06-04 20:03:39 +0200304temp[1-*]_type Sensor type selection.
Jean Delvareb26f9332007-08-16 14:30:01 +0200305 Integers 1 to 6
Rudolf Marek057bc352006-06-04 20:03:39 +0200306 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700307 1: PII/Celeron Diode
308 2: 3904 transistor
309 3: thermal diode
Jean Delvareb26f9332007-08-16 14:30:01 +0200310 4: thermistor
Rudolf Marek61db0112006-12-12 18:18:30 +0100311 5: AMD AMDSI
312 6: Intel PECI
Linus Torvalds1da177e2005-04-16 15:20:36 -0700313 Not all types are supported by all chips
314
Rudolf Marek057bc352006-06-04 20:03:39 +0200315temp[1-*]_max Temperature max value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200316 Unit: millidegree Celsius (or millivolt, see below)
Rudolf Marek057bc352006-06-04 20:03:39 +0200317 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700318
Rudolf Marek057bc352006-06-04 20:03:39 +0200319temp[1-*]_min Temperature min value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200320 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200321 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700322
Rudolf Marek057bc352006-06-04 20:03:39 +0200323temp[1-*]_max_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700324 Temperature hysteresis value for max limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200325 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700326 Must be reported as an absolute temperature, NOT a delta
327 from the max value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200328 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700329
Rudolf Marek057bc352006-06-04 20:03:39 +0200330temp[1-*]_input Temperature input value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200331 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200332 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700333
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200334temp[1-*]_crit Temperature critical max value, typically greater than
Linus Torvalds1da177e2005-04-16 15:20:36 -0700335 corresponding temp_max values.
Jean Delvare740e06a2006-06-05 20:31:20 +0200336 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200337 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700338
Rudolf Marek057bc352006-06-04 20:03:39 +0200339temp[1-*]_crit_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700340 Temperature hysteresis value for critical limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200341 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700342 Must be reported as an absolute temperature, NOT a delta
343 from the critical value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200344 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700345
Guenter Roeck28e74382010-10-28 20:31:42 +0200346temp[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
353temp[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
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200360temp[1-*]_lcrit Temperature critical min value, typically lower than
361 corresponding temp_min values.
362 Unit: millidegree Celsius
363 RW
364
Jean Delvare176544d2007-08-20 16:44:44 +0200365temp[1-*]_offset
Hartmut Rick59ac8362006-03-23 16:37:23 +0100366 Temperature offset which is added to the temperature reading
367 by the chip.
368 Unit: millidegree Celsius
369 Read/Write value.
370
Jean Delvare176544d2007-08-20 16:44:44 +0200371temp[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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700378
Andre Prendelcd4e96c2009-06-15 18:39:49 +0200379temp[1-*]_lowest
380 Historical minimum temperature
381 Unit: millidegree Celsius
382 RO
383
384temp[1-*]_highest
385 Historical maximum temperature
386 Unit: millidegree Celsius
387 RO
388
389temp[1-*]_reset_history
390 Reset temp_lowest and temp_highest
391 WO
392
393temp_reset_history
394 Reset temp_lowest and temp_highest for all sensors
395 WO
396
Jean Delvare740e06a2006-06-05 20:31:20 +0200397Some chips measure temperature using external thermistors and an ADC, and
398report the temperature measurement as a voltage. Converting this voltage
399back to a temperature (or the other way around for limits) requires
400mathematical functions not available in the kernel, so the conversion
401must occur in user space. For these chips, all temp* files described
402above should contain values expressed in millivolt instead of millidegree
403Celsius. In other words, such temperature channels are handled as voltage
404channels by the driver.
405
Rudolf Marek057bc352006-06-04 20:03:39 +0200406Also see the Alarms section for status flags associated with temperatures.
407
Linus Torvalds1da177e2005-04-16 15:20:36 -0700408
409************
410* Currents *
411************
412
Rudolf Marek057bc352006-06-04 20:03:39 +0200413curr[1-*]_max Current max value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700414 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200415 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700416
Rudolf Marek057bc352006-06-04 20:03:39 +0200417curr[1-*]_min Current min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700418 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200419 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700420
Guenter Roeck581693b2010-06-28 13:22:27 -0700421curr[1-*]_lcrit Current critical low value
422 Unit: milliampere
423 RW
424
425curr[1-*]_crit Current critical high value.
426 Unit: milliampere
427 RW
428
Rudolf Marek057bc352006-06-04 20:03:39 +0200429curr[1-*]_input Current input value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700430 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200431 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700432
Guenter Roeck0084e9f2011-07-09 10:32:11 -0700433curr[1-*]_average
434 Average current use
435 Unit: milliampere
436 RO
437
438curr[1-*]_lowest
439 Historical minimum current
440 Unit: milliampere
441 RO
442
443curr[1-*]_highest
444 Historical maximum current
445 Unit: milliampere
446 RO
447
448curr[1-*]_reset_history
449 Reset currX_lowest and currX_highest
450 WO
451
452curr_reset_history
453 Reset currX_lowest and currX_highest for all sensors
454 WO
455
Guenter Roeck581693b2010-06-28 13:22:27 -0700456Also see the Alarms section for status flags associated with currents.
457
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700458*********
459* Power *
460*********
461
462power[1-*]_average Average power use
463 Unit: microWatt
464 RO
465
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700466power[1-*]_average_interval Power use averaging interval. A poll
467 notification is sent to this file if the
468 hardware changes the averaging interval.
Darrick J. Wongddedc652008-10-09 15:33:58 +0200469 Unit: milliseconds
470 RW
471
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700472power[1-*]_average_interval_max Maximum power use averaging interval
473 Unit: milliseconds
474 RO
475
476power[1-*]_average_interval_min Minimum power use averaging interval
477 Unit: milliseconds
478 RO
479
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700480power[1-*]_average_highest Historical average maximum power use
481 Unit: microWatt
482 RO
483
484power[1-*]_average_lowest Historical average minimum power use
485 Unit: microWatt
486 RO
487
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700488power[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
494power[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
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700500power[1-*]_input Instantaneous power use
501 Unit: microWatt
502 RO
503
504power[1-*]_input_highest Historical maximum power use
505 Unit: microWatt
506 RO
507
508power[1-*]_input_lowest Historical minimum power use
509 Unit: microWatt
510 RO
511
512power[1-*]_reset_history Reset input_highest, input_lowest,
513 average_highest and average_lowest.
514 WO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700515
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700516power[1-*]_accuracy Accuracy of the power meter.
517 Unit: Percent
518 RO
519
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700520power[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
529power[1-*]_cap_hyst Margin of hysteresis built around capping and
530 notification.
531 Unit: microWatt
532 RW
533
534power[1-*]_cap_max Maximum cap that can be set.
535 Unit: microWatt
536 RO
537
538power[1-*]_cap_min Minimum cap that can be set.
539 Unit: microWatt
540 RO
541
Guenter Roeck581693b2010-06-28 13:22:27 -0700542power[1-*]_max Maximum power.
543 Unit: microWatt
544 RW
545
546power[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
554Also see the Alarms section for status flags associated with power readings.
555
Jean Delvare400b48e2006-03-23 16:46:47 +0100556**********
Darrick J. Wongddedc652008-10-09 15:33:58 +0200557* Energy *
558**********
559
560energy[1-*]_input Cumulative energy use
561 Unit: microJoule
562 RO
563
Jean Delvareec199202009-03-30 21:46:44 +0200564
Guenter Roeckc6c2c162011-01-06 07:52:03 -0800565************
566* Humidity *
567************
568
569humidity[1-*]_input Humidity
570 Unit: milli-percent (per cent mille, pcm)
571 RO
572
573
Darrick J. Wongddedc652008-10-09 15:33:58 +0200574**********
Jean Delvare400b48e2006-03-23 16:46:47 +0100575* Alarms *
576**********
577
578Each channel or limit may have an associated alarm file, containing a
579boolean value. 1 means than an alarm condition exists, 0 means no alarm.
580
581Usually a given chip will either use channel-related alarms, or
582limit-related alarms, not both. The driver should just reflect the hardware
583implementation.
584
Rudolf Marek057bc352006-06-04 20:03:39 +0200585in[0-*]_alarm
Guenter Roecke04a7152010-08-14 21:08:53 +0200586curr[1-*]_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700587power[1-*]_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200588fan[1-*]_alarm
589temp[1-*]_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100590 Channel alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200591 0: no alarm
592 1: alarm
593 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100594
595OR
596
Rudolf Marek057bc352006-06-04 20:03:39 +0200597in[0-*]_min_alarm
598in[0-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700599in[0-*]_lcrit_alarm
600in[0-*]_crit_alarm
Guenter Roecke04a7152010-08-14 21:08:53 +0200601curr[1-*]_min_alarm
602curr[1-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700603curr[1-*]_lcrit_alarm
604curr[1-*]_crit_alarm
605power[1-*]_cap_alarm
606power[1-*]_max_alarm
607power[1-*]_crit_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200608fan[1-*]_min_alarm
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200609fan[1-*]_max_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200610temp[1-*]_min_alarm
611temp[1-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700612temp[1-*]_lcrit_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200613temp[1-*]_crit_alarm
Guenter Roeck28e74382010-10-28 20:31:42 +0200614temp[1-*]_emergency_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100615 Limit alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200616 0: no alarm
617 1: alarm
618 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100619
620Each input channel may have an associated fault file. This can be used
621to notify open diodes, unconnected fans etc. where the hardware
622supports it. When this boolean has value 1, the measurement for that
623channel should not be trusted.
624
Jean Delvare7817a392007-06-09 10:11:16 -0400625fan[1-*]_fault
626temp[1-*]_fault
Jean Delvare400b48e2006-03-23 16:46:47 +0100627 Input fault condition
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300628 0: no fault occurred
Rudolf Marek057bc352006-06-04 20:03:39 +0200629 1: fault condition
630 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100631
632Some chips also offer the possibility to get beeped when an alarm occurs:
633
634beep_enable Master beep enable
Rudolf Marek057bc352006-06-04 20:03:39 +0200635 0: no beeps
636 1: beeps
637 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100638
Rudolf Marek057bc352006-06-04 20:03:39 +0200639in[0-*]_beep
Guenter Roecke04a7152010-08-14 21:08:53 +0200640curr[1-*]_beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200641fan[1-*]_beep
642temp[1-*]_beep
Jean Delvare400b48e2006-03-23 16:46:47 +0100643 Channel beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200644 0: disable
645 1: enable
646 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100647
648In theory, a chip could provide per-limit beep masking, but no such chip
649was seen so far.
650
651Old drivers provided a different, non-standard interface to alarms and
652beeps. These interface files are deprecated, but will be kept around
653for compatibility reasons:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700654
655alarms Alarm bitmask.
Rudolf Marek057bc352006-06-04 20:03:39 +0200656 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700657 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
Jean Delvare400b48e2006-03-23 16:46:47 +0100664 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700667 Bits are defined in kernel/include/sensors.h.
668
Linus Torvalds1da177e2005-04-16 15:20:36 -0700669beep_mask Bitmask for beep.
Jean Delvare400b48e2006-03-23 16:46:47 +0100670 Same format as 'alarms' with the same bit locations,
671 use discouraged for the same reason. Use individual
672 *_beep files instead.
Rudolf Marek057bc352006-06-04 20:03:39 +0200673 RW
Hans de Goede2ed42632007-09-21 17:03:32 +0200674
675
Jean Delvareec199202009-03-30 21:46:44 +0200676***********************
677* Intrusion detection *
678***********************
679
680intrusion[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
690intrusion[0-*]_beep
691 Chassis intrusion beep
692 0: disable
693 1: enable
694 RW
695
696
Hans de Goede2ed42632007-09-21 17:03:32 +0200697sysfs attribute writes interpretation
698-------------------------------------
699
700hwmon sysfs attributes always contain numbers, so the first thing to do is to
701convert the input to a number, there are 2 ways todo this depending whether
702the number can be negative or not:
703unsigned long u = simple_strtoul(buf, NULL, 10);
704long s = simple_strtol(buf, NULL, 10);
705
706With buf being the buffer with the user input being passed by the kernel.
707Notice that we do not use the second argument of strto[u]l, and thus cannot
708tell when 0 is returned, if this was really 0 or is caused by invalid input.
709This is done deliberately as checking this everywhere would add a lot of
710code to the kernel.
711
712Notice that it is important to always store the converted value in an
713unsigned long or long, so that no wrap around can happen before any further
714checking.
715
716After the input string is converted to an (unsigned) long, the value should be
717checked if its acceptable. Be careful with further conversions on the value
718before checking it for validity, as these conversions could still cause a wrap
719around before the check. For example do not multiply the result, and only
720add/subtract if it has been divided before the add/subtract.
721
722What to do if a value is found to be invalid, depends on the type of the
723sysfs attribute that is being set. If it is a continuous setting like a
724tempX_max or inX_max attribute, then the value should be clamped to its
725limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
726continuous like for example a tempX_type, then when an invalid value is
727written, -EINVAL should be returned.
728
729Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
Jean Delvare5fbea512007-10-07 22:44:33 +0200730
731 long v = simple_strtol(buf, NULL, 10) / 1000;
732 v = SENSORS_LIMIT(v, -128, 127);
733 /* write v to register */
Hans de Goede2ed42632007-09-21 17:03:32 +0200734
735Example2, fan divider setting, valid values 2, 4 and 8:
Hans de Goede2ed42632007-09-21 17:03:32 +0200736
Jean Delvare5fbea512007-10-07 22:44:33 +0200737 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 */