1287225Simp#- 2287225Simp# Copyright (c) 2015 M. Warner Losh <imp@freebsd.org> 3287225Simp# All rights reserved. 4287225Simp# 5287225Simp# Redistribution and use in source and binary forms, with or without 6287225Simp# modification, are permitted provided that the following conditions 7287225Simp# are met: 8287225Simp# 1. Redistributions of source code must retain the above copyright 9287225Simp# notice, this list of conditions and the following disclaimer. 10287225Simp# 2. Redistributions in binary form must reproduce the above copyright 11287225Simp# notice, this list of conditions and the following disclaimer in the 12287225Simp# documentation and/or other materials provided with the distribution. 13287225Simp# 14287225Simp# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15287225Simp# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16287225Simp# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17287225Simp# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18287225Simp# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19287225Simp# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20287225Simp# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21287225Simp# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22287225Simp# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23287225Simp# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24287225Simp# SUCH DAMAGE. 25287225Simp# 26287225Simp# $FreeBSD: releng/11.0/sys/dev/ow/owll_if.m 287225 2015-08-27 23:33:38Z imp $ 27287225Simp# 28287225Simp 29287225Simp#include <sys/bus.h> 30287225Simp#include <dev/ow/owll.h> 31287225Simp 32287225SimpINTERFACE owll; 33287225Simp 34287225Simp# 35287225Simp# Dallas Semiconductor 1-Wire bus Link Layer (owll) 36287225Simp# 37287225Simp# See Maxim Application Note AN937: Book of iButton Standards for the 38287225Simp# 1-Wire protocol specification. 39287225Simp# http://pdfserv.maximintegrated.com/en/an/AN937.pdf 40287225Simp# 41287225Simp# Note: 1-Wire is a registered trademark of Maxim Integrated Products, Inc. 42287225Simp# 43287225Simp# This file provides an interface to the logical layer of the protocol. 44287225Simp# Although the first implementation is done with GPIO bit banging, some 45287225Simp# SoCs have a 1-Wire controller with more smarts or hardware offload. 46287225Simp# Maxim datasheets also describe how to use UARTs to generate timing, 47287225Simp# as well as both usb and i2c 1-Wire controllers. 48287225Simp# 49287225Simp# Chapter 4 has all the electrical timing diagrams that make up the link 50287225Simp# layer of this protocol. 51287225Simp# 52287225Simp# Two speed classes are defined: Regular speed and Overdrive speed. 53287225Simp# It is the responsibility of a device implementing the owll(9) interface 54287225Simp# to ensure that the timings are met: 55287225Simp# 56287225Simp# Regular Overdrive 57287225Simp# 58287225Simp# 60us <= tSLOT < 120us 6us <= tSLOT <= 16us 59287225Simp# 60us <= tLOW0 < tSLOT < 120us 6us <= tLOW0 < tSLOT < 16us 60287225Simp# 1us <= tLOW1 < 15us 1us <= tLOW < 2us 61287225Simp# 1us < tLOWR < 15us 1us <= tLOWR < 2us 62287225Simp# 0 <= tRELEASE < 45us 0 <= tRELEASE < 4us 63287225Simp# 1us <= tREC < inf 1us <= tREC < inf 64287225Simp# tRDV = 15us tRDV = 2us 65287225Simp# 480us <= tRSTL < inf 48us <= tRSTL < 80us 66287225Simp# 480us <= tRSTH < inf 48us <= tRSTH < inf 67287225Simp# 15us < tPDH < 60us 2us <= tPDH < 6us 68287225Simp# 60us < tPDL < 240us 8us <= tPDL < 24us 69287225Simp# 70287225Simp# In the diagrams below, R is driven by the resistor pullup, M is driven by 71287225Simp# the master, and S is driven by the slave / target. 72287225Simp# 73287225Simp# All of these methods are expected to be called from the "network"/bus layer 74287225Simp# for doing its operations. See 1wn_if.m for those. 75287225Simp# 76287225Simp# Note: This is the polling / busy-wait interface. An interrupt-based interface 77287225Simp# may be different. But an interrupt-based, non-blocking interface can be tricky. 78287225Simp# 79287225Simp# Only the owbus should talk to this interface. 80287225Simp# 81287225Simp 82287225Simp# WRITE-ONE (see above for timings) From Figure 4-1 AN-937 83287225Simp# 84287225Simp# |<---------tSLOT---->|<-tREC->| 85287225Simp# High RRRRM | RRRRRRRRRRRR|RRRRRRRRM 86287225Simp# M | R | | | M 87287225Simp# M| R | | | M 88287225Simp# Low MMMMMMM | | | MMMMMM... 89287225Simp# |<-tLOW1->| | | 90287225Simp# |<------15us--->| | 91287225Simp# |<--------60us---->| 92287225Simp# 93287225Simp# 94287225SimpMETHOD int write_one { 95287225Simp device_t lldev; /* Link Level device (eg bridge) */ 96287225Simp struct ow_timing *timing; /* timing values */ 97287225Simp}; 98287225Simp 99287225Simp 100287225Simp# WRITE-ZERO (see above for timings) From Figure 4-2 AN-937 101287225Simp# 102287225Simp# |<---------tSLOT------>|<-tREC->| 103287225Simp# High RRRRM | | |RRRRRRRM 104287225Simp# M | | R M 105287225Simp# M| | | |R M 106287225Simp# Low MMMMMMMMMMMMMMMMMMMMMR MMMMMM... 107287225Simp# |<--15us->| | | 108287225Simp# |<------60us--->| | 109287225Simp# |<-------tLOW0------>| 110287225Simp# 111287225Simp# 112287225SimpMETHOD int write_zero { 113287225Simp device_t lldev; /* Link Level device (eg bridge) */ 114287225Simp struct ow_timing *timing; /* timing values */ 115287225Simp}; 116287225Simp 117287225Simp# READ-DATA (see above for timings) From Figure 4-3 AN-937 118287225Simp# 119287225Simp# |<---------tSLOT------>|<-tREC->| 120287225Simp# High RRRRM | rrrrrrrrrrrrrrrRRRRRRRM 121287225Simp# M | r | R M 122287225Simp# M| r | |R M 123287225Simp# Low MMMMMMMSSSSSSSSSSSSSSR MMMMMM... 124287225Simp# |<tLOWR>< sample > | 125287225Simp# |<------tRDV---->| | 126287225Simp# ->| |<-tRELEASE 127287225Simp# 128287225Simp# r -- allowed to pull high via the resistor when slave writes a 1-bit 129287225Simp# 130287225SimpMETHOD int read_data { 131287225Simp device_t lldev; /* Link Level device (eg bridge) */ 132287225Simp struct ow_timing *timing; /* timing values */ 133287225Simp int *bit; /* Bit we sampled */ 134287225Simp}; 135287225Simp 136287225Simp# RESET AND PRESENCE PULSE (see above for timings) From Figure 4-4 AN-937 137287225Simp# 138287225Simp# |<---------tRSTH------------>| 139287225Simp# High RRRM | | RRRRRRRS | RRRR RRM 140287225Simp# M | |R| |S | R M 141287225Simp# M| R | | S |R M 142287225Simp# Low MMMMMMMM MMMMMM| | | SSSSSSSSSS MMMMMM 143287225Simp# |<----tRSTL--->| | |<-tPDL---->| 144287225Simp# | ->| |<-tR | | 145287225Simp# |<tPDH>| 146287225Simp# 147287225Simp# Note: for Regular Speed operations, tRSTL + tR should be less than 960us to 148287225Simp# avoid interfering with other devives on the bus. 149287225Simp# 150287225Simp# Returns errors associating with acquiring the bus, or EIO to indicate 151287225Simp# that the bus was low during the RRRR time where it should have been 152287225Simp# pulled high. The present field is always updated, even on error. 153287225Simp# 154287225SimpMETHOD int reset_and_presence { 155287225Simp device_t lldev; /* Link level device (eg bridge) */ 156287225Simp struct ow_timing *timing; /* timing values */ 157287225Simp int *present; /* 0 = slave 1 = no slave -1 = bus error */ 158287225Simp}; 159