share/man/man4/owc.4

   1 .\"
   2 .\" Copyright (c) 2015 M. Warner Losh
   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. The name of the author may not be used to endorse or promote products
  11 .\"    derived from this software without specific prior written permission.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd June 26, 2019
  28 .Dt OWC 4
  29 .Os
  30 .Sh NAME
  31 .Nm owc
  32 .Nd Dallas Semiconductor 1-Wire Controller
  33 .Sh SYNOPSIS
  34 .Cd device owc
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 module implements Dallas Semiconductor 1-Wire signaling.
  39 It attaches the
  40 .Xr ow 4
  41 driver 1-Wire bus protocol.
  42 The
  43 .Nm
  44 device implements the Link Layer of the 1-Wire bus protocol stack.
  45 .Pp
  46 Bit banging a pin on a
  47 .Xr gpiobus 4
  48 is the only supported controller.
  49 Both standard and overdrive transfer timings are implemented.
  50 Strong pull-up functionality needed to support parasitic mode is not
  51 implemented.
  52 .Pp
  53 To enable 1-Wire for FDT systems requires modifying the DTS for your
  54 board to add something like:
  55 .Bd -literal
  56 / {
  57         ...
  58         onewire {
  59                 compatible = "w1-gpio";
  60                 gpios = <&gpio 4 1>;
  61         };
  62         ...
  63 };
  64 .Ed
  65 .Pp
  66 The gpios property describes the GPIO pin the 1-Wire bus is connected
  67 to.
  68 For more details about the
  69 .Va gpios
  70 property, please consult
  71 .Pa /usr/src/sys/dts/bindings-gpio.txt .
  72 .Pp
  73 On a
  74 .Xr device.hints 5
  75 based system these values are required for the
  76 .Nm :
  77 .Bl -tag -width ".Va hint.owc.%d.atXXX"
  78 .It Va hint.owc.%d.at
  79 The
  80 .Nm gpiobus
  81 you are attaching to.
  82 .It Va hint.owc.%d.pins
  83 This is a bitmask that defines a pin on the
  84 .Nm gpiobus
  85 that is to be used for the 1-Wire bus.
  86 For instance, to configure pin 10, use the bitmask of 0x400.
  87 Please note that this mask should have only one bit set
  88 (any other bits - i.e., pins - will be ignored).
  89 .El
  90 .Sh SEE ALSO
  91 .Xr gpiobus 4 ,
  92 .Xr ow 4 ,
  93 .Xr ow_temp 4 ,
  94 .Xr owll 9 ,
  95 .Xr own 9
  96 .Sh LEGAL
  97 .Tn 1-Wire
  98 is a registered trademark of Maxim Integrated Products, Inc.
  99 .Sh HISTORY
 100 The
 101 .Nm
 102 driver first appeared in
 103 .Fx 11.0 .
 104 .Sh AUTHORS
 105 The
 106 .Nm
 107 device driver and this manual page were written by
 108 .An Warner Losh .
 109 .Sh CAVEATS
 110 The gpio driver implements timing by busy waiting, which can cause a
 111 high load on slower systems.
 112 .Sh BUGS
 113 Overdrive mode has not actually been tested.