Evgeniy Polyakov | 4754639 | 2005-06-04 01:31:47 +0400 | [diff] [blame] | 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. |
Evgeniy Polyakov | f522d23 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 30 | If there is no driver for the family, default one is assigned, which allows to perform |
| 31 | almost any kind of operations. Each logical operation is a transaction |
| 32 | in nature, which can contain several (two or one) low-level operations. |
| 33 | Let's see how one can read EEPROM context: |
| 34 | 1. one must write control buffer, i.e. buffer containing command byte |
| 35 | and two byte address. At this step bus is reset and appropriate device |
| 36 | is selected using either W1_SKIP_ROM or W1_MATCH_ROM command. |
| 37 | Then provided control buffer is being written to the wire. |
| 38 | 2. reading. This will issue reading eeprom response. |
| 39 | |
| 40 | It is possible that between 1. and 2. w1 master thread will reset bus for searching |
| 41 | and slave device will be even removed, but in this case 0xff will |
| 42 | be read, since no device was selected. |
Evgeniy Polyakov | 4754639 | 2005-06-04 01:31:47 +0400 | [diff] [blame] | 43 | |
| 44 | |
| 45 | W1 device families |
| 46 | ------------------------------------------------------------------ |
| 47 | Slave devices are handled by a driver written for a family of w1 devices. |
| 48 | |
| 49 | A family driver populates a struct w1_family_ops (see w1_family.h) and |
| 50 | registers with the w1 subsystem. |
| 51 | |
| 52 | Current family drivers: |
| 53 | w1_therm - (ds18?20 thermal sensor family driver) |
| 54 | provides temperature reading function which is bound to ->rbin() method |
| 55 | of the above w1_family_ops structure. |
| 56 | |
| 57 | w1_smem - driver for simple 64bit memory cell provides ID reading method. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 58 | |
| 59 | You can call above methods by reading appropriate sysfs files. |
Evgeniy Polyakov | 4754639 | 2005-06-04 01:31:47 +0400 | [diff] [blame] | 60 | |
| 61 | |
| 62 | What does a w1 master driver need to implement? |
| 63 | ------------------------------------------------------------------ |
| 64 | |
| 65 | The driver for w1 bus master must provide at minimum two functions. |
| 66 | |
| 67 | Emulated devices must provide the ability to set the output signal level |
| 68 | (write_bit) and sample the signal level (read_bit). |
| 69 | |
| 70 | Devices that support the 1-wire natively must provide the ability to write and |
| 71 | sample a bit (touch_bit) and reset the bus (reset_bus). |
| 72 | |
| 73 | Most hardware provides higher-level functions that offload w1 handling. |
| 74 | See struct w1_bus_master definition in w1.h for details. |
| 75 | |
| 76 | |
| 77 | w1 master sysfs interface |
| 78 | ------------------------------------------------------------------ |
| 79 | <xx-xxxxxxxxxxxxx> - a directory for a found device. The format is family-serial |
| 80 | bus - (standard) symlink to the w1 bus |
| 81 | driver - (standard) symlink to the w1 driver |
David Fries | eba3b06 | 2008-10-15 22:04:47 -0700 | [diff] [blame^] | 82 | w1_master_add - Manually register a slave device |
Evgeniy Polyakov | 4754639 | 2005-06-04 01:31:47 +0400 | [diff] [blame] | 83 | w1_master_attempts - the number of times a search was attempted |
| 84 | w1_master_max_slave_count |
| 85 | - the maximum slaves that may be attached to a master |
| 86 | w1_master_name - the name of the device (w1_bus_masterX) |
David Fries | eba3b06 | 2008-10-15 22:04:47 -0700 | [diff] [blame^] | 87 | w1_master_pullup - 5V strong pullup 0 enabled, 1 disabled |
| 88 | w1_master_remove - Manually remove a slave device |
Evgeniy Polyakov | 4754639 | 2005-06-04 01:31:47 +0400 | [diff] [blame] | 89 | w1_master_search - the number of searches left to do, -1=continual (default) |
| 90 | w1_master_slave_count |
| 91 | - the number of slaves found |
| 92 | w1_master_slaves - the names of the slaves, one per line |
| 93 | w1_master_timeout - the delay in seconds between searches |
| 94 | |
| 95 | If you have a w1 bus that never changes (you don't add or remove devices), |
David Fries | eba3b06 | 2008-10-15 22:04:47 -0700 | [diff] [blame^] | 96 | you can set the module parameter search_count to a small positive number |
| 97 | for an initially small number of bus searches. Alternatively it could be |
| 98 | set to zero, then manually add the slave device serial numbers by |
| 99 | w1_master_add device file. The w1_master_add and w1_master_remove files |
| 100 | generally only make sense when searching is disabled, as a search will |
| 101 | redetect manually removed devices that are present and timeout manually |
| 102 | added devices that aren't on the bus. |
Evgeniy Polyakov | 4754639 | 2005-06-04 01:31:47 +0400 | [diff] [blame] | 103 | |
| 104 | |
| 105 | w1 slave sysfs interface |
| 106 | ------------------------------------------------------------------ |
| 107 | bus - (standard) symlink to the w1 bus |
| 108 | driver - (standard) symlink to the w1 driver |
| 109 | name - the device name, usually the same as the directory name |
| 110 | w1_slave - (optional) a binary file whose meaning depends on the |
| 111 | family driver |
Evgeniy Polyakov | f522d23 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 112 | rw - (optional) created for slave devices which do not have |
| 113 | appropriate family driver. Allows to read/write binary data. |