Index: share/man/man4/iic.4
===================================================================
--- share/man/man4/iic.4
+++ share/man/man4/iic.4
@@ -57,7 +57,9 @@
 (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.
-All other elements are ignored.
+All other elements are ignored.  If successul, this command will acquire
+exclusive ownership of the underlying iicbus instance for the file descriptor
+on which it is issued.
 .It Dv I2CRPTSTART
 .Pq Vt "struct iiccmd"
 Sends the repeated start condition to the slave specified by the
@@ -65,20 +67,33 @@
 element to the bus.
 The slave address should be specified as in
 .Dv I2CSTART .
-All other elements are ignored.
+All other elements are ignored.  For this command to succeed, the
+.Dv I2CSTART
+command 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 the
+.Dv I2CSTART
+command was previously issued on the file descriptor, this command will
+terminate the current transaction and release exclusive ownership of the
+underlying iicbus instance.  Otherwise, it will perform no action.
 .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, this command will release exclusive ownership of the underlying iicbus
+instance.
 .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
+command on the file descriptor.
 The
 .Va slave
 element is ignored.
@@ -96,7 +111,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
+command on the file descriptor.
 The
 .Va slave
 element is ignored.
@@ -116,6 +133,13 @@
 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 the
+.Dv I2CSTART
+command must be terminated by
+.Dv I2CSTOP
+or
+.Dv I2CRSTCARD
+before this command can be issued on the same file descriptor.
 A read transfer is specified if
 .Dv IIC_M_RD
 is set in
@@ -138,6 +162,17 @@
 This ioctl is intended to be
 .Tn Linux
 compatible.
+.It Dv I2CSADDR
+.Pq Vt "uint8_t"
+Associates the specified address with the file descriptor for use by
+subsequent
+.Xr read 2
+or
+.Xr write 2
+calls.
+The argument should be an 8-bit address (i.e., 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 +191,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 +205,36 @@
 };
 .Ed
 .Pp
-It is also possible to use read/write routines, then I2C start/stop handshake is
+It is also possible to use the
+.Xr read 2
+or
+.Xr write 2
+calls, in which case the 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
+However, the address used for the read/write calls 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 /dev/iic? file descriptor.
+Closing the file descriptor will clear any addressing state established by a
+previous
+.Dv I2CSTART
+or
+.Dv I2CSADDR
+command, and will stop any transaction (and release iicbus ownership)
+established by a not-yet-terminated
+.Dv I2CSTART
+command.
+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 /dev/iic? device.  Concurrent transactions on those descriptors will be
+synchronized by the exclusive-ownership requests issued to the underlying
+iicbus instance. 
 .Sh SEE ALSO
 .Xr ioctl 2 ,
 .Xr read 2 ,
@@ -193,9 +252,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.