2 # Copyright (c) 2015 M. Warner Losh <imp@FreeBSD.org>
4 # Redistribution and use in source and binary forms, with or without
5 # modification, are permitted provided that the following conditions
7 # 1. Redistributions of source code must retain the above copyright
8 # notice, this list of conditions and the following disclaimer.
9 # 2. Redistributions in binary form must reproduce the above copyright
10 # notice, this list of conditions and the following disclaimer in the
11 # documentation and/or other materials provided with the distribution.
13 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 #include <dev/ow/owll.h>
34 # Dallas Semiconductor 1-Wire bus Link Layer (owll)
36 # See Maxim Application Note AN937: Book of iButton Standards for the
37 # 1-Wire protocol specification.
38 # http://pdfserv.maximintegrated.com/en/an/AN937.pdf
40 # Note: 1-Wire is a registered trademark of Maxim Integrated Products, Inc.
42 # This file provides an interface to the logical layer of the protocol.
43 # Although the first implementation is done with GPIO bit banging, some
44 # SoCs have a 1-Wire controller with more smarts or hardware offload.
45 # Maxim datasheets also describe how to use UARTs to generate timing,
46 # as well as both usb and i2c 1-Wire controllers.
48 # Chapter 4 has all the electrical timing diagrams that make up the link
49 # layer of this protocol.
51 # Two speed classes are defined: Regular speed and Overdrive speed.
52 # It is the responsibility of a device implementing the owll(9) interface
53 # to ensure that the timings are met:
57 # 60us <= tSLOT < 120us 6us <= tSLOT <= 16us
58 # 60us <= tLOW0 < tSLOT < 120us 6us <= tLOW0 < tSLOT < 16us
59 # 1us <= tLOW1 < 15us 1us <= tLOW < 2us
60 # 1us < tLOWR < 15us 1us <= tLOWR < 2us
61 # 0 <= tRELEASE < 45us 0 <= tRELEASE < 4us
62 # 1us <= tREC < inf 1us <= tREC < inf
63 # tRDV = 15us tRDV = 2us
64 # 480us <= tRSTL < inf 48us <= tRSTL < 80us
65 # 480us <= tRSTH < inf 48us <= tRSTH < inf
66 # 15us < tPDH < 60us 2us <= tPDH < 6us
67 # 60us < tPDL < 240us 8us <= tPDL < 24us
69 # In the diagrams below, R is driven by the resistor pullup, M is driven by
70 # the master, and S is driven by the slave / target.
72 # All of these methods are expected to be called from the "network"/bus layer
73 # for doing its operations. See 1wn_if.m for those.
75 # Note: This is the polling / busy-wait interface. An interrupt-based interface
76 # may be different. But an interrupt-based, non-blocking interface can be tricky.
78 # Only the owbus should talk to this interface.
81 # WRITE-ONE (see above for timings) From Figure 4-1 AN-937
83 # |<---------tSLOT---->|<-tREC->|
84 # High RRRRM | RRRRRRRRRRRR|RRRRRRRRM
87 # Low MMMMMMM | | | MMMMMM...
90 # |<--------60us---->|
93 METHOD int write_one {
94 device_t lldev; /* Link Level device (eg bridge) */
95 struct ow_timing *timing; /* timing values */
99 # WRITE-ZERO (see above for timings) From Figure 4-2 AN-937
101 # |<---------tSLOT------>|<-tREC->|
102 # High RRRRM | | |RRRRRRRM
105 # Low MMMMMMMMMMMMMMMMMMMMMR MMMMMM...
107 # |<------60us--->| |
108 # |<-------tLOW0------>|
111 METHOD int write_zero {
112 device_t lldev; /* Link Level device (eg bridge) */
113 struct ow_timing *timing; /* timing values */
116 # READ-DATA (see above for timings) From Figure 4-3 AN-937
118 # |<---------tSLOT------>|<-tREC->|
119 # High RRRRM | rrrrrrrrrrrrrrrRRRRRRRM
122 # Low MMMMMMMSSSSSSSSSSSSSSR MMMMMM...
123 # |<tLOWR>< sample > |
124 # |<------tRDV---->| |
127 # r -- allowed to pull high via the resistor when slave writes a 1-bit
129 METHOD int read_data {
130 device_t lldev; /* Link Level device (eg bridge) */
131 struct ow_timing *timing; /* timing values */
132 int *bit; /* Bit we sampled */
135 # RESET AND PRESENCE PULSE (see above for timings) From Figure 4-4 AN-937
137 # |<---------tRSTH------------>|
138 # High RRRM | | RRRRRRRS | RRRR RRM
141 # Low MMMMMMMM MMMMMM| | | SSSSSSSSSS MMMMMM
142 # |<----tRSTL--->| | |<-tPDL---->|
146 # Note: for Regular Speed operations, tRSTL + tR should be less than 960us to
147 # avoid interfering with other devives on the bus.
149 # Returns errors associating with acquiring the bus, or EIO to indicate
150 # that the bus was low during the RRRR time where it should have been
151 # pulled high. The present field is always updated, even on error.
153 METHOD int reset_and_presence {
154 device_t lldev; /* Link level device (eg bridge) */
155 struct ow_timing *timing; /* timing values */
156 int *present; /* 0 = slave 1 = no slave -1 = bus error */