path: root/share/man/man9/own.9

.\"
.\" Copyright (c) 2015 M. Warner Losh <imp@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd July 20, 2015
.Dt OWN 9
.Os
.Sh NAME
.Nm own ,
.Nm own_send_command ,
.Nm own_command_wait ,
.Nm own_self_command ,
.Nm own_acquire_bus ,
.Nm own crc ,
.Nm own_release_bus ,
.Nm OWN_ACQUIRE_BUS ,
.Nm OWN_CRC ,
.Nm OWN_RELEASE_BUS ,
.Nm OWN_SEND_COMMAND
.Nd Dallas Semiconductor 1-Wire Network and Transport Interface
.Sh SYNOPSIS
.In sys/bus.h
.In dev/ow/own.h
.Ft int
.Fn own_send_command "device_t pdev" "struct ow_cmd *cmd"
.Ft int
.Fn own_command_wait "device_t pdev" "struct ow_cmd *cmd"
.Ft int
.Fn own_self_command "device_t pdev" "struct ow_cmd *cmd" "uint8_t xpt_cmd"
.Ft int
.Fn own_acquire_bus "device_t pdev" "int how"
.Ft int
.Fn own_release_bus "device_t pdev"
.Ft int
.Fn own_crc "device_t pdev" "uint8_t *buffer" "size_t len"
.Ft int
.Fn OWN_SEND_COMMAND "device_t ndev" "device_t pdev" "struct ow_cmd *cmd"
.Ft int
.Fn OWN_ACQUIRE_BUS "device_t ndev" "device_t pdev" "int how"
.Ft void
.Fn OWN_RELEASE_BUS "device_t ndev" "device_t pdev"
.Ft uint8_t
.Fn OWN_CRC "device_t ndev" "device_t pdev" "uint8_t *buffer" "size_t len"
.Sh DESCRIPTION
The
.Nm
interface defines three sets of functions for interacting with 1-Wire
devices:
sending commands,
reserving the bus,
and
ensuring data integrity.
Wrappers are provided for the raw
.Nm OWN
.Xr kobj 9
interfaces and should be used for improved safety over the
.Xr kobj 9
ones.
.Ss Bus Commands
The 1-Wire bus defines different layers of access to the devices on
the bus.
The
.Nm
functions provide access to the network and transport layers.
The network layer designates the next command as being either for all
devices on the bus, or for a specific device.
The network layer also specifies the speed used by the link layer.
.Pp
.Vt "struct ow_cmd"
encapsulates network access, speed, and timing information.
It specifies the commands to send and whether or not to read data.
Its members are:
.Bl -tag -width ".Va xxxx"
.It Va flags
Flags controlling the interpretation of the structure.
These flags are defined in
.In dev/ow/ow.h :
.Bl -tag -width indent
.It OW_FLAG_OVERDRIVE
Send
.Va xpt_cmd
bytes and read
.Va xpt_read
bytes at overdrive speed.
.It OW_FLAG_READ_BIT
Interpret
.Va xpt_read_len
to be in bits to be read after
.Va xpt_cmd
rather than bytes.
.El
.It Va rom_cmd
ROM command bytes to send.
.It Va rom_len
Number of ROM command bytes to send.
.It Va rom_read_len
Number of bytes to read after sending the ROM command.
.It Va rom_read
Buffer for bytes read after the ROM command.
.It Va xpt_cmd
Transport command to send.
.It Va xpt_len
Length of the transport command bytes to send.
Specify 0 for no transport command.
.It Va xpt_read_len
Number of bytes to read after
.Va xpt_cmd
bytes are sent.
If the
.Dv OW_FLAG_READ_BIT
bit is set in
.Va flags ,
then it is the number of bits to read.
Bits read are packed into bytes.
.It Va xpt_read
Buffer for data read.
.El
.Pp
.Fn own_command_wait
acquires the 1-Wire bus, waiting if necessary,
sends the command,
and
then releases the bus.
.Fn own_send_command
sends the command without bus reservation.
.Fa pdev
is the client device (the presentation layer device) sending the command.
The
.Fa cmd
argument describes the transaction to send to the 1-Wire bus.
.Pp
.Fn own_self_command
fills in
.Fa cmd
with a MATCH_ROM ROM command, the ROM address of
.Fa pdev
and the
.Fa xpt_cmd
as a convenient way to create directed commands.
.Ss Bus Reservation
The 1-Wire system includes an advisory lock for the bus that
presentation layer devices can use to coordinate access.
Locking is purely advisory at this time.
.Pp
.Fn own_acquire_bus
reserves the bus.
It waits indefinitely if the
.Fa how
argument is
.Dv OWN_WAIT
and returns the error
.Dv EWOULDBLOCK
if passed
.Dv OWN_DONTWAIT
when the bus is owned by another client.
.Pp
.Fn own_release_bus
releases the bus.
.Ss Data Integrity
.Fn own_crc
computes the 1-Wire standard CRC function over the data
passed in
.Fa buffer
and
.Fa len
and returns the result.
.Ss Notes
The 1-Wire standard (Maxim AN937) defines layers that are akin to ISO
networking layers.
The lowest relevant layer, the link layer, defines the polling windows
and the timing of the signaling of different modes.
The network layer is built on top of the link layer
and is used to address devices in a unicast or multicast manner.
The transport layer defines commands and responses from the devices.
The presentation layer is composed of the device specific commands and
actions used to control the specific 1-Wire devices on bus.
.Pp
These interfaces are implemented by the
.Xr ow 4
device.
Presentation layer devices (children of the newbus
.Xr ow 4
device) should only call the functions described here.
The functionality provided by the
.Xr owc 4
device (specifically the
.Xr owll 9
interface) should only be called by the
.Xr ow 4
driver.
.Sh SEE ALSO
.Xr ow 4 ,
.Xr owc 4 ,
.Xr owll 9
.Pa  https://pdfserv.maximintegrated.com/en/an/AN937.pdf
.Sh LEGAL
.Tn 1-Wire
is a registered trademark of Maxim Integrated Products, Inc.
.Sh HISTORY
The
.Nm
driver first appeared in
.Fx 11.0 .
.Sh AUTHORS
The
.Nm
device driver and this manual page were written by
.An Warner Losh .