share/man/man4/owc.4

   1 .\"
   2 .\" Copyright (c) 2015 M. Warner Losh <imp@FreeBSD.org>
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. The name of the author may not be used to endorse or promote products
  10 .\"    derived from this software without specific prior written permission.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd June 26, 2019
  27 .Dt OWC 4
  28 .Os
  29 .Sh NAME
  30 .Nm owc
  31 .Nd Dallas Semiconductor 1-Wire Controller
  32 .Sh SYNOPSIS
  33 .Cd device owc
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 module implements Dallas Semiconductor 1-Wire signaling.
  38 It attaches the
  39 .Xr ow 4
  40 driver 1-Wire bus protocol.
  41 The
  42 .Nm
  43 device implements the Link Layer of the 1-Wire bus protocol stack.
  44 .Pp
  45 Bit banging a pin on a
  46 .Xr gpiobus 4
  47 is the only supported controller.
  48 Both standard and overdrive transfer timings are implemented.
  49 Strong pull-up functionality needed to support parasitic mode is not
  50 implemented.
  51 .Pp
  52 To enable 1-Wire for FDT systems requires modifying the DTS for your
  53 board to add something like:
  54 .Bd -literal
  55 / {
  56         ...
  57         onewire {
  58                 compatible = "w1-gpio";
  59                 gpios = <&gpio 4 1>;
  60         };
  61         ...
  62 };
  63 .Ed
  64 .Pp
  65 The gpios property describes the GPIO pin the 1-Wire bus is connected
  66 to.
  67 For more details about the
  68 .Va gpios
  69 property, please consult
  70 .Pa /usr/src/sys/dts/bindings-gpio.txt .
  71 .Pp
  72 On a
  73 .Xr device.hints 5
  74 based system these values are required for the
  75 .Nm :
  76 .Bl -tag -width ".Va hint.owc.%d.atXXX"
  77 .It Va hint.owc.%d.at
  78 The
  79 .Nm gpiobus
  80 you are attaching to.
  81 .It Va hint.owc.%d.pins
  82 This is a bitmask that defines a pin on the
  83 .Nm gpiobus
  84 that is to be used for the 1-Wire bus.
  85 For instance, to configure pin 10, use the bitmask of 0x400.
  86 Please note that this mask should have only one bit set
  87 (any other bits - i.e., pins - will be ignored).
  88 .El
  89 .Sh SEE ALSO
  90 .Xr gpiobus 4 ,
  91 .Xr ow 4 ,
  92 .Xr ow_temp 4 ,
  93 .Xr owll 9 ,
  94 .Xr own 9
  95 .Sh LEGAL
  96 .Tn 1-Wire
  97 is a registered trademark of Maxim Integrated Products, Inc.
  98 .Sh HISTORY
  99 The
 100 .Nm
 101 driver first appeared in
 102 .Fx 11.0 .
 103 .Sh AUTHORS
 104 The
 105 .Nm
 106 device driver and this manual page were written by
 107 .An Warner Losh .
 108 .Sh CAVEATS
 109 The gpio driver implements timing by busy waiting, which can cause a
 110 high load on slower systems.
 111 .Sh BUGS
 112 Overdrive mode has not actually been tested.