share/man/man9/own.9

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