Naming and data format standards for sysfs files¶

The libsensors library offers an interface to the raw sensors datathrough the sysfs interface. Since lm-sensors 3.0.0, libsensors iscompletely chip-independent. It assumes that all the kernel driversimplement the standard sysfs interface described in this document.This makes adding or updating support for any given chip very easy, aslibsensors, and applications using it, do not need to be modified.This is a major improvement compared to lm-sensors 2.

Note that motherboards vary widely in the connections to sensor chips.There is no standard that ensures, for example, that the secondtemperature sensor is connected to the CPU, or that the second fan is onthe CPU. Also, some values reported by the chips need some computationbefore they make full sense. For example, most chips can only measurevoltages between 0 and +4V. Other voltages are scaled back into thatrange using external resistors. Since the values of these resistorscan change from motherboard to motherboard, the conversions cannot behard coded into the driver and have to be done in user space.

For this reason, even if we aim at a chip-independent libsensors, it willstill require a configuration file (e.g. /etc/sensors.conf) for propervalues conversion, labeling of inputs and hiding of unused inputs.

An alternative method that some programs use is to access the sysfsfiles directly. This document briefly describes the standards that thedrivers follow, so that an application program can scan for entries andaccess this data in a simple and consistent way. That said, such programswill have to implement conversion, labeling and hiding of inputs. Forthis reason, it is still not recommended to bypass the library.

Each chip gets its own directory in the sysfs /sys/devices tree. Tofind all sensor chips, it is easier to follow the device symlinks from/sys/class/hwmon/hwmon*.

Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributesin the “physical” device directory. Since lm-sensors 3.0.1, attributes foundin the hwmon “class” device directory are also supported. Complex drivers(e.g. drivers for multifunction chips) may want to use this possibility toavoid namespace pollution. The only drawback will be that older versions oflibsensors won’t support the driver in question.

All sysfs values are fixed point numbers.

There is only one value per file, unlike the older /proc specification.The common scheme for files naming is: <type><number>_<item>. Usualtypes for sensor chips are “in” (voltage), “temp” (temperature) and“fan” (fan). Usual items are “input” (measured value), “max” (highthreshold, “min” (low threshold). Numbering usually starts from 1,except for voltages which start from 0 (because most data sheets usethis). A number is always used for elements that can be present morethan once, even if there is a single element of the given type on thespecific chip. Other files do not refer to a specific element, sothey have a simple name, and no number.

Alarms are direct indications read from the chips. The drivers do NOTmake comparisons of readings to thresholds. This allows violationsbetween readings to be caught and alarmed. The exact definition of analarm (for example, whether a threshold must be met or must be exceededto cause an alarm) is chip-dependent.

When setting values of hwmon sysfs attributes, the string representation ofthe desired value must be written, note that strings which are not a numberare interpreted as 0! For more on how written strings are interpreted see the“sysfs attribute writes interpretation” section at the end of this file.

Attribute access¶

Hardware monitoring sysfs attributes are displayed by unrestricted userspaceapplications. For this reason, all standard ABI attributes shall be worldreadable. Writeable standard ABI attributes shall be writeable only forprivileged users.

[0-*]	denotes any positive number starting from 0
[1-*]	denotes any positive number starting from 1
RO	read only value
WO	write only value
RW	read/write value

Read/write values may be read-only for some chips, depending on thehardware implementation.

All entries (except name) are optional, and should only be created in agiven driver if the chip has the feature.

SeeABI file testing/sysfs-class-hwmon for a complete descriptionof the attributes.

Global attributes¶

name: The chip name.
label: A descriptive label that allows to uniquely identify a devicewithin the system.
update_interval: The interval at which the chip will update readings.

Voltages¶

in[0-*]_min: Voltage min value.
in[0-*]_lcrit: Voltage critical min value.
in[0-*]_max: Voltage max value.
in[0-*]_crit: Voltage critical max value.
in[0-*]_input: Voltage input value.
in[0-*]_average: Average voltage
in[0-*]_lowest: Historical minimum voltage
in[0-*]_highest: Historical maximum voltage
in[0-*]_reset_history: Reset inX_lowest and inX_highest
in_reset_history: Reset inX_lowest and inX_highest for all sensors
in[0-*]_label: Suggested voltage channel label.
in[0-*]_enable: Enable or disable the sensors.
cpu[0-*]_vid: CPU core reference voltage.
vrm: Voltage Regulator Module version number.
in[0-*]_rated_min: Minimum rated voltage.
in[0-*]_rated_max: Maximum rated voltage.

Also see the Alarms section for status flags associated with voltages.

Fans¶

fan[1-*]_min: Fan minimum value
fan[1-*]_max: Fan maximum value
fan[1-*]_input: Fan input value.
fan[1-*]_div: Fan divisor.
fan[1-*]_pulses: Number of tachometer pulses per fan revolution.
fan[1-*]_target: Desired fan speed
fan[1-*]_label: Suggested fan channel label.
fan[1-*]_enable: Enable or disable the sensors.

Also see the Alarms section for status flags associated with fans.

PWM¶

pwm[1-*]: Pulse width modulation fan control.
pwm[1-*]_enable: Fan speed control method.
pwm[1-*]_mode: direct current or pulse-width modulation.
pwm[1-*]_freq: Base PWM frequency in Hz.
pwm[1-*]_auto_channels_temp: Select which temperature channels affect this PWM output inauto mode.
pwm[1-*]_auto_point[1-*]_pwm /pwm[1-*]_auto_point[1-*]_temp /pwm[1-*]_auto_point[1-*]_temp_hyst: Define the PWM vs temperature curve.
temp[1-*]_auto_point[1-*]_pwm /temp[1-*]_auto_point[1-*]_temp /temp[1-*]_auto_point[1-*]_temp_hyst: Define the PWM vs temperature curve.

There is a third case where trip points are associated to both PWM outputchannels and temperature channels: the PWM values are associated to PWMoutput channels while the temperature values are associated to temperaturechannels. In that case, the result is determined by the mapping betweentemperature inputs and PWM outputs. When several temperature inputs aremapped to a given PWM output, this leads to several candidate PWM values.The actual result is up to the chip, but in general the highest candidatevalue (fastest fan speed) wins.

Temperatures¶

temp[1-*]_type: Sensor type selection.
temp[1-*]_max: Temperature max value.
temp[1-*]_min: Temperature min value.
temp[1-*]_max_hyst: Temperature hysteresis value for max limit.
temp[1-*]_min_hyst: Temperature hysteresis value for min limit.
temp[1-*]_input: Temperature input value.
temp[1-*]_crit: Temperature critical max value, typically greater thancorresponding temp_max values.
temp[1-*]_crit_hyst: Temperature hysteresis value for critical limit.
temp[1-*]_emergency: Temperature emergency max value, for chips supporting more thantwo upper temperature limits.
temp[1-*]_emergency_hyst: Temperature hysteresis value for emergency limit.
temp[1-*]_lcrit: Temperature critical min value, typically lower thancorresponding temp_min values.
temp[1-*]_lcrit_hyst: Temperature hysteresis value for critical min limit.
temp[1-*]_offset: Temperature offset which is added to the temperature readingby the chip.
temp[1-*]_label: Suggested temperature channel label.
temp[1-*]_lowest: Historical minimum temperature
temp[1-*]_highest: Historical maximum temperature
temp[1-*]_reset_history: Reset temp_lowest and temp_highest
temp_reset_history: Reset temp_lowest and temp_highest for all sensors
temp[1-*]_enable: Enable or disable the sensors.
temp[1-*]_rated_min: Minimum rated temperature.
temp[1-*]_rated_max: Maximum rated temperature.

Some chips measure temperature using external thermistors and an ADC, andreport the temperature measurement as a voltage. Converting this voltageback to a temperature (or the other way around for limits) requiresmathematical functions not available in the kernel, so the conversionmust occur in user space. For these chips, all temp* files describedabove should contain values expressed in millivolt instead of millidegreeCelsius. In other words, such temperature channels are handled as voltagechannels by the driver.

Also see the Alarms section for status flags associated with temperatures.

Currents¶

curr[1-*]_max

Current max value.

curr[1-*]_min

Current min value.

curr[1-*]_lcrit

Current critical low value

curr[1-*]_crit

Current critical high value.

curr[1-*]_input

Current input value.

curr[1-*]_average

Average current use.

curr[1-*]_lowest

Historical minimum current.

curr[1-*]_highest

Historical maximum current.

curr[1-*]_reset_history

Reset currX_lowest and currX_highest

curr_reset_history

Reset currX_lowest and currX_highest for all sensors.

curr[1-*]_enable

Enable or disable the sensors.

curr[1-*]_rated_min

Minimum rated current.

curr[1-*]_rated_max

Maximum rated current.

Also see the Alarms section for status flags associated with currents.

Power¶

power[1-*]_average

Average power use.

power[1-*]_average_interval

Power use averaging interval.

power[1-*]_average_interval_max

Maximum power use averaging interval.

power[1-*]_average_interval_min

Minimum power use averaging interval.

power[1-*]_average_highest

Historical average maximum power use

power[1-*]_average_lowest

Historical average minimum power use

power[1-*]_average_max

A poll notification is sent topower[1-*]_average whenpower use rises above this value.

power[1-*]_average_min

A poll notification is sent topower[1-*]_average whenpower use sinks below this value.

power[1-*]_input

Instantaneous power use.

power[1-*]_input_highest

Historical maximum power use

power[1-*]_input_lowest

Historical minimum power use.

power[1-*]_reset_history

Reset input_highest, input_lowest, average_highest andaverage_lowest.

power[1-*]_accuracy

Accuracy of the power meter.

power[1-*]_cap

If power use rises above this limit, thesystem should take action to reduce power use.

power[1-*]_cap_hyst

Margin of hysteresis built around capping and notification.

power[1-*]_cap_max

Maximum cap that can be set.

power[1-*]_cap_min

Minimum cap that can be set.

power[1-*]_max

Maximum power.

power[1-*]_crit

Critical maximum power.

If power rises to or above this limit, thesystem is expected take drastic action to reducepower consumption, such as a system shutdown ora forced powerdown of some devices.

Unit: microWatt

power[1-*]_enable

Enable or disable the sensors.

When disabled the sensor read will return-ENODATA.

1: Enable
0: Disable

power[1-*]_rated_min

Minimum rated power.

Unit: microWatt

power[1-*]_rated_max

Maximum rated power.

Unit: microWatt

Also see the Alarms section for status flags associated with power readings.

Energy¶

energy[1-*]_input

Cumulative energy use

Unit: microJoule

energy[1-*]_enable

Enable or disable the sensors.

When disabled the sensor read will return-ENODATA.

1: Enable
0: Disable

Humidity¶

humidity[1-*]_input: Humidity.
humidity[1-*]_enable: Enable or disable the sensors.
humidity[1-*]_rated_min: Minimum rated humidity.
humidity[1-*]_rated_max: Maximum rated humidity.

Alarms¶

Each channel or limit may have an associated alarm file, containing aboolean value. 1 means than an alarm condition exists, 0 means no alarm.

Usually a given chip will either use channel-related alarms, orlimit-related alarms, not both. The driver should just reflect the hardwareimplementation.

`in[0-*]_alarm`,`curr[1-*]_alarm`,`power[1-*]_alarm`,`fan[1-*]_alarm`,`temp[1-*]_alarm`

Channel alarm

0: no alarm
1: alarm
RO

`in[0-*]_min_alarm`,`in[0-*]_max_alarm`,`in[0-*]_lcrit_alarm`,`in[0-*]_crit_alarm`,`curr[1-*]_min_alarm`,`curr[1-*]_max_alarm`,`curr[1-*]_lcrit_alarm`,`curr[1-*]_crit_alarm`,`power[1-*]_cap_alarm`,`power[1-*]_max_alarm`,`power[1-*]_crit_alarm`,`fan[1-*]_min_alarm`,`fan[1-*]_max_alarm`,`temp[1-*]_min_alarm`,`temp[1-*]_max_alarm`,`temp[1-*]_lcrit_alarm`,`temp[1-*]_crit_alarm`,`temp[1-*]_emergency_alarm`

Limit alarm

0: no alarm
1: alarm

Each input channel may have an associated fault file. This can be usedto notify open diodes, unconnected fans etc. where the hardwaresupports it. When this boolean has value 1, the measurement for thatchannel should not be trusted.

fan[1-*]_fault /temp[1-*]_fault: Input fault condition.

Some chips also offer the possibility to get beeped when an alarm occurs:

beep_enable: Master beep enable.
in[0-*]_beep,curr[1-*]_beep,fan[1-*]_beep,temp[1-*]_beep,: Channel beep.

In theory, a chip could provide per-limit beep masking, but no such chipwas seen so far.

Old drivers provided a different, non-standard interface to alarms andbeeps. These interface files are deprecated, but will be kept aroundfor compatibility reasons:

alarms: Alarm bitmask.
beep_mask: Bitmask for beep.

Intrusion detection¶

intrusion[0-*]_alarm: Chassis intrusion detection.
intrusion[0-*]_beep: Chassis intrusion beep.

Average sample configuration¶

Devices allowing for reading {in,power,curr,temp}_average values may exportattributes for controlling number of samples used to compute average.

samples

Sets number of average samples for all types of measurements.

in_samplespower_samplescurr_samplestemp_samples

Sets number of average samples for specific type ofmeasurements.

Note that on some devices it won’t be possible to set all ofthem to different values so changing one might also changesome others.

sysfs attribute writes interpretation¶

hwmon sysfs attributes always contain numbers, so the first thing to do is toconvert the input to a number, there are 2 ways todo this depending whetherthe number can be negative or not:

unsigned long u = simple_strtoul(buf, NULL, 10);long s = simple_strtol(buf, NULL, 10);

With buf being the buffer with the user input being passed by the kernel.Notice that we do not use the second argument of strto[u]l, and thus cannottell when 0 is returned, if this was really 0 or is caused by invalid input.This is done deliberately as checking this everywhere would add a lot ofcode to the kernel.

Notice that it is important to always store the converted value in anunsigned long or long, so that no wrap around can happen before any furtherchecking.

After the input string is converted to an (unsigned) long, the value should bechecked if its acceptable. Be careful with further conversions on the valuebefore checking it for validity, as these conversions could still cause a wraparound before the check. For example do not multiply the result, and onlyadd/subtract if it has been divided before the add/subtract.

What to do if a value is found to be invalid, depends on the type of thesysfs attribute that is being set. If it is a continuous setting like atempX_max or inX_max attribute, then the value should be clamped to itslimits using clamp_val(value, min_limit, max_limit). If it is not continuouslike for example a tempX_type, then when an invalid value is written,-EINVAL should be returned.

Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):

long v = simple_strtol(buf, NULL, 10) / 1000;v = clamp_val(v, -128, 127);/* write v to register */

Example2, fan divider setting, valid values 2, 4 and 8:

unsigned long v = simple_strtoul(buf, NULL, 10);switch (v) {case 2: v = 1; break;case 4: v = 2; break;case 8: v = 3; break;default:        return -EINVAL;}/* write v to register */

Movatterモバイル変換

Naming and data format standards for sysfs files¶

Attribute access¶

Global attributes¶

Voltages¶

Fans¶

PWM¶

Temperatures¶

Currents¶

Power¶

Energy¶

Humidity¶

Alarms¶

Intrusion detection¶

Average sample configuration¶

sysfs attribute writes interpretation¶