Index: head/share/man/man4/iic.4
===================================================================
--- head/share/man/man4/iic.4
+++ head/share/man/man4/iic.4
@@ -54,10 +54,12 @@
 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 @@
 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 @@
 .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 @@
 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 @@
 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 @@
 {
 	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 @@
 };
 .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 @@
 .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.