diff options
Diffstat (limited to 'Documentation/w1')
| -rw-r--r-- | Documentation/w1/masters/ds2490.rst | 2 | ||||
| -rw-r--r-- | Documentation/w1/masters/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/w1/masters/omap-hdq.rst | 2 | ||||
| -rw-r--r-- | Documentation/w1/masters/w1-gpio.rst | 2 | ||||
| -rw-r--r-- | Documentation/w1/masters/w1-uart.rst | 54 | ||||
| -rw-r--r-- | Documentation/w1/slaves/w1_ds2438.rst | 19 | ||||
| -rw-r--r-- | Documentation/w1/slaves/w1_therm.rst | 108 | ||||
| -rw-r--r-- | Documentation/w1/w1-generic.rst | 4 | ||||
| -rw-r--r-- | Documentation/w1/w1-netlink.rst | 2 |
9 files changed, 168 insertions, 26 deletions
diff --git a/Documentation/w1/masters/ds2490.rst b/Documentation/w1/masters/ds2490.rst index 7e5b50f9c0f5..842e7ae80424 100644 --- a/Documentation/w1/masters/ds2490.rst +++ b/Documentation/w1/masters/ds2490.rst @@ -52,7 +52,7 @@ Notes and limitations. clear the entire bulk in buffer. It would be possible to read the maximum buffer size to not run into this error condition, only extra bytes in the buffer is a logic error in the driver. The code should - should match reads and writes as well as data sizes. Reads and + match reads and writes as well as data sizes. Reads and writes are serialized and the status verifies that the chip is idle (and data is available) before the read is executed, so it should not happen. diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst index 4442a98850ad..cc40189909fd 100644 --- a/Documentation/w1/masters/index.rst +++ b/Documentation/w1/masters/index.rst @@ -12,3 +12,4 @@ mxc-w1 omap-hdq w1-gpio + w1-uart diff --git a/Documentation/w1/masters/omap-hdq.rst b/Documentation/w1/masters/omap-hdq.rst index 345298a59e50..5347b5d9e90a 100644 --- a/Documentation/w1/masters/omap-hdq.rst +++ b/Documentation/w1/masters/omap-hdq.rst @@ -44,7 +44,7 @@ that the ID used should be same for both master and slave driver loading. e.g:: insmod omap_hdq.ko W1_ID=2 - inamod w1_bq27000.ko F_ID=2 + insmod w1_bq27000.ko F_ID=2 The driver also supports 1-wire mode. In this mode, there is no need to pass slave ID as parameter. The driver will auto-detect slaves connected diff --git a/Documentation/w1/masters/w1-gpio.rst b/Documentation/w1/masters/w1-gpio.rst index 18fdb7366372..15236605503b 100644 --- a/Documentation/w1/masters/w1-gpio.rst +++ b/Documentation/w1/masters/w1-gpio.rst @@ -11,7 +11,7 @@ Description GPIO 1-wire bus master driver. The driver uses the GPIO API to control the wire and the GPIO pin can be specified using GPIO machine descriptor tables. It is also possible to define the master using device tree, see -Documentation/devicetree/bindings/w1/w1-gpio.txt +Documentation/devicetree/bindings/w1/w1-gpio.yaml Example (mach-at91) diff --git a/Documentation/w1/masters/w1-uart.rst b/Documentation/w1/masters/w1-uart.rst new file mode 100644 index 000000000000..8d0f122178d4 --- /dev/null +++ b/Documentation/w1/masters/w1-uart.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +===================== +Kernel driver w1-uart +===================== + +Author: Christoph Winklhofer <cj.winklhofer@gmail.com> + + +Description +----------- + +UART 1-Wire bus driver. The driver utilizes the UART interface via the +Serial Device Bus to create the 1-Wire timing patterns as described in +the document `"Using a UART to Implement a 1-Wire Bus Master"`_. + +.. _"Using a UART to Implement a 1-Wire Bus Master": https://www.analog.com/en/technical-articles/using-a-uart-to-implement-a-1wire-bus-master.html + +In short, the UART peripheral must support full-duplex and operate in +open-drain mode. The timing patterns are generated by a specific +combination of baud-rate and transmitted byte, which corresponds to a +1-Wire read bit, write bit or reset pulse. + +For instance the timing pattern for a 1-Wire reset and presence detect uses +the baud-rate 9600, i.e. 104.2 us per bit. The transmitted byte 0xf0 over +UART (least significant bit first, start-bit low) sets the reset low time +for 1-Wire to 521 us. A present 1-Wire device changes the received byte by +pulling the line low, which is used by the driver to evaluate the result of +the 1-Wire operation. + +Similar for a 1-Wire read bit or write bit, which uses the baud-rate +115200, i.e. 8.7 us per bit. The transmitted byte 0x80 is used for a +Write-0 operation (low time 69.6us) and the byte 0xff for Read-0, Read-1 +and Write-1 (low time 8.7us). + +The default baud-rate for reset and presence detection is 9600 and for +a 1-Wire read or write operation 115200. In case the actual baud-rate +is different from the requested one, the transmitted byte is adapted +to generate the 1-Wire timing patterns. + + +Usage +----- + +Specify the UART 1-wire bus in the device tree by adding the single child +onewire to the serial node (e.g. uart0). For example: +:: + + @uart0 { + ... + onewire { + compatible = "w1-uart"; + }; + }; diff --git a/Documentation/w1/slaves/w1_ds2438.rst b/Documentation/w1/slaves/w1_ds2438.rst index a29309a3f8e5..4fa671fbc93f 100644 --- a/Documentation/w1/slaves/w1_ds2438.rst +++ b/Documentation/w1/slaves/w1_ds2438.rst @@ -22,7 +22,7 @@ is also often used in weather stations and applications such as: rain gauge, wind speed/direction measuring, humidity sensing, etc. Current support is provided through the following sysfs files (all files -except "iad" are readonly): +except "iad" and "offset" are readonly): "iad" ----- @@ -44,6 +44,23 @@ Internally when this file is read, the additional CRC byte is also obtained from the slave device. If it is correct, the 8 bytes page data are passed to userspace, otherwise an I/O error is returned. +"page1" +------- +This file provides full 8 bytes of the chip Page 1 (01h). +This page contains the ICA, elapsed time meter and current offset data of the DS2438. +Internally when this file is read, the additional CRC byte is also obtained +from the slave device. If it is correct, the 8 bytes page data are passed +to userspace, otherwise an I/O error is returned. + +"offset" +-------- +This file controls the 2-byte Offset Register of the chip. +Writing a 2-byte value will change the Offset Register, which changes the +current measurement done by the chip. Changing this register to the two's complement +of the current register while forcing zero current through the load will calibrate +the chip, canceling offset errors in the current ADC. + + "temperature" ------------- Opening and reading this file initiates the CONVERT_T (temperature conversion) diff --git a/Documentation/w1/slaves/w1_therm.rst b/Documentation/w1/slaves/w1_therm.rst index 90531c340a07..6aec04dd0905 100644 --- a/Documentation/w1/slaves/w1_therm.rst +++ b/Documentation/w1/slaves/w1_therm.rst @@ -6,6 +6,8 @@ Supported chips: * Maxim ds18*20 based temperature sensors. * Maxim ds1825 based temperature sensors. + * GXCAS GX20MH01 temperature sensor. + * Maxim MAX31850 thermoelement interface. Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru> @@ -13,8 +15,8 @@ Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru> Description ----------- -w1_therm provides basic temperature conversion for ds18*20 devices, and the -ds28ea00 device. +w1_therm provides basic temperature conversion for ds18*20, ds28ea00, GX20MH01 +and MAX31850 devices. Supported family codes: @@ -26,28 +28,73 @@ W1_THERM_DS1825 0x3B W1_THERM_DS28EA00 0x42 ==================== ==== -Support is provided through the sysfs w1_slave file. Each open and -read sequence will initiate a temperature conversion then provide two -lines of ASCII output. The first line contains the nine hex bytes +Support is provided through the sysfs entry ``w1_slave``. Each open and +read sequence will initiate a temperature conversion, then provide two +lines of ASCII output. The first line contains the nine hex bytes read along with a calculated crc value and YES or NO if it matched. -If the crc matched the returned values are retained. The second line +If the crc matched the returned values are retained. The second line displays the retained values along with a temperature in millidegrees Centigrade after t=. -Parasite powered devices are limited to one slave performing a -temperature conversion at a time. If none of the devices are parasite -powered it would be possible to convert all the devices at the same -time and then go back to read individual sensors. That isn't -currently supported. The driver also doesn't support reduced -precision (which would also reduce the conversion time) when reading values. +Alternatively, temperature can be read using ``temperature`` sysfs, it +returns only the temperature in millidegrees Centigrade. -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. +A bulk read of all devices on the bus could be done writing ``trigger`` +to ``therm_bulk_read`` entry at w1_bus_master level. This will +send the convert command to all devices on the bus, and if parasite +powered devices are detected on the bus (and strong pullup is enabled +in the module), it will drive the line high during the longer conversion +time required by parasited powered device on the line. Reading +``therm_bulk_read`` will return 0 if no bulk conversion pending, +-1 if at least one sensor still in conversion, 1 if conversion is complete +but at least one sensor value has not been read yet. Result temperature is +then accessed by reading the ``temperature`` entry of each device, which +may return empty if conversion is still in progress. Note that if a bulk +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). -To store the current precision configuration into EEPROM, the value 0 -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. +A strong pullup will be applied during the conversion if required. + +``conv_time`` is used to get current conversion time (read), and +adjust it (write). A temperature conversion time depends on the device type and +its 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`` 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 resolution value (in bits) to ``w1_slave`` will change the +precision of the sensor for the next readings. Allowed resolutions are defined by +the sensor. Resolution is reset when the sensor gets power-cycled. + +To store the current resolution in EEPROM, write ``0`` to ``w1_slave``. +Since the EEPROM has a limited amount of writes (>50k), this command should be +used wisely. + +Alternatively, resolution can be read or written using the dedicated +``resolution`` entry on each device, if supported by the sensor. + +Some non-genuine DS18B20 chips are fixed in 12-bit mode only, so the actual +resolution is read back from the chip and verified. + +Note: Changing the resolution reverts the conversion time to default. + +The write-only sysfs entry ``eeprom_cmd`` is an alternative for EEPROM operations. +Write ``save`` to save device RAM to EEPROM. Write ``restore`` to restore EEPROM +data in device RAM. + +``ext_power`` entry allows checking the power state of each device. Reads +``0`` if the device is parasite powered, ``1`` if the device is externally powered. + +Sysfs ``alarms`` allow read or write TH and TL (Temperature High an Low) alarms. +Values shall be space separated and in the device range (typical -55 degC +to 125 degC). Values are integer as they are store in a 8bit register in +the device. Lowest value is automatically put to TL. Once set, alarms could +be search at master level. The module parameter strong_pullup can be set to 0 to disable the strong pullup, 1 to enable autodetection or 2 to force strong pullup. @@ -70,5 +117,28 @@ The DS28EA00 provides an additional two pins for implementing a sequence detection algorithm. This feature allows you to determine the physical 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 +``w1_seq``. 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). More details in +Documentation/ABI/testing/sysfs-driver-w1_therm + +GX20MH01 device shares family number 0x28 with DS18*20. The device is generally +compatible with DS18B20. Added are lowest 2\ :sup:`-5`, 2\ :sup:`-6` temperature +bits in Config register; R2 bit in Config register enabling 13 and 14 bit +resolutions. The device is powered up in 14-bit resolution mode. The conversion +times specified in the datasheet are too low and have to be increased. The +device supports driver features ``1`` and ``2``. + +MAX31850 device shares family number 0x3B with DS1825. The device is generally +compatible with DS1825. The higher 4 bits of Config register read all 1, +indicating 15, but the device is always operating in 14-bit resolution mode. diff --git a/Documentation/w1/w1-generic.rst b/Documentation/w1/w1-generic.rst index da4e8b4e9b01..96a042585fce 100644 --- a/Documentation/w1/w1-generic.rst +++ b/Documentation/w1/w1-generic.rst @@ -101,7 +101,7 @@ w1_master_search (rw) the number of searches left to do, w1_master_slave_count (ro) the number of slaves found w1_master_slaves (ro) the names of the slaves, one per line w1_master_timeout (ro) the delay in seconds between searches -w1_master_timeout_us (ro) the delay in microseconds beetwen searches +w1_master_timeout_us (ro) the delay in microseconds between searches ========================= ===================================================== If you have a w1 bus that never changes (you don't add or remove devices), @@ -113,7 +113,7 @@ generally only make sense when searching is disabled, as a search will redetect manually removed devices that are present and timeout manually added devices that aren't on the bus. -Bus searches occur at an interval, specified as a summ of timeout and +Bus searches occur at an interval, specified as a sum of timeout and timeout_us module parameters (either of which may be 0) for as long as w1_master_search remains greater than 0 or is -1. Each search attempt decrements w1_master_search by 1 (down to 0) and increments diff --git a/Documentation/w1/w1-netlink.rst b/Documentation/w1/w1-netlink.rst index aaa13243a5e4..be4f7b82dcb4 100644 --- a/Documentation/w1/w1-netlink.rst +++ b/Documentation/w1/w1-netlink.rst @@ -66,7 +66,7 @@ Each connector message can include one or more w1_netlink_msg with zero or more attached w1_netlink_cmd messages. For event messages there are no w1_netlink_cmd embedded structures, -only connector header and w1_netlink_msg strucutre with "len" field +only connector header and w1_netlink_msg structure with "len" field being zero and filled type (one of event types) and id: either 8 bytes of slave unique id in host order, or master's id, which is assigned to bus master device |