Luca Ceresoli | f6fcefa | 2020-01-29 16:19:51 +0100 | [diff] [blame] | 1 | ================ |
| 2 | The I2C Protocol |
| 3 | ================ |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 4 | |
Luca Ceresoli | 9bbebdf7 | 2022-08-08 16:17:00 +0200 | [diff] [blame] | 5 | This document is an overview of the basic I2C transactions and the kernel |
| 6 | APIs to perform them. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 7 | |
| 8 | Key to symbols |
| 9 | ============== |
| 10 | |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 11 | =============== ============================================================= |
Luca Ceresoli | 02622c8 | 2020-01-29 16:19:34 +0100 | [diff] [blame] | 12 | S Start condition |
| 13 | P Stop condition |
| 14 | Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0. |
Luca Ceresoli | db0d742 | 2020-01-29 16:19:35 +0100 | [diff] [blame] | 15 | A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit |
Luca Ceresoli | 24d129d | 2022-08-08 16:17:01 +0200 | [diff] [blame] | 16 | Addr (7 bits) I2C 7 bit address. Note that this can be expanded to |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 17 | get a 10 bit I2C address. |
Luca Ceresoli | 0721cee | 2022-08-08 16:17:02 +0200 | [diff] [blame] | 18 | Data (8 bits) A plain data byte. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 19 | |
Luca Ceresoli | 02622c8 | 2020-01-29 16:19:34 +0100 | [diff] [blame] | 20 | [..] Data sent by I2C device, as opposed to data sent by the |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 21 | host adapter. |
| 22 | =============== ============================================================= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 23 | |
| 24 | |
| 25 | Simple send transaction |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 26 | ======================= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 27 | |
Luca Ceresoli | ca5dbb0 | 2020-01-29 16:19:52 +0100 | [diff] [blame] | 28 | Implemented by i2c_master_send():: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 29 | |
| 30 | S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P |
| 31 | |
| 32 | |
| 33 | Simple receive transaction |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 34 | ========================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 35 | |
Luca Ceresoli | ca5dbb0 | 2020-01-29 16:19:52 +0100 | [diff] [blame] | 36 | Implemented by i2c_master_recv():: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 37 | |
| 38 | S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P |
| 39 | |
| 40 | |
| 41 | Combined transactions |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 42 | ===================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 43 | |
Luca Ceresoli | ca5dbb0 | 2020-01-29 16:19:52 +0100 | [diff] [blame] | 44 | Implemented by i2c_transfer(). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 45 | |
Luca Ceresoli | f954731 | 2020-01-29 16:19:33 +0100 | [diff] [blame] | 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:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 49 | |
| 50 | S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P |
| 51 | |
| 52 | |
| 53 | Modified transactions |
| 54 | ===================== |
| 55 | |
Wolfram Sang | 9f02fba | 2014-04-06 13:37:38 +0200 | [diff] [blame] | 56 | The following modifications to the I2C protocol can also be generated by |
Luca Ceresoli | 2f07c05 | 2020-01-29 16:19:29 +0100 | [diff] [blame] | 57 | setting these flags for I2C messages. With the exception of I2C_M_NOSTART, they |
Wolfram Sang | 9f02fba | 2014-04-06 13:37:38 +0200 | [diff] [blame] | 58 | are usually only needed to work around device issues: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 59 | |
Wolfram Sang | 9f02fba | 2014-04-06 13:37:38 +0200 | [diff] [blame] | 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: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 70 | In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some |
| 71 | point. For example, setting I2C_M_NOSTART on the second partial message |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 72 | generates something like:: |
| 73 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 74 | S Addr Rd [A] [Data] NA Data [A] P |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 75 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 76 | If you set the I2C_M_NOSTART variable for the first partial message, |
Luca Ceresoli | f954731 | 2020-01-29 16:19:33 +0100 | [diff] [blame] | 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. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 80 | |
Mark Brown | 14674e7 | 2012-05-30 10:55:34 +0200 | [diff] [blame] | 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 | |
Wolfram Sang | 9f02fba | 2014-04-06 13:37:38 +0200 | [diff] [blame] | 86 | I2C_M_REV_DIR_ADDR: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 87 | This toggles the Rd/Wr flag. That is, if you want to do a write, but |
| 88 | need to emit an Rd instead of a Wr, or vice versa, you set this |
Mauro Carvalho Chehab | ccf988b | 2019-07-26 09:51:16 -0300 | [diff] [blame] | 89 | flag. For example:: |
| 90 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 91 | S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P |
| 92 | |
Wolfram Sang | 9f02fba | 2014-04-06 13:37:38 +0200 | [diff] [blame] | 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. |