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 32INTERFACE 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# 94METHOD 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# 112METHOD 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# 130METHOD 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# 154METHOD 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}; 159