From 7ebd8b66dd9e5a0b65e5ee5e2b8e7ca382ec97b7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 17 Apr 2019 06:46:29 -0300 Subject: docs: hwmon: Add an index file and rename docs to *.rst Now that all files were converted to ReST format, rename them and add an index. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Guenter Roeck --- Documentation/hwmon/sysfs-interface | 1086 ----------------------------------- 1 file changed, 1086 deletions(-) delete mode 100644 Documentation/hwmon/sysfs-interface (limited to 'Documentation/hwmon/sysfs-interface') diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface deleted file mode 100644 index fd590633bb14..000000000000 --- a/Documentation/hwmon/sysfs-interface +++ /dev/null @@ -1,1086 +0,0 @@ -Naming and data format standards for sysfs files -================================================ - -The libsensors library offers an interface to the raw sensors data -through the sysfs interface. Since lm-sensors 3.0.0, libsensors is -completely chip-independent. It assumes that all the kernel drivers -implement the standard sysfs interface described in this document. -This makes adding or updating support for any given chip very easy, as -libsensors, 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 second -temperature sensor is connected to the CPU, or that the second fan is on -the CPU. Also, some values reported by the chips need some computation -before they make full sense. For example, most chips can only measure -voltages between 0 and +4V. Other voltages are scaled back into that -range using external resistors. Since the values of these resistors -can change from motherboard to motherboard, the conversions cannot be -hard 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 will -still require a configuration file (e.g. /etc/sensors.conf) for proper -values conversion, labeling of inputs and hiding of unused inputs. - -An alternative method that some programs use is to access the sysfs -files directly. This document briefly describes the standards that the -drivers follow, so that an application program can scan for entries and -access this data in a simple and consistent way. That said, such programs -will have to implement conversion, labeling and hiding of inputs. For -this reason, it is still not recommended to bypass the library. - -Each chip gets its own directory in the sysfs /sys/devices tree. To -find 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 attributes -in the "physical" device directory. Since lm-sensors 3.0.1, attributes found -in the hwmon "class" device directory are also supported. Complex drivers -(e.g. drivers for multifunction chips) may want to use this possibility to -avoid namespace pollution. The only drawback will be that older versions of -libsensors 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: _. Usual -types for sensor chips are "in" (voltage), "temp" (temperature) and -"fan" (fan). Usual items are "input" (measured value), "max" (high -threshold, "min" (low threshold). Numbering usually starts from 1, -except for voltages which start from 0 (because most data sheets use -this). A number is always used for elements that can be present more -than once, even if there is a single element of the given type on the -specific chip. Other files do not refer to a specific element, so -they have a simple name, and no number. - -Alarms are direct indications read from the chips. The drivers do NOT -make comparisons of readings to thresholds. This allows violations -between readings to be caught and alarmed. The exact definition of an -alarm (for example, whether a threshold must be met or must be exceeded -to cause an alarm) is chip-dependent. - -When setting values of hwmon sysfs attributes, the string representation of -the desired value must be written, note that strings which are not a number -are interpreted as 0! For more on how written strings are interpreted see the -"sysfs attribute writes interpretation" section at the end of this file. - -------------------------------------------------------------------------- - -======= =========================================== -`[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 the -hardware implementation. - -All entries (except name) are optional, and should only be created in a -given driver if the chip has the feature. - - -***************** -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. - - -******** -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. - -Also see the Alarms section for status flags associated with voltages. - - -**** -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. - - -*** -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 - -`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 -channels. In that case, the result is determined by the mapping between -temperature inputs and PWM outputs. When several temperature inputs are -mapped 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 candidate -value (fastest fan speed) wins. - - -************ -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 - -`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 - -`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 - -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 -mathematical functions not available in the kernel, so the conversion -must occur in user space. For these chips, all temp* files described -above should contain values expressed in millivolt instead of millidegree -Celsius. In other words, such temperature channels are handled as voltage -channels by the driver. - -Also see the Alarms section for status flags associated with temperatures. - - -******** -Currents -******** - -`curr[1-*]_max` - Current max value - - Unit: milliampere - - RW - -`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 - -`curr[1-*]_average` - Average current use - - Unit: milliampere - - RO - -`curr[1-*]_lowest` - Historical minimum current - - Unit: milliampere - - RO - -`curr[1-*]_highest` - Historical maximum current - Unit: milliampere - RO - -`curr[1-*]_reset_history` - Reset currX_lowest and currX_highest - - WO - -`curr_reset_history` - Reset currX_lowest and currX_highest for all sensors - - WO - -`curr[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 currents. - -***** -Power -***** - -`power[1-*]_average` - Average power use - - Unit: microWatt - - RO - -`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[1-*]_average_interval_max` - Maximum power use averaging interval - - Unit: milliseconds - - RO - -`power[1-*]_average_interval_min` - Minimum power use averaging interval - - Unit: milliseconds - - RO - -`power[1-*]_average_highest` - Historical average maximum power use - - Unit: microWatt - - RO - -`power[1-*]_average_lowest` - Historical average minimum power use - - Unit: microWatt - - RO - -`power[1-*]_average_max` - A poll notification is sent to - `power[1-*]_average` when power use - rises above this value. - - Unit: microWatt - - RW - -`power[1-*]_average_min` - A poll notification is sent to - `power[1-*]_average` when power use - sinks below this value. - - Unit: microWatt - - RW - -`power[1-*]_input` - Instantaneous power use - - Unit: microWatt - - RO - -`power[1-*]_input_highest` - Historical maximum power use - - Unit: microWatt - - RO - -`power[1-*]_input_lowest` - Historical minimum power use - - Unit: microWatt - - RO - -`power[1-*]_reset_history` - Reset input_highest, input_lowest, - average_highest and average_lowest. - - WO - -`power[1-*]_accuracy` - Accuracy of the power meter. - - Unit: Percent - - RO - -`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 - -`power[1-*]_cap_hyst` - Margin of hysteresis built around capping and - notification. - - Unit: microWatt - - RW - -`power[1-*]_cap_max` - Maximum cap that can be set. - - Unit: microWatt - - RO - -`power[1-*]_cap_min` - Minimum cap that can be set. - - Unit: microWatt - - RO - -`power[1-*]_max` - Maximum power. - - Unit: microWatt - - RW - -`power[1-*]_crit` - Critical maximum power. - - If power rises to or above this limit, the - system is expected take drastic action to reduce - power consumption, such as a system shutdown or - a forced powerdown of some devices. - - Unit: microWatt - - RW - -`power[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 power readings. - -****** -Energy -****** - -`energy[1-*]_input` - Cumulative energy use - - Unit: microJoule - - RO - -`energy[1-*]_enable` - Enable or disable the sensors. - - When disabled the sensor read will return - -ENODATA. - - - 1: Enable - - 0: Disable - - RW - -******** -Humidity -******** - -`humidity[1-*]_input` - Humidity - - Unit: milli-percent (per cent mille, pcm) - - RO - - -`humidity[1-*]_enable` - Enable or disable the sensors - - When disabled the sensor read will return - -ENODATA. - - - 1: Enable - - 0: Disable - - RW - -****** -Alarms -****** - -Each channel or limit may have an associated alarm file, containing a -boolean value. 1 means than an alarm condition exists, 0 means no alarm. - -Usually a given chip will either use channel-related alarms, or -limit-related alarms, not both. The driver should just reflect the hardware -implementation. - -+-------------------------------+-----------------------+ -| **`in[0-*]_alarm`, | Channel alarm | -| `curr[1-*]_alarm`, | | -| `power[1-*]_alarm`, | - 0: no alarm | -| `fan[1-*]_alarm`, | - 1: alarm | -| `temp[1-*]_alarm`** | | -| | RO | -+-------------------------------+-----------------------+ - -**OR** - -+-------------------------------+-----------------------+ -| **`in[0-*]_min_alarm`, | Limit alarm | -| `in[0-*]_max_alarm`, | | -| `in[0-*]_lcrit_alarm`, | - 0: no alarm | -| `in[0-*]_crit_alarm`, | - 1: alarm | -| `curr[1-*]_min_alarm`, | | -| `curr[1-*]_max_alarm`, | RO | -| `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`** | | -+-------------------------------+-----------------------+ - -Each input channel may have an associated fault file. This can be used -to notify open diodes, unconnected fans etc. where the hardware -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 - -Some chips also offer the possibility to get beeped when an alarm occurs: - -`beep_enable` - Master beep enable - - - 0: no beeps - - 1: beeps - - RW - -`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`, - Channel beep - - - 0: disable - - 1: enable - - RW - -In theory, a chip could provide per-limit beep masking, but no such chip -was seen so far. - -Old drivers provided a different, non-standard interface to alarms and -beeps. These interface files are deprecated, but will be kept around -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 - - -******************* -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. - -`intrusion[0-*]_beep` - Chassis intrusion beep - - 0: disable - 1: enable - - RW - -**************************** -Average sample configuration -**************************** - -Devices allowing for reading {in,power,curr,temp}_average values may export -attributes for controlling number of samples used to compute average. - -+--------------+---------------------------------------------------------------+ -| samples | Sets number of average samples for all types of measurements. | -| | | -| | RW | -+--------------+---------------------------------------------------------------+ -| in_samples | Sets number of average samples for specific type of | -| power_samples| measurements. | -| curr_samples | | -| temp_samples | Note that on some devices it won't be possible to set all of | -| | them to different values so changing one might also change | -| | some others. | -| | | -| | RW | -+--------------+---------------------------------------------------------------+ - -sysfs attribute writes interpretation -------------------------------------- - -hwmon sysfs attributes always contain numbers, so the first thing to do is to -convert the input to a number, there are 2 ways todo this depending whether -the 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 cannot -tell 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 of -code to the kernel. - -Notice that it is important to always store the converted value in an -unsigned long or long, so that no wrap around can happen before any further -checking. - -After the input string is converted to an (unsigned) long, the value should be -checked if its acceptable. Be careful with further conversions on the value -before checking it for validity, as these conversions could still cause a wrap -around before the check. For example do not multiply the result, and only -add/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 the -sysfs attribute that is being set. If it is a continuous setting like a -tempX_max or inX_max attribute, then the value should be clamped to its -limits using clamp_val(value, min_limit, max_limit). If it is not continuous -like 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 */ -- cgit v1.2.3