2 .\" Copyright (c) 2015 M. Warner Losh
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nm own_send_command ,
33 .Nm own_commmand_wait ,
34 .Nm own_self_command ,
42 .Nd Dallas Semiconductor 1-Wire Network and Transport Interface
47 .Fn own_send_command "device_t pdev" "struct ow_cmd *cmd"
49 .Fn own_command_wait "device_t pdev" "struct ow_cmd *cmd"
51 .Fn own_self_command "device_t pdev" "struct ow_cmd *cmd" "uint8_t xpt_cmd"
53 .Fn own_acquire_bus "device_t pdev" "int how"
55 .Fn own_release_bus "device_t pdev"
57 .Fn own_crc "device_t pdev" "uint8_t *buffer" "size_t len"
59 .Fn OWN_SEND_COMMAND "device_t ndev" "device_t pdev" "struct ow_cmd *cmd"
61 .Fn OWN_ACQUIRE_BUS "device_t ndev" "device_t pdev" "int how"
63 .Fn OWN_RELEASE_BUS "device_t ndev" "device_t pdev"
65 .Fn OWN_CRC "device_t ndev" "device_t pdev" "uint8_t *buffer" "size_t len"
69 interface defines three sets of functions for interacting with 1-Wire
74 ensuring data integrity.
75 Wrappers are provided for the raw
78 interfaces and should be used for improved safety over the
82 The 1-Wire bus defines different layers of access to the devices on
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.
92 encapsulates network access, speed, and timing information.
93 It specifies the commands to send and whether or not to read data.
95 .Bl -tag -width ".Va xxxx"
97 Flags controlling the interpretation of the structure.
98 These flags are defined in
100 .Bl -tag -width indent
101 .It OW_FLAG_OVERDRIVE
106 bytes at overdrive speed.
110 to be in bits to be read after
115 ROM command bytes to send.
117 Number of ROM command bytes to send.
119 Number of bytes to read after sending the ROM command.
121 Buffer for bytes read after the ROM command.
123 Transport command to send.
125 Length of the transport command bytes to send.
126 Specify 0 for no transport command.
128 Number of bytes to read after
135 then it is the number of bits to read.
136 Bits read are packed into bytes.
138 Buffer for data read.
142 acquires the 1-Wire bus, waiting if necessary,
145 then releases the bus.
147 sends the command without bus reservation.
149 is the client device (the presentation layer device) sending the command.
152 argument describes the transaction to send to the 1-Wire bus.
157 with a MATCH_ROM ROM command, the ROM address of
161 as a convenient way to create directed commands.
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.
169 It waits indefinitely if the
173 and returns the error
177 when the bus is owned by another client.
183 computes the 1-Wire standard CRC function over the data
188 and returns the result.
190 The 1-Wire standard (Maxim AN937) defines layers that are akin to ISO
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.
200 These interfaces are implemented by the
203 Presentation layer devices (children of the newbus
205 device) should only call the functions described here.
206 The functionality provided by the
208 device (specifically the
210 interface) should only be called by the
217 .Pa http://pdfserv.maximintegrated.com/en/an/AN937.pdf
220 is a registered trademark of Maxim Integrated Products, Inc.
224 driver first appeared in
229 device driver and this manual page were written by