summaryrefslogtreecommitdiff
path: root/Documentation/hwmon
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2021-09-30 12:44:49 +0300
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>2021-10-05 17:25:16 +0300
commit036d6a4e75c9e49e510b32c0b963e3f15f56f5ad (patch)
tree86b3ee409104c62b127e4cd613803929585a746d /Documentation/hwmon
parentbf0cf3219144e1acdf8582a084e498fcfe67b825 (diff)
downloadlinux-036d6a4e75c9e49e510b32c0b963e3f15f56f5ad.tar.xz
ABI: sysfs-class-hwmon: add ABI documentation for it
Move the ABI attributes documentation from: Documentation/hwmon/sysfs-interface.rst in order for it to follow the usual ABI documentation. That allows script/get_abi.pl to properly handle it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/5f47619ed882b0b8d1c84b56f7ea17bac0854b77.1632994837.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'Documentation/hwmon')
-rw-r--r--Documentation/hwmon/sysfs-interface.rst596
1 files changed, 42 insertions, 554 deletions
diff --git a/Documentation/hwmon/sysfs-interface.rst b/Documentation/hwmon/sysfs-interface.rst
index 13c5acb72d63..85652a6aaa3e 100644
--- a/Documentation/hwmon/sysfs-interface.rst
+++ b/Documentation/hwmon/sysfs-interface.rst
@@ -89,6 +89,8 @@ hardware implementation.
All entries (except name) are optional, and should only be created in a
given driver if the chip has the feature.
+See Documentation/ABI/testing/sysfs-class-hwmon for a complete description
+of the attributes.
*****************
Global attributes
@@ -96,22 +98,9 @@ Global attributes
`name`
The chip name.
- This should be a short, lowercase string, not containing
- whitespace, dashes, or the wildcard character '*'.
- This attribute represents the chip name. It is the only
- mandatory attribute.
- I2C devices get this attribute created automatically.
-
- RO
`update_interval`
The interval at which the chip will update readings.
- Unit: millisecond
-
- RW
-
- Some devices have a variable update rate or interval.
- This attribute can be used to change it to the desired value.
********
@@ -121,148 +110,51 @@ Voltages
`in[0-*]_min`
Voltage min value.
- Unit: millivolt
-
- RW
-
`in[0-*]_lcrit`
Voltage critical min value.
- Unit: millivolt
-
- RW
-
- If voltage drops to or below this limit, the system may
- take drastic action such as power down or reset. At the very
- least, it should report a fault.
-
`in[0-*]_max`
Voltage max value.
- Unit: millivolt
-
- RW
-
`in[0-*]_crit`
Voltage critical max value.
- Unit: millivolt
-
- RW
-
- If voltage reaches or exceeds this limit, the system may
- take drastic action such as power down or reset. At the very
- least, it should report a fault.
-
`in[0-*]_input`
Voltage input value.
- Unit: millivolt
-
- RO
-
- Voltage measured on the chip pin.
-
- Actual voltage depends on the scaling resistors on the
- motherboard, as recommended in the chip datasheet.
-
- This varies by chip and by motherboard.
- Because of this variation, values are generally NOT scaled
- by the chip driver, and must be done by the application.
- However, some drivers (notably lm87 and via686a)
- do scale, because of internal resistors built into a chip.
- These drivers will output the actual voltage. Rule of
- thumb: drivers should report the voltage values at the
- "pins" of the chip.
-
`in[0-*]_average`
Average voltage
- Unit: millivolt
-
- RO
-
`in[0-*]_lowest`
Historical minimum voltage
- Unit: millivolt
-
- RO
-
`in[0-*]_highest`
Historical maximum voltage
- Unit: millivolt
-
- RO
-
`in[0-*]_reset_history`
Reset inX_lowest and inX_highest
- WO
-
`in_reset_history`
Reset inX_lowest and inX_highest for all sensors
- WO
-
`in[0-*]_label`
Suggested voltage channel label.
- Text string
-
- Should only be created if the driver has hints about what
- this voltage channel is being used for, and user-space
- doesn't. In all other cases, the label is provided by
- user-space.
-
- RO
-
`in[0-*]_enable`
Enable or disable the sensors.
- When disabled the sensor read will return -ENODATA.
-
- - 1: Enable
- - 0: Disable
-
- RW
-
`cpu[0-*]_vid`
CPU core reference voltage.
- Unit: millivolt
-
- RO
-
- Not always correct.
-
`vrm`
Voltage Regulator Module version number.
- RW (but changing it should no more be necessary)
-
- Originally the VRM standard version multiplied by 10, but now
- an arbitrary number, as not all standards have a version
- number.
-
- Affects the way the driver calculates the CPU core reference
- voltage from the vid pins.
-
`in[0-*]_rated_min`
Minimum rated voltage.
- Unit: millivolt
-
- RO
-
`in[0-*]_rated_max`
Maximum rated voltage.
- Unit: millivolt
-
- RO
-
Also see the Alarms section for status flags associated with voltages.
@@ -273,83 +165,27 @@ Fans
`fan[1-*]_min`
Fan minimum value
- Unit: revolution/min (RPM)
-
- RW
-
`fan[1-*]_max`
Fan maximum value
- Unit: revolution/min (RPM)
-
- Only rarely supported by the hardware.
- RW
-
`fan[1-*]_input`
Fan input value.
- Unit: revolution/min (RPM)
-
- RO
-
`fan[1-*]_div`
Fan divisor.
- Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
-
- RW
-
- Some chips only support values 1, 2, 4 and 8.
- Note that this is actually an internal clock divisor, which
- affects the measurable speed range, not the read value.
-
`fan[1-*]_pulses`
Number of tachometer pulses per fan revolution.
- Integer value, typically between 1 and 4.
-
- RW
-
- This value is a characteristic of the fan connected to the
- device's input, so it has to be set in accordance with the fan
- model.
-
- Should only be created if the chip has a register to configure
- the number of pulses. In the absence of such a register (and
- thus attribute) the value assumed by all devices is 2 pulses
- per fan revolution.
-
`fan[1-*]_target`
Desired fan speed
- Unit: revolution/min (RPM)
-
- RW
-
- Only makes sense if the chip supports closed-loop fan speed
- control based on the measured fan speed.
-
`fan[1-*]_label`
Suggested fan channel label.
- Text string
-
- Should only be created if the driver has hints about what
- this fan channel is being used for, and user-space doesn't.
- In all other cases, the label is provided by user-space.
-
- RO
-
`fan[1-*]_enable`
Enable or disable the sensors.
- When disabled the sensor read will return -ENODATA.
-
- - 1: Enable
- - 0: Disable
-
- RW
-
Also see the Alarms section for status flags associated with fans.
@@ -360,63 +196,25 @@ PWM
`pwm[1-*]`
Pulse width modulation fan control.
- Integer value in the range 0 to 255
-
- RW
-
- 255 is max or 100%.
-
`pwm[1-*]_enable`
Fan speed control method:
- - 0: no fan speed control (i.e. fan at full speed)
- - 1: manual fan speed control enabled (using `pwm[1-*]`)
- - 2+: automatic fan speed control enabled
-
- Check individual chip documentation files for automatic mode
- details.
-
- RW
-
`pwm[1-*]_mode`
- - 0: DC mode (direct current)
- - 1: PWM mode (pulse-width modulation)
-
- RW
+ direct current or pulse-width modulation.
`pwm[1-*]_freq`
Base PWM frequency in Hz.
- Only possibly available when pwmN_mode is PWM, but not always
- present even then.
-
- RW
-
`pwm[1-*]_auto_channels_temp`
Select which temperature channels affect this PWM output in
auto mode.
- Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
- Which values are possible depend on the chip used.
-
- RW
-
`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.
- Number of trip points is chip-dependent. Use this for chips
- which associate trip points to PWM output channels.
-
- RW
-
`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.
- Number of trip points is chip-dependent. Use this for chips
- which associate trip points to temperature channels.
-
- RW
-
There is a third case where trip points are associated to both PWM output
channels and temperature channels: the PWM values are associated to PWM
output channels while the temperature values are associated to temperature
@@ -434,182 +232,70 @@ Temperatures
`temp[1-*]_type`
Sensor type selection.
- Integers 1 to 6
-
- RW
-
- - 1: CPU embedded diode
- - 2: 3904 transistor
- - 3: thermal diode
- - 4: thermistor
- - 5: AMD AMDSI
- - 6: Intel PECI
-
- Not all types are supported by all chips
-
`temp[1-*]_max`
Temperature max value.
- Unit: millidegree Celsius (or millivolt, see below)
-
- RW
-
`temp[1-*]_min`
Temperature min value.
- Unit: millidegree Celsius
-
- RW
-
`temp[1-*]_max_hyst`
Temperature hysteresis value for max limit.
- Unit: millidegree Celsius
-
- Must be reported as an absolute temperature, NOT a delta
- from the max value.
-
- RW
-
`temp[1-*]_min_hyst`
Temperature hysteresis value for min limit.
- Unit: millidegree Celsius
-
- Must be reported as an absolute temperature, NOT a delta
- from the min value.
-
- RW
`temp[1-*]_input`
- Temperature input value.
-
- Unit: millidegree Celsius
-
- RO
+ Temperature input value.
`temp[1-*]_crit`
Temperature critical max value, typically greater than
corresponding temp_max values.
- Unit: millidegree Celsius
-
- RW
-
`temp[1-*]_crit_hyst`
Temperature hysteresis value for critical limit.
- Unit: millidegree Celsius
-
- Must be reported as an absolute temperature, NOT a delta
- from the critical value.
-
- RW
-
`temp[1-*]_emergency`
Temperature emergency max value, for chips supporting more than
- two upper temperature limits. Must be equal or greater than
- corresponding temp_crit values.
-
- Unit: millidegree Celsius
-
- RW
+ two upper temperature limits.
`temp[1-*]_emergency_hyst`
Temperature hysteresis value for emergency limit.
- Unit: millidegree Celsius
-
- Must be reported as an absolute temperature, NOT a delta
- from the emergency value.
-
- RW
-
`temp[1-*]_lcrit`
Temperature critical min value, typically lower than
corresponding temp_min values.
- Unit: millidegree Celsius
-
- RW
-
`temp[1-*]_lcrit_hyst`
Temperature hysteresis value for critical min limit.
- Unit: millidegree Celsius
-
- Must be reported as an absolute temperature, NOT a delta
- from the critical min value.
-
- RW
-
`temp[1-*]_offset`
Temperature offset which is added to the temperature reading
by the chip.
- Unit: millidegree Celsius
-
- Read/Write value.
-
`temp[1-*]_label`
Suggested temperature channel label.
- Text string
-
- Should only be created if the driver has hints about what
- this temperature channel is being used for, and user-space
- doesn't. In all other cases, the label is provided by
- user-space.
-
- RO
-
`temp[1-*]_lowest`
Historical minimum temperature
- Unit: millidegree Celsius
-
- RO
-
`temp[1-*]_highest`
Historical maximum temperature
- Unit: millidegree Celsius
-
- RO
-
`temp[1-*]_reset_history`
Reset temp_lowest and temp_highest
- WO
-
`temp_reset_history`
Reset temp_lowest and temp_highest for all sensors
- WO
-
`temp[1-*]_enable`
Enable or disable the sensors.
- When disabled the sensor read will return -ENODATA.
-
- - 1: Enable
- - 0: Disable
-
- RW
-
`temp[1-*]_rated_min`
Minimum rated temperature.
- Unit: millidegree Celsius
-
- RO
-
`temp[1-*]_rated_max`
Maximum rated temperature.
- Unit: millidegree Celsius
-
- RO
-
Some chips measure temperature using external thermistors and an ADC, and
report the temperature measurement as a voltage. Converting this voltage
back to a temperature (or the other way around for limits) requires
@@ -627,58 +313,28 @@ Currents
********
`curr[1-*]_max`
- Current max value
-
- Unit: milliampere
-
- RW
+ Current max value.
`curr[1-*]_min`
Current min value.
- Unit: milliampere
-
- RW
-
`curr[1-*]_lcrit`
Current critical low value
- Unit: milliampere
-
- RW
-
`curr[1-*]_crit`
Current critical high value.
- Unit: milliampere
-
- RW
-
`curr[1-*]_input`
- Current input value
-
- Unit: milliampere
-
- RO
+ Current input value.
`curr[1-*]_average`
- Average current use
-
- Unit: milliampere
-
- RO
+ Average current use.
`curr[1-*]_lowest`
- Historical minimum current
-
- Unit: milliampere
-
- RO
+ Historical minimum current.
`curr[1-*]_highest`
- Historical maximum current
- Unit: milliampere
- RO
+ Historical maximum current.
`curr[1-*]_reset_history`
Reset currX_lowest and currX_highest
@@ -686,34 +342,17 @@ Currents
WO
`curr_reset_history`
- Reset currX_lowest and currX_highest for all sensors
-
- WO
+ Reset currX_lowest and currX_highest for all sensors.
`curr[1-*]_enable`
Enable or disable the sensors.
- When disabled the sensor read will return -ENODATA.
-
- - 1: Enable
- - 0: Disable
-
- RW
-
`curr[1-*]_rated_min`
Minimum rated current.
- Unit: milliampere
-
- RO
-
`curr[1-*]_rated_max`
Maximum rated current.
- Unit: milliampere
-
- RO
-
Also see the Alarms section for status flags associated with currents.
*****
@@ -721,141 +360,62 @@ Power
*****
`power[1-*]_average`
- Average power use
-
- Unit: microWatt
-
- RO
+ Average power use.
`power[1-*]_average_interval`
- Power use averaging interval. A poll
- notification is sent to this file if the
- hardware changes the averaging interval.
-
- Unit: milliseconds
-
- RW
+ Power use averaging interval.
`power[1-*]_average_interval_max`
- Maximum power use averaging interval
-
- Unit: milliseconds
-
- RO
+ Maximum power use averaging interval.
`power[1-*]_average_interval_min`
- Minimum power use averaging interval
-
- Unit: milliseconds
-
- RO
+ Minimum power use averaging interval.
`power[1-*]_average_highest`
- Historical average maximum power use
-
- Unit: microWatt
-
- RO
+ Historical average maximum power use
`power[1-*]_average_lowest`
- Historical average minimum power use
-
- Unit: microWatt
-
- RO
+ Historical average minimum power use
`power[1-*]_average_max`
- A poll notification is sent to
- `power[1-*]_average` when power use
- rises above this value.
-
- Unit: microWatt
-
- RW
+ A poll notification is sent to `power[1-*]_average` when
+ power use rises above this value.
`power[1-*]_average_min`
- A poll notification is sent to
- `power[1-*]_average` when power use
- sinks below this value.
-
- Unit: microWatt
-
- RW
+ A poll notification is sent to `power[1-*]_average` when
+ power use sinks below this value.
`power[1-*]_input`
- Instantaneous power use
-
- Unit: microWatt
-
- RO
+ Instantaneous power use.
`power[1-*]_input_highest`
- Historical maximum power use
-
- Unit: microWatt
-
- RO
+ Historical maximum power use
`power[1-*]_input_lowest`
- Historical minimum power use
-
- Unit: microWatt
-
- RO
+ Historical minimum power use.
`power[1-*]_reset_history`
- Reset input_highest, input_lowest,
- average_highest and average_lowest.
-
- WO
+ Reset input_highest, input_lowest, average_highest and
+ average_lowest.
`power[1-*]_accuracy`
- Accuracy of the power meter.
-
- Unit: Percent
-
- RO
+ Accuracy of the power meter.
`power[1-*]_cap`
- If power use rises above this limit, the
- system should take action to reduce power use.
- A poll notification is sent to this file if the
- cap is changed by the hardware. The `*_cap`
- files only appear if the cap is known to be
- enforced by hardware.
-
- Unit: microWatt
-
- RW
+ If power use rises above this limit, the
+ system should take action to reduce power use.
`power[1-*]_cap_hyst`
- Margin of hysteresis built around capping and
- notification.
-
- Unit: microWatt
-
- RW
+ Margin of hysteresis built around capping and notification.
`power[1-*]_cap_max`
- Maximum cap that can be set.
-
- Unit: microWatt
-
- RO
+ Maximum cap that can be set.
`power[1-*]_cap_min`
- Minimum cap that can be set.
-
- Unit: microWatt
-
- RO
+ Minimum cap that can be set.
`power[1-*]_max`
- Maximum power.
-
- Unit: microWatt
-
- RW
+ Maximum power.
`power[1-*]_crit`
Critical maximum power.
@@ -923,37 +483,16 @@ Humidity
********
`humidity[1-*]_input`
- Humidity
-
- Unit: milli-percent (per cent mille, pcm)
-
- RO
-
+ Humidity.
`humidity[1-*]_enable`
- Enable or disable the sensors
-
- When disabled the sensor read will return
- -ENODATA.
-
- - 1: Enable
- - 0: Disable
-
- RW
+ Enable or disable the sensors.
`humidity[1-*]_rated_min`
- Minimum rated humidity.
-
- Unit: milli-percent (per cent mille, pcm)
-
- RO
+ Minimum rated humidity.
`humidity[1-*]_rated_max`
- Maximum rated humidity.
-
- Unit: milli-percent (per cent mille, pcm)
-
- RO
+ Maximum rated humidity.
******
Alarms
@@ -1004,30 +543,15 @@ supports it. When this boolean has value 1, the measurement for that
channel should not be trusted.
`fan[1-*]_fault` / `temp[1-*]_fault`
- Input fault condition
-
- - 0: no fault occurred
- - 1: fault condition
-
- RO
+ Input fault condition.
Some chips also offer the possibility to get beeped when an alarm occurs:
`beep_enable`
- Master beep enable
-
- - 0: no beeps
- - 1: beeps
-
- RW
+ Master beep enable.
`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`,
- Channel beep
-
- - 0: disable
- - 1: enable
-
- RW
+ Channel beep.
In theory, a chip could provide per-limit beep masking, but no such chip
was seen so far.
@@ -1039,29 +563,8 @@ for compatibility reasons:
`alarms`
Alarm bitmask.
- RO
-
- Integer representation of one to four bytes.
-
- A '1' bit means an alarm.
-
- Chips should be programmed for 'comparator' mode so that
- the alarm will 'come back' after you read the register
- if it is still valid.
-
- Generally a direct representation of a chip's internal
- alarm registers; there is no standard for the position
- of individual bits. For this reason, the use of this
- interface file for new drivers is discouraged. Use
- `individual *_alarm` and `*_fault` files instead.
- Bits are defined in kernel/include/sensors.h.
-
`beep_mask`
Bitmask for beep.
- Same format as 'alarms' with the same bit locations,
- use discouraged for the same reason. Use individual
- `*_beep` files instead.
- RW
*******************
@@ -1069,25 +572,10 @@ Intrusion detection
*******************
`intrusion[0-*]_alarm`
- Chassis intrusion detection
-
- - 0: OK
- - 1: intrusion detected
-
- RW
-
- Contrary to regular alarm flags which clear themselves
- automatically when read, this one sticks until cleared by
- the user. This is done by writing 0 to the file. Writing
- other values is unsupported.
+ Chassis intrusion detection.
`intrusion[0-*]_beep`
- Chassis intrusion beep
-
- 0: disable
- 1: enable
-
- RW
+ Chassis intrusion beep.
****************************
Average sample configuration