Commit | Line | Data |
---|---|---|
e9bb6275 MCC |
1 | ========================================= |
2 | Introduction to the 1-wire (w1) subsystem | |
3 | ========================================= | |
4 | ||
4754639d EP |
5 | The 1-wire bus is a simple master-slave bus that communicates via a single |
6 | signal wire (plus ground, so two wires). | |
7 | ||
8 | Devices communicate on the bus by pulling the signal to ground via an open | |
9 | drain output and by sampling the logic level of the signal line. | |
10 | ||
11 | The w1 subsystem provides the framework for managing w1 masters and | |
12 | communication with slaves. | |
13 | ||
14 | All w1 slave devices must be connected to a w1 bus master device. | |
15 | ||
16 | Example w1 master devices: | |
e9bb6275 MCC |
17 | |
18 | - DS9490 usb device | |
19 | - W1-over-GPIO | |
20 | - DS2482 (i2c to w1 bridge) | |
21 | - Emulated devices, such as a RS232 converter, parallel port adapter, etc | |
4754639d EP |
22 | |
23 | ||
24 | What does the w1 subsystem do? | |
e9bb6275 MCC |
25 | ------------------------------ |
26 | ||
4754639d EP |
27 | When a w1 master driver registers with the w1 subsystem, the following occurs: |
28 | ||
29 | - sysfs entries for that w1 master are created | |
30 | - the w1 bus is periodically searched for new slave devices | |
31 | ||
8d7bda51 AS |
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 driver is attached to the slave. | |
f522d239 EP |
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 operation is a transaction | |
36 | in nature, which can contain several (two or one) low-level operations. | |
37 | Let's see how one can read EEPROM context: | |
38 | 1. one must write control buffer, i.e. buffer containing command byte | |
39 | and two byte address. At this step bus is reset and appropriate device | |
40 | is selected using either W1_SKIP_ROM or W1_MATCH_ROM command. | |
41 | Then provided control buffer is being written to the wire. | |
42 | 2. reading. This will issue reading eeprom response. | |
43 | ||
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 this case 0xff will | |
46 | be read, since no device was selected. | |
4754639d EP |
47 | |
48 | ||
49 | W1 device families | |
e9bb6275 MCC |
50 | ------------------ |
51 | ||
4754639d EP |
52 | Slave devices are handled by a driver written for a family of w1 devices. |
53 | ||
54 | A family driver populates a struct w1_family_ops (see w1_family.h) and | |
55 | registers with the w1 subsystem. | |
56 | ||
57 | Current family drivers: | |
e9bb6275 MCC |
58 | |
59 | w1_therm | |
60 | - (ds18?20 thermal sensor family driver) | |
4754639d EP |
61 | provides temperature reading function which is bound to ->rbin() method |
62 | of the above w1_family_ops structure. | |
63 | ||
e9bb6275 MCC |
64 | w1_smem |
65 | - driver for simple 64bit memory cell provides ID reading method. | |
1da177e4 LT |
66 | |
67 | You can call above methods by reading appropriate sysfs files. | |
4754639d EP |
68 | |
69 | ||
70 | What does a w1 master driver need to implement? | |
e9bb6275 | 71 | ----------------------------------------------- |
4754639d EP |
72 | |
73 | The driver for w1 bus master must provide at minimum two functions. | |
74 | ||
75 | Emulated devices must provide the ability to set the output signal level | |
76 | (write_bit) and sample the signal level (read_bit). | |
77 | ||
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 (reset_bus). | |
80 | ||
81 | Most hardware provides higher-level functions that offload w1 handling. | |
82 | See struct w1_bus_master definition in w1.h for details. | |
83 | ||
84 | ||
85 | w1 master sysfs interface | |
e9bb6275 MCC |
86 | ------------------------- |
87 | ||
88 | ========================= ===================================================== | |
89 | <xx-xxxxxxxxxxxx> A directory for a found device. The format is | |
90 | family-serial | |
91 | bus (standard) symlink to the w1 bus | |
92 | driver (standard) symlink to the w1 driver | |
93 | w1_master_add (rw) manually register a slave device | |
94 | w1_master_attempts (ro) the number of times a search was attempted | |
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 device (w1_bus_masterX) | |
97 | w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled | |
98 | w1_master_remove (rw) manually remove a slave device | |
99 | w1_master_search (rw) the number of searches left to do, | |
100 | -1=continual (default) | |
101 | w1_master_slave_count (ro) the number of slaves found | |
102 | w1_master_slaves (ro) the names of the slaves, one per line | |
103 | w1_master_timeout (ro) the delay in seconds between searches | |
104 | w1_master_timeout_us (ro) the delay in microseconds beetwen searches | |
105 | ========================= ===================================================== | |
4754639d EP |
106 | |
107 | If you have a w1 bus that never changes (you don't add or remove devices), | |
eba3b06d DF |
108 | you can set the module parameter search_count to a small positive number |
109 | for an initially small number of bus searches. Alternatively it could be | |
110 | set to zero, then manually add the slave device serial numbers by | |
111 | w1_master_add device file. The w1_master_add and w1_master_remove files | |
112 | generally only make sense when searching is disabled, as a search will | |
113 | redetect manually removed devices that are present and timeout manually | |
114 | added devices that aren't on the bus. | |
4754639d | 115 | |
c3098356 DK |
116 | Bus searches occur at an interval, specified as a summ of timeout and |
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 -1. Each search attempt | |
119 | decrements w1_master_search by 1 (down to 0) and increments | |
120 | w1_master_attempts by 1. | |
4754639d EP |
121 | |
122 | w1 slave sysfs interface | |
e9bb6275 MCC |
123 | ------------------------ |
124 | ||
125 | =================== ============================================================ | |
126 | bus (standard) symlink to the w1 bus | |
127 | driver (standard) symlink to the w1 driver | |
128 | name the device name, usually the same as the directory name | |
129 | w1_slave (optional) a binary file whose meaning depends on the | |
130 | family driver | |
131 | rw (optional) created for slave devices which do not have | |
132 | appropriate family driver. Allows to read/write binary data. | |
133 | =================== ============================================================ |