w1: w1_therm: Add sysfs entries to control conversion time and driver features

The conversion time of common DS18B20 clones deviates from
datasheet specs. Allow adjustment and automatic measure of the
conversion time.

Add 'conv_time' sysfs attribute:
  *read*: Current conversion time in milliseconds.
  *write*:
     '0': Set default conversion time.
     '1': Measure and set the conversion time. Make a
          single temperature conversion, poll and measure
          an actual value. Measured value is increased
          by 20% for temperature drift. A new conversion
          time is returned by reading the same attribute.
     other positive value:
        Set the conversion time in milliseconds.

The setting is active until a resolution change. Then it is reset to
default conversion time for a new resolution.

Add 'features' sysfs attribute to control optional driver settings
per device. Bit masks to read/write (logical OR):
  1: Enable check for conversion success. If byte 6 of
     scratchpad memory is 0xC after conversion, and
     temperature reads 85.00 (powerup value) or 127.94
     (insufficient power) - return a conversion error.

  2: Enable poll for conversion completion. Generate read cycles
     after the conversion start and wait for 1's. In parasite
     power mode this feature is not available.

There are some clones of DS18B20 with fixed 12 bit resolution. Make the
driver verify the resolution by reading back the device after resolution
change.

Signed-off-by: Ivan Zaentsev <ivan.zaentsev@wirenboard.ru>
Acked-by: Evgeniy Polyakov <zbr@ioremap.net>
Link: https://lore.kernel.org/r/20200904160004.87710-1-ivan.zaentsev@wirenboard.ru
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

1 files changed, 32 insertions, 5 deletions

diff --git a/Documentation/w1/slaves/w1_therm.rst b/Documentation/w1/slaves/w1_therm.rst
index cc4edae17751..f1148181f53e 100644
--- a/Documentation/w1/slaves/w1_therm.rst
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -52,6 +52,19 @@ read is sent but one sensor is not read immediately, the next access to
 temperature on this device will return the temperature measured at the
 time of issue of the bulk read command (not the current temperature).
 
+A strong pullup will be applied during the conversion if required.
+
+``conv_time`` sysfs entry is used to get current conversion time (read), and
+adjust it (write). A temperature conversion time depends on the device type and
+it's current resolution. Default conversion time is set by the driver according
+to the device datasheet. A conversion time for many original device clones
+deviate from datasheet specs. There are three options: 1) manually set the
+correct conversion time by writing a value in milliseconds to ``conv_time``; 2)
+auto measure and set a conversion time by writing ``1`` to
+``conv_time``; 3) use ``features`` entry to enable poll for conversion
+completion. Options 2, 3 can't be used in parasite power mode. To get back to
+the default conversion time write ``0`` to ``conv_time``.
+
 Writing a value between 9 and 12 to the sysfs w1_slave file will change the
 precision of the sensor for the next readings. This value is in (volatile)
 SRAM, so it is reset when the sensor gets power-cycled.
@@ -61,11 +74,14 @@ has to be written to the sysfs w1_slave file. Since the EEPROM has a limited
 amount of writes (>50k), this command should be used wisely.
 
 Alternatively, resolution can be set or read (value from 9 to 12) using the
-dedicated resolution sysfs entry on each device. This sysfs entry is not
-present for devices not supporting this feature. Driver will adjust the
-correct conversion time for each device regarding to its resolution setting.
-In particular, strong pullup will be applied if required during the conversion
-duration.
+dedicated resolution sysfs entry on each device. This sysfs entry is not present
+for devices not supporting this feature.
+
+Some non-genuine DS18B20 chips are
+fixed in 12-bit mode only, so the actual resolution is read back from the chip
+and verified by the driver.
+
+Note: Changing the resolution reverts the conversion time to default.
 
 The write-only sysfs entry eeprom is an alternative for EEPROM operations:
   * 'save': will save device RAM to EEPROM
@@ -104,3 +120,14 @@ location of the chip in the 1-wire bus without needing pre-existing
 knowledge of the bus ordering.  Support is provided through the sysfs
 w1_seq file.  The file will contain a single line with an integer value
 representing the device index in the bus starting at 0.
+
+``features`` sysfs entry controls optional driver settings per device.
+Insufficient power in parasite mode, line noise and insufficient conversion time
+may lead to conversion failure. Original DS18B20 and some clones allow for
+detection of invalid conversion. Write bit mask ``1`` to ``features`` to enable
+checking the conversion success. If byte 6 of scratchpad memory is 0xC after
+conversion and temperature reads 85.00 (powerup value) or 127.94 (insufficient
+power), the driver returns a conversion error. Bit mask ``2`` enables poll for
+conversion completion (normal power only) by generating read cycles on the bus
+after conversion starts. In parasite power mode this feature is not available.
+Feature bit masks may be combined (OR).