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

================
The I2C Protocol
================

This document is an overview of the basic I2C transactions and the kernel
APIs to perform them.

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

=============== =============================================================
S               Start condition
P               Stop condition
Rd/Wr (1 bit)   Read/Write bit. Rd equals 1, Wr equals 0.
A, NA (1 bit)   Acknowledge (ACK) and Not Acknowledge (NACK) bit
Addr  (7 bits)  I2C 7 bit address. Note that this can be expanded to
                get a 10 bit I2C address.
Data  (8 bits)  A plain data byte.

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


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

Implemented by i2c_master_send()::

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


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

Implemented by i2c_master_recv()::

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


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

Implemented by i2c_transfer().

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