by Guenter Roeck

[permalink] [raw]

Subject: Re: [PATCH v2 2/7] ABI: sysfs-class-hwmon: add ABI documentation for it

On 9/30/21 2:44 AM, Mauro Carvalho Chehab wrote:
> Move the ABI attributes documentation from:
> Documentation/hwmon/sysfs-interface.rst
>
The patche moves th documentation; it doesn't add it.
That should be reflected in the subject.

> 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 <[email protected]>
> ---
>
> See [PATCH v2 0/7] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/ABI/testing/sysfs-class-hwmon | 918 ++++++++++++++++++++
> Documentation/hwmon/sysfs-interface.rst | 596 +------------
> MAINTAINERS | 1 +
> 3 files changed, 961 insertions(+), 554 deletions(-)
> create mode 100644 Documentation/ABI/testing/sysfs-class-hwmon
>
> diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
> new file mode 100644
> index 000000000000..ea5a129ae082
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-hwmon
> @@ -0,0 +1,918 @@
> +What: /sys/class/hwmon/hwmonX/name
> +Description:
> + 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.

The above sentence is obsolete and should be removed. The name attribute is generated
automatically for all non-obsolete APIs.

> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/update_interval
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/inY_min
> +Description:
> + Voltage min value.
> +
> + Unit: millivolt
> +
> + RW
> +
The range of "Y" gets lost in those definitions. They are still retained in
the original file, so maybe tit doesn't matter. It seems a bit
incomplete, though.

> +What: /sys/class/hwmon/hwmonX/inY_lcrit
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/inY_max
> +Description:
> + Voltage max value.
> +
> + Unit: millivolt
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/inY_crit
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/inY_input
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/inY_average
> +Description:
> + Average voltage
> +
> + Unit: millivolt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/inY_lowest
> +Description:
> + Historical minimum voltage
> +
> + Unit: millivolt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/inY_highest
> +Description:
> + Historical maximum voltage
> +
> + Unit: millivolt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/inY_reset_history
> +Description:
> + Reset inX_lowest and inX_highest
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/in_reset_history
> +Description:
> + Reset inX_lowest and inX_highest for all sensors
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/inY_label
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/inY_enable
> +Description:
> + Enable or disable the sensors.
> +
> + When disabled the sensor read will return -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/cpuY_vid
> +Description:
> + CPU core reference voltage.
> +
> + Unit: millivolt
> +
> + RO
> +
> + Not always correct.
> +
> +What: /sys/class/hwmon/hwmonX/vrm
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/inY_rated_min
> +Description:
> + Minimum rated voltage.
> +
> + Unit: millivolt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/inY_rated_max
> +Description:
> + Maximum rated voltage.
> +
> + Unit: millivolt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/fanY_min
> +Description:
> + Fan minimum value
> +
> + Unit: revolution/min (RPM)
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/fanY_max
> +Description:
> + Fan maximum value
> +
> + Unit: revolution/min (RPM)
> +
> + Only rarely supported by the hardware.
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/fanY_input
> +Description:
> + Fan input value.
> +
> + Unit: revolution/min (RPM)
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/fanY_div
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/fanY_pulses
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/fanY_target
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/fanY_label
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/fanY_enable
> +Description:
> + Enable or disable the sensors.
> +
> + When disabled the sensor read will return -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/pwmY
> +Description:
> + Pulse width modulation fan control.
> +
> + Integer value in the range 0 to 255
> +
> + RW
> +
> + 255 is max or 100%.
> +
> +What: /sys/class/hwmon/hwmonX/pwmY_enable
> +Description:
> + Fan speed control method:
> +
> + - 0: no fan speed control (i.e. fan at full speed)
> + - 1: manual fan speed control enabled (using `pwmY`)
> + - 2+: automatic fan speed control enabled
> +
> + Check individual chip documentation files for automatic mode
> + details.
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/pwmY_mode
> +Description:
> + - 0: DC mode (direct current)
> + - 1: PWM mode (pulse-width modulation)
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/pwmY_freq
> +Description:
> + Base PWM frequency in Hz.
> +
> + Only possibly available when pwmN_mode is PWM, but not always
> + present even then.
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/pwmY_auto_channels_temp
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/pwmY_auto_pointZ_pwm
> +What: /sys/class/hwmon/hwmonX/pwmY_auto_pointZ_temp
> +What: /sys/class/hwmon/hwmonX/pwmY_auto_pointZ_temp_hyst
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/tempY_auto_pointZ_pwm
> +What: /sys/class/hwmon/hwmonX/tempY_auto_pointZ_temp
> +What: /sys/class/hwmon/hwmonX/tempY_auto_pointZ_temp_hyst
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/tempY_type
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/tempY_max
> +Description:
> + Temperature max value.
> +
> + Unit: millidegree Celsius (or millivolt, see below)
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_min
> +Description:
> + Temperature min value.
> +
> + Unit: millidegree Celsius
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_max_hyst
> +Description:
> + Temperature hysteresis value for max limit.
> +
> + Unit: millidegree Celsius
> +
> + Must be reported as an absolute temperature, NOT a delta
> + from the max value.
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_min_hyst
> +Description:
> + Temperature hysteresis value for min limit.
> + Unit: millidegree Celsius
> +
> + Must be reported as an absolute temperature, NOT a delta
> + from the min value.
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_input
> +Description:
> + Temperature input value.
> +
> + Unit: millidegree Celsius
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/tempY_crit
> +Description:
> + Temperature critical max value, typically greater than
> + corresponding temp_max values.
> +
> + Unit: millidegree Celsius
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_crit_hyst
> +Description:
> + Temperature hysteresis value for critical limit.
> +
> + Unit: millidegree Celsius
> +
> + Must be reported as an absolute temperature, NOT a delta
> + from the critical value.
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_emergency
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/tempY_emergency_hyst
> +Description:
> + Temperature hysteresis value for emergency limit.
> +
> + Unit: millidegree Celsius
> +
> + Must be reported as an absolute temperature, NOT a delta
> + from the emergency value.
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_lcrit
> +Description:
> + Temperature critical min value, typically lower than
> + corresponding temp_min values.
> +
> + Unit: millidegree Celsius
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_lcrit_hyst
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/tempY_offset
> +Description:
> + Temperature offset which is added to the temperature reading
> + by the chip.
> +
> + Unit: millidegree Celsius
> +
> + Read/Write value.
> +
> +What: /sys/class/hwmon/hwmonX/tempY_label
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/tempY_lowest
> +Description:
> + Historical minimum temperature
> +
> + Unit: millidegree Celsius
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/tempY_highest
> +Description:
> + Historical maximum temperature
> +
> + Unit: millidegree Celsius
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/tempY_reset_history
> +Description:
> + Reset temp_lowest and temp_highest
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/temp_reset_history
> +Description:
> + Reset temp_lowest and temp_highest for all sensors
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/tempY_enable
> +Description:
> + Enable or disable the sensors.
> +
> + When disabled the sensor read will return -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/tempY_rated_min
> +Description:
> + Minimum rated temperature.
> +
> + Unit: millidegree Celsius
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/tempY_rated_max
> +Description:
> + Maximum rated temperature.
> +
> + Unit: millidegree Celsius
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/currY_max
> +Description:
> + Current max value
> +
> + Unit: milliampere
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/currY_min
> +Description:
> + Current min value.
> +
> + Unit: milliampere
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/currY_lcrit
> +Description:
> + Current critical low value
> +
> + Unit: milliampere
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/currY_crit
> +Description:
> + Current critical high value.
> +
> + Unit: milliampere
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/currY_input
> +Description:
> + Current input value
> +
> + Unit: milliampere
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/currY_average
> +Description:
> + Average current use
> +
> + Unit: milliampere
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/currY_lowest
> +Description:
> + Historical minimum current
> +
> + Unit: milliampere
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/currY_highest
> +Description:
> + Historical maximum current
> + Unit: milliampere
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/currY_reset_history
> +Description:
> + Reset currX_lowest and currX_highest
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/curr_reset_history
> +Description:
> + Reset currX_lowest and currX_highest for all sensors
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/currY_enable
> +Description:
> + Enable or disable the sensors.
> +
> + When disabled the sensor read will return -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/currY_rated_min
> +Description:
> + Minimum rated current.
> +
> + Unit: milliampere
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/currY_rated_max
> +Description:
> + Maximum rated current.
> +
> + Unit: milliampere
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average
> +Description:
> + Average power use
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_interval
> +Description:
> + Power use averaging interval. A poll
> + notification is sent to this file if the
> + hardware changes the averaging interval.
> +
> + Unit: milliseconds
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_interval_max
> +Description:
> + Maximum power use averaging interval
> +
> + Unit: milliseconds
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_interval_min
> +Description:
> + Minimum power use averaging interval
> +
> + Unit: milliseconds
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_highest
> +Description:
> + Historical average maximum power use
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_lowest
> +Description:
> + Historical average minimum power use
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_max
> +Description:
> + A poll notification is sent to
> + `powerY_average` when power use
> + rises above this value.
> +
> + Unit: microWatt
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/powerY_average_min
> +Description:
> + A poll notification is sent to
> + `powerY_average` when power use
> + sinks below this value.
> +
> + Unit: microWatt
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/powerY_input
> +Description:
> + Instantaneous power use
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_input_highest
> +Description:
> + Historical maximum power use
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_input_lowest
> +Description:
> + Historical minimum power use
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_reset_history
> +Description:
> + Reset input_highest, input_lowest,
> + average_highest and average_lowest.
> +
> + WO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_accuracy
> +Description:
> + Accuracy of the power meter.
> +
> + Unit: Percent
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_cap
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/powerY_cap_hyst
> +Description:
> + Margin of hysteresis built around capping and
> + notification.
> +
> + Unit: microWatt
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/powerY_cap_max
> +Description:
> + Maximum cap that can be set.
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_cap_min
> +Description:
> + Minimum cap that can be set.
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_max
> +Description:
> + Maximum power.
> +
> + Unit: microWatt
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/powerY_crit
> +Description:
> + 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
> +
> +What: /sys/class/hwmon/hwmonX/powerY_enable
> +Description:
> + Enable or disable the sensors.
> +
> + When disabled the sensor read will return
> + -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/powerY_rated_min
> +Description:
> + Minimum rated power.
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/powerY_rated_max
> +Description:
> + Maximum rated power.
> +
> + Unit: microWatt
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/energyY_input
> +Description:
> + Cumulative energy use
> +
> + Unit: microJoule
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/energyY_enable
> +Description:
> + Enable or disable the sensors.
> +
> + When disabled the sensor read will return
> + -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/humidityY_input
> +Description:
> + Humidity
> +
> + Unit: milli-percent (per cent mille, pcm)
> +
> + RO
> +
> +
> +What: /sys/class/hwmon/hwmonX/humidityY_enable
> +Description:
> + Enable or disable the sensors
> +
> + When disabled the sensor read will return
> + -ENODATA.
> +
> + - 1: Enable
> + - 0: Disable
> +
> + RW
> +
> +What: /sys/class/hwmon/hwmonX/humidityY_rated_min
> +Description:
> + Minimum rated humidity.
> +
> + Unit: milli-percent (per cent mille, pcm)
> +
> + RO
> +
> +What: /sys/class/hwmon/hwmonX/humidityY_rated_max
> +Description:
> + Maximum rated humidity.
> +
> + Unit: milli-percent (per cent mille, pcm)
> +
> + RO
> +
> +
> +What: /sys/class/hwmon/hwmonX/intrusionY_alarm
> +Description:
> + 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.
> +
> +What: /sys/class/hwmon/hwmonX/intrusionY_beep
> +Description:
> + Chassis intrusion beep
> +
> + - 0: disable
> + - 1: enable
> +
> + RW
> 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
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 179eadaebe76..e9fd362ef4d6 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8274,6 +8274,7 @@ L: [email protected]
> S: Maintained
> W: http://hwmon.wiki.kernel.org/
> T: git git://git.kernel.org/pub/scm/linux/kernel/git/groeck/linux-staging.git
> +F: Documentation/ABI/testing/sysfs-class-hwmon
> F: Documentation/devicetree/bindings/hwmon/
> F: Documentation/hwmon/
> F: drivers/hwmon/
>

2021-10-08 14:57:09

by Guenter Roeck

[permalink] [raw]

Subject: Re: [PATCH v2 3/7] ABI: sysfs-class-hwmon: add a description for tempY_crit_alarm

On 9/30/21 2:44 AM, Mauro Carvalho Chehab wrote:
> Such ABI symbol is currently not described. Document it.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> See [PATCH v2 0/7] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/ABI/testing/sysfs-class-hwmon | 14 ++++++++++++++
> 1 file changed, 14 insertions(+)
>
> diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
> index ea5a129ae082..1f20687def44 100644
> --- a/Documentation/ABI/testing/sysfs-class-hwmon
> +++ b/Documentation/ABI/testing/sysfs-class-hwmon
> @@ -410,6 +410,20 @@ Description:
>
> RW
>
> +What: /sys/class/hwmon/hwmonX/tempY_crit_alarm
> +Description:
> + Critical high temperature alarm flag.
> +
> + - 0: OK
> + - 1: temperature has reached tempY_crit
> +
> + 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.
> +

That is not really correct. It _may_ be current implementation for some drivers,
but such an implementation would not be correct. The proper implementation would
be to auto-clear the flag after it was read unless the condition persists.

> What: /sys/class/hwmon/hwmonX/tempY_crit_hyst
> Description:
> Temperature hysteresis value for critical limit.
>

This should be documented as part of the previous patch, together with
all other alarm attributes.

Guenter