Differential D2461 Diff 5403 head/share/man/man4/iic.4

Changeset View

Standalone View

head/share/man/man4/iic.4

	Show First 20 Lines • Show All 48 Lines • ▼ Show 20 Lines
	.It Dv I2CSTART			.It Dv I2CSTART
	.Pq Vt "struct iiccmd"			.Pq Vt "struct iiccmd"
	Sends the start condition to the slave specified by the			Sends the start condition to the slave specified by the
	.Va slave			.Va slave
	element to the bus.			element to the bus.
	The			The
	.Va slave			.Va slave
	element consists of a 7-bit address and a read/write bit			element consists of a 7-bit address and a read/write bit
	(i.e., 7-bit address << 1 \| r/w).			(that is, a 7-bit address << 1 \| r/w).
	If the read/write bit is set a read operation is initiated, if the read/write			A read operation is initiated when the read/write bit is set, or a write
	bit is cleared a write operation is initiated.			operation when it is cleared.
	All other elements are ignored.			All other elements are ignored.
				If successful, the file descriptor receives exclusive
				ownership of the underlying iicbus instance.
	.It Dv I2CRPTSTART			.It Dv I2CRPTSTART
	.Pq Vt "struct iiccmd"			.Pq Vt "struct iiccmd"
	Sends the repeated start condition to the slave specified by the			Sends the repeated start condition to the slave specified by the
	.Va slave			.Va slave
	element to the bus.			element to the bus.
	The slave address should be specified as in			The slave address should be specified as in
	.Dv I2CSTART .			.Dv I2CSTART .
	All other elements are ignored.			All other elements are ignored.
				.Dv I2CSTART
				must have previously been issued on the same file descriptor.
	.It Dv I2CSTOP			.It Dv I2CSTOP
	No argument is passed.			No argument is passed.
	Sends the stop condition to the bus.			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			.It Dv I2CRSTCARD
	.Pq Vt "struct iiccmd"			.Pq Vt "struct iiccmd"
	Resets the bus.			Resets the bus.
	The argument is completely ignored.			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			.It Dv I2CWRITE
	.Pq Vt "struct iiccmd"			.Pq Vt "struct iiccmd"
	Writes data to the			Writes data to the
	.Xr iicbus 4 .			.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			The
	.Va slave			.Va slave
	element is ignored.			element is ignored.
	The			The
	.Va count			.Va count
	element is the number of bytes to write.			element is the number of bytes to write.
	The			The
	.Va last			.Va last
	element is a boolean flag.			element is a boolean flag.
	It is non-zero when additional write commands will follow.			It is non-zero when additional write commands will follow.
	The			The
	.Va buf			.Va buf
	element is a pointer to the data to write to the bus.			element is a pointer to the data to write to the bus.
	.It Dv I2CREAD			.It Dv I2CREAD
	.Pq Vt "struct iiccmd"			.Pq Vt "struct iiccmd"
	Reads data from the			Reads data from the
	.Xr iicbus 4 .			.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			The
	.Va slave			.Va slave
	element is ignored.			element is ignored.
	The			The
	.Va count			.Va count
	element is the number of bytes to write.			element is the number of bytes to write.
	The			The
	.Va last			.Va last
	element is a boolean flag.			element is a boolean flag.
	It is non-zero when additional write commands will follow.			It is non-zero when additional write commands will follow.
	The			The
	.Va buf			.Va buf
	element is a pointer to where to store the data read from the bus.			element is a pointer to where to store the data read from the bus.
	Short reads on the bus produce undefined results.			Short reads on the bus produce undefined results.
	.It Dv I2CRDWR			.It Dv I2CRDWR
	.Pq Vt "struct iic_rdwr_data"			.Pq Vt "struct iic_rdwr_data"
	Generic read/write interface.			Generic read/write interface.
	Allows for an arbitrary number of commands to be sent to			Allows for an arbitrary number of commands to be sent to
	an arbitrary number of devices on the bus.			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			A read transfer is specified if
	.Dv IIC_M_RD			.Dv IIC_M_RD
	is set in			is set in
	.Va flags .			.Va flags .
	Otherwise the transfer is a write transfer.			Otherwise the transfer is a write transfer.
	The			The
	.Va slave			.Va slave
	element specifies the 7-bit address with the read/write bit for the transfer.			element specifies the 7-bit address with the read/write bit for the transfer.
	The read/write bit will be handled by the iicbus stack based on the specified			The read/write bit will be handled by the iicbus stack based on the specified
	transfer operation.			transfer operation.
	The			The
	.Va len			.Va len
	element is the number of			element is the number of
	.Pq Vt "struct iic_msg"			.Pq Vt "struct iic_msg"
	messages encoded on			messages encoded on
	.Pq Vt "struct iic_rdwr_data" .			.Pq Vt "struct iic_rdwr_data" .
	The			The
	.Va buf			.Va buf
	element is a buffer for that data.			element is a buffer for that data.
	This ioctl is intended to be			This ioctl is intended to be
	.Tn Linux			.Tn Linux
	compatible.			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			.El
	.Pp			.Pp
	The following data structures are defined in			The following data structures are defined in
	.In dev/iicbus/iic.h			.In dev/iicbus/iic.h
	and referenced above:			and referenced above:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	struct iiccmd {			struct iiccmd {
	u_char slave;			u_char slave;
	int count;			int count;
	int last;			int last;
	char *buf;			char *buf;
	};			};

	/* Designed to be compatible with linux's struct i2c_msg */			/* Designed to be compatible with linux's struct i2c_msg */
	struct iic_msg			struct iic_msg
	{			{
	uint16_t slave;			uint16_t slave;
	uint16_t flags;			uint16_t flags;
				#define IIC_M_WR 0 /* Fake flag for write */
	#define IIC_M_RD 0x0001 /* read vs 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 */			uint16_t len; /* msg length */
	uint8_t * buf;			uint8_t * buf;
	};			};

	struct iic_rdwr_data {			struct iic_rdwr_data {
	struct iic_msg *msgs;			struct iic_msg *msgs;
	uint32_t nmsgs;			uint32_t nmsgs;
	};			};
	.Ed			.Ed
	.Pp			.Pp
	It is also possible to use read/write routines, then I2C start/stop handshake is			It is also possible to use
	managed by the			.Xr read 2
	.Xr iicbus 4			or
	system.			.Xr write 2 ,
	However, the address used for the read/write routines is the one			in which case the I2C start/stop handshake is managed by
	passed to last			.Xr iicbus 4 .
				The address used for the read/write operation is the one passed to the most
				recent
	.Dv I2CSTART			.Dv I2CSTART
	.Xr ioctl 2			.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			.Sh SEE ALSO
	.Xr ioctl 2 ,			.Xr ioctl 2 ,
	.Xr read 2 ,			.Xr read 2 ,
	.Xr write 2 ,			.Xr write 2 ,
	.Xr iicbus 4			.Xr iicbus 4
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Nm			.Nm
	manual page first appeared in			manual page first appeared in
	.Fx 3.0 .			.Fx 3.0 .
	.Sh AUTHORS			.Sh AUTHORS
	.An -nosplit			.An -nosplit
	This			This
	manual page was written by			manual page was written by
	.An Nicolas Souchu			.An Nicolas Souchu
	and			and
	.An M. Warner Losh .			.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.