From e9bb627561535dd584b43a8c0afe93a67bc6a2c5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:53 -0300 Subject: docs: w1: convert to ReST and add to the kAPI group of docs The 1wire documentation was written with w1 developers in mind, so, it makes sense to add it together with the driver-api set. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/w1/slaves/index.rst | 16 ++++++++ Documentation/w1/slaves/w1_ds2406 | 25 ------------ Documentation/w1/slaves/w1_ds2406.rst | 27 +++++++++++++ Documentation/w1/slaves/w1_ds2413 | 50 ----------------------- Documentation/w1/slaves/w1_ds2413.rst | 59 +++++++++++++++++++++++++++ Documentation/w1/slaves/w1_ds2423 | 47 --------------------- Documentation/w1/slaves/w1_ds2423.rst | 54 +++++++++++++++++++++++++ Documentation/w1/slaves/w1_ds2438 | 63 ----------------------------- Documentation/w1/slaves/w1_ds2438.rst | 69 +++++++++++++++++++++++++++++++ Documentation/w1/slaves/w1_ds28e04 | 36 ----------------- Documentation/w1/slaves/w1_ds28e04.rst | 41 +++++++++++++++++++ Documentation/w1/slaves/w1_ds28e17 | 68 ------------------------------- Documentation/w1/slaves/w1_ds28e17.rst | 72 +++++++++++++++++++++++++++++++++ Documentation/w1/slaves/w1_therm | 67 ------------------------------ Documentation/w1/slaves/w1_therm.rst | 74 ++++++++++++++++++++++++++++++++++ 15 files changed, 412 insertions(+), 356 deletions(-) create mode 100644 Documentation/w1/slaves/index.rst delete mode 100644 Documentation/w1/slaves/w1_ds2406 create mode 100644 Documentation/w1/slaves/w1_ds2406.rst delete mode 100644 Documentation/w1/slaves/w1_ds2413 create mode 100644 Documentation/w1/slaves/w1_ds2413.rst delete mode 100644 Documentation/w1/slaves/w1_ds2423 create mode 100644 Documentation/w1/slaves/w1_ds2423.rst delete mode 100644 Documentation/w1/slaves/w1_ds2438 create mode 100644 Documentation/w1/slaves/w1_ds2438.rst delete mode 100644 Documentation/w1/slaves/w1_ds28e04 create mode 100644 Documentation/w1/slaves/w1_ds28e04.rst delete mode 100644 Documentation/w1/slaves/w1_ds28e17 create mode 100644 Documentation/w1/slaves/w1_ds28e17.rst delete mode 100644 Documentation/w1/slaves/w1_therm create mode 100644 Documentation/w1/slaves/w1_therm.rst (limited to 'Documentation/w1/slaves') diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst new file mode 100644 index 000000000000..d0697b202f09 --- /dev/null +++ b/Documentation/w1/slaves/index.rst @@ -0,0 +1,16 @@ +. SPDX-License-Identifier: GPL-2.0 + +==================== +1-wire Slave Drivers +==================== + +.. toctree:: + :maxdepth: 1 + + w1_ds2406 + w1_ds2413 + w1_ds2423 + w1_ds2438 + w1_ds28e04 + w1_ds28e17 + w1_therm diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406 deleted file mode 100644 index 8137fe6f6c3d..000000000000 --- a/Documentation/w1/slaves/w1_ds2406 +++ /dev/null @@ -1,25 +0,0 @@ -w1_ds2406 kernel driver -======================= - -Supported chips: - * Maxim DS2406 (and other family 0x12) addressable switches - -Author: Scott Alfter - -Description ------------ - -The w1_ds2406 driver allows connected devices to be switched on and off. -These chips also provide 128 bytes of OTP EPROM, but reading/writing it is -not supported. In TSOC-6 form, the DS2406 provides two switch outputs and -can be provided with power on a dedicated input. In TO-92 form, it provides -one output and uses parasitic power only. - -The driver provides two sysfs files. state is readable; it gives the -current state of each switch, with PIO A in bit 0 and PIO B in bit 1. The -driver ORs this state with 0x30, so shell scripts get an ASCII 0/1/2/3 to -work with. output is writable; bits 0 and 1 control PIO A and B, -respectively. Bits 2-7 are ignored, so it's safe to write ASCII data. - -CRCs are checked on read and write. Failed checks cause an I/O error to be -returned. On a failed write, the switch status is not changed. diff --git a/Documentation/w1/slaves/w1_ds2406.rst b/Documentation/w1/slaves/w1_ds2406.rst new file mode 100644 index 000000000000..d3e68266084f --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2406.rst @@ -0,0 +1,27 @@ +======================= +w1_ds2406 kernel driver +======================= + +Supported chips: + + * Maxim DS2406 (and other family 0x12) addressable switches + +Author: Scott Alfter + +Description +----------- + +The w1_ds2406 driver allows connected devices to be switched on and off. +These chips also provide 128 bytes of OTP EPROM, but reading/writing it is +not supported. In TSOC-6 form, the DS2406 provides two switch outputs and +can be provided with power on a dedicated input. In TO-92 form, it provides +one output and uses parasitic power only. + +The driver provides two sysfs files. state is readable; it gives the +current state of each switch, with PIO A in bit 0 and PIO B in bit 1. The +driver ORs this state with 0x30, so shell scripts get an ASCII 0/1/2/3 to +work with. output is writable; bits 0 and 1 control PIO A and B, +respectively. Bits 2-7 are ignored, so it's safe to write ASCII data. + +CRCs are checked on read and write. Failed checks cause an I/O error to be +returned. On a failed write, the switch status is not changed. diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413 deleted file mode 100644 index 936263a8ccb4..000000000000 --- a/Documentation/w1/slaves/w1_ds2413 +++ /dev/null @@ -1,50 +0,0 @@ -Kernel driver w1_ds2413 -======================= - -Supported chips: - * Maxim DS2413 1-Wire Dual Channel Addressable Switch - -supported family codes: - W1_FAMILY_DS2413 0x3A - -Author: Mariusz Bialonczyk - -Description ------------ - -The DS2413 chip has two open-drain outputs (PIO A and PIO B). -Support is provided through the sysfs files "output" and "state". - -Reading state -------------- -The "state" file provides one-byte value which is in the same format as for -the chip PIO_ACCESS_READ command (refer the datasheet for details): - -Bit 0: PIOA Pin State -Bit 1: PIOA Output Latch State -Bit 2: PIOB Pin State -Bit 3: PIOB Output Latch State -Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module) - -This file is readonly. - -Writing output --------------- -You can set the PIO pins using the "output" file. -It is writable, you can write one-byte value to this sysfs file. -Similarly the byte format is the same as for the PIO_ACCESS_WRITE command: - -Bit 0: PIOA -Bit 1: PIOB -Bit 2-7: No matter (driver will set it to "1"s) - - -The chip has some kind of basic protection against transmission errors. -When reading the state, there is a four complement bits. -The driver is checking this complement, and when it is wrong then it is -returning I/O error. - -When writing output, the master must repeat the PIO Output Data byte in -its inverted form and it is waiting for a confirmation. -If the write is unsuccessful for three times, the write also returns -I/O error. diff --git a/Documentation/w1/slaves/w1_ds2413.rst b/Documentation/w1/slaves/w1_ds2413.rst new file mode 100644 index 000000000000..c15bb5b919b7 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2413.rst @@ -0,0 +1,59 @@ +======================= +Kernel driver w1_ds2413 +======================= + +Supported chips: + + * Maxim DS2413 1-Wire Dual Channel Addressable Switch + +supported family codes: + + ================ ==== + W1_FAMILY_DS2413 0x3A + ================ ==== + +Author: Mariusz Bialonczyk + +Description +----------- + +The DS2413 chip has two open-drain outputs (PIO A and PIO B). +Support is provided through the sysfs files "output" and "state". + +Reading state +------------- +The "state" file provides one-byte value which is in the same format as for +the chip PIO_ACCESS_READ command (refer the datasheet for details): + +======== ============================================================= +Bit 0: PIOA Pin State +Bit 1: PIOA Output Latch State +Bit 2: PIOB Pin State +Bit 3: PIOB Output Latch State +Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module) +======== ============================================================= + +This file is readonly. + +Writing output +-------------- +You can set the PIO pins using the "output" file. +It is writable, you can write one-byte value to this sysfs file. +Similarly the byte format is the same as for the PIO_ACCESS_WRITE command: + +======== ====================================== +Bit 0: PIOA +Bit 1: PIOB +Bit 2-7: No matter (driver will set it to "1"s) +======== ====================================== + + +The chip has some kind of basic protection against transmission errors. +When reading the state, there is a four complement bits. +The driver is checking this complement, and when it is wrong then it is +returning I/O error. + +When writing output, the master must repeat the PIO Output Data byte in +its inverted form and it is waiting for a confirmation. +If the write is unsuccessful for three times, the write also returns +I/O error. diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423 deleted file mode 100644 index 3f98b505a0ee..000000000000 --- a/Documentation/w1/slaves/w1_ds2423 +++ /dev/null @@ -1,47 +0,0 @@ -Kernel driver w1_ds2423 -======================= - -Supported chips: - * Maxim DS2423 based counter devices. - -supported family codes: - W1_THERM_DS2423 0x1D - -Author: Mika Laitio - -Description ------------ - -Support is provided through the sysfs w1_slave file. Each opening and -read sequence of w1_slave file initiates the read of counters and ram -available in DS2423 pages 12 - 15. - -Result of each page is provided as an ASCII output where each counter -value and associated ram buffer is outpputed to own line. - -Each lines will contain the values of 42 bytes read from the counter and -memory page along the crc=YES or NO for indicating whether the read operation -was successful and CRC matched. -If the operation was successful, there is also in the end of each line -a counter value expressed as an integer after c= - -Meaning of 42 bytes represented is following: - - 1 byte from ram page - - 4 bytes for the counter value - - 4 zero bytes - - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes - - 31 remaining bytes from the ram page - - crc=YES/NO indicating whether read was ok and crc matched - - c= current counter value - -example from the successful read: -00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 -00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 - -example from the read with crc errors: -00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO -00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO -00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst new file mode 100644 index 000000000000..755d659ad997 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2423.rst @@ -0,0 +1,54 @@ +Kernel driver w1_ds2423 +======================= + +Supported chips: + + * Maxim DS2423 based counter devices. + +supported family codes: + + =============== ==== + W1_THERM_DS2423 0x1D + =============== ==== + +Author: Mika Laitio + +Description +----------- + +Support is provided through the sysfs w1_slave file. Each opening and +read sequence of w1_slave file initiates the read of counters and ram +available in DS2423 pages 12 - 15. + +Result of each page is provided as an ASCII output where each counter +value and associated ram buffer is outpputed to own line. + +Each lines will contain the values of 42 bytes read from the counter and +memory page along the crc=YES or NO for indicating whether the read operation +was successful and CRC matched. +If the operation was successful, there is also in the end of each line +a counter value expressed as an integer after c= + +Meaning of 42 bytes represented is following: + + - 1 byte from ram page + - 4 bytes for the counter value + - 4 zero bytes + - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes + - 31 remaining bytes from the ram page + - crc=YES/NO indicating whether read was ok and crc matched + - c= current counter value + +example from the successful read:: + + 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 + 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 + +example from the read with crc errors:: + + 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO + 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO + 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438 deleted file mode 100644 index e64f65a09387..000000000000 --- a/Documentation/w1/slaves/w1_ds2438 +++ /dev/null @@ -1,63 +0,0 @@ -Kernel driver w1_ds2438 -======================= - -Supported chips: - * Maxim DS2438 Smart Battery Monitor - -supported family codes: - W1_FAMILY_DS2438 0x26 - -Author: Mariusz Bialonczyk - -Description ------------ - -The DS2438 chip provides several functions that are desirable to carry in -a battery pack. It also has a 40 bytes of nonvolatile EEPROM. -Because the ability of temperature, current and voltage measurement, the chip -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): - -"iad" ------ -This file controls the 'Current A/D Control Bit' (IAD) in the -Status/Configuration Register. -Writing a zero value will clear the IAD bit and disables the current -measurements. -Writing value "1" is setting the IAD bit (enables the measurements). -The IAD bit is enabled by default in the DS2438. - -When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII. -An I/O error is returned when there is a problem setting the new value. - -"page0" -------- -This file provides full 8 bytes of the chip Page 0 (00h). -This page contains the most frequently accessed information 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. - -"temperature" -------------- -Opening and reading this file initiates the CONVERT_T (temperature conversion) -command of the chip, afterwards the temperature is read from the device -registers and provided as an ASCII decimal value. - -Important: The returned value has to be divided by 256 to get a real -temperature in degrees Celsius. - -"vad", "vdd" ------------- -Opening and reading this file initiates the CONVERT_V (voltage conversion) -command of the chip. - -Depending on a sysfs filename a different input for the A/D will be selected: -vad: general purpose A/D input (VAD) -vdd: battery input (VDD) - -After the voltage conversion the value is returned as decimal ASCII. -Note: To get a volts the value has to be divided by 100. diff --git a/Documentation/w1/slaves/w1_ds2438.rst b/Documentation/w1/slaves/w1_ds2438.rst new file mode 100644 index 000000000000..a29309a3f8e5 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2438.rst @@ -0,0 +1,69 @@ +Kernel driver w1_ds2438 +======================= + +Supported chips: + + * Maxim DS2438 Smart Battery Monitor + +supported family codes: + ================ ==== + W1_FAMILY_DS2438 0x26 + ================ ==== + +Author: Mariusz Bialonczyk + +Description +----------- + +The DS2438 chip provides several functions that are desirable to carry in +a battery pack. It also has a 40 bytes of nonvolatile EEPROM. +Because the ability of temperature, current and voltage measurement, the chip +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): + +"iad" +----- +This file controls the 'Current A/D Control Bit' (IAD) in the +Status/Configuration Register. +Writing a zero value will clear the IAD bit and disables the current +measurements. +Writing value "1" is setting the IAD bit (enables the measurements). +The IAD bit is enabled by default in the DS2438. + +When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII. +An I/O error is returned when there is a problem setting the new value. + +"page0" +------- +This file provides full 8 bytes of the chip Page 0 (00h). +This page contains the most frequently accessed information 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. + +"temperature" +------------- +Opening and reading this file initiates the CONVERT_T (temperature conversion) +command of the chip, afterwards the temperature is read from the device +registers and provided as an ASCII decimal value. + +Important: The returned value has to be divided by 256 to get a real +temperature in degrees Celsius. + +"vad", "vdd" +------------ +Opening and reading this file initiates the CONVERT_V (voltage conversion) +command of the chip. + +Depending on a sysfs filename a different input for the A/D will be selected: + +vad: + general purpose A/D input (VAD) +vdd: + battery input (VDD) + +After the voltage conversion the value is returned as decimal ASCII. +Note: To get a volts the value has to be divided by 100. diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04 deleted file mode 100644 index 7819b65cfa48..000000000000 --- a/Documentation/w1/slaves/w1_ds28e04 +++ /dev/null @@ -1,36 +0,0 @@ -Kernel driver w1_ds28e04 -======================== - -Supported chips: - * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO - -supported family codes: - W1_FAMILY_DS28E04 0x1C - -Author: Markus Franke, - -Description ------------ - -Support is provided through the sysfs files "eeprom" and "pio". CRC checking -during memory accesses can optionally be enabled/disabled via the device -attribute "crccheck". The strong pull-up can optionally be enabled/disabled -via the module parameter "w1_strong_pullup". - -Memory Access - - A read operation on the "eeprom" file reads the given amount of bytes - from the EEPROM of the DS28E04. - - A write operation on the "eeprom" file writes the given byte sequence - to the EEPROM of the DS28E04. If CRC checking mode is enabled only - fully aligned blocks of 32 bytes with valid CRC16 values (in bytes 30 - and 31) are allowed to be written. - -PIO Access - - The 2 PIOs of the DS28E04-100 are accessible via the "pio" sysfs file. - - The current status of the PIO's is returned as an 8 bit value. Bit 0/1 - represent the state of PIO_0/PIO_1. Bits 2..7 do not care. The PIO's are - driven low-active, i.e. the driver delivers/expects low-active values. diff --git a/Documentation/w1/slaves/w1_ds28e04.rst b/Documentation/w1/slaves/w1_ds28e04.rst new file mode 100644 index 000000000000..b12b118890d3 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds28e04.rst @@ -0,0 +1,41 @@ +======================== +Kernel driver w1_ds28e04 +======================== + +Supported chips: + + * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO + +supported family codes: + + ================= ==== + W1_FAMILY_DS28E04 0x1C + ================= ==== + +Author: Markus Franke, + +Description +----------- + +Support is provided through the sysfs files "eeprom" and "pio". CRC checking +during memory accesses can optionally be enabled/disabled via the device +attribute "crccheck". The strong pull-up can optionally be enabled/disabled +via the module parameter "w1_strong_pullup". + +Memory Access + + A read operation on the "eeprom" file reads the given amount of bytes + from the EEPROM of the DS28E04. + + A write operation on the "eeprom" file writes the given byte sequence + to the EEPROM of the DS28E04. If CRC checking mode is enabled only + fully aligned blocks of 32 bytes with valid CRC16 values (in bytes 30 + and 31) are allowed to be written. + +PIO Access + + The 2 PIOs of the DS28E04-100 are accessible via the "pio" sysfs file. + + The current status of the PIO's is returned as an 8 bit value. Bit 0/1 + represent the state of PIO_0/PIO_1. Bits 2..7 do not care. The PIO's are + driven low-active, i.e. the driver delivers/expects low-active values. diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17 deleted file mode 100644 index 7fcfad5b4a37..000000000000 --- a/Documentation/w1/slaves/w1_ds28e17 +++ /dev/null @@ -1,68 +0,0 @@ -Kernel driver w1_ds28e17 -======================== - -Supported chips: - * Maxim DS28E17 1-Wire-to-I2C Master Bridge - -supported family codes: - W1_FAMILY_DS28E17 0x19 - -Author: Jan Kandziora - - -Description ------------ -The DS28E17 is a Onewire slave device which acts as an I2C bus master. - -This driver creates a new I2C bus for any DS28E17 device detected. I2C buses -come and go as the DS28E17 devices come and go. I2C slave devices connected to -a DS28E17 can be accessed by the kernel or userspace tools as if they were -connected to a "native" I2C bus master. - - -An udev rule like the following -------------------------------------------------------------------------------- -SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \ - SYMLINK+="i2c-$attr{name}" -------------------------------------------------------------------------------- -may be used to create stable /dev/i2c- entries based on the unique id of the -DS28E17 chip. - - -Driver parameters are: - -speed: - This sets up the default I2C speed a DS28E17 get configured for as soon - it is connected. The power-on default of the DS28E17 is 400kBaud, but - chips may come and go on the Onewire bus without being de-powered and - as soon the "w1_ds28e17" driver notices a freshly connected, or - reconnected DS28E17 device on the Onewire bus, it will re-apply this - setting. - - Valid values are 100, 400, 900 [kBaud]. Any other value means to leave - alone the current DS28E17 setting on detect. The default value is 100. - -stretch: - This sets up the default stretch value used for freshly connected - DS28E17 devices. It is a multiplier used on the calculation of the busy - wait time for an I2C transfer. This is to account for I2C slave devices - which make heavy use of the I2C clock stretching feature and thus, the - needed timeout cannot be pre-calculated correctly. As the w1_ds28e17 - driver checks the DS28E17's busy flag in a loop after the precalculated - wait time, it should be hardly needed to tweak this setting. - - Leave it at 1 unless you get ETIMEDOUT errors and a "w1_slave_driver - 19-00000002dbd8: busy timeout" in the kernel log. - - Valid values are 1 to 9. The default is 1. - - -The driver creates sysfs files /sys/bus/w1/devices/19-/speed and -/sys/bus/w1/devices/19-/stretch for each device, preloaded with the default -settings from the driver parameters. They may be changed anytime. In addition a -directory /sys/bus/w1/devices/19-/i2c- for the I2C bus master sysfs -structure is created. - - -See https://github.com/ianka/w1_ds28e17 for even more information. - diff --git a/Documentation/w1/slaves/w1_ds28e17.rst b/Documentation/w1/slaves/w1_ds28e17.rst new file mode 100644 index 000000000000..e2d9f96d8f2c --- /dev/null +++ b/Documentation/w1/slaves/w1_ds28e17.rst @@ -0,0 +1,72 @@ +======================== +Kernel driver w1_ds28e17 +======================== + +Supported chips: + + * Maxim DS28E17 1-Wire-to-I2C Master Bridge + +supported family codes: + + ================= ==== + W1_FAMILY_DS28E17 0x19 + ================= ==== + +Author: Jan Kandziora + + +Description +----------- +The DS28E17 is a Onewire slave device which acts as an I2C bus master. + +This driver creates a new I2C bus for any DS28E17 device detected. I2C buses +come and go as the DS28E17 devices come and go. I2C slave devices connected to +a DS28E17 can be accessed by the kernel or userspace tools as if they were +connected to a "native" I2C bus master. + + +An udev rule like the following:: + + SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \ + SYMLINK+="i2c-$attr{name}" + +may be used to create stable /dev/i2c- entries based on the unique id of the +DS28E17 chip. + + +Driver parameters are: + +speed: + This sets up the default I2C speed a DS28E17 get configured for as soon + it is connected. The power-on default of the DS28E17 is 400kBaud, but + chips may come and go on the Onewire bus without being de-powered and + as soon the "w1_ds28e17" driver notices a freshly connected, or + reconnected DS28E17 device on the Onewire bus, it will re-apply this + setting. + + Valid values are 100, 400, 900 [kBaud]. Any other value means to leave + alone the current DS28E17 setting on detect. The default value is 100. + +stretch: + This sets up the default stretch value used for freshly connected + DS28E17 devices. It is a multiplier used on the calculation of the busy + wait time for an I2C transfer. This is to account for I2C slave devices + which make heavy use of the I2C clock stretching feature and thus, the + needed timeout cannot be pre-calculated correctly. As the w1_ds28e17 + driver checks the DS28E17's busy flag in a loop after the precalculated + wait time, it should be hardly needed to tweak this setting. + + Leave it at 1 unless you get ETIMEDOUT errors and a "w1_slave_driver + 19-00000002dbd8: busy timeout" in the kernel log. + + Valid values are 1 to 9. The default is 1. + + +The driver creates sysfs files /sys/bus/w1/devices/19-/speed and +/sys/bus/w1/devices/19-/stretch for each device, preloaded with the default +settings from the driver parameters. They may be changed anytime. In addition a +directory /sys/bus/w1/devices/19-/i2c- for the I2C bus master sysfs +structure is created. + + +See https://github.com/ianka/w1_ds28e17 for even more information. diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm deleted file mode 100644 index d1f93af36f38..000000000000 --- a/Documentation/w1/slaves/w1_therm +++ /dev/null @@ -1,67 +0,0 @@ -Kernel driver w1_therm -==================== - -Supported chips: - * Maxim ds18*20 based temperature sensors. - * Maxim ds1825 based temperature sensors. - -Author: Evgeniy Polyakov - - -Description ------------ - -w1_therm provides basic temperature conversion for ds18*20 devices, and the -ds28ea00 device. -supported family codes: -W1_THERM_DS18S20 0x10 -W1_THERM_DS1822 0x22 -W1_THERM_DS18B20 0x28 -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 -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 -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. - -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. - -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. - -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. -In case of autodetection, the driver will use the "READ POWER SUPPLY" -command to check if there are pariste powered devices on the bus. -If so, it will activate the master's strong pullup. -In case the detection of parasite devices using this command fails -(seems to be the case with some DS18S20) the strong pullup can -be force-enabled. -If the strong pullup is enabled, the master's strong pullup will be -driven when the conversion is taking place, provided the master driver -does support the strong pullup (or it falls back to a pullup -resistor). The DS18b20 temperature sensor specification lists a -maximum current draw of 1.5mA and that a 5k pullup resistor is not -sufficient. The strong pullup is designed to provide the additional -current required. - -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 -representing the device index in the bus starting at 0. diff --git a/Documentation/w1/slaves/w1_therm.rst b/Documentation/w1/slaves/w1_therm.rst new file mode 100644 index 000000000000..90531c340a07 --- /dev/null +++ b/Documentation/w1/slaves/w1_therm.rst @@ -0,0 +1,74 @@ +====================== +Kernel driver w1_therm +====================== + +Supported chips: + + * Maxim ds18*20 based temperature sensors. + * Maxim ds1825 based temperature sensors. + +Author: Evgeniy Polyakov + + +Description +----------- + +w1_therm provides basic temperature conversion for ds18*20 devices, and the +ds28ea00 device. + +Supported family codes: + +==================== ==== +W1_THERM_DS18S20 0x10 +W1_THERM_DS1822 0x22 +W1_THERM_DS18B20 0x28 +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 +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 +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. + +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. + +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. + +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. +In case of autodetection, the driver will use the "READ POWER SUPPLY" +command to check if there are pariste powered devices on the bus. +If so, it will activate the master's strong pullup. +In case the detection of parasite devices using this command fails +(seems to be the case with some DS18S20) the strong pullup can +be force-enabled. + +If the strong pullup is enabled, the master's strong pullup will be +driven when the conversion is taking place, provided the master driver +does support the strong pullup (or it falls back to a pullup +resistor). The DS18b20 temperature sensor specification lists a +maximum current draw of 1.5mA and that a 5k pullup resistor is not +sufficient. The strong pullup is designed to provide the additional +current required. + +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 +representing the device index in the bus starting at 0. -- cgit v1.2.3