OpenCores
URL https://opencores.org/ocsvn/test_project/test_project/trunk

Subversion Repositories test_project

[/] [test_project/] [trunk/] [linux_sd_driver/] [Documentation/] [hwmon/] [sysfs-interface] - Blame information for rev 62

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 62 marcus.erl
Naming and data format standards for sysfs files
2
------------------------------------------------
3
 
4
The libsensors library offers an interface to the raw sensors data
5
through the sysfs interface. See libsensors documentation and source for
6
further information. As of writing this document, libsensors
7
(from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating
8
support for any given chip requires modifying the library's code.
9
This is because libsensors was written for the procfs interface
10
older kernel modules were using, which wasn't standardized enough.
11
Recent versions of libsensors (from lm_sensors 2.8.2 and later) have
12
support for the sysfs interface, though.
13
 
14
The new sysfs interface was designed to be as chip-independent as
15
possible.
16
 
17
Note that motherboards vary widely in the connections to sensor chips.
18
There is no standard that ensures, for example, that the second
19
temperature sensor is connected to the CPU, or that the second fan is on
20
the CPU. Also, some values reported by the chips need some computation
21
before they make full sense. For example, most chips can only measure
22
voltages between 0 and +4V. Other voltages are scaled back into that
23
range using external resistors. Since the values of these resistors
24
can change from motherboard to motherboard, the conversions cannot be
25
hard coded into the driver and have to be done in user space.
26
 
27
For this reason, even if we aim at a chip-independent libsensors, it will
28
still require a configuration file (e.g. /etc/sensors.conf) for proper
29
values conversion, labeling of inputs and hiding of unused inputs.
30
 
31
An alternative method that some programs use is to access the sysfs
32
files directly. This document briefly describes the standards that the
33
drivers follow, so that an application program can scan for entries and
34
access this data in a simple and consistent way. That said, such programs
35
will have to implement conversion, labeling and hiding of inputs. For
36
this reason, it is still not recommended to bypass the library.
37
 
38
If you are developing a userspace application please send us feedback on
39
this standard.
40
 
41
Note that this standard isn't completely established yet, so it is subject
42
to changes. If you are writing a new hardware monitoring driver those
43
features can't seem to fit in this interface, please contact us with your
44
extension proposal. Keep in mind that backward compatibility must be
45
preserved.
46
 
47
Each chip gets its own directory in the sysfs /sys/devices tree.  To
48
find all sensor chips, it is easier to follow the device symlinks from
49
/sys/class/hwmon/hwmon*.
50
 
51
All sysfs values are fixed point numbers.
52
 
53
There is only one value per file, unlike the older /proc specification.
54
The common scheme for files naming is: _. Usual
55
types for sensor chips are "in" (voltage), "temp" (temperature) and
56
"fan" (fan). Usual items are "input" (measured value), "max" (high
57
threshold, "min" (low threshold). Numbering usually starts from 1,
58
except for voltages which start from 0 (because most data sheets use
59
this). A number is always used for elements that can be present more
60
than once, even if there is a single element of the given type on the
61
specific chip. Other files do not refer to a specific element, so
62
they have a simple name, and no number.
63
 
64
Alarms are direct indications read from the chips. The drivers do NOT
65
make comparisons of readings to thresholds. This allows violations
66
between readings to be caught and alarmed. The exact definition of an
67
alarm (for example, whether a threshold must be met or must be exceeded
68
to cause an alarm) is chip-dependent.
69
 
70
When setting values of hwmon sysfs attributes, the string representation of
71
the desired value must be written, note that strings which are not a number
72
are interpreted as 0! For more on how written strings are interpreted see the
73
"sysfs attribute writes interpretation" section at the end of this file.
74
 
75
-------------------------------------------------------------------------
76
 
77
[0-*]   denotes any positive number starting from 0
78
[1-*]   denotes any positive number starting from 1
79
RO      read only value
80
RW      read/write value
81
 
82
Read/write values may be read-only for some chips, depending on the
83
hardware implementation.
84
 
85
All entries (except name) are optional, and should only be created in a
86
given driver if the chip has the feature.
87
 
88
 
89
********
90
* Name *
91
********
92
 
93
name            The chip name.
94
                This should be a short, lowercase string, not containing
95
                spaces nor dashes, representing the chip name. This is
96
                the only mandatory attribute.
97
                I2C devices get this attribute created automatically.
98
                RO
99
 
100
 
101
************
102
* Voltages *
103
************
104
 
105
in[0-*]_min     Voltage min value.
106
                Unit: millivolt
107
                RW
108
 
109
in[0-*]_max     Voltage max value.
110
                Unit: millivolt
111
                RW
112
 
113
in[0-*]_input   Voltage input value.
114
                Unit: millivolt
115
                RO
116
                Voltage measured on the chip pin.
117
                Actual voltage depends on the scaling resistors on the
118
                motherboard, as recommended in the chip datasheet.
119
                This varies by chip and by motherboard.
120
                Because of this variation, values are generally NOT scaled
121
                by the chip driver, and must be done by the application.
122
                However, some drivers (notably lm87 and via686a)
123
                do scale, because of internal resistors built into a chip.
124
                These drivers will output the actual voltage. Rule of
125
                thumb: drivers should report the voltage values at the
126
                "pins" of the chip.
127
 
128
in[0-*]_label   Suggested voltage channel label.
129
                Text string
130
                Should only be created if the driver has hints about what
131
                this voltage channel is being used for, and user-space
132
                doesn't. In all other cases, the label is provided by
133
                user-space.
134
                RO
135
 
136
cpu[0-*]_vid    CPU core reference voltage.
137
                Unit: millivolt
138
                RO
139
                Not always correct.
140
 
141
vrm             Voltage Regulator Module version number.
142
                RW (but changing it should no more be necessary)
143
                Originally the VRM standard version multiplied by 10, but now
144
                an arbitrary number, as not all standards have a version
145
                number.
146
                Affects the way the driver calculates the CPU core reference
147
                voltage from the vid pins.
148
 
149
Also see the Alarms section for status flags associated with voltages.
150
 
151
 
152
********
153
* Fans *
154
********
155
 
156
fan[1-*]_min    Fan minimum value
157
                Unit: revolution/min (RPM)
158
                RW
159
 
160
fan[1-*]_input  Fan input value.
161
                Unit: revolution/min (RPM)
162
                RO
163
 
164
fan[1-*]_div    Fan divisor.
165
                Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
166
                RW
167
                Some chips only support values 1, 2, 4 and 8.
168
                Note that this is actually an internal clock divisor, which
169
                affects the measurable speed range, not the read value.
170
 
171
fan[1-*]_target
172
                Desired fan speed
173
                Unit: revolution/min (RPM)
174
                RW
175
                Only makes sense if the chip supports closed-loop fan speed
176
                control based on the measured fan speed.
177
 
178
fan[1-*]_label  Suggested fan channel label.
179
                Text string
180
                Should only be created if the driver has hints about what
181
                this fan channel is being used for, and user-space doesn't.
182
                In all other cases, the label is provided by user-space.
183
                RO
184
 
185
Also see the Alarms section for status flags associated with fans.
186
 
187
 
188
*******
189
* PWM *
190
*******
191
 
192
pwm[1-*]        Pulse width modulation fan control.
193
                Integer value in the range 0 to 255
194
                RW
195
                255 is max or 100%.
196
 
197
pwm[1-*]_enable
198
                Fan speed control method:
199
                0: no fan speed control (i.e. fan at full speed)
200
                1: manual fan speed control enabled (using pwm[1-*])
201
                2+: automatic fan speed control enabled
202
                Check individual chip documentation files for automatic mode
203
                details.
204
                RW
205
 
206
pwm[1-*]_mode   0: DC mode (direct current)
207
                1: PWM mode (pulse-width modulation)
208
                RW
209
 
210
pwm[1-*]_freq   Base PWM frequency in Hz.
211
                Only possibly available when pwmN_mode is PWM, but not always
212
                present even then.
213
                RW
214
 
215
pwm[1-*]_auto_channels_temp
216
                Select which temperature channels affect this PWM output in
217
                auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
218
                Which values are possible depend on the chip used.
219
                RW
220
 
221
pwm[1-*]_auto_point[1-*]_pwm
222
pwm[1-*]_auto_point[1-*]_temp
223
pwm[1-*]_auto_point[1-*]_temp_hyst
224
                Define the PWM vs temperature curve. Number of trip points is
225
                chip-dependent. Use this for chips which associate trip points
226
                to PWM output channels.
227
                RW
228
 
229
OR
230
 
231
temp[1-*]_auto_point[1-*]_pwm
232
temp[1-*]_auto_point[1-*]_temp
233
temp[1-*]_auto_point[1-*]_temp_hyst
234
                Define the PWM vs temperature curve. Number of trip points is
235
                chip-dependent. Use this for chips which associate trip points
236
                to temperature channels.
237
                RW
238
 
239
 
240
****************
241
* Temperatures *
242
****************
243
 
244
temp[1-*]_type  Sensor type selection.
245
                Integers 1 to 6
246
                RW
247
                1: PII/Celeron Diode
248
                2: 3904 transistor
249
                3: thermal diode
250
                4: thermistor
251
                5: AMD AMDSI
252
                6: Intel PECI
253
                Not all types are supported by all chips
254
 
255
temp[1-*]_max   Temperature max value.
256
                Unit: millidegree Celsius (or millivolt, see below)
257
                RW
258
 
259
temp[1-*]_min   Temperature min value.
260
                Unit: millidegree Celsius
261
                RW
262
 
263
temp[1-*]_max_hyst
264
                Temperature hysteresis value for max limit.
265
                Unit: millidegree Celsius
266
                Must be reported as an absolute temperature, NOT a delta
267
                from the max value.
268
                RW
269
 
270
temp[1-*]_input Temperature input value.
271
                Unit: millidegree Celsius
272
                RO
273
 
274
temp[1-*]_crit  Temperature critical value, typically greater than
275
                corresponding temp_max values.
276
                Unit: millidegree Celsius
277
                RW
278
 
279
temp[1-*]_crit_hyst
280
                Temperature hysteresis value for critical limit.
281
                Unit: millidegree Celsius
282
                Must be reported as an absolute temperature, NOT a delta
283
                from the critical value.
284
                RW
285
 
286
temp[1-*]_offset
287
                Temperature offset which is added to the temperature reading
288
                by the chip.
289
                Unit: millidegree Celsius
290
                Read/Write value.
291
 
292
temp[1-*]_label Suggested temperature channel label.
293
                Text string
294
                Should only be created if the driver has hints about what
295
                this temperature channel is being used for, and user-space
296
                doesn't. In all other cases, the label is provided by
297
                user-space.
298
                RO
299
 
300
Some chips measure temperature using external thermistors and an ADC, and
301
report the temperature measurement as a voltage. Converting this voltage
302
back to a temperature (or the other way around for limits) requires
303
mathematical functions not available in the kernel, so the conversion
304
must occur in user space. For these chips, all temp* files described
305
above should contain values expressed in millivolt instead of millidegree
306
Celsius. In other words, such temperature channels are handled as voltage
307
channels by the driver.
308
 
309
Also see the Alarms section for status flags associated with temperatures.
310
 
311
 
312
************
313
* Currents *
314
************
315
 
316
Note that no known chip provides current measurements as of writing,
317
so this part is theoretical, so to say.
318
 
319
curr[1-*]_max   Current max value
320
                Unit: milliampere
321
                RW
322
 
323
curr[1-*]_min   Current min value.
324
                Unit: milliampere
325
                RW
326
 
327
curr[1-*]_input Current input value
328
                Unit: milliampere
329
                RO
330
 
331
*********
332
* Power *
333
*********
334
 
335
power[1-*]_average              Average power use
336
                                Unit: microWatt
337
                                RO
338
 
339
power[1-*]_average_highest      Historical average maximum power use
340
                                Unit: microWatt
341
                                RO
342
 
343
power[1-*]_average_lowest       Historical average minimum power use
344
                                Unit: microWatt
345
                                RO
346
 
347
power[1-*]_input                Instantaneous power use
348
                                Unit: microWatt
349
                                RO
350
 
351
power[1-*]_input_highest        Historical maximum power use
352
                                Unit: microWatt
353
                                RO
354
 
355
power[1-*]_input_lowest         Historical minimum power use
356
                                Unit: microWatt
357
                                RO
358
 
359
power[1-*]_reset_history        Reset input_highest, input_lowest,
360
                                average_highest and average_lowest.
361
                                WO
362
 
363
**********
364
* Alarms *
365
**********
366
 
367
Each channel or limit may have an associated alarm file, containing a
368
boolean value. 1 means than an alarm condition exists, 0 means no alarm.
369
 
370
Usually a given chip will either use channel-related alarms, or
371
limit-related alarms, not both. The driver should just reflect the hardware
372
implementation.
373
 
374
in[0-*]_alarm
375
fan[1-*]_alarm
376
temp[1-*]_alarm
377
                Channel alarm
378
                0: no alarm
379
                1: alarm
380
                RO
381
 
382
OR
383
 
384
in[0-*]_min_alarm
385
in[0-*]_max_alarm
386
fan[1-*]_min_alarm
387
temp[1-*]_min_alarm
388
temp[1-*]_max_alarm
389
temp[1-*]_crit_alarm
390
                Limit alarm
391
                0: no alarm
392
                1: alarm
393
                RO
394
 
395
Each input channel may have an associated fault file. This can be used
396
to notify open diodes, unconnected fans etc. where the hardware
397
supports it. When this boolean has value 1, the measurement for that
398
channel should not be trusted.
399
 
400
in[0-*]_fault
401
fan[1-*]_fault
402
temp[1-*]_fault
403
                Input fault condition
404
                0: no fault occured
405
                1: fault condition
406
                RO
407
 
408
Some chips also offer the possibility to get beeped when an alarm occurs:
409
 
410
beep_enable     Master beep enable
411
                0: no beeps
412
                1: beeps
413
                RW
414
 
415
in[0-*]_beep
416
fan[1-*]_beep
417
temp[1-*]_beep
418
                Channel beep
419
                0: disable
420
                1: enable
421
                RW
422
 
423
In theory, a chip could provide per-limit beep masking, but no such chip
424
was seen so far.
425
 
426
Old drivers provided a different, non-standard interface to alarms and
427
beeps. These interface files are deprecated, but will be kept around
428
for compatibility reasons:
429
 
430
alarms          Alarm bitmask.
431
                RO
432
                Integer representation of one to four bytes.
433
                A '1' bit means an alarm.
434
                Chips should be programmed for 'comparator' mode so that
435
                the alarm will 'come back' after you read the register
436
                if it is still valid.
437
                Generally a direct representation of a chip's internal
438
                alarm registers; there is no standard for the position
439
                of individual bits. For this reason, the use of this
440
                interface file for new drivers is discouraged. Use
441
                individual *_alarm and *_fault files instead.
442
                Bits are defined in kernel/include/sensors.h.
443
 
444
beep_mask       Bitmask for beep.
445
                Same format as 'alarms' with the same bit locations,
446
                use discouraged for the same reason. Use individual
447
                *_beep files instead.
448
                RW
449
 
450
 
451
sysfs attribute writes interpretation
452
-------------------------------------
453
 
454
hwmon sysfs attributes always contain numbers, so the first thing to do is to
455
convert the input to a number, there are 2 ways todo this depending whether
456
the number can be negative or not:
457
unsigned long u = simple_strtoul(buf, NULL, 10);
458
long s = simple_strtol(buf, NULL, 10);
459
 
460
With buf being the buffer with the user input being passed by the kernel.
461
Notice that we do not use the second argument of strto[u]l, and thus cannot
462
tell when 0 is returned, if this was really 0 or is caused by invalid input.
463
This is done deliberately as checking this everywhere would add a lot of
464
code to the kernel.
465
 
466
Notice that it is important to always store the converted value in an
467
unsigned long or long, so that no wrap around can happen before any further
468
checking.
469
 
470
After the input string is converted to an (unsigned) long, the value should be
471
checked if its acceptable. Be careful with further conversions on the value
472
before checking it for validity, as these conversions could still cause a wrap
473
around before the check. For example do not multiply the result, and only
474
add/subtract if it has been divided before the add/subtract.
475
 
476
What to do if a value is found to be invalid, depends on the type of the
477
sysfs attribute that is being set. If it is a continuous setting like a
478
tempX_max or inX_max attribute, then the value should be clamped to its
479
limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
480
continuous like for example a tempX_type, then when an invalid value is
481
written, -EINVAL should be returned.
482
 
483
Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
484
 
485
        long v = simple_strtol(buf, NULL, 10) / 1000;
486
        v = SENSORS_LIMIT(v, -128, 127);
487
        /* write v to register */
488
 
489
Example2, fan divider setting, valid values 2, 4 and 8:
490
 
491
        unsigned long v = simple_strtoul(buf, NULL, 10);
492
 
493
        switch (v) {
494
        case 2: v = 1; break;
495
        case 4: v = 2; break;
496
        case 8: v = 3; break;
497
        default:
498
                return -EINVAL;
499
        }
500
        /* write v to register */

powered by: WebSVN 2.1.0

© copyright 1999-2025 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.