Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a64ec07d authored by David Brownell's avatar David Brownell Committed by Jean Delvare
Browse files

i2c: Document struct i2c_msg 



Clarify use of the I2C_M_* flags by highlighting the fact that
most of them depend on I2C_FUNC_PROTOCOL_MANGLING.

Also provide kerneldoc for i2c_smbus_read_block_data() and also
for "struct i2c_msg".

Signed-off-by: default avatarDavid Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: default avatarJean Delvare <khali@linux-fr.org>
parent 553515e5

drivers/i2c/i2c-core.c

+16 −1
Original line number Diff line number Diff line
@@ -1307,7 +1307,22 @@ s32 i2c_smbus_write_word_data(struct i2c_client *client, u8 command, u16 value) 
}

EXPORT_SYMBOL(i2c_smbus_write_word_data);



/* Returns the number of read bytes */

/**

 * i2c_smbus_read_block_data - SMBus block read request

 * @client: Handle to slave device

 * @command: Command byte issued to let the slave know what data should

 *	be returned

 * @values: Byte array into which data will be read; big enough to hold

 *	the data returned by the slave.  SMBus allows at most 32 bytes.

 *

 * Returns the number of bytes read in the slave's response, else a

 * negative number to indicate some kind of error.

 *

 * Note that using this function requires that the client's adapter support

 * the I2C_FUNC_SMBUS_READ_BLOCK_DATA functionality.  Not all adapter drivers

 * support this; its emulation through I2C messaging relies on a specific

 * mechanism (I2C_M_RECV_LEN) which may not be implemented.

 */

s32 i2c_smbus_read_block_data(struct i2c_client *client, u8 command,

			      u8 *values)

{

include/linux/i2c.h

+42 −9
Original line number Diff line number Diff line
@@ -443,18 +443,51 @@ static inline int i2c_adapter_id(struct i2c_adapter *adap) 
}

#endif /* __KERNEL__ */



/*

 * I2C Message - used for pure i2c transaction, also from /dev interface

/**

 * struct i2c_msg - an I2C transaction segment beginning with START

 * @addr: Slave address, either seven or ten bits.  When this is a ten

 *	bit address, I2C_M_TEN must be set in @flags and the adapter

 *	must support I2C_FUNC_10BIT_ADDR.

 * @flags: I2C_M_RD is handled by all adapters.  No other flags may be

 *	provided unless the adapter exported the relevant I2C_FUNC_*

 *	flags through i2c_check_functionality().

 * @len: Number of data bytes in @buf being read from or written to the

 *	I2C slave address.  For read transactions where I2C_M_RECV_LEN

 *	is set, the caller guarantees that this buffer can hold up to

 *	32 bytes in addition to the initial length byte sent by the

 *	slave (plus, if used, the SMBus PEC); and this value will be

 *	incremented by the number of block data bytes received.

 * @buf: The buffer into which data is read, or from which it's written.

 *

 * An i2c_msg is the low level representation of one segment of an I2C

 * transaction.  It is visible to drivers in the @i2c_transfer() procedure,

 * to userspace from i2c-dev, and to I2C adapter drivers through the

 * @i2c_adapter.@master_xfer() method.

 *

 * Except when I2C "protocol mangling" is used, all I2C adapters implement

 * the standard rules for I2C transactions.  Each transaction begins with a

 * START.  That is followed by the slave address, and a bit encoding read

 * versus write.  Then follow all the data bytes, possibly including a byte

 * with SMBus PEC.  The transfer terminates with a NAK, or when all those

 * bytes have been transferred and ACKed.  If this is the last message in a

 * group, it is followed by a STOP.  Otherwise it is followed by the next

 * @i2c_msg transaction segment, beginning with a (repeated) START.

 *

 * Alternatively, when the adapter supports I2C_FUNC_PROTOCOL_MANGLING then

 * passing certain @flags may have changed those standard protocol behaviors.

 * Those flags are only for use with broken/nonconforming slaves, and with

 * adapters which are known to support the specific mangling options they

 * need (one or more of IGNORE_NAK, NO_RD_ACK, NOSTART, and REV_DIR_ADDR).

 */

struct i2c_msg {

	__u16 addr;	/* slave address			*/

	__u16 flags;

#define I2C_M_TEN	0x10	/* we have a ten bit chip address	*/

#define I2C_M_RD	0x01

#define I2C_M_NOSTART	0x4000

#define I2C_M_REV_DIR_ADDR	0x2000

#define I2C_M_IGNORE_NAK	0x1000

#define I2C_M_NO_RD_ACK		0x0800

#define I2C_M_TEN		0x0010	/* this is a ten bit chip address */

#define I2C_M_RD		0x0001	/* read data, from slave to master */

#define I2C_M_NOSTART		0x4000	/* if I2C_FUNC_PROTOCOL_MANGLING */

#define I2C_M_REV_DIR_ADDR	0x2000	/* if I2C_FUNC_PROTOCOL_MANGLING */

#define I2C_M_IGNORE_NAK	0x1000	/* if I2C_FUNC_PROTOCOL_MANGLING */

#define I2C_M_NO_RD_ACK		0x0800	/* if I2C_FUNC_PROTOCOL_MANGLING */

#define I2C_M_RECV_LEN		0x0400	/* length will be first received byte */

	__u16 len;		/* msg length				*/

	__u8 *buf;		/* pointer to msg data			*/