share/man/man9/own.9

   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 July 20, 2015
  28 .Dt OWN 9
  29 .Os
  30 .Sh NAME
  31 .Nm own ,
  32 .Nm own_send_command ,
  33 .Nm own_commmand_wait ,
  34 .Nm own_self_command ,
  35 .Nm own_acquire_bus ,
  36 .Nm own crc ,
  37 .Nm own_release_bus ,
  38 .Nm OWN_ACQUIRE_BUS ,
  39 .Nm OWN_CRC ,
  40 .Nm OWN_RELEASE_BUS ,
  41 .Nm OWN_SEND_COMMAND
  42 .Nd Dallas Semiconductor 1-Wire Network and Transport Interface
  43 .Sh SYNOPSIS
  44 .In sys/bus.h
  45 .In dev/ow/own.h
  46 .Ft int
  47 .Fn own_send_command "device_t pdev" "struct ow_cmd *cmd"
  48 .Ft int
  49 .Fn own_command_wait "device_t pdev" "struct ow_cmd *cmd"
  50 .Ft int
  51 .Fn own_self_command "device_t pdev" "struct ow_cmd *cmd" "uint8_t xpt_cmd"
  52 .Ft int
  53 .Fn own_acquire_bus "device_t pdev" "int how"
  54 .Ft int
  55 .Fn own_release_bus "device_t pdev"
  56 .Ft int
  57 .Fn own_crc "device_t pdev" "uint8_t *buffer" "size_t len"
  58 .Ft int
  59 .Fn OWN_SEND_COMMAND "device_t ndev" "device_t pdev" "struct ow_cmd *cmd"
  60 .Ft int
  61 .Fn OWN_ACQUIRE_BUS "device_t ndev" "device_t pdev" "int how"
  62 .Ft void
  63 .Fn OWN_RELEASE_BUS "device_t ndev" "device_t pdev"
  64 .Ft uint8_t
  65 .Fn OWN_CRC "device_t ndev" "device_t pdev" "uint8_t *buffer" "size_t len"
  66 .Sh DESCRIPTION
  67 The
  68 .Nm
  69 interface defines three sets of functions for interacting with 1-Wire
  70 devices:
  71 sending commands,
  72 reserving the bus,
  73 and
  74 ensuring data integrity.
  75 Wrappers are provided for the raw
  76 .Nm OWN
  77 .Xr kobj 9
  78 interfaces and should be used for improved safety over the
  79 .Xr kobj 9
  80 ones.
  81 .Ss Bus Commands
  82 The 1-Wire bus defines different layers of access to the devices on
  83 the bus.
  84 The
  85 .Nm
  86 functions provide access to the network and transport layers.
  87 The network layer designates the next command as being either for all
  88 devices on the bus, or for a specific device.
  89 The network layer also specifies the speed used by the link layer.
  90 .Pp
  91 .Vt "struct ow_cmd"
  92 encapsulates network access, speed, and timing information.
  93 It specifies the commands to send and whether or not to read data.
  94 Its members are:
  95 .Bl -tag -width ".Va xxxx"
  96 .It Va flags
  97 Flags controlling the interpretation of the structure.
  98 These flags are defined in
  99 .In dev/ow/ow.h :
 100 .Bl -tag -width indent
 101 .It OW_FLAG_OVERDRIVE
 102 Send
 103 .Va xpt_cmd
 104 bytes and read
 105 .Va xpt_read
 106 bytes at overdrive speed.
 107 .It OW_FLAG_READ_BIT
 108 Interpret
 109 .Va xpt_read_len
 110 to be in bits to be read after
 111 .Va xpt_cmd
 112 rather than bytes.
 113 .El
 114 .It Va rom_cmd
 115 ROM command bytes to send.
 116 .It Va rom_len
 117 Number of ROM command bytes to send.
 118 .It Va rom_read_len
 119 Number of bytes to read after sending the ROM command.
 120 .It Va rom_read
 121 Buffer for bytes read after the ROM command.
 122 .It Va xpt_cmd
 123 Transport command to send.
 124 .It Va xpt_len
 125 Length of the transport command bytes to send.
 126 Specify 0 for no transport command.
 127 .It Va xpt_read_len
 128 Number of bytes to read after
 129 .Va xpt_cmd
 130 bytes are sent.
 131 If the
 132 .Dv OW_FLAG_READ_BIT
 133 bit is set in
 134 .Va flags ,
 135 then it is the number of bits to read.
 136 Bits read are packed into bytes.
 137 .It Va xpt_read
 138 Buffer for data read.
 139 .El
 140 .Pp
 141 .Fn own_command_wait
 142 acquires the 1-Wire bus, waiting if necessary,
 143 sends the command,
 144 and
 145 then releases the bus.
 146 .Fn own_send_command
 147 sends the command without bus reservation.
 148 .Fa pdev
 149 is the client device (the presentation layer device) sending the command.
 150 The
 151 .Fa cmd
 152 argument describes the transaction to send to the 1-Wire bus.
 153 .Pp
 154 .Fn own_self_command
 155 fills in
 156 .Fa cmd
 157 with a MATCH_ROM ROM command, the ROM address of
 158 .Fa pdev
 159 and the
 160 .Fa xpt_cmd
 161 as a convenient way to create directed commands.
 162 .Ss Bus Reservation
 163 The 1-Wire system includes an advisory lock for the bus that
 164 presentation layer devices can use to coordinate access.
 165 Locking is purely advisory at this time.
 166 .Pp
 167 .Fn own_acquire_bus
 168 reserves the bus.
 169 It waits indefinitely if the
 170 .Fa how
 171 argument is
 172 .Dv OWN_WAIT
 173 and returns the error
 174 .Dv EWOULDBLOCK
 175 if passed
 176 .Dv OWN_DONTWAIT
 177 when the bus is owned by another client.
 178 .Pp
 179 .Fn own_release_bus
 180 releases the bus.
 181 .Ss Data Integrity
 182 .Fn own_crc
 183 computes the 1-Wire standard CRC function over the data
 184 passed in
 185 .Fa buffer
 186 and
 187 .Fa len
 188 and returns the result.
 189 .Ss Notes
 190 The 1-Wire standard (Maxim AN937) defines layers that are akin to ISO
 191 networking layers.
 192 The lowest relevant layer, the link layer, defines the polling windows
 193 and the timing of the signaling of different modes.
 194 The network layer is built on top of the link layer
 195 and is used to address devices in a unicast or multicast manner.
 196 The transport layer defines commands and responses from the devices.
 197 The presentation layer is composed of the device specific commands and
 198 actions used to control the specific 1-Wire devices on bus.
 199 .Pp
 200 These interfaces are implemented by the
 201 .Xr ow 4
 202 device.
 203 Presentation layer devices (children of the newbus
 204 .Xr ow 4
 205 device) should only call the functions described here.
 206 The functionality provided by the
 207 .Xr owc 4
 208 device (specifically the
 209 .Xr owll 9
 210 interface) should only be called by the
 211 .Xr ow 4
 212 driver.
 213 .Sh SEE ALSO
 214 .Xr ow 4 ,
 215 .Xr owc 4 ,
 216 .Xr owll 9
 217 .Pa  https://pdfserv.maximintegrated.com/en/an/AN937.pdf
 218 .Sh LEGAL
 219 .Tn 1-Wire
 220 is a registered trademark of Maxim Integrated Products, Inc.
 221 .Sh HISTORY
 222 The
 223 .Nm
 224 driver first appeared in
 225 .Fx 11.0 .
 226 .Sh AUTHORS
 227 The
 228 .Nm
 229 device driver and this manual page were written by
 230 .An Warner Losh .