Commit | Line | Data |
---|---|---|
4754639d EP |
1 | The 1-wire (w1) subsystem |
2 | ------------------------------------------------------------------ | |
3 | The 1-wire bus is a simple master-slave bus that communicates via a single | |
4 | signal wire (plus ground, so two wires). | |
5 | ||
6 | Devices communicate on the bus by pulling the signal to ground via an open | |
7 | drain output and by sampling the logic level of the signal line. | |
8 | ||
9 | The w1 subsystem provides the framework for managing w1 masters and | |
10 | communication with slaves. | |
11 | ||
12 | All w1 slave devices must be connected to a w1 bus master device. | |
13 | ||
14 | Example w1 master devices: | |
15 | DS9490 usb device | |
16 | W1-over-GPIO | |
17 | DS2482 (i2c to w1 bridge) | |
18 | Emulated devices, such as a RS232 converter, parallel port adapter, etc | |
19 | ||
20 | ||
21 | What does the w1 subsystem do? | |
22 | ------------------------------------------------------------------ | |
23 | When a w1 master driver registers with the w1 subsystem, the following occurs: | |
24 | ||
25 | - sysfs entries for that w1 master are created | |
26 | - the w1 bus is periodically searched for new slave devices | |
27 | ||
28 | When a device is found on the bus, w1 core checks if driver for it's family is | |
29 | loaded. If so, the family driver is attached to the slave. | |
30 | If there is no driver for the family, a simple sysfs entry is created | |
31 | for the slave device. | |
32 | ||
33 | ||
34 | W1 device families | |
35 | ------------------------------------------------------------------ | |
36 | Slave devices are handled by a driver written for a family of w1 devices. | |
37 | ||
38 | A family driver populates a struct w1_family_ops (see w1_family.h) and | |
39 | registers with the w1 subsystem. | |
40 | ||
41 | Current family drivers: | |
42 | w1_therm - (ds18?20 thermal sensor family driver) | |
43 | provides temperature reading function which is bound to ->rbin() method | |
44 | of the above w1_family_ops structure. | |
45 | ||
46 | w1_smem - driver for simple 64bit memory cell provides ID reading method. | |
1da177e4 LT |
47 | |
48 | You can call above methods by reading appropriate sysfs files. | |
4754639d EP |
49 | |
50 | ||
51 | What does a w1 master driver need to implement? | |
52 | ------------------------------------------------------------------ | |
53 | ||
54 | The driver for w1 bus master must provide at minimum two functions. | |
55 | ||
56 | Emulated devices must provide the ability to set the output signal level | |
57 | (write_bit) and sample the signal level (read_bit). | |
58 | ||
59 | Devices that support the 1-wire natively must provide the ability to write and | |
60 | sample a bit (touch_bit) and reset the bus (reset_bus). | |
61 | ||
62 | Most hardware provides higher-level functions that offload w1 handling. | |
63 | See struct w1_bus_master definition in w1.h for details. | |
64 | ||
65 | ||
66 | w1 master sysfs interface | |
67 | ------------------------------------------------------------------ | |
68 | <xx-xxxxxxxxxxxxx> - a directory for a found device. The format is family-serial | |
69 | bus - (standard) symlink to the w1 bus | |
70 | driver - (standard) symlink to the w1 driver | |
71 | w1_master_attempts - the number of times a search was attempted | |
72 | w1_master_max_slave_count | |
73 | - the maximum slaves that may be attached to a master | |
74 | w1_master_name - the name of the device (w1_bus_masterX) | |
75 | w1_master_search - the number of searches left to do, -1=continual (default) | |
76 | w1_master_slave_count | |
77 | - the number of slaves found | |
78 | w1_master_slaves - the names of the slaves, one per line | |
79 | w1_master_timeout - the delay in seconds between searches | |
80 | ||
81 | If you have a w1 bus that never changes (you don't add or remove devices), | |
82 | you can set w1_master_search to a positive value to disable searches. | |
83 | ||
84 | ||
85 | w1 slave sysfs interface | |
86 | ------------------------------------------------------------------ | |
87 | bus - (standard) symlink to the w1 bus | |
88 | driver - (standard) symlink to the w1 driver | |
89 | name - the device name, usually the same as the directory name | |
90 | w1_slave - (optional) a binary file whose meaning depends on the | |
91 | family driver | |
92 |