blob: 8f63c244f1aab95b610c711abdaddc5e4335e7ee [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
Guenter Roeck2d2e1482011-03-02 15:19:35 -0800190fan[1-*]_pulses Number of tachometer pulses per fan revolution.
191 Integer value, typically between 1 and 4.
192 RW
193 This value is a characteristic of the fan connected to the
194 device's input, so it has to be set in accordance with the fan
195 model.
196 Should only be created if the chip has a register to configure
197 the number of pulses. In the absence of such a register (and
198 thus attribute) the value assumed by all devices is 2 pulses
199 per fan revolution.
200
Jean Delvare2dbc5142007-05-08 17:22:00 +0200201fan[1-*]_target
202 Desired fan speed
203 Unit: revolution/min (RPM)
204 RW
205 Only makes sense if the chip supports closed-loop fan speed
206 control based on the measured fan speed.
207
Jean Delvare176544d2007-08-20 16:44:44 +0200208fan[1-*]_label Suggested fan channel label.
209 Text string
210 Should only be created if the driver has hints about what
211 this fan channel is being used for, and user-space doesn't.
212 In all other cases, the label is provided by user-space.
213 RO
214
Rudolf Marek057bc352006-06-04 20:03:39 +0200215Also see the Alarms section for status flags associated with fans.
216
217
Linus Torvalds1da177e2005-04-16 15:20:36 -0700218*******
219* PWM *
220*******
221
Rudolf Marek057bc352006-06-04 20:03:39 +0200222pwm[1-*] Pulse width modulation fan control.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700223 Integer value in the range 0 to 255
Rudolf Marek057bc352006-06-04 20:03:39 +0200224 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700225 255 is max or 100%.
226
Rudolf Marek057bc352006-06-04 20:03:39 +0200227pwm[1-*]_enable
Jean Delvare875f25d2007-06-27 21:26:08 +0200228 Fan speed control method:
229 0: no fan speed control (i.e. fan at full speed)
230 1: manual fan speed control enabled (using pwm[1-*])
231 2+: automatic fan speed control enabled
Jean Delvaref8d0c192007-02-14 21:15:02 +0100232 Check individual chip documentation files for automatic mode
233 details.
Rudolf Marek057bc352006-06-04 20:03:39 +0200234 RW
235
Jean Delvaref8d0c192007-02-14 21:15:02 +0100236pwm[1-*]_mode 0: DC mode (direct current)
237 1: PWM mode (pulse-width modulation)
238 RW
239
240pwm[1-*]_freq Base PWM frequency in Hz.
241 Only possibly available when pwmN_mode is PWM, but not always
242 present even then.
Rudolf Marek057bc352006-06-04 20:03:39 +0200243 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700244
245pwm[1-*]_auto_channels_temp
246 Select which temperature channels affect this PWM output in
247 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
248 Which values are possible depend on the chip used.
Rudolf Marek057bc352006-06-04 20:03:39 +0200249 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700250
251pwm[1-*]_auto_point[1-*]_pwm
252pwm[1-*]_auto_point[1-*]_temp
253pwm[1-*]_auto_point[1-*]_temp_hyst
254 Define the PWM vs temperature curve. Number of trip points is
255 chip-dependent. Use this for chips which associate trip points
256 to PWM output channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200257 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700258
Linus Torvalds1da177e2005-04-16 15:20:36 -0700259temp[1-*]_auto_point[1-*]_pwm
260temp[1-*]_auto_point[1-*]_temp
261temp[1-*]_auto_point[1-*]_temp_hyst
262 Define the PWM vs temperature curve. Number of trip points is
263 chip-dependent. Use this for chips which associate trip points
264 to temperature channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200265 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700266
Jean Delvaref7290e22009-12-09 20:35:47 +0100267There is a third case where trip points are associated to both PWM output
268channels and temperature channels: the PWM values are associated to PWM
269output channels while the temperature values are associated to temperature
270channels. In that case, the result is determined by the mapping between
271temperature inputs and PWM outputs. When several temperature inputs are
272mapped to a given PWM output, this leads to several candidate PWM values.
273The actual result is up to the chip, but in general the highest candidate
274value (fastest fan speed) wins.
275
Linus Torvalds1da177e2005-04-16 15:20:36 -0700276
277****************
278* Temperatures *
279****************
280
Rudolf Marek057bc352006-06-04 20:03:39 +0200281temp[1-*]_type Sensor type selection.
Jean Delvareb26f9332007-08-16 14:30:01 +0200282 Integers 1 to 6
Rudolf Marek057bc352006-06-04 20:03:39 +0200283 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700284 1: PII/Celeron Diode
285 2: 3904 transistor
286 3: thermal diode
Jean Delvareb26f9332007-08-16 14:30:01 +0200287 4: thermistor
Rudolf Marek61db0112006-12-12 18:18:30 +0100288 5: AMD AMDSI
289 6: Intel PECI
Linus Torvalds1da177e2005-04-16 15:20:36 -0700290 Not all types are supported by all chips
291
Rudolf Marek057bc352006-06-04 20:03:39 +0200292temp[1-*]_max Temperature max value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200293 Unit: millidegree Celsius (or millivolt, see below)
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-*]_min Temperature min value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200297 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200298 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700299
Rudolf Marek057bc352006-06-04 20:03:39 +0200300temp[1-*]_max_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700301 Temperature hysteresis value for max limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200302 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700303 Must be reported as an absolute temperature, NOT a delta
304 from the max value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200305 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700306
Rudolf Marek057bc352006-06-04 20:03:39 +0200307temp[1-*]_input Temperature input value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200308 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200309 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700310
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200311temp[1-*]_crit Temperature critical max value, typically greater than
Linus Torvalds1da177e2005-04-16 15:20:36 -0700312 corresponding temp_max values.
Jean Delvare740e06a2006-06-05 20:31:20 +0200313 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200314 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700315
Rudolf Marek057bc352006-06-04 20:03:39 +0200316temp[1-*]_crit_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700317 Temperature hysteresis value for critical limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200318 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700319 Must be reported as an absolute temperature, NOT a delta
320 from the critical value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200321 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700322
Guenter Roeck28e7438f2010-10-28 20:31:42 +0200323temp[1-*]_emergency
324 Temperature emergency max value, for chips supporting more than
325 two upper temperature limits. Must be equal or greater than
326 corresponding temp_crit values.
327 Unit: millidegree Celsius
328 RW
329
330temp[1-*]_emergency_hyst
331 Temperature hysteresis value for emergency limit.
332 Unit: millidegree Celsius
333 Must be reported as an absolute temperature, NOT a delta
334 from the emergency value.
335 RW
336
Guenter Roeckf46fc8c2010-08-14 21:08:52 +0200337temp[1-*]_lcrit Temperature critical min value, typically lower than
338 corresponding temp_min values.
339 Unit: millidegree Celsius
340 RW
341
Jean Delvare176544d2007-08-20 16:44:44 +0200342temp[1-*]_offset
Hartmut Rick59ac8362006-03-23 16:37:23 +0100343 Temperature offset which is added to the temperature reading
344 by the chip.
345 Unit: millidegree Celsius
346 Read/Write value.
347
Jean Delvare176544d2007-08-20 16:44:44 +0200348temp[1-*]_label Suggested temperature channel label.
349 Text string
350 Should only be created if the driver has hints about what
351 this temperature channel is being used for, and user-space
352 doesn't. In all other cases, the label is provided by
353 user-space.
354 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700355
Andre Prendelcd4e96c2009-06-15 18:39:49 +0200356temp[1-*]_lowest
357 Historical minimum temperature
358 Unit: millidegree Celsius
359 RO
360
361temp[1-*]_highest
362 Historical maximum temperature
363 Unit: millidegree Celsius
364 RO
365
366temp[1-*]_reset_history
367 Reset temp_lowest and temp_highest
368 WO
369
370temp_reset_history
371 Reset temp_lowest and temp_highest for all sensors
372 WO
373
Jean Delvare740e06a2006-06-05 20:31:20 +0200374Some chips measure temperature using external thermistors and an ADC, and
375report the temperature measurement as a voltage. Converting this voltage
376back to a temperature (or the other way around for limits) requires
377mathematical functions not available in the kernel, so the conversion
378must occur in user space. For these chips, all temp* files described
379above should contain values expressed in millivolt instead of millidegree
380Celsius. In other words, such temperature channels are handled as voltage
381channels by the driver.
382
Rudolf Marek057bc352006-06-04 20:03:39 +0200383Also see the Alarms section for status flags associated with temperatures.
384
Linus Torvalds1da177e2005-04-16 15:20:36 -0700385
386************
387* Currents *
388************
389
Rudolf Marek057bc352006-06-04 20:03:39 +0200390curr[1-*]_max Current max value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700391 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200392 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700393
Rudolf Marek057bc352006-06-04 20:03:39 +0200394curr[1-*]_min Current min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700395 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200396 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700397
Guenter Roeck581693b2010-06-28 13:22:27 -0700398curr[1-*]_lcrit Current critical low value
399 Unit: milliampere
400 RW
401
402curr[1-*]_crit Current critical high value.
403 Unit: milliampere
404 RW
405
Rudolf Marek057bc352006-06-04 20:03:39 +0200406curr[1-*]_input Current input value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700407 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200408 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700409
Guenter Roeck581693b2010-06-28 13:22:27 -0700410Also see the Alarms section for status flags associated with currents.
411
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700412*********
413* Power *
414*********
415
416power[1-*]_average Average power use
417 Unit: microWatt
418 RO
419
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700420power[1-*]_average_interval Power use averaging interval. A poll
421 notification is sent to this file if the
422 hardware changes the averaging interval.
Darrick J. Wongddedc652008-10-09 15:33:58 +0200423 Unit: milliseconds
424 RW
425
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700426power[1-*]_average_interval_max Maximum power use averaging interval
427 Unit: milliseconds
428 RO
429
430power[1-*]_average_interval_min Minimum power use averaging interval
431 Unit: milliseconds
432 RO
433
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700434power[1-*]_average_highest Historical average maximum power use
435 Unit: microWatt
436 RO
437
438power[1-*]_average_lowest Historical average minimum power use
439 Unit: microWatt
440 RO
441
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700442power[1-*]_average_max A poll notification is sent to
443 power[1-*]_average when power use
444 rises above this value.
445 Unit: microWatt
446 RW
447
448power[1-*]_average_min A poll notification is sent to
449 power[1-*]_average when power use
450 sinks below this value.
451 Unit: microWatt
452 RW
453
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700454power[1-*]_input Instantaneous power use
455 Unit: microWatt
456 RO
457
458power[1-*]_input_highest Historical maximum power use
459 Unit: microWatt
460 RO
461
462power[1-*]_input_lowest Historical minimum power use
463 Unit: microWatt
464 RO
465
466power[1-*]_reset_history Reset input_highest, input_lowest,
467 average_highest and average_lowest.
468 WO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700469
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700470power[1-*]_accuracy Accuracy of the power meter.
471 Unit: Percent
472 RO
473
Darrick J. Wong115a57c2009-10-26 16:50:07 -0700474power[1-*]_cap If power use rises above this limit, the
475 system should take action to reduce power use.
476 A poll notification is sent to this file if the
477 cap is changed by the hardware. The *_cap
478 files only appear if the cap is known to be
479 enforced by hardware.
480 Unit: microWatt
481 RW
482
483power[1-*]_cap_hyst Margin of hysteresis built around capping and
484 notification.
485 Unit: microWatt
486 RW
487
488power[1-*]_cap_max Maximum cap that can be set.
489 Unit: microWatt
490 RO
491
492power[1-*]_cap_min Minimum cap that can be set.
493 Unit: microWatt
494 RO
495
Guenter Roeck581693b2010-06-28 13:22:27 -0700496power[1-*]_max Maximum power.
497 Unit: microWatt
498 RW
499
500power[1-*]_crit Critical maximum power.
501 If power rises to or above this limit, the
502 system is expected take drastic action to reduce
503 power consumption, such as a system shutdown or
504 a forced powerdown of some devices.
505 Unit: microWatt
506 RW
507
508Also see the Alarms section for status flags associated with power readings.
509
Jean Delvare400b48e2006-03-23 16:46:47 +0100510**********
Darrick J. Wongddedc652008-10-09 15:33:58 +0200511* Energy *
512**********
513
514energy[1-*]_input Cumulative energy use
515 Unit: microJoule
516 RO
517
Jean Delvareec199202009-03-30 21:46:44 +0200518
Guenter Roeckc6c2c162011-01-06 07:52:03 -0800519************
520* Humidity *
521************
522
523humidity[1-*]_input Humidity
524 Unit: milli-percent (per cent mille, pcm)
525 RO
526
527
Darrick J. Wongddedc652008-10-09 15:33:58 +0200528**********
Jean Delvare400b48e2006-03-23 16:46:47 +0100529* Alarms *
530**********
531
532Each channel or limit may have an associated alarm file, containing a
533boolean value. 1 means than an alarm condition exists, 0 means no alarm.
534
535Usually a given chip will either use channel-related alarms, or
536limit-related alarms, not both. The driver should just reflect the hardware
537implementation.
538
Rudolf Marek057bc352006-06-04 20:03:39 +0200539in[0-*]_alarm
Guenter Roecke04a7152010-08-14 21:08:53 +0200540curr[1-*]_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700541power[1-*]_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200542fan[1-*]_alarm
543temp[1-*]_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100544 Channel alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200545 0: no alarm
546 1: alarm
547 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100548
549OR
550
Rudolf Marek057bc352006-06-04 20:03:39 +0200551in[0-*]_min_alarm
552in[0-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700553in[0-*]_lcrit_alarm
554in[0-*]_crit_alarm
Guenter Roecke04a7152010-08-14 21:08:53 +0200555curr[1-*]_min_alarm
556curr[1-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700557curr[1-*]_lcrit_alarm
558curr[1-*]_crit_alarm
559power[1-*]_cap_alarm
560power[1-*]_max_alarm
561power[1-*]_crit_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200562fan[1-*]_min_alarm
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200563fan[1-*]_max_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200564temp[1-*]_min_alarm
565temp[1-*]_max_alarm
Guenter Roeck581693b2010-06-28 13:22:27 -0700566temp[1-*]_lcrit_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200567temp[1-*]_crit_alarm
Guenter Roeck28e7438f2010-10-28 20:31:42 +0200568temp[1-*]_emergency_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100569 Limit alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200570 0: no alarm
571 1: alarm
572 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100573
574Each input channel may have an associated fault file. This can be used
575to notify open diodes, unconnected fans etc. where the hardware
576supports it. When this boolean has value 1, the measurement for that
577channel should not be trusted.
578
Jean Delvare7817a392007-06-09 10:11:16 -0400579fan[1-*]_fault
580temp[1-*]_fault
Jean Delvare400b48e2006-03-23 16:46:47 +0100581 Input fault condition
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300582 0: no fault occurred
Rudolf Marek057bc352006-06-04 20:03:39 +0200583 1: fault condition
584 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100585
586Some chips also offer the possibility to get beeped when an alarm occurs:
587
588beep_enable Master beep enable
Rudolf Marek057bc352006-06-04 20:03:39 +0200589 0: no beeps
590 1: beeps
591 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100592
Rudolf Marek057bc352006-06-04 20:03:39 +0200593in[0-*]_beep
Guenter Roecke04a7152010-08-14 21:08:53 +0200594curr[1-*]_beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200595fan[1-*]_beep
596temp[1-*]_beep
Jean Delvare400b48e2006-03-23 16:46:47 +0100597 Channel beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200598 0: disable
599 1: enable
600 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100601
602In theory, a chip could provide per-limit beep masking, but no such chip
603was seen so far.
604
605Old drivers provided a different, non-standard interface to alarms and
606beeps. These interface files are deprecated, but will be kept around
607for compatibility reasons:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700608
609alarms Alarm bitmask.
Rudolf Marek057bc352006-06-04 20:03:39 +0200610 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700611 Integer representation of one to four bytes.
612 A '1' bit means an alarm.
613 Chips should be programmed for 'comparator' mode so that
614 the alarm will 'come back' after you read the register
615 if it is still valid.
616 Generally a direct representation of a chip's internal
617 alarm registers; there is no standard for the position
Jean Delvare400b48e2006-03-23 16:46:47 +0100618 of individual bits. For this reason, the use of this
619 interface file for new drivers is discouraged. Use
620 individual *_alarm and *_fault files instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700621 Bits are defined in kernel/include/sensors.h.
622
Linus Torvalds1da177e2005-04-16 15:20:36 -0700623beep_mask Bitmask for beep.
Jean Delvare400b48e2006-03-23 16:46:47 +0100624 Same format as 'alarms' with the same bit locations,
625 use discouraged for the same reason. Use individual
626 *_beep files instead.
Rudolf Marek057bc352006-06-04 20:03:39 +0200627 RW
Hans de Goede2ed42632007-09-21 17:03:32 +0200628
629
Jean Delvareec199202009-03-30 21:46:44 +0200630***********************
631* Intrusion detection *
632***********************
633
634intrusion[0-*]_alarm
635 Chassis intrusion detection
636 0: OK
637 1: intrusion detected
638 RW
639 Contrary to regular alarm flags which clear themselves
640 automatically when read, this one sticks until cleared by
641 the user. This is done by writing 0 to the file. Writing
642 other values is unsupported.
643
644intrusion[0-*]_beep
645 Chassis intrusion beep
646 0: disable
647 1: enable
648 RW
649
650
Hans de Goede2ed42632007-09-21 17:03:32 +0200651sysfs attribute writes interpretation
652-------------------------------------
653
654hwmon sysfs attributes always contain numbers, so the first thing to do is to
655convert the input to a number, there are 2 ways todo this depending whether
656the number can be negative or not:
657unsigned long u = simple_strtoul(buf, NULL, 10);
658long s = simple_strtol(buf, NULL, 10);
659
660With buf being the buffer with the user input being passed by the kernel.
661Notice that we do not use the second argument of strto[u]l, and thus cannot
662tell when 0 is returned, if this was really 0 or is caused by invalid input.
663This is done deliberately as checking this everywhere would add a lot of
664code to the kernel.
665
666Notice that it is important to always store the converted value in an
667unsigned long or long, so that no wrap around can happen before any further
668checking.
669
670After the input string is converted to an (unsigned) long, the value should be
671checked if its acceptable. Be careful with further conversions on the value
672before checking it for validity, as these conversions could still cause a wrap
673around before the check. For example do not multiply the result, and only
674add/subtract if it has been divided before the add/subtract.
675
676What to do if a value is found to be invalid, depends on the type of the
677sysfs attribute that is being set. If it is a continuous setting like a
678tempX_max or inX_max attribute, then the value should be clamped to its
679limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
680continuous like for example a tempX_type, then when an invalid value is
681written, -EINVAL should be returned.
682
683Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
Jean Delvare5fbea512007-10-07 22:44:33 +0200684
685 long v = simple_strtol(buf, NULL, 10) / 1000;
686 v = SENSORS_LIMIT(v, -128, 127);
687 /* write v to register */
Hans de Goede2ed42632007-09-21 17:03:32 +0200688
689Example2, fan divider setting, valid values 2, 4 and 8:
Hans de Goede2ed42632007-09-21 17:03:32 +0200690
Jean Delvare5fbea512007-10-07 22:44:33 +0200691 unsigned long v = simple_strtoul(buf, NULL, 10);
692
693 switch (v) {
694 case 2: v = 1; break;
695 case 4: v = 2; break;
696 case 8: v = 3; break;
697 default:
698 return -EINVAL;
699 }
700 /* write v to register */