svn commit: r282966 - head/share/man/man4
Jason A. Harmening
jah at FreeBSD.org
Fri May 15 12:28:18 UTC 2015
Author: jah
Date: Fri May 15 12:28:17 2015
New Revision: 282966
URL: https://svnweb.freebsd.org/changeset/base/282966
Log:
Update iic(4) man page to reflect recent changes
Differential Revision: https://reviews.freebsd.org/D2461
Reviewed by: wblock
Approved by: kib (mentor)
Modified:
head/share/man/man4/iic.4
Modified: head/share/man/man4/iic.4
==============================================================================
--- head/share/man/man4/iic.4 Fri May 15 12:19:45 2015 (r282965)
+++ head/share/man/man4/iic.4 Fri May 15 12:28:17 2015 (r282966)
@@ -54,10 +54,12 @@ element to the bus.
The
.Va slave
element consists of a 7-bit address and a read/write bit
-(i.e., 7-bit address << 1 | r/w).
-If the read/write bit is set a read operation is initiated, if the read/write
-bit is cleared a write operation is initiated.
+(that is, a 7-bit address << 1 | r/w).
+A read operation is initiated when the read/write bit is set, or a write
+operation when it is cleared.
All other elements are ignored.
+If successful, the file descriptor receives exclusive
+ownership of the underlying iicbus instance.
.It Dv I2CRPTSTART
.Pq Vt "struct iiccmd"
Sends the repeated start condition to the slave specified by the
@@ -66,19 +68,33 @@ element to the bus.
The slave address should be specified as in
.Dv I2CSTART .
All other elements are ignored.
+.Dv I2CSTART
+must have previously been issued on the same file descriptor.
.It Dv I2CSTOP
No argument is passed.
Sends the stop condition to the bus.
-This terminates the current transaction.
+If
+.Dv I2CSTART
+was previously issued on the file descriptor, the current transaction is
+terminated and exclusive ownership of the underlying iicbus instance is
+released.
+Otherwise, no action is performed.
.It Dv I2CRSTCARD
.Pq Vt "struct iiccmd"
Resets the bus.
The argument is completely ignored.
+This command does not require
+.Dv I2CSTART
+to have been previously issued on the file descriptor.
+If it was previously issued, exclusive ownership of the underlying iicbus
+instance is released.
.It Dv I2CWRITE
.Pq Vt "struct iiccmd"
Writes data to the
.Xr iicbus 4 .
-The bus should already be started.
+The bus must already be started by a previous
+.Dv I2CSTART
+on the file descriptor.
The
.Va slave
element is ignored.
@@ -96,7 +112,9 @@ element is a pointer to the data to writ
.Pq Vt "struct iiccmd"
Reads data from the
.Xr iicbus 4 .
-The bus should already be started.
+The bus must already be started by a previous
+.Dv I2CSTART
+on the file descriptor.
The
.Va slave
element is ignored.
@@ -116,6 +134,15 @@ Short reads on the bus produce undefined
Generic read/write interface.
Allows for an arbitrary number of commands to be sent to
an arbitrary number of devices on the bus.
+Any previous transaction started by
+.Dv I2CSTART
+must be terminated by
+.Dv I2CSTOP
+or
+.Dv I2CRSTCARD
+before
+.Dv I2CRDWR
+can be issued on the same file descriptor.
A read transfer is specified if
.Dv IIC_M_RD
is set in
@@ -138,6 +165,17 @@ element is a buffer for that data.
This ioctl is intended to be
.Tn Linux
compatible.
+.It Dv I2CSADDR
+.Pq Vt "uint8_t"
+Associate the specified address with the file descriptor for use by
+subsequent
+.Xr read 2
+or
+.Xr write 2
+calls.
+The argument is an 8-bit address (that is, a 7-bit address << 1).
+The read/write bit in the least-significant position is ignored.
+Any subsequent read or write operation will set or clear that bit as needed.
.El
.Pp
The following data structures are defined in
@@ -156,7 +194,10 @@ struct iic_msg
{
uint16_t slave;
uint16_t flags;
-#define IIC_M_RD 0x0001 /* read vs write */
+#define IIC_M_WR 0 /* Fake flag for write */
+#define IIC_M_RD 0x0001 /* read vs write */
+#define IIC_M_NOSTOP 0x0002 /* do not send a I2C stop after message */
+#define IIC_M_NOSTART 0x0004 /* do not send a I2C start before message */
uint16_t len; /* msg length */
uint8_t * buf;
};
@@ -167,15 +208,37 @@ struct iic_rdwr_data {
};
.Ed
.Pp
-It is also possible to use read/write routines, then I2C start/stop handshake is
-managed by the
-.Xr iicbus 4
-system.
-However, the address used for the read/write routines is the one
-passed to last
+It is also possible to use
+.Xr read 2
+or
+.Xr write 2 ,
+in which case the I2C start/stop handshake is managed by
+.Xr iicbus 4 .
+The address used for the read/write operation is the one passed to the most
+recent
.Dv I2CSTART
.Xr ioctl 2
-to this device.
+or
+.Dv I2CSADDR
+.Xr ioctl 2
+on the open
+.Pa /dev/iic?
+file descriptor.
+Closing the file descriptor clears any addressing state established by a
+previous
+.Dv I2CSTART
+or
+.Dv I2CSADDR ,
+stops any transaction established by a not-yet-terminated
+.Dv I2CSTART ,
+and releases iicbus ownership.
+Because addressing state is stored on a per-file-descriptor basis, it is
+permissible for multiple file descriptors to be simultaneously open on the
+same
+.Pa /dev/iic?
+device.
+Concurrent transactions on those descriptors are synchronized by the
+exclusive-ownership requests issued to the underlying iicbus instance.
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr read 2 ,
@@ -193,9 +256,3 @@ manual page was written by
.An Nicolas Souchu
and
.An M. Warner Losh .
-.Sh BUGS
-Only the
-.Dv I2CRDWR
-.Xr ioctl 2
-is thread safe.
-All other interfaces suffer from some kind of race.
More information about the svn-src-all
mailing list