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