Date: Fri, 15 May 2015 12:28:17 +0000 (UTC) From: "Jason A. Harmening" <jah@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r282966 - head/share/man/man4 Message-ID: <201505151228.t4FCSHbl012961@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201505151228.t4FCSHbl012961>