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