Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756557AbdLVSKf (ORCPT ); Fri, 22 Dec 2017 13:10:35 -0500 Received: from mail-pf0-f195.google.com ([209.85.192.195]:45865 "EHLO mail-pf0-f195.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755940AbdLVSKb (ORCPT ); Fri, 22 Dec 2017 13:10:31 -0500 X-Google-Smtp-Source: ACJfBosI5qdd3nJYtFT/VuaydDCpbJB+6LcDSWBSjLOBOPIDbQg3Ufww+WZl83WH04G1gmrkDH3M6g== Date: Fri, 22 Dec 2017 10:10:28 -0800 From: Guenter Roeck To: Aishwarya Pant Cc: Jean Delvare , linux-hwmon@vger.kernel.org, linux-kernel@vger.kernel.org, David Frey , Pascal Sachs , julia.lawall@lip6.fr Subject: Re: [PATCH] hwmon: (sht3x) move sysfs documentation to Documentation/ABI Message-ID: <20171222181028.GB15397@roeck-us.net> References: <20171222172604.GA9918@mordor.localdomain> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20171222172604.GA9918@mordor.localdomain> User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 8574 Lines: 216 On Fri, Dec 22, 2017 at 10:56:04PM +0530, Aishwarya Pant wrote: > The sysfs documentation for sht3x devices should be with the rest of the > interfaces in Documentation/ABI. The motivation behind this is that > documentation should be where the user expects it to be, rather than > where the developer expects it to be. > > ABI documentation requires a specific format and this is how the > information in it was filled- > > What: sht3x is an i2c device so it would be connected to the > i2c bus > Date: from the commit date that introduced the attribute > KernelVersion: from the first stable version git tag that contains the > commit > Contact: module author(s) > Description: from Documentation/hwmon/sht3x > > Signed-off-by: Aishwarya Pant Nack - I don't want to have to deal with two sets of locations for hwmon documentations, and the ABI documentation is terrible when it comes to documenting a driver with a generic ABI (and I really do not want to have to maintain all those entries below). Last but not least, the locations below are wrong: the official location for hwmon device attributes is /sys/class/hwmon/...; anything else is arbitrary and _not_ part of the hwmon sysfs ABI. Guenter > --- > > There are things that might be wrong here and I am unsure of- > 1. Whether this file should be in stable or testing? > 2. Contact information, full sysfs path etc > > I am doing this is in an exercise to move sysfs documentation to its right > place and identify places where it might be missing. hwmon drivers seem to have > a quite nice documentation, but just not in the ABI format. > Mostly for historic reasons. > Documentation/ABI/stable/sysfs-bus-i2c-hwmon-sht3x | 128 +++++++++++++++++++++ > Documentation/hwmon/sht3x | 25 ---- > 2 files changed, 128 insertions(+), 25 deletions(-) > create mode 100644 Documentation/ABI/stable/sysfs-bus-i2c-hwmon-sht3x > > diff --git a/Documentation/ABI/stable/sysfs-bus-i2c-hwmon-sht3x b/Documentation/ABI/stable/sysfs-bus-i2c-hwmon-sht3x > new file mode 100644 > index 000000000000..0e8355c625f5 > --- /dev/null > +++ b/Documentation/ABI/stable/sysfs-bus-i2c-hwmon-sht3x > @@ -0,0 +1,128 @@ > +What: /sys/bus/i2c/devices/.../temp1_input > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RO) Temperature input value > + Unit: millidegree Celsius > + > +What: /sys/bus/i2c/devices/.../temp1_max > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) Temperature max value. > + Unit: millidegree Celsius > + > +What: /sys/bus/i2c/devices/.../temp1_max_hyst > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) Temperature hysteresis value for max limit > + Unit: millidegree Celsius > + > +What: /sys/bus/i2c/devices/.../temp1_min > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) Temperature min value > + Unit: millidegree Celsius > + > +What: /sys/bus/i2c/devices/.../temp1_min_hyst > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) Temperature hysteresis value for min limit. > + Unit: millidegree Celsius > + > +What: /sys/bus/i2c/devices/.../temp1_alarm > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RO) Channel alarm > + 0: no alarm > + 1: alarm is set when the temperature is outside the configured > + limits. > + Only works in periodic measure mode > + > +What: /sys/bus/i2c/devices/.../humidity1_input > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RO) humidity input > + Unit: milli-percent > + > +What: /sys/bus/i2c/devices/.../humidity1_max > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) humidity max value > + Unit: milli-percent > + > +What: /sys/bus/i2c/devices/.../humidity1_max_hyst > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) humidity hysteresis value for max limit > + Unit: milli-percent > + > +What: /sys/bus/i2c/devices/.../humidity1_min > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) humidity min value > + Unit: milli-percent > + > +What: /sys/bus/i2c/devices/.../humidity1_min_hyst > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) humidity hysteresis value for min limit > + Unit: milli-percent > + > +What: /sys/bus/i2c/devices/.../humidity1_alarm > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RO) humidity alarm > + 0: no alarm > + 1: alarm is set when the humidity is outside the configured > + limits > + Only works in periodic measure mode > + > +What: /sys/bus/i2c/devices/.../heater_enable > +Date: July 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) Enable on-chip heater to remove excess humidity from sensor > + 0: turned off > + 1: turned on > + > +What: /sys/bus/i2c/devices/.../update_interval > +Date: June 2016 > +KernelVersion: 4.8 > +Contact: David Frey , > + Pascal Sachs > +Description: (RW) value is 0 for single shot, otherwise it is interval in > + msec for periodic measurement. > + The allowed update_interval in milliseconds are as follows: > + * 0 single shot mode > + * 2000 0.5 Hz periodic measurement > + * 1000 1 Hz periodic measurement > + * 500 2 Hz periodic measurement > + * 250 4 Hz periodic measurement > + * 100 10 Hz periodic measurement > + If the interval is not supported by the sensor, the next faster > + interval is chosen. > + Unit: milliseconds > diff --git a/Documentation/hwmon/sht3x b/Documentation/hwmon/sht3x > index b0d88184f48e..744dc9b00e8b 100644 > --- a/Documentation/hwmon/sht3x > +++ b/Documentation/hwmon/sht3x > @@ -49,28 +49,3 @@ the alert pin on the sensor is set to high. > When the temperature and humidity readings move back between the hysteresis > values, the alert bit is set to 0 and the alert pin on the sensor is set to > low. > - > -sysfs-Interface > ---------------- > - > -temp1_input: temperature input > -humidity1_input: humidity input > -temp1_max: temperature max value > -temp1_max_hyst: temperature hysteresis value for max limit > -humidity1_max: humidity max value > -humidity1_max_hyst: humidity hysteresis value for max limit > -temp1_min: temperature min value > -temp1_min_hyst: temperature hysteresis value for min limit > -humidity1_min: humidity min value > -humidity1_min_hyst: humidity hysteresis value for min limit > -temp1_alarm: alarm flag is set to 1 if the temperature is outside the > - configured limits. Alarm only works in periodic measure mode > -humidity1_alarm: alarm flag is set to 1 if the humidity is outside the > - configured limits. Alarm only works in periodic measure mode > -heater_enable: heater enable, heating element removes excess humidity from > - sensor > - 0: turned off > - 1: turned on > -update_interval: update interval, 0 for single shot, interval in msec > - for periodic measurement. If the interval is not supported > - by the sensor, the next faster interval is chosen > -- > 2.15.1 >