tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
e9bb6275
f139291c
+308
-169
+1
-1
Documentation/ABI/stable/sysfs-bus-w1
+1
-1
Documentation/ABI/stable/sysfs-bus-w1
···
6
6
control systems are attached/generate presence for as short as
7
7
100 ms - hence the tens-to-hundreds milliseconds scan intervals
8
8
are required.
9
-
see Documentation/w1/w1.generic for detailed information.
9
+
see Documentation/w1/w1-generic.rst for detailed information.
10
10
Users: any user space application which wants to know bus scanning
11
11
interval
+2
-2
Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+2
-2
Documentation/ABI/stable/sysfs-driver-w1_ds28e04
···
2
2
Date: May 2012
3
3
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
4
4
Description: read/write the contents of the two PIO's of the DS28E04-100
5
-
see Documentation/w1/slaves/w1_ds28e04 for detailed information
5
+
see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
6
6
Users: any user space application which wants to communicate with DS28E04-100
7
7
8
8
···
11
11
Date: May 2012
12
12
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
13
13
Description: read/write the contents of the EEPROM memory of the DS28E04-100
14
-
see Documentation/w1/slaves/w1_ds28e04 for detailed information
14
+
see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
15
15
Users: any user space application which wants to communicate with DS28E04-100
+1
-1
Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+1
-1
Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
···
2
2
Date: Apr 2015
3
3
Contact: Matt Campbell <mattrcampbell@gmail.com>
4
4
Description: Support for the DS28EA00 chain sequence function
5
-
see Documentation/w1/slaves/w1_therm for detailed information
5
+
see Documentation/w1/slaves/w1_therm.rst for detailed information
6
6
Users: any user space application which wants to communicate with DS28EA00
+1
Documentation/index.rst
+1
Documentation/index.rst
+21
Documentation/w1/index.rst
+21
Documentation/w1/index.rst
···
1
+
. SPDX-License-Identifier: GPL-2.0
2
+
3
+
================
4
+
1-Wire Subsystem
5
+
================
6
+
7
+
.. toctree::
8
+
:maxdepth: 1
9
+
10
+
11
+
w1-generic.rst
12
+
w1-netlink.rst
13
+
masters/index
14
+
slaves/index
15
+
16
+
.. only:: subproject and html
17
+
18
+
Indices
19
+
=======
20
+
21
+
* :ref:`genindex`
+12
-4
Documentation/w1/masters/ds2482
Documentation/w1/masters/ds2482.rst
+12
-4
Documentation/w1/masters/ds2482
Documentation/w1/masters/ds2482.rst
···
1
+
====================
1
2
Kernel driver ds2482
2
3
====================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim DS2482-100, Maxim DS2482-800
8
+
6
9
Prefix: 'ds2482'
10
+
7
11
Addresses scanned: None
12
+
8
13
Datasheets:
9
-
http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
10
-
http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
14
+
15
+
- http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
16
+
- http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
11
17
12
18
Author: Ben Gardner <bgardner@wabtec.com>
13
19
···
29
23
---------------
30
24
31
25
Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
26
+
32
27
However, the device cannot be detected without writing to the i2c bus, so no
33
28
detection is done. You should instantiate the device explicitly.
34
29
35
-
$ modprobe ds2482
36
-
$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
30
+
::
37
31
32
+
$ modprobe ds2482
33
+
$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+5
-1
Documentation/w1/masters/ds2490
Documentation/w1/masters/ds2490.rst
+5
-1
Documentation/w1/masters/ds2490
Documentation/w1/masters/ds2490.rst
···
1
+
====================
1
2
Kernel driver ds2490
2
3
====================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim DS2490 based
6
8
7
9
Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
···
20
18
low-level operational chip.
21
19
22
20
Notes and limitations.
21
+
23
22
- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
24
23
- The 5V strong pullup is supported with a minimum of 5.9mA and a
25
24
maximum of 30.4 mA. (From DS2490.pdf)
···
68
65
reattaching would clear the problem. usbmon output in the guest and
69
66
host did not explain the problem. My guess is a bug in either qemu
70
67
or the host OS and more likely the host OS.
71
-
-- 03-06-2008 David Fries <David@Fries.net>
68
+
69
+
03-06-2008 David Fries <David@Fries.net>
+14
Documentation/w1/masters/index.rst
+14
Documentation/w1/masters/index.rst
-12
Documentation/w1/masters/mxc-w1
-12
Documentation/w1/masters/mxc-w1
···
1
-
Kernel driver mxc_w1
2
-
====================
3
-
4
-
Supported chips:
5
-
* Freescale MX27, MX31 and probably other i.MX SoCs
6
-
Datasheets:
7
-
http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
8
-
http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
9
-
Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
10
-
11
-
Author: Originally based on Freescale code, prepared for mainline by
12
-
Sascha Hauer <s.hauer@pengutronix.de>
+17
Documentation/w1/masters/mxc-w1.rst
+17
Documentation/w1/masters/mxc-w1.rst
···
1
+
====================
2
+
Kernel driver mxc_w1
3
+
====================
4
+
5
+
Supported chips:
6
+
7
+
* Freescale MX27, MX31 and probably other i.MX SoCs
8
+
9
+
Datasheets:
10
+
11
+
- http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
12
+
- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
13
+
14
+
Author:
15
+
16
+
Originally based on Freescale code, prepared for mainline by
17
+
Sascha Hauer <s.hauer@pengutronix.de>
+7
-5
Documentation/w1/masters/omap-hdq
Documentation/w1/masters/omap-hdq.rst
+7
-5
Documentation/w1/masters/omap-hdq
Documentation/w1/masters/omap-hdq.rst
···
1
-
Kernel driver for omap HDQ/1-wire module.
1
+
========================================
2
+
Kernel driver for omap HDQ/1-wire module
2
3
========================================
3
4
4
5
Supported chips:
5
6
================
6
-
HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
7
+
HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
7
8
8
9
A useful link about HDQ basics:
9
10
===============================
···
41
40
Please note to load both the modules with a different ID if required, but note
42
41
that the ID used should be same for both master and slave driver loading.
43
42
44
-
e.g:
45
-
insmod omap_hdq.ko W1_ID=2
46
-
inamod w1_bq27000.ko F_ID=2
43
+
e.g::
44
+
45
+
insmod omap_hdq.ko W1_ID=2
46
+
inamod w1_bq27000.ko F_ID=2
47
47
48
48
The driver also supports 1-wire mode. In this mode, there is no need to
49
49
pass slave ID as parameter. The driver will auto-detect slaves connected
+12
-9
Documentation/w1/masters/w1-gpio
Documentation/w1/masters/w1-gpio.rst
+12
-9
Documentation/w1/masters/w1-gpio
Documentation/w1/masters/w1-gpio.rst
···
1
+
=====================
1
2
Kernel driver w1-gpio
2
3
=====================
3
4
···
17
16
Example (mach-at91)
18
17
-------------------
19
18
20
-
#include <linux/gpio/machine.h>
21
-
#include <linux/w1-gpio.h>
19
+
::
22
20
23
-
static struct gpiod_lookup_table foo_w1_gpiod_table = {
21
+
#include <linux/gpio/machine.h>
22
+
#include <linux/w1-gpio.h>
23
+
24
+
static struct gpiod_lookup_table foo_w1_gpiod_table = {
24
25
.dev_id = "w1-gpio",
25
26
.table = {
26
27
GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
27
28
GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
28
29
},
29
-
};
30
+
};
30
31
31
-
static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
32
+
static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
32
33
.ext_pullup_enable_pin = -EINVAL,
33
-
};
34
+
};
34
35
35
-
static struct platform_device foo_w1_device = {
36
+
static struct platform_device foo_w1_device = {
36
37
.name = "w1-gpio",
37
38
.id = -1,
38
39
.dev.platform_data = &foo_w1_gpio_pdata,
39
-
};
40
+
};
40
41
41
-
...
42
+
...
42
43
at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
43
44
at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
44
45
gpiod_add_lookup_table(&foo_w1_gpiod_table);
+16
Documentation/w1/slaves/index.rst
+16
Documentation/w1/slaves/index.rst
+3
-1
Documentation/w1/slaves/w1_ds2406
Documentation/w1/slaves/w1_ds2406.rst
+3
-1
Documentation/w1/slaves/w1_ds2406
Documentation/w1/slaves/w1_ds2406.rst
···
1
+
=======================
1
2
w1_ds2406 kernel driver
2
3
=======================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim DS2406 (and other family 0x12) addressable switches
6
8
7
9
Author: Scott Alfter <scott@alfter.us>
···
11
9
Description
12
10
-----------
13
11
14
-
The w1_ds2406 driver allows connected devices to be switched on and off.
12
+
The w1_ds2406 driver allows connected devices to be switched on and off.
15
13
These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
16
14
not supported. In TSOC-6 form, the DS2406 provides two switch outputs and
17
15
can be provided with power on a dedicated input. In TO-92 form, it provides
+9
Documentation/w1/slaves/w1_ds2413
Documentation/w1/slaves/w1_ds2413.rst
+9
Documentation/w1/slaves/w1_ds2413
Documentation/w1/slaves/w1_ds2413.rst
···
1
+
=======================
1
2
Kernel driver w1_ds2413
2
3
=======================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim DS2413 1-Wire Dual Channel Addressable Switch
6
8
7
9
supported family codes:
10
+
11
+
================ ====
8
12
W1_FAMILY_DS2413 0x3A
13
+
================ ====
9
14
10
15
Author: Mariusz Bialonczyk <manio@skyboo.net>
11
16
···
25
20
The "state" file provides one-byte value which is in the same format as for
26
21
the chip PIO_ACCESS_READ command (refer the datasheet for details):
27
22
23
+
======== =============================================================
28
24
Bit 0: PIOA Pin State
29
25
Bit 1: PIOA Output Latch State
30
26
Bit 2: PIOB Pin State
31
27
Bit 3: PIOB Output Latch State
32
28
Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
29
+
======== =============================================================
33
30
34
31
This file is readonly.
35
32
···
41
34
It is writable, you can write one-byte value to this sysfs file.
42
35
Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
43
36
37
+
======== ======================================
44
38
Bit 0: PIOA
45
39
Bit 1: PIOB
46
40
Bit 2-7: No matter (driver will set it to "1"s)
41
+
======== ======================================
47
42
48
43
49
44
The chip has some kind of basic protection against transmission errors.
-47
Documentation/w1/slaves/w1_ds2423
-47
Documentation/w1/slaves/w1_ds2423
···
1
-
Kernel driver w1_ds2423
2
-
=======================
3
-
4
-
Supported chips:
5
-
* Maxim DS2423 based counter devices.
6
-
7
-
supported family codes:
8
-
W1_THERM_DS2423 0x1D
9
-
10
-
Author: Mika Laitio <lamikr@pilppa.org>
11
-
12
-
Description
13
-
-----------
14
-
15
-
Support is provided through the sysfs w1_slave file. Each opening and
16
-
read sequence of w1_slave file initiates the read of counters and ram
17
-
available in DS2423 pages 12 - 15.
18
-
19
-
Result of each page is provided as an ASCII output where each counter
20
-
value and associated ram buffer is outpputed to own line.
21
-
22
-
Each lines will contain the values of 42 bytes read from the counter and
23
-
memory page along the crc=YES or NO for indicating whether the read operation
24
-
was successful and CRC matched.
25
-
If the operation was successful, there is also in the end of each line
26
-
a counter value expressed as an integer after c=
27
-
28
-
Meaning of 42 bytes represented is following:
29
-
- 1 byte from ram page
30
-
- 4 bytes for the counter value
31
-
- 4 zero bytes
32
-
- 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
33
-
- 31 remaining bytes from the ram page
34
-
- crc=YES/NO indicating whether read was ok and crc matched
35
-
- c=<int> current counter value
36
-
37
-
example from the successful read:
38
-
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
39
-
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
40
-
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
41
-
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
42
-
43
-
example from the read with crc errors:
44
-
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
45
-
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
46
-
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
47
-
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
+54
Documentation/w1/slaves/w1_ds2423.rst
+54
Documentation/w1/slaves/w1_ds2423.rst
···
1
+
Kernel driver w1_ds2423
2
+
=======================
3
+
4
+
Supported chips:
5
+
6
+
* Maxim DS2423 based counter devices.
7
+
8
+
supported family codes:
9
+
10
+
=============== ====
11
+
W1_THERM_DS2423 0x1D
12
+
=============== ====
13
+
14
+
Author: Mika Laitio <lamikr@pilppa.org>
15
+
16
+
Description
17
+
-----------
18
+
19
+
Support is provided through the sysfs w1_slave file. Each opening and
20
+
read sequence of w1_slave file initiates the read of counters and ram
21
+
available in DS2423 pages 12 - 15.
22
+
23
+
Result of each page is provided as an ASCII output where each counter
24
+
value and associated ram buffer is outpputed to own line.
25
+
26
+
Each lines will contain the values of 42 bytes read from the counter and
27
+
memory page along the crc=YES or NO for indicating whether the read operation
28
+
was successful and CRC matched.
29
+
If the operation was successful, there is also in the end of each line
30
+
a counter value expressed as an integer after c=
31
+
32
+
Meaning of 42 bytes represented is following:
33
+
34
+
- 1 byte from ram page
35
+
- 4 bytes for the counter value
36
+
- 4 zero bytes
37
+
- 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
38
+
- 31 remaining bytes from the ram page
39
+
- crc=YES/NO indicating whether read was ok and crc matched
40
+
- c=<int> current counter value
41
+
42
+
example from the successful read::
43
+
44
+
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
45
+
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
46
+
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
47
+
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
48
+
49
+
example from the read with crc errors::
50
+
51
+
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
52
+
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
53
+
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
54
+
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
+8
-2
Documentation/w1/slaves/w1_ds2438
Documentation/w1/slaves/w1_ds2438.rst
+8
-2
Documentation/w1/slaves/w1_ds2438
Documentation/w1/slaves/w1_ds2438.rst
···
2
2
=======================
3
3
4
4
Supported chips:
5
+
5
6
* Maxim DS2438 Smart Battery Monitor
6
7
7
8
supported family codes:
9
+
================ ====
8
10
W1_FAMILY_DS2438 0x26
11
+
================ ====
9
12
10
13
Author: Mariusz Bialonczyk <manio@skyboo.net>
11
14
···
59
56
command of the chip.
60
57
61
58
Depending on a sysfs filename a different input for the A/D will be selected:
62
-
vad: general purpose A/D input (VAD)
63
-
vdd: battery input (VDD)
59
+
60
+
vad:
61
+
general purpose A/D input (VAD)
62
+
vdd:
63
+
battery input (VDD)
64
64
65
65
After the voltage conversion the value is returned as decimal ASCII.
66
66
Note: To get a volts the value has to be divided by 100.
+5
Documentation/w1/slaves/w1_ds28e04
Documentation/w1/slaves/w1_ds28e04.rst
+5
Documentation/w1/slaves/w1_ds28e04
Documentation/w1/slaves/w1_ds28e04.rst
···
1
+
========================
1
2
Kernel driver w1_ds28e04
2
3
========================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
6
8
7
9
supported family codes:
10
+
11
+
================= ====
8
12
W1_FAMILY_DS28E04 0x1C
13
+
================= ====
9
14
10
15
Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
11
16
+10
-6
Documentation/w1/slaves/w1_ds28e17
Documentation/w1/slaves/w1_ds28e17.rst
+10
-6
Documentation/w1/slaves/w1_ds28e17
Documentation/w1/slaves/w1_ds28e17.rst
···
1
+
========================
1
2
Kernel driver w1_ds28e17
2
3
========================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim DS28E17 1-Wire-to-I2C Master Bridge
6
8
7
9
supported family codes:
10
+
11
+
================= ====
8
12
W1_FAMILY_DS28E17 0x19
13
+
================= ====
9
14
10
15
Author: Jan Kandziora <jjj@gmx.de>
11
16
···
25
20
connected to a "native" I2C bus master.
26
21
27
22
28
-
An udev rule like the following
29
-
-------------------------------------------------------------------------------
30
-
SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
31
-
SYMLINK+="i2c-$attr{name}"
32
-
-------------------------------------------------------------------------------
23
+
An udev rule like the following::
24
+
25
+
SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
26
+
SYMLINK+="i2c-$attr{name}"
27
+
33
28
may be used to create stable /dev/i2c- entries based on the unique id of the
34
29
DS28E17 chip.
35
30
···
70
65
71
66
72
67
See https://github.com/ianka/w1_ds28e17 for even more information.
73
-
+9
-2
Documentation/w1/slaves/w1_therm
Documentation/w1/slaves/w1_therm.rst
+9
-2
Documentation/w1/slaves/w1_therm
Documentation/w1/slaves/w1_therm.rst
···
1
+
======================
1
2
Kernel driver w1_therm
2
-
====================
3
+
======================
3
4
4
5
Supported chips:
6
+
5
7
* Maxim ds18*20 based temperature sensors.
6
8
* Maxim ds1825 based temperature sensors.
7
9
···
15
13
16
14
w1_therm provides basic temperature conversion for ds18*20 devices, and the
17
15
ds28ea00 device.
18
-
supported family codes:
16
+
17
+
Supported family codes:
18
+
19
+
==================== ====
19
20
W1_THERM_DS18S20 0x10
20
21
W1_THERM_DS1822 0x22
21
22
W1_THERM_DS18B20 0x28
22
23
W1_THERM_DS1825 0x3B
23
24
W1_THERM_DS28EA00 0x42
25
+
==================== ====
24
26
25
27
Support is provided through the sysfs w1_slave file. Each open and
26
28
read sequence will initiate a temperature conversion then provide two
···
57
51
In case the detection of parasite devices using this command fails
58
52
(seems to be the case with some DS18S20) the strong pullup can
59
53
be force-enabled.
54
+
60
55
If the strong pullup is enabled, the master's strong pullup will be
61
56
driven when the conversion is taking place, provided the master driver
62
57
does support the strong pullup (or it falls back to a pullup
+50
-38
Documentation/w1/w1.generic
Documentation/w1/w1-generic.rst
+50
-38
Documentation/w1/w1.generic
Documentation/w1/w1-generic.rst
···
1
-
The 1-wire (w1) subsystem
2
-
------------------------------------------------------------------
1
+
=========================================
2
+
Introduction to the 1-wire (w1) subsystem
3
+
=========================================
4
+
3
5
The 1-wire bus is a simple master-slave bus that communicates via a single
4
6
signal wire (plus ground, so two wires).
5
7
···
14
12
All w1 slave devices must be connected to a w1 bus master device.
15
13
16
14
Example w1 master devices:
17
-
DS9490 usb device
18
-
W1-over-GPIO
19
-
DS2482 (i2c to w1 bridge)
20
-
Emulated devices, such as a RS232 converter, parallel port adapter, etc
15
+
16
+
- DS9490 usb device
17
+
- W1-over-GPIO
18
+
- DS2482 (i2c to w1 bridge)
19
+
- Emulated devices, such as a RS232 converter, parallel port adapter, etc
21
20
22
21
23
22
What does the w1 subsystem do?
24
-
------------------------------------------------------------------
23
+
------------------------------
24
+
25
25
When a w1 master driver registers with the w1 subsystem, the following occurs:
26
26
27
27
- sysfs entries for that w1 master are created
···
47
43
48
44
49
45
W1 device families
50
-
------------------------------------------------------------------
46
+
------------------
47
+
51
48
Slave devices are handled by a driver written for a family of w1 devices.
52
49
53
50
A family driver populates a struct w1_family_ops (see w1_family.h) and
54
51
registers with the w1 subsystem.
55
52
56
53
Current family drivers:
57
-
w1_therm - (ds18?20 thermal sensor family driver)
54
+
55
+
w1_therm
56
+
- (ds18?20 thermal sensor family driver)
58
57
provides temperature reading function which is bound to ->rbin() method
59
58
of the above w1_family_ops structure.
60
59
61
-
w1_smem - driver for simple 64bit memory cell provides ID reading method.
60
+
w1_smem
61
+
- driver for simple 64bit memory cell provides ID reading method.
62
62
63
63
You can call above methods by reading appropriate sysfs files.
64
64
65
65
66
66
What does a w1 master driver need to implement?
67
-
------------------------------------------------------------------
67
+
-----------------------------------------------
68
68
69
69
The driver for w1 bus master must provide at minimum two functions.
70
70
···
83
75
84
76
85
77
w1 master sysfs interface
86
-
------------------------------------------------------------------
87
-
<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial
88
-
bus - (standard) symlink to the w1 bus
89
-
driver - (standard) symlink to the w1 driver
90
-
w1_master_add - (rw) manually register a slave device
91
-
w1_master_attempts - (ro) the number of times a search was attempted
92
-
w1_master_max_slave_count
93
-
- (rw) maximum number of slaves to search for at a time
94
-
w1_master_name - (ro) the name of the device (w1_bus_masterX)
95
-
w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled
96
-
w1_master_remove - (rw) manually remove a slave device
97
-
w1_master_search - (rw) the number of searches left to do,
98
-
-1=continual (default)
99
-
w1_master_slave_count
100
-
- (ro) the number of slaves found
101
-
w1_master_slaves - (ro) the names of the slaves, one per line
102
-
w1_master_timeout - (ro) the delay in seconds between searches
103
-
w1_master_timeout_us
104
-
- (ro) the delay in microseconds beetwen searches
78
+
-------------------------
79
+
80
+
========================= =====================================================
81
+
<xx-xxxxxxxxxxxx> A directory for a found device. The format is
82
+
family-serial
83
+
bus (standard) symlink to the w1 bus
84
+
driver (standard) symlink to the w1 driver
85
+
w1_master_add (rw) manually register a slave device
86
+
w1_master_attempts (ro) the number of times a search was attempted
87
+
w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
88
+
w1_master_name (ro) the name of the device (w1_bus_masterX)
89
+
w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
90
+
w1_master_remove (rw) manually remove a slave device
91
+
w1_master_search (rw) the number of searches left to do,
92
+
-1=continual (default)
93
+
w1_master_slave_count (ro) the number of slaves found
94
+
w1_master_slaves (ro) the names of the slaves, one per line
95
+
w1_master_timeout (ro) the delay in seconds between searches
96
+
w1_master_timeout_us (ro) the delay in microseconds beetwen searches
97
+
========================= =====================================================
105
98
106
99
If you have a w1 bus that never changes (you don't add or remove devices),
107
100
you can set the module parameter search_count to a small positive number
···
120
111
w1_master_attempts by 1.
121
112
122
113
w1 slave sysfs interface
123
-
------------------------------------------------------------------
124
-
bus - (standard) symlink to the w1 bus
125
-
driver - (standard) symlink to the w1 driver
126
-
name - the device name, usually the same as the directory name
127
-
w1_slave - (optional) a binary file whose meaning depends on the
128
-
family driver
129
-
rw - (optional) created for slave devices which do not have
130
-
appropriate family driver. Allows to read/write binary data.
114
+
------------------------
115
+
116
+
=================== ============================================================
117
+
bus (standard) symlink to the w1 bus
118
+
driver (standard) symlink to the w1 driver
119
+
name the device name, usually the same as the directory name
120
+
w1_slave (optional) a binary file whose meaning depends on the
121
+
family driver
122
+
rw (optional) created for slave devices which do not have
123
+
appropriate family driver. Allows to read/write binary data.
124
+
=================== ============================================================
+51
-38
Documentation/w1/w1.netlink
Documentation/w1/w1-netlink.rst
+51
-38
Documentation/w1/w1.netlink
Documentation/w1/w1-netlink.rst
···
1
-
Userspace communication protocol over connector [1].
1
+
===============================================
2
+
Userspace communication protocol over connector
3
+
===============================================
2
4
3
-
4
-
Message types.
5
+
Message types
5
6
=============
6
7
7
8
There are three types of messages between w1 core and userspace:
9
+
8
10
1. Events. They are generated each time a new master or slave device
9
-
is found either due to automatic or requested search.
11
+
is found either due to automatic or requested search.
10
12
2. Userspace commands.
11
13
3. Replies to userspace commands.
12
14
13
15
14
-
Protocol.
16
+
Protocol
15
17
========
16
18
17
-
[struct cn_msg] - connector header.
19
+
::
20
+
21
+
[struct cn_msg] - connector header.
18
22
Its length field is equal to size of the attached data
19
-
[struct w1_netlink_msg] - w1 netlink header.
23
+
[struct w1_netlink_msg] - w1 netlink header.
20
24
__u8 type - message type.
21
25
W1_LIST_MASTERS
22
26
list current bus masters
···
44
40
} mst;
45
41
} id;
46
42
47
-
[struct w1_netlink_cmd] - command for given master or slave device.
43
+
[struct w1_netlink_cmd] - command for given master or slave device.
48
44
__u8 cmd - command opcode.
49
45
W1_CMD_READ - read command
50
46
W1_CMD_WRITE - write command
···
75
71
Currently replies to userspace commands are only generated for read
76
72
command request. One reply is generated exactly for one w1_netlink_cmd
77
73
read request. Replies are not combined when sent - i.e. typical reply
78
-
messages looks like the following:
74
+
messages looks like the following::
79
75
80
-
[cn_msg][w1_netlink_msg][w1_netlink_cmd]
81
-
cn_msg.len = sizeof(struct w1_netlink_msg) +
76
+
[cn_msg][w1_netlink_msg][w1_netlink_cmd]
77
+
cn_msg.len = sizeof(struct w1_netlink_msg) +
82
78
sizeof(struct w1_netlink_cmd) +
83
79
cmd->len;
84
-
w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
85
-
w1_netlink_cmd.len = cmd->len;
80
+
w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
81
+
w1_netlink_cmd.len = cmd->len;
86
82
87
83
Replies to W1_LIST_MASTERS should send a message back to the userspace
88
84
which will contain list of all registered master ids in the following
89
-
format:
85
+
format::
90
86
91
87
cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
92
88
w1_netlink_msg) plus number of masters multiplied by 4)
···
94
90
number of masters multiplied by 4 (u32 size))
95
91
id0 ... idN
96
92
97
-
Each message is at most 4k in size, so if number of master devices
98
-
exceeds this, it will be split into several messages.
93
+
Each message is at most 4k in size, so if number of master devices
94
+
exceeds this, it will be split into several messages.
99
95
100
96
W1 search and alarm search commands.
101
-
request:
102
-
[cn_msg]
103
-
[w1_netlink_msg type = W1_MASTER_CMD
104
-
id is equal to the bus master id to use for searching]
105
-
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
106
97
107
-
reply:
98
+
request::
99
+
100
+
[cn_msg]
101
+
[w1_netlink_msg type = W1_MASTER_CMD
102
+
id is equal to the bus master id to use for searching]
103
+
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
104
+
105
+
reply::
106
+
108
107
[cn_msg, ack = 1 and increasing, 0 means the last message,
109
-
seq is equal to the request seq]
108
+
seq is equal to the request seq]
110
109
[w1_netlink_msg type = W1_MASTER_CMD]
111
110
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
112
111
len is equal to number of IDs multiplied by 8]
113
112
[64bit-id0 ... 64bit-idN]
113
+
114
114
Length in each header corresponds to the size of the data behind it, so
115
115
w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
116
-
Can be zero.
117
-
w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
118
-
cn_msg->len = sizeof(struct w1_netlink_msg) +
116
+
Can be zero.
117
+
118
+
::
119
+
120
+
w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
121
+
cn_msg->len = sizeof(struct w1_netlink_msg) +
119
122
sizeof(struct w1_netlink_cmd) +
120
123
N*8;
121
124
122
-
W1 reset command.
123
-
[cn_msg]
124
-
[w1_netlink_msg type = W1_MASTER_CMD
125
-
id is equal to the bus master id to use for searching]
126
-
[w1_netlink_cmd cmd = W1_CMD_RESET]
125
+
W1 reset command::
126
+
127
+
[cn_msg]
128
+
[w1_netlink_msg type = W1_MASTER_CMD
129
+
id is equal to the bus master id to use for searching]
130
+
[w1_netlink_cmd cmd = W1_CMD_RESET]
127
131
128
132
129
-
Command status replies.
133
+
Command status replies
130
134
======================
131
135
132
136
Each command (either root, master or slave with or without w1_netlink_cmd
···
162
150
even if there were errors, only length mismatch interrupts message processing.
163
151
164
152
165
-
Operation steps in w1 core when new command is received.
153
+
Operation steps in w1 core when new command is received
166
154
=======================================================
167
155
168
156
When new message (w1_netlink_msg) is received w1 core detects if it is
···
179
167
and next w1_netlink_msg header processing started.
180
168
181
169
182
-
Connector [1] specific documentation.
170
+
Connector [1] specific documentation
183
171
====================================
184
172
185
173
Each connector message includes two u32 fields as "address".
···
192
180
acknowledge number is set to seq+1.
193
181
194
182
195
-
Additional documantion, source code examples.
196
-
============================================
183
+
Additional documentation, source code examples
184
+
==============================================
197
185
198
186
1. Documentation/driver-api/connector.rst
199
187
2. http://www.ioremap.net/archive/w1
200
-
This archive includes userspace application w1d.c which uses
201
-
read/write/search commands for all master/slave devices found on the bus.
188
+
189
+
This archive includes userspace application w1d.c which uses
190
+
read/write/search commands for all master/slave devices found on the bus.