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

Commit a1681781 authored by Jean Delvare's avatar Jean Delvare Committed by Jean Delvare
Browse files

i2c: Mention functionality flags in SMBus protocol documentation 



While the mapping between I2C adapter functionality flags and
i2c_smbus_*() helper functions is rather obvious, let's still document
it for clarity.

Also drop the reference to 2 command byte I2C block reads, there is no
support for that in the kernel at the moment.

Signed-off-by: default avatarJean Delvare <khali@linux-fr.org>
parent 8117e41e

Documentation/i2c/smbus-protocol

+31 −9
Original line number Original line Diff line number Diff line
@@ -23,6 +23,12 @@ don't match these function names. For some of the operations which pass a 
single data byte, the functions using SMBus protocol operation names execute

single data byte, the functions using SMBus protocol operation names execute

a different protocol operation entirely.

a different protocol operation entirely.





Each transaction type corresponds to a functionality flag. Before calling a

transaction function, a device driver should always check (just once) for

the corresponding functionality flag to ensure that the underlying I2C

adapter supports the transaction in question. See

<file:Documentation/i2c/functionality> for the details.







Key to symbols

Key to symbols

==============

==============
@@ -49,6 +55,8 @@ This sends a single bit to the device, at the place of the Rd/Wr bit. 




A Addr Rd/Wr [A] P

A Addr Rd/Wr [A] P





Functionality flag: I2C_FUNC_SMBUS_QUICK







SMBus Receive Byte:  i2c_smbus_read_byte()

SMBus Receive Byte:  i2c_smbus_read_byte()

==========================================

==========================================
@@ -60,6 +68,8 @@ the previous SMBus command. 




S Addr Rd [A] [Data] NA P

S Addr Rd [A] [Data] NA P





Functionality flag: I2C_FUNC_SMBUS_READ_BYTE







SMBus Send Byte:  i2c_smbus_write_byte()

SMBus Send Byte:  i2c_smbus_write_byte()

========================================

========================================
@@ -69,6 +79,8 @@ to a device. See Receive Byte for more information. 




S Addr Wr [A] Data [A] P

S Addr Wr [A] Data [A] P





Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE







SMBus Read Byte:  i2c_smbus_read_byte_data()

SMBus Read Byte:  i2c_smbus_read_byte_data()

============================================

============================================
@@ -78,6 +90,8 @@ The register is specified through the Comm byte. 




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

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





Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA







SMBus Read Word:  i2c_smbus_read_word_data()

SMBus Read Word:  i2c_smbus_read_word_data()

============================================

============================================
@@ -88,6 +102,8 @@ byte. But this time, the data is a complete word (16 bits). 




S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P

S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P





Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA



Note the convenience function i2c_smbus_read_word_swapped is

Note the convenience function i2c_smbus_read_word_swapped is

available for reads where the two data bytes are the other way

available for reads where the two data bytes are the other way

around (not SMBus compliant, but very popular.)

around (not SMBus compliant, but very popular.)
@@ -102,6 +118,8 @@ the Read Byte operation. 




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

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





Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA







SMBus Write Word:  i2c_smbus_write_word_data()

SMBus Write Word:  i2c_smbus_write_word_data()

==============================================

==============================================
@@ -112,6 +130,8 @@ specified through the Comm byte. 




S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P

S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P





Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA



Note the convenience function i2c_smbus_write_word_swapped is

Note the convenience function i2c_smbus_write_word_swapped is

available for writes where the two data bytes are the other way

available for writes where the two data bytes are the other way

around (not SMBus compliant, but very popular.)

around (not SMBus compliant, but very popular.)
@@ -126,6 +146,8 @@ This command selects a device register (through the Comm byte), sends 
S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] 

S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] 

                             S Addr Rd [A] [DataLow] A [DataHigh] NA P

                             S Addr Rd [A] [DataLow] A [DataHigh] NA P





Functionality flag: I2C_FUNC_SMBUS_PROC_CALL







SMBus Block Read:  i2c_smbus_read_block_data()

SMBus Block Read:  i2c_smbus_read_block_data()

==============================================

==============================================
@@ -137,6 +159,8 @@ of data is specified by the device in the Count byte. 
S Addr Wr [A] Comm [A] 

S Addr Wr [A] Comm [A] 

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

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





Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA







SMBus Block Write:  i2c_smbus_write_block_data()

SMBus Block Write:  i2c_smbus_write_block_data()

================================================

================================================
@@ -147,6 +171,8 @@ Comm byte. The amount of data is specified in the Count byte. 




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

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





Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA







SMBus Block Write - Block Read Process Call

SMBus Block Write - Block Read Process Call

===========================================

===========================================
@@ -160,6 +186,8 @@ This command selects a device register (through the Comm byte), sends 
S Addr Wr [A] Comm [A] Count [A] Data [A] ...

S Addr Wr [A] Comm [A] Count [A] Data [A] ...

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

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





Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL







SMBus Host Notify

SMBus Host Notify

=================

=================
@@ -229,15 +257,7 @@ designated register that is specified through the Comm byte. 
S Addr Wr [A] Comm [A] 

S Addr Wr [A] Comm [A] 

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

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







Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK

I2C Block Read (2 Comm bytes)

=============================



This command reads a block of bytes from a device, from a 

designated register that is specified through the two Comm bytes.



S Addr Wr [A] Comm1 [A] Comm2 [A] 

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









I2C Block Write:  i2c_smbus_write_i2c_block_data()

I2C Block Write:  i2c_smbus_write_i2c_block_data()
@@ -249,3 +269,5 @@ Comm byte. Note that command lengths of 0, 2, or more bytes are 
supported as they are indistinguishable from data.

supported as they are indistinguishable from data.





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

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



Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK