[linux-2.6-block.git] / Documentation / i2c / i2c-protocol.rst

============
I2C Protocol
============

This document describes the i2c protocol. Or will, when it is finished :-)

Key to symbols
==============

=============== =============================================================
S     (1 bit) : Start bit
P     (1 bit) : Stop bit
Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
A, NA (1 bit) : Accept and reverse accept bit.
Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
                get a 10 bit I2C address.
Comm  (8 bits): Command byte, a data byte which often selects a register on
                the device.
Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                for 16 bit data.
Count (8 bits): A data byte containing the length of a block operation.

[..]:           Data sent by I2C device, as opposed to data sent by the
                host adapter.
=============== =============================================================


Simple send transaction
=======================

This corresponds to i2c_master_send::

  S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P


Simple receive transaction
==========================

This corresponds to i2c_master_recv::

  S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P


Combined transactions
=====================

This corresponds to i2c_transfer

They are just like the above transactions, but instead of a stop bit P
a start bit S is sent and the transaction continues. An example of
a byte read, followed by a byte write::

  S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P


Modified transactions
=====================

The following modifications to the I2C protocol can also be generated by
setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they
are usually only needed to work around device issues:

I2C_M_IGNORE_NAK:
    Normally message is interrupted immediately if there is [NA] from the
    client. Setting this flag treats any [NA] as [A], and all of
    message is sent.
    These messages may still fail to SCL lo->hi timeout.

I2C_M_NO_RD_ACK:
    In a read message, master A/NA bit is skipped.

I2C_M_NOSTART:
    In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
    point. For example, setting I2C_M_NOSTART on the second partial message
    generates something like::

      S Addr Rd [A] [Data] NA Data [A] P

    If you set the I2C_M_NOSTART variable for the first partial message,
    we do not generate Addr, but we do generate the startbit S. This will
    probably confuse all other clients on your bus, so don't try this.

    This is often used to gather transmits from multiple data buffers in
    system memory into something that appears as a single transfer to the
    I2C device but may also be used between direction changes by some
    rare devices.

I2C_M_REV_DIR_ADDR:
    This toggles the Rd/Wr flag. That is, if you want to do a write, but
    need to emit an Rd instead of a Wr, or vice versa, you set this
    flag. For example::

      S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P

I2C_M_STOP:
    Force a stop condition (P) after the message. Some I2C related protocols
    like SCCB require that. Normally, you really don't want to get interrupted
    between the messages of one transfer.
Commit	Line	Data
ccf988b6 MCC	1	============
	2	I2C Protocol
	3	============
	4
1da177e4 LT	5	This document describes the i2c protocol. Or will, when it is finished :-)
	6
	7	Key to symbols
	8	==============
	9
ccf988b6	10	=============== =============================================================
1da177e4 LT	11	S (1 bit) : Start bit
	12	P (1 bit) : Stop bit
	13	Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
9f02fba8 WS	14	A, NA (1 bit) : Accept and reverse accept bit.
9f02fba8 WS	15	Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
1da177e4 LT	16	get a 10 bit I2C address.
	17	Comm (8 bits): Command byte, a data byte which often selects a register on
	18	the device.
	19	Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
	20	for 16 bit data.
	21	Count (8 bits): A data byte containing the length of a block operation.
	22
ccf988b6 MCC	23	[..]: Data sent by I2C device, as opposed to data sent by the
	24	host adapter.
	25	=============== =============================================================
1da177e4 LT	26
	27
	28	Simple send transaction
ccf988b6	29	=======================
1da177e4	30
ccf988b6	31	This corresponds to i2c_master_send::
1da177e4 LT	32
	33	S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
	34
	35
	36	Simple receive transaction
ccf988b6	37	==========================
1da177e4	38
ccf988b6	39	This corresponds to i2c_master_recv::
1da177e4 LT	40
	41	S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
	42
	43
	44	Combined transactions
ccf988b6	45	=====================
1da177e4 LT	46
	47	This corresponds to i2c_transfer
	48
	49	They are just like the above transactions, but instead of a stop bit P
	50	a start bit S is sent and the transaction continues. An example of
ccf988b6	51	a byte read, followed by a byte write::
1da177e4 LT	52
	53	S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
	54
	55
	56	Modified transactions
	57	=====================
	58
9f02fba8 WS	59	The following modifications to the I2C protocol can also be generated by
	60	setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they
	61	are usually only needed to work around device issues:
1da177e4	62
9f02fba8 WS	63	I2C_M_IGNORE_NAK:
	64	Normally message is interrupted immediately if there is [NA] from the
	65	client. Setting this flag treats any [NA] as [A], and all of
	66	message is sent.
	67	These messages may still fail to SCL lo->hi timeout.
	68
	69	I2C_M_NO_RD_ACK:
	70	In a read message, master A/NA bit is skipped.
	71
	72	I2C_M_NOSTART:
1da177e4 LT	73	In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
1da177e4 LT	74	point. For example, setting I2C_M_NOSTART on the second partial message
ccf988b6 MCC	75	generates something like::
ccf988b6 MCC	76
1da177e4	77	S Addr Rd [A] [Data] NA Data [A] P
ccf988b6	78
1da177e4 LT	79	If you set the I2C_M_NOSTART variable for the first partial message,
	80	we do not generate Addr, but we do generate the startbit S. This will
	81	probably confuse all other clients on your bus, so don't try this.
	82
14674e70 MB	83	This is often used to gather transmits from multiple data buffers in
	84	system memory into something that appears as a single transfer to the
	85	I2C device but may also be used between direction changes by some
	86	rare devices.
	87
9f02fba8	88	I2C_M_REV_DIR_ADDR:
1da177e4 LT	89	This toggles the Rd/Wr flag. That is, if you want to do a write, but
1da177e4 LT	90	need to emit an Rd instead of a Wr, or vice versa, you set this
ccf988b6 MCC	91	flag. For example::
ccf988b6 MCC	92
1da177e4 LT	93	S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
1da177e4 LT	94
9f02fba8 WS	95	I2C_M_STOP:
	96	Force a stop condition (P) after the message. Some I2C related protocols
	97	like SCCB require that. Normally, you really don't want to get interrupted
	98	between the messages of one transfer.