2 .\" Copyright (c) 2015 M. Warner Losh <imp@FreeBSD.org>
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nm own_send_command ,
32 .Nm own_commmand_wait ,
33 .Nm own_self_command ,
41 .Nd Dallas Semiconductor 1-Wire Network and Transport Interface
46 .Fn own_send_command "device_t pdev" "struct ow_cmd *cmd"
48 .Fn own_command_wait "device_t pdev" "struct ow_cmd *cmd"
50 .Fn own_self_command "device_t pdev" "struct ow_cmd *cmd" "uint8_t xpt_cmd"
52 .Fn own_acquire_bus "device_t pdev" "int how"
54 .Fn own_release_bus "device_t pdev"
56 .Fn own_crc "device_t pdev" "uint8_t *buffer" "size_t len"
58 .Fn OWN_SEND_COMMAND "device_t ndev" "device_t pdev" "struct ow_cmd *cmd"
60 .Fn OWN_ACQUIRE_BUS "device_t ndev" "device_t pdev" "int how"
62 .Fn OWN_RELEASE_BUS "device_t ndev" "device_t pdev"
64 .Fn OWN_CRC "device_t ndev" "device_t pdev" "uint8_t *buffer" "size_t len"
68 interface defines three sets of functions for interacting with 1-Wire
73 ensuring data integrity.
74 Wrappers are provided for the raw
77 interfaces and should be used for improved safety over the
81 The 1-Wire bus defines different layers of access to the devices on
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.
91 encapsulates network access, speed, and timing information.
92 It specifies the commands to send and whether or not to read data.
94 .Bl -tag -width ".Va xxxx"
96 Flags controlling the interpretation of the structure.
97 These flags are defined in
99 .Bl -tag -width indent
100 .It OW_FLAG_OVERDRIVE
105 bytes at overdrive speed.
109 to be in bits to be read after
114 ROM command bytes to send.
116 Number of ROM command bytes to send.
118 Number of bytes to read after sending the ROM command.
120 Buffer for bytes read after the ROM command.
122 Transport command to send.
124 Length of the transport command bytes to send.
125 Specify 0 for no transport command.
127 Number of bytes to read after
134 then it is the number of bits to read.
135 Bits read are packed into bytes.
137 Buffer for data read.
141 acquires the 1-Wire bus, waiting if necessary,
144 then releases the bus.
146 sends the command without bus reservation.
148 is the client device (the presentation layer device) sending the command.
151 argument describes the transaction to send to the 1-Wire bus.
156 with a MATCH_ROM ROM command, the ROM address of
160 as a convenient way to create directed commands.
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.
168 It waits indefinitely if the
172 and returns the error
176 when the bus is owned by another client.
182 computes the 1-Wire standard CRC function over the data
187 and returns the result.
189 The 1-Wire standard (Maxim AN937) defines layers that are akin to ISO
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.
199 These interfaces are implemented by the
202 Presentation layer devices (children of the newbus
204 device) should only call the functions described here.
205 The functionality provided by the
207 device (specifically the
209 interface) should only be called by the
216 .Pa https://pdfserv.maximintegrated.com/en/an/AN937.pdf
219 is a registered trademark of Maxim Integrated Products, Inc.
223 driver first appeared in
228 device driver and this manual page were written by