1 ========================================= 1 =========================================
2 Introduction to the 1-wire (w1) subsystem 2 Introduction to the 1-wire (w1) subsystem
3 ========================================= 3 =========================================
4 4
5 The 1-wire bus is a simple master-slave bus th 5 The 1-wire bus is a simple master-slave bus that communicates via a single
6 signal wire (plus ground, so two wires). 6 signal wire (plus ground, so two wires).
7 7
8 Devices communicate on the bus by pulling the 8 Devices communicate on the bus by pulling the signal to ground via an open
9 drain output and by sampling the logic level o 9 drain output and by sampling the logic level of the signal line.
10 10
11 The w1 subsystem provides the framework for ma 11 The w1 subsystem provides the framework for managing w1 masters and
12 communication with slaves. 12 communication with slaves.
13 13
14 All w1 slave devices must be connected to a w1 14 All w1 slave devices must be connected to a w1 bus master device.
15 15
16 Example w1 master devices: 16 Example w1 master devices:
17 17
18 - DS9490 usb device 18 - DS9490 usb device
19 - W1-over-GPIO 19 - W1-over-GPIO
20 - DS2482 (i2c to w1 bridge) 20 - DS2482 (i2c to w1 bridge)
21 - Emulated devices, such as a RS232 conver 21 - Emulated devices, such as a RS232 converter, parallel port adapter, etc
22 22
23 23
24 What does the w1 subsystem do? 24 What does the w1 subsystem do?
25 ------------------------------ 25 ------------------------------
26 26
27 When a w1 master driver registers with the w1 27 When a w1 master driver registers with the w1 subsystem, the following occurs:
28 28
29 - sysfs entries for that w1 master are create 29 - sysfs entries for that w1 master are created
30 - the w1 bus is periodically searched for new 30 - the w1 bus is periodically searched for new slave devices
31 31
32 When a device is found on the bus, w1 core tri 32 When a device is found on the bus, w1 core tries to load the driver for its family
33 and check if it is loaded. If so, the family d 33 and check if it is loaded. If so, the family driver is attached to the slave.
34 If there is no driver for the family, default 34 If there is no driver for the family, default one is assigned, which allows to perform
35 almost any kind of operations. Each logical op 35 almost any kind of operations. Each logical operation is a transaction
36 in nature, which can contain several (two or o 36 in nature, which can contain several (two or one) low-level operations.
37 Let's see how one can read EEPROM context: 37 Let's see how one can read EEPROM context:
38 1. one must write control buffer, i.e. buffer 38 1. one must write control buffer, i.e. buffer containing command byte
39 and two byte address. At this step bus is rese 39 and two byte address. At this step bus is reset and appropriate device
40 is selected using either W1_SKIP_ROM or W1_MAT 40 is selected using either W1_SKIP_ROM or W1_MATCH_ROM command.
41 Then provided control buffer is being written 41 Then provided control buffer is being written to the wire.
42 2. reading. This will issue reading eeprom res 42 2. reading. This will issue reading eeprom response.
43 43
44 It is possible that between 1. and 2. w1 maste 44 It is possible that between 1. and 2. w1 master thread will reset bus for searching
45 and slave device will be even removed, but in 45 and slave device will be even removed, but in this case 0xff will
46 be read, since no device was selected. 46 be read, since no device was selected.
47 47
48 48
49 W1 device families 49 W1 device families
50 ------------------ 50 ------------------
51 51
52 Slave devices are handled by a driver written 52 Slave devices are handled by a driver written for a family of w1 devices.
53 53
54 A family driver populates a struct w1_family_o 54 A family driver populates a struct w1_family_ops (see w1_family.h) and
55 registers with the w1 subsystem. 55 registers with the w1 subsystem.
56 56
57 Current family drivers: 57 Current family drivers:
58 58
59 w1_therm 59 w1_therm
60 - (ds18?20 thermal sensor family driver) 60 - (ds18?20 thermal sensor family driver)
61 provides temperature reading function whic 61 provides temperature reading function which is bound to ->rbin() method
62 of the above w1_family_ops structure. 62 of the above w1_family_ops structure.
63 63
64 w1_smem 64 w1_smem
65 - driver for simple 64bit memory cell provid 65 - driver for simple 64bit memory cell provides ID reading method.
66 66
67 You can call above methods by reading appropri 67 You can call above methods by reading appropriate sysfs files.
68 68
69 69
70 What does a w1 master driver need to implement 70 What does a w1 master driver need to implement?
71 ---------------------------------------------- 71 -----------------------------------------------
72 72
73 The driver for w1 bus master must provide at m 73 The driver for w1 bus master must provide at minimum two functions.
74 74
75 Emulated devices must provide the ability to s 75 Emulated devices must provide the ability to set the output signal level
76 (write_bit) and sample the signal level (read_ 76 (write_bit) and sample the signal level (read_bit).
77 77
78 Devices that support the 1-wire natively must 78 Devices that support the 1-wire natively must provide the ability to write and
79 sample a bit (touch_bit) and reset the bus (re 79 sample a bit (touch_bit) and reset the bus (reset_bus).
80 80
81 Most hardware provides higher-level functions 81 Most hardware provides higher-level functions that offload w1 handling.
82 See struct w1_bus_master definition in w1.h fo 82 See struct w1_bus_master definition in w1.h for details.
83 83
84 84
85 w1 master sysfs interface 85 w1 master sysfs interface
86 ------------------------- 86 -------------------------
87 87
88 ========================= ==================== 88 ========================= =====================================================
89 <xx-xxxxxxxxxxxx> A directory for a fo 89 <xx-xxxxxxxxxxxx> A directory for a found device. The format is
90 family-serial 90 family-serial
91 bus (standard) symlink t 91 bus (standard) symlink to the w1 bus
92 driver (standard) symlink t 92 driver (standard) symlink to the w1 driver
93 w1_master_add (rw) manually regist 93 w1_master_add (rw) manually register a slave device
94 w1_master_attempts (ro) the number of t 94 w1_master_attempts (ro) the number of times a search was attempted
95 w1_master_max_slave_count (rw) maximum number 95 w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
96 w1_master_name (ro) the name of the 96 w1_master_name (ro) the name of the device (w1_bus_masterX)
97 w1_master_pullup (rw) 5V strong pullu 97 w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
98 w1_master_remove (rw) manually remove 98 w1_master_remove (rw) manually remove a slave device
99 w1_master_search (rw) the number of s 99 w1_master_search (rw) the number of searches left to do,
100 -1=continual (defaul 100 -1=continual (default)
101 w1_master_slave_count (ro) the number of s 101 w1_master_slave_count (ro) the number of slaves found
102 w1_master_slaves (ro) the names of th 102 w1_master_slaves (ro) the names of the slaves, one per line
103 w1_master_timeout (ro) the delay in se 103 w1_master_timeout (ro) the delay in seconds between searches
104 w1_master_timeout_us (ro) the delay in mi 104 w1_master_timeout_us (ro) the delay in microseconds between searches
105 ========================= ==================== 105 ========================= =====================================================
106 106
107 If you have a w1 bus that never changes (you d 107 If you have a w1 bus that never changes (you don't add or remove devices),
108 you can set the module parameter search_count 108 you can set the module parameter search_count to a small positive number
109 for an initially small number of bus searches. 109 for an initially small number of bus searches. Alternatively it could be
110 set to zero, then manually add the slave devic 110 set to zero, then manually add the slave device serial numbers by
111 w1_master_add device file. The w1_master_add 111 w1_master_add device file. The w1_master_add and w1_master_remove files
112 generally only make sense when searching is di 112 generally only make sense when searching is disabled, as a search will
113 redetect manually removed devices that are pre 113 redetect manually removed devices that are present and timeout manually
114 added devices that aren't on the bus. 114 added devices that aren't on the bus.
115 115
116 Bus searches occur at an interval, specified a 116 Bus searches occur at an interval, specified as a sum of timeout and
117 timeout_us module parameters (either of which 117 timeout_us module parameters (either of which may be 0) for as long as
118 w1_master_search remains greater than 0 or is 118 w1_master_search remains greater than 0 or is -1. Each search attempt
119 decrements w1_master_search by 1 (down to 0) a 119 decrements w1_master_search by 1 (down to 0) and increments
120 w1_master_attempts by 1. 120 w1_master_attempts by 1.
121 121
122 w1 slave sysfs interface 122 w1 slave sysfs interface
123 ------------------------ 123 ------------------------
124 124
125 =================== ========================== 125 =================== ============================================================
126 bus (standard) symlink to the 126 bus (standard) symlink to the w1 bus
127 driver (standard) symlink to the 127 driver (standard) symlink to the w1 driver
128 name the device name, usually t 128 name the device name, usually the same as the directory name
129 w1_slave (optional) a binary file w 129 w1_slave (optional) a binary file whose meaning depends on the
130 family driver 130 family driver
131 rw (optional) created for sla 131 rw (optional) created for slave devices which do not have
132 appropriate family driver. 132 appropriate family driver. Allows to read/write binary data.
133 =================== ========================== 133 =================== ============================================================
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.