Changeset View
Standalone View
share/man/man9/own.9
- This file was added.
.\" | |||||
.\" Copyright (c) 2015 M. Warner Losh | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" 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_commmand_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, | |||||
wblock: Missing "s", extra word:
These functions are split into three groups: | |||||
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 | |||||
Not Done Inline ActionsA little vague here. "Should" used as a recommendation is fine. "Generally" gets a little questionable. As opposed to what other options? Why? Something about the wrappers providing safer or more general-purpose usage? wblock: A little vague here. "Should" used as a recommendation is fine. "Generally" gets a little… | |||||
ones. | |||||
.Ss Bus Commands | |||||
Not Done Inline ActionsProbably can replace "to the devices on the bus" with just "to devices.": The 1-Wire bus defines different layers of access to devices. wblock: Probably can replace "to the devices on the bus" with just "to devices.":
The 1-Wire bus… | |||||
The 1-Wire bus defines different layers of access to the devices on | |||||
the bus. | |||||
The | |||||
.Nm | |||||
Not Done Inline Actions"of the bus" is not needed: functions provide access to the network and transport layers. wblock: "of the bus" is not needed:
functions provide access to the network and transport layers. | |||||
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 | |||||
Not Done Inline ActionsTrailing preposition. Some people say these are fine, but they often indicate that the sentence can be rearranged to make more sense. Not sure on this. Does the network layer "specify" (as in choose) the clock speed of transport layer commands, or do transport layer commands just work at whatever rate the network layer is set to use? In other words, can transport layer commands run at a different clock rate than the network layer? I'd guess not, and guess that it really means this: Transport layer commands run at a clock rate (speed?) determined by the network layer. wblock: Trailing preposition. Some people say these are fine, but they often indicate that the… | |||||
.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: | |||||
Not Done Inline ActionsRearrange to avoid nonspecific "it" when possible. Also, serial comma: Network access, speed, and timing information are encapsulated in this structure, wblock: Rearrange to avoid nonspecific "it" when possible. Also, serial comma:
Network access, speed… | |||||
.Bl -tag -width ".Va xxxx" | |||||
.It Va flags | |||||
Not Done Inline Actionss/files/fields/ (although this came up the other day somewhere else, C actually calls these "members" of a struct) wblock: s/files/fields/ (although this came up the other day somewhere else, C actually calls these… | |||||
Flags controlling the interpretation of the structure. | |||||
These flags are defined in | |||||
.In dev/ow/ow.h : | |||||
Not Done Inline Actions"Various" is not needed. Flags to control the interpretation of the structure. wblock: "Various" is not needed.
Flags to control the interpretation of the structure. | |||||
.Bl -tag -width indent | |||||
Not Done Inline ActionsThese flags are defined in wblock: These flags are defined in | |||||
.It OW_FLAG_OVERDRIVE | |||||
Send | |||||
.Va xpt_cmd | |||||
bytes and read | |||||
Not Done Inline ActionsROM is capitalized later on, should be here also. wblock: ROM is capitalized later on, should be here also. | |||||
.Va xpt_read | |||||
bytes at overdrive speed. | |||||
Not Done Inline ActionsThis is... confusing. It is hard to tell the groupings. "Send Transport" seems like a description, not a verb, but hard to tell. Is "stuff" a noun or a verb? If this is just a single flag, it might help to start with "Enable" or "Set". Some quotes on the pairings of words could help, too: Enable (Later flags are described with sentences ending in a period, so I added that here too.) wblock: This is... confusing. It is hard to tell the groupings. "Send Transport" seems like a… | |||||
.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. | |||||
Not Done Inline ActionsProbably: wblock: Probably:
s/send/sent/ | |||||
If the | |||||
.Dv OW_FLAG_READ_BIT | |||||
bit is set in | |||||
.Va flags , | |||||
Not Done Inline ActionsNeeds a comma for the pause: .Va flags , wblock: Needs a comma for the pause:
.Va flags , | |||||
then it is the number of bits to read. | |||||
Not Done Inline Actions"then" is not needed. it is the number of bits to read. wblock: "then" is not needed.
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, | |||||
Not Done Inline ActionsAvoid the "The blah function" and use just a comma rather than the aside. Also, use active voice: .Fn own_command_wait wblock: Avoid the "The blah function" and use just a comma rather than the aside. Also, use active… | |||||
and | |||||
then releases the bus. | |||||
.Fn own_send_command | |||||
sends the command without bus reservation. | |||||
.Fa pdev | |||||
Not Done Inline ActionsAgain, recommend losing the redundant "The function" wording and pause: .Fn own_send_command wblock: Again, recommend losing the redundant "The function" wording and pause:
.Fn own_send_command… | |||||
is the client device (the presentation layer device) sending the command. | |||||
The | |||||
Not Done Inline Actions"The" not needed. wblock: "The" not needed. | |||||
.Fa cmd | |||||
argument describes the transaction to send to the 1-Wire bus. | |||||
.Pp | |||||
Not Done Inline ActionsTrailing preposition... but let's see if the alternative is any better: .Fa pdev Hmm, not bad. wblock: Trailing preposition... but let's see if the alternative is any better:
.Fa pdev
is the client… | |||||
.Fn own_self_command | |||||
Not Done Inline Actions"The" and "argument" are not needed. .Fa cmd wblock: "The" and "argument" are not needed.
.Fa cmd
describes the transaction to send to the 1-Wire… | |||||
fills in | |||||
.Fa cmd | |||||
with a MATCH_ROM ROM command, the ROM address of | |||||
.Fa pdev | |||||
Not Done Inline Actions"The" not needed. wblock: "The" not needed. | |||||
and the | |||||
.Fa xpt_cmd | |||||
Not Done Inline Actions"the ... argument" is not needed. But some rewriting to avoid this long sentence should be done: .Fn own_self_command wblock: "the ... argument" is not needed. But some rewriting to avoid this long sentence should be… | |||||
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 | |||||
Not Done Inline ActionsThe final "to the bus" is not needed: presentation layer devices can use to coordinate access. wblock: The final "to the bus" is not needed:
presentation layer devices can use to coordinate access. | |||||
.Fa how | |||||
Not Done Inline Actionss/The locking/Locking/ Locking is purely advisory at present. wblock: s/The locking/Locking/
s/at this time/at present/
Locking is purely advisory at present. | |||||
argument is | |||||
.Dv OWN_WAIT | |||||
and returns the error | |||||
Not Done Inline ActionsEliminating the "The ... function" and going passive->active: .Fn own_acquire_bus wblock: Eliminating the "The ... function" and going passive->active:
.Fn own_acquire_bus
reserves the… | |||||
.Dv EWOULDBLOCK | |||||
if passed | |||||
Not Done Inline ActionsWe're talking about the function already, so I'm inclined to use "It" here. And passive->active: It waits indefinitely if wblock: We're talking about the function already, so I'm inclined to use "It" here. And passive… | |||||
.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 | |||||
Not Done Inline ActionsSimplify this sentence, removing the "The ... function": .Fn own_release_bus wblock: Simplify this sentence, removing the "The ... function":
.Fn own_release_bus
releases the bus. | |||||
.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. | |||||
Not Done Inline ActionsNice! Easier to read without saying "the buffer argument" and "the len argument". wblock: Nice! Easier to read without saying "the buffer argument" and "the len argument". | |||||
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 | |||||
Not Done Inline ActionsProbably can remove a "the": the timing of signaling of different modes, and the polling Could be clearer if the multiple "of"s could be simplified ("timing of signalling of different modes"). Maybe break into separate sentences. wblock: Probably can remove a "the":
the timing of signaling of different modes, and the polling… | |||||
.Xr ow 4 | |||||
device. | |||||
Presentation layer devices (children of the newbus | |||||
.Xr ow 4 | |||||
Not Done Inline Actions"is" is not quite right here. Maybe: presentation layer is composed of the device-specific commands and actions used to wblock: "is" is not quite right here. Maybe:
presentation layer is composed of the device-specific… | |||||
device) should only call the functions described here. | |||||
Not Done Inline Actions"the" not needed here, nor is "on bus": control specific 1-Wire devices. wblock: "the" not needed here, nor is "on bus":
control specific 1-Wire devices. | |||||
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. | |||||
Not Done Inline ActionsGuidelines say we should always call them "manual pages", but here we can probably do better: device) should only call the functions described here. wblock: Guidelines say we should always call them "manual pages", but here we can probably do better… | |||||
.Sh SEE ALSO | |||||
.Xr ow 4 , | |||||
.Xr owc 4 , | |||||
.Xr owll 9 | |||||
.Pa http://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 . |
Missing "s", extra word:
These functions are split into three groups: