sys/dev/ow/owll_if.m

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