blob: 004ee161721e9b3bd1aa213c174a594174b187c8 [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
73RW read/write value
74
75Read/write values may be read-only for some chips, depending on the
76hardware implementation.
77
Jean Delvare176544d2007-08-20 16:44:44 +020078All entries (except name) are optional, and should only be created in a
79given driver if the chip has the feature.
80
81
82********
83* Name *
84********
85
86name The chip name.
87 This should be a short, lowercase string, not containing
88 spaces nor dashes, representing the chip name. This is
89 the only mandatory attribute.
90 I2C devices get this attribute created automatically.
91 RO
92
Jean Delvare740e06a2006-06-05 20:31:20 +020093
Linus Torvalds1da177e2005-04-16 15:20:36 -070094************
95* Voltages *
96************
97
Rudolf Marek057bc352006-06-04 20:03:39 +020098in[0-*]_min Voltage min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -070099 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200100 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101
Rudolf Marek057bc352006-06-04 20:03:39 +0200102in[0-*]_max Voltage max value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700103 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200104 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700105
Rudolf Marek057bc352006-06-04 20:03:39 +0200106in[0-*]_input Voltage input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700107 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200108 RO
109 Voltage measured on the chip pin.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700110 Actual voltage depends on the scaling resistors on the
111 motherboard, as recommended in the chip datasheet.
112 This varies by chip and by motherboard.
113 Because of this variation, values are generally NOT scaled
114 by the chip driver, and must be done by the application.
115 However, some drivers (notably lm87 and via686a)
Rudolf Marek057bc352006-06-04 20:03:39 +0200116 do scale, because of internal resistors built into a chip.
Jean Delvare176544d2007-08-20 16:44:44 +0200117 These drivers will output the actual voltage. Rule of
118 thumb: drivers should report the voltage values at the
119 "pins" of the chip.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700120
Jean Delvare176544d2007-08-20 16:44:44 +0200121in[0-*]_label Suggested voltage channel label.
122 Text string
123 Should only be created if the driver has hints about what
124 this voltage channel is being used for, and user-space
125 doesn't. In all other cases, the label is provided by
126 user-space.
127 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700128
Rudolf Marek057bc352006-06-04 20:03:39 +0200129cpu[0-*]_vid CPU core reference voltage.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700130 Unit: millivolt
Rudolf Marek057bc352006-06-04 20:03:39 +0200131 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700132 Not always correct.
133
134vrm Voltage Regulator Module version number.
Rudolf Marek057bc352006-06-04 20:03:39 +0200135 RW (but changing it should no more be necessary)
136 Originally the VRM standard version multiplied by 10, but now
137 an arbitrary number, as not all standards have a version
138 number.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700139 Affects the way the driver calculates the CPU core reference
140 voltage from the vid pins.
141
Rudolf Marek057bc352006-06-04 20:03:39 +0200142Also see the Alarms section for status flags associated with voltages.
143
Linus Torvalds1da177e2005-04-16 15:20:36 -0700144
145********
146* Fans *
147********
148
Rudolf Marek057bc352006-06-04 20:03:39 +0200149fan[1-*]_min Fan minimum value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700150 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200151 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700152
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200153fan[1-*]_max Fan maximum value
154 Unit: revolution/min (RPM)
155 Only rarely supported by the hardware.
156 RW
157
Rudolf Marek057bc352006-06-04 20:03:39 +0200158fan[1-*]_input Fan input value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700159 Unit: revolution/min (RPM)
Rudolf Marek057bc352006-06-04 20:03:39 +0200160 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700161
Rudolf Marek057bc352006-06-04 20:03:39 +0200162fan[1-*]_div Fan divisor.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700163 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
Rudolf Marek057bc352006-06-04 20:03:39 +0200164 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700165 Some chips only support values 1, 2, 4 and 8.
166 Note that this is actually an internal clock divisor, which
167 affects the measurable speed range, not the read value.
168
Jean Delvare2dbc5142007-05-08 17:22:00 +0200169fan[1-*]_target
170 Desired fan speed
171 Unit: revolution/min (RPM)
172 RW
173 Only makes sense if the chip supports closed-loop fan speed
174 control based on the measured fan speed.
175
Jean Delvare176544d2007-08-20 16:44:44 +0200176fan[1-*]_label Suggested fan channel label.
177 Text string
178 Should only be created if the driver has hints about what
179 this fan channel is being used for, and user-space doesn't.
180 In all other cases, the label is provided by user-space.
181 RO
182
Rudolf Marek057bc352006-06-04 20:03:39 +0200183Also see the Alarms section for status flags associated with fans.
184
185
Linus Torvalds1da177e2005-04-16 15:20:36 -0700186*******
187* PWM *
188*******
189
Rudolf Marek057bc352006-06-04 20:03:39 +0200190pwm[1-*] Pulse width modulation fan control.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700191 Integer value in the range 0 to 255
Rudolf Marek057bc352006-06-04 20:03:39 +0200192 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700193 255 is max or 100%.
194
Rudolf Marek057bc352006-06-04 20:03:39 +0200195pwm[1-*]_enable
Jean Delvare875f25d2007-06-27 21:26:08 +0200196 Fan speed control method:
197 0: no fan speed control (i.e. fan at full speed)
198 1: manual fan speed control enabled (using pwm[1-*])
199 2+: automatic fan speed control enabled
Jean Delvaref8d0c192007-02-14 21:15:02 +0100200 Check individual chip documentation files for automatic mode
201 details.
Rudolf Marek057bc352006-06-04 20:03:39 +0200202 RW
203
Jean Delvaref8d0c192007-02-14 21:15:02 +0100204pwm[1-*]_mode 0: DC mode (direct current)
205 1: PWM mode (pulse-width modulation)
206 RW
207
208pwm[1-*]_freq Base PWM frequency in Hz.
209 Only possibly available when pwmN_mode is PWM, but not always
210 present even then.
Rudolf Marek057bc352006-06-04 20:03:39 +0200211 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700212
213pwm[1-*]_auto_channels_temp
214 Select which temperature channels affect this PWM output in
215 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
216 Which values are possible depend on the chip used.
Rudolf Marek057bc352006-06-04 20:03:39 +0200217 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700218
219pwm[1-*]_auto_point[1-*]_pwm
220pwm[1-*]_auto_point[1-*]_temp
221pwm[1-*]_auto_point[1-*]_temp_hyst
222 Define the PWM vs temperature curve. Number of trip points is
223 chip-dependent. Use this for chips which associate trip points
224 to PWM output channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200225 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700226
227OR
228
229temp[1-*]_auto_point[1-*]_pwm
230temp[1-*]_auto_point[1-*]_temp
231temp[1-*]_auto_point[1-*]_temp_hyst
232 Define the PWM vs temperature curve. Number of trip points is
233 chip-dependent. Use this for chips which associate trip points
234 to temperature channels.
Rudolf Marek057bc352006-06-04 20:03:39 +0200235 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700236
237
238****************
239* Temperatures *
240****************
241
Rudolf Marek057bc352006-06-04 20:03:39 +0200242temp[1-*]_type Sensor type selection.
Jean Delvareb26f9332007-08-16 14:30:01 +0200243 Integers 1 to 6
Rudolf Marek057bc352006-06-04 20:03:39 +0200244 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700245 1: PII/Celeron Diode
246 2: 3904 transistor
247 3: thermal diode
Jean Delvareb26f9332007-08-16 14:30:01 +0200248 4: thermistor
Rudolf Marek61db0112006-12-12 18:18:30 +0100249 5: AMD AMDSI
250 6: Intel PECI
Linus Torvalds1da177e2005-04-16 15:20:36 -0700251 Not all types are supported by all chips
252
Rudolf Marek057bc352006-06-04 20:03:39 +0200253temp[1-*]_max Temperature max value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200254 Unit: millidegree Celsius (or millivolt, see below)
Rudolf Marek057bc352006-06-04 20:03:39 +0200255 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700256
Rudolf Marek057bc352006-06-04 20:03:39 +0200257temp[1-*]_min Temperature min value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200258 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200259 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700260
Rudolf Marek057bc352006-06-04 20:03:39 +0200261temp[1-*]_max_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700262 Temperature hysteresis value for max limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200263 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700264 Must be reported as an absolute temperature, NOT a delta
265 from the max value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200266 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700267
Rudolf Marek057bc352006-06-04 20:03:39 +0200268temp[1-*]_input Temperature input value.
Jean Delvare740e06a2006-06-05 20:31:20 +0200269 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200270 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700271
Rudolf Marek057bc352006-06-04 20:03:39 +0200272temp[1-*]_crit Temperature critical value, typically greater than
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273 corresponding temp_max values.
Jean Delvare740e06a2006-06-05 20:31:20 +0200274 Unit: millidegree Celsius
Rudolf Marek057bc352006-06-04 20:03:39 +0200275 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700276
Rudolf Marek057bc352006-06-04 20:03:39 +0200277temp[1-*]_crit_hyst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700278 Temperature hysteresis value for critical limit.
Jean Delvare740e06a2006-06-05 20:31:20 +0200279 Unit: millidegree Celsius
Linus Torvalds1da177e2005-04-16 15:20:36 -0700280 Must be reported as an absolute temperature, NOT a delta
281 from the critical value.
Rudolf Marek057bc352006-06-04 20:03:39 +0200282 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700283
Jean Delvare176544d2007-08-20 16:44:44 +0200284temp[1-*]_offset
Hartmut Rick59ac8362006-03-23 16:37:23 +0100285 Temperature offset which is added to the temperature reading
286 by the chip.
287 Unit: millidegree Celsius
288 Read/Write value.
289
Jean Delvare176544d2007-08-20 16:44:44 +0200290temp[1-*]_label Suggested temperature channel label.
291 Text string
292 Should only be created if the driver has hints about what
293 this temperature channel is being used for, and user-space
294 doesn't. In all other cases, the label is provided by
295 user-space.
296 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700297
Jean Delvare740e06a2006-06-05 20:31:20 +0200298Some chips measure temperature using external thermistors and an ADC, and
299report the temperature measurement as a voltage. Converting this voltage
300back to a temperature (or the other way around for limits) requires
301mathematical functions not available in the kernel, so the conversion
302must occur in user space. For these chips, all temp* files described
303above should contain values expressed in millivolt instead of millidegree
304Celsius. In other words, such temperature channels are handled as voltage
305channels by the driver.
306
Rudolf Marek057bc352006-06-04 20:03:39 +0200307Also see the Alarms section for status flags associated with temperatures.
308
Linus Torvalds1da177e2005-04-16 15:20:36 -0700309
310************
311* Currents *
312************
313
314Note that no known chip provides current measurements as of writing,
315so this part is theoretical, so to say.
316
Rudolf Marek057bc352006-06-04 20:03:39 +0200317curr[1-*]_max Current max value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700318 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200319 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700320
Rudolf Marek057bc352006-06-04 20:03:39 +0200321curr[1-*]_min Current min value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700322 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200323 RW
Linus Torvalds1da177e2005-04-16 15:20:36 -0700324
Rudolf Marek057bc352006-06-04 20:03:39 +0200325curr[1-*]_input Current input value
Linus Torvalds1da177e2005-04-16 15:20:36 -0700326 Unit: milliampere
Rudolf Marek057bc352006-06-04 20:03:39 +0200327 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700328
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700329*********
330* Power *
331*********
332
333power[1-*]_average Average power use
334 Unit: microWatt
335 RO
336
Darrick J. Wongddedc652008-10-09 15:33:58 +0200337power[1-*]_average_interval Power use averaging interval
338 Unit: milliseconds
339 RW
340
Darrick J. Wong38fb56a2007-10-09 13:39:24 -0700341power[1-*]_average_highest Historical average maximum power use
342 Unit: microWatt
343 RO
344
345power[1-*]_average_lowest Historical average minimum power use
346 Unit: microWatt
347 RO
348
349power[1-*]_input Instantaneous power use
350 Unit: microWatt
351 RO
352
353power[1-*]_input_highest Historical maximum power use
354 Unit: microWatt
355 RO
356
357power[1-*]_input_lowest Historical minimum power use
358 Unit: microWatt
359 RO
360
361power[1-*]_reset_history Reset input_highest, input_lowest,
362 average_highest and average_lowest.
363 WO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700364
Jean Delvare400b48e2006-03-23 16:46:47 +0100365**********
Darrick J. Wongddedc652008-10-09 15:33:58 +0200366* Energy *
367**********
368
369energy[1-*]_input Cumulative energy use
370 Unit: microJoule
371 RO
372
Jean Delvareec199202009-03-30 21:46:44 +0200373
Darrick J. Wongddedc652008-10-09 15:33:58 +0200374**********
Jean Delvare400b48e2006-03-23 16:46:47 +0100375* Alarms *
376**********
377
378Each channel or limit may have an associated alarm file, containing a
379boolean value. 1 means than an alarm condition exists, 0 means no alarm.
380
381Usually a given chip will either use channel-related alarms, or
382limit-related alarms, not both. The driver should just reflect the hardware
383implementation.
384
Rudolf Marek057bc352006-06-04 20:03:39 +0200385in[0-*]_alarm
386fan[1-*]_alarm
387temp[1-*]_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100388 Channel alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200389 0: no alarm
390 1: alarm
391 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100392
393OR
394
Rudolf Marek057bc352006-06-04 20:03:39 +0200395in[0-*]_min_alarm
396in[0-*]_max_alarm
397fan[1-*]_min_alarm
Christian Engelmayerd54d4622009-06-01 13:46:50 +0200398fan[1-*]_max_alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200399temp[1-*]_min_alarm
400temp[1-*]_max_alarm
401temp[1-*]_crit_alarm
Jean Delvare400b48e2006-03-23 16:46:47 +0100402 Limit alarm
Rudolf Marek057bc352006-06-04 20:03:39 +0200403 0: no alarm
404 1: alarm
405 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100406
407Each input channel may have an associated fault file. This can be used
408to notify open diodes, unconnected fans etc. where the hardware
409supports it. When this boolean has value 1, the measurement for that
410channel should not be trusted.
411
Jean Delvare7817a392007-06-09 10:11:16 -0400412in[0-*]_fault
413fan[1-*]_fault
414temp[1-*]_fault
Jean Delvare400b48e2006-03-23 16:46:47 +0100415 Input fault condition
Rudolf Marek057bc352006-06-04 20:03:39 +0200416 0: no fault occured
417 1: fault condition
418 RO
Jean Delvare400b48e2006-03-23 16:46:47 +0100419
420Some chips also offer the possibility to get beeped when an alarm occurs:
421
422beep_enable Master beep enable
Rudolf Marek057bc352006-06-04 20:03:39 +0200423 0: no beeps
424 1: beeps
425 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100426
Rudolf Marek057bc352006-06-04 20:03:39 +0200427in[0-*]_beep
428fan[1-*]_beep
429temp[1-*]_beep
Jean Delvare400b48e2006-03-23 16:46:47 +0100430 Channel beep
Rudolf Marek057bc352006-06-04 20:03:39 +0200431 0: disable
432 1: enable
433 RW
Jean Delvare400b48e2006-03-23 16:46:47 +0100434
435In theory, a chip could provide per-limit beep masking, but no such chip
436was seen so far.
437
438Old drivers provided a different, non-standard interface to alarms and
439beeps. These interface files are deprecated, but will be kept around
440for compatibility reasons:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700441
442alarms Alarm bitmask.
Rudolf Marek057bc352006-06-04 20:03:39 +0200443 RO
Linus Torvalds1da177e2005-04-16 15:20:36 -0700444 Integer representation of one to four bytes.
445 A '1' bit means an alarm.
446 Chips should be programmed for 'comparator' mode so that
447 the alarm will 'come back' after you read the register
448 if it is still valid.
449 Generally a direct representation of a chip's internal
450 alarm registers; there is no standard for the position
Jean Delvare400b48e2006-03-23 16:46:47 +0100451 of individual bits. For this reason, the use of this
452 interface file for new drivers is discouraged. Use
453 individual *_alarm and *_fault files instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700454 Bits are defined in kernel/include/sensors.h.
455
Linus Torvalds1da177e2005-04-16 15:20:36 -0700456beep_mask Bitmask for beep.
Jean Delvare400b48e2006-03-23 16:46:47 +0100457 Same format as 'alarms' with the same bit locations,
458 use discouraged for the same reason. Use individual
459 *_beep files instead.
Rudolf Marek057bc352006-06-04 20:03:39 +0200460 RW
Hans de Goede2ed42632007-09-21 17:03:32 +0200461
462
Jean Delvareec199202009-03-30 21:46:44 +0200463***********************
464* Intrusion detection *
465***********************
466
467intrusion[0-*]_alarm
468 Chassis intrusion detection
469 0: OK
470 1: intrusion detected
471 RW
472 Contrary to regular alarm flags which clear themselves
473 automatically when read, this one sticks until cleared by
474 the user. This is done by writing 0 to the file. Writing
475 other values is unsupported.
476
477intrusion[0-*]_beep
478 Chassis intrusion beep
479 0: disable
480 1: enable
481 RW
482
483
Hans de Goede2ed42632007-09-21 17:03:32 +0200484sysfs attribute writes interpretation
485-------------------------------------
486
487hwmon sysfs attributes always contain numbers, so the first thing to do is to
488convert the input to a number, there are 2 ways todo this depending whether
489the number can be negative or not:
490unsigned long u = simple_strtoul(buf, NULL, 10);
491long s = simple_strtol(buf, NULL, 10);
492
493With buf being the buffer with the user input being passed by the kernel.
494Notice that we do not use the second argument of strto[u]l, and thus cannot
495tell when 0 is returned, if this was really 0 or is caused by invalid input.
496This is done deliberately as checking this everywhere would add a lot of
497code to the kernel.
498
499Notice that it is important to always store the converted value in an
500unsigned long or long, so that no wrap around can happen before any further
501checking.
502
503After the input string is converted to an (unsigned) long, the value should be
504checked if its acceptable. Be careful with further conversions on the value
505before checking it for validity, as these conversions could still cause a wrap
506around before the check. For example do not multiply the result, and only
507add/subtract if it has been divided before the add/subtract.
508
509What to do if a value is found to be invalid, depends on the type of the
510sysfs attribute that is being set. If it is a continuous setting like a
511tempX_max or inX_max attribute, then the value should be clamped to its
512limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
513continuous like for example a tempX_type, then when an invalid value is
514written, -EINVAL should be returned.
515
516Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
Jean Delvare5fbea512007-10-07 22:44:33 +0200517
518 long v = simple_strtol(buf, NULL, 10) / 1000;
519 v = SENSORS_LIMIT(v, -128, 127);
520 /* write v to register */
Hans de Goede2ed42632007-09-21 17:03:32 +0200521
522Example2, fan divider setting, valid values 2, 4 and 8:
Hans de Goede2ed42632007-09-21 17:03:32 +0200523
Jean Delvare5fbea512007-10-07 22:44:33 +0200524 unsigned long v = simple_strtoul(buf, NULL, 10);
525
526 switch (v) {
527 case 2: v = 1; break;
528 case 4: v = 2; break;
529 case 8: v = 3; break;
530 default:
531 return -EINVAL;
532 }
533 /* write v to register */