Re: [PATCH v3] i2c-tools: add new tool 'i2ctransfer'

[Wolfram Sang]

On Mon, Mar 13, 2017 at 12:41:35PM +0100, Wolfram Sang wrote:
> From: Wolfram Sang <wsa+renesas@xxxxxxxxxxxxxxxxxxxx>
> 
> This tool allows to construct and concat multiple I2C messages into one
> single transfer. Its aim is to test I2C master controllers, and so there
> is no SMBus fallback.
> 
> I've been missing such a tool a number of times now, so I finally got
> around to writing it myself. As with all I2C tools, it can be dangerous,
> but it can also be very useful when developing.
> 
> It has been tested with various Renesas I2C IP cores as well as Tegra,
> i.MX and AT91.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@xxxxxxxxxxxxxxxxxxxx>
> Cc: Jean Delvare <jdelvare@xxxxxxx>
> Cc: Uwe Kleine-KÃnig <u.kleine-koenig@xxxxxxxxxxxxxx>
> Cc: Ezequiel Garcia <ezequiel@xxxxxxxxxxxxxxxxxxxx>
> Cc: Geert Uytterhoeven <geert@xxxxxxxxxxxxxx>
> ---
> 
> Changes since V2:
> * reworded and added some paragraphs in the man page based on review comments
> * corrected some issues in help output
> * no code logic changes
> 
> I'll send out a diff compared to the previous version in a reply to this mail.
> I think it will help given that the changes are mainly textual.

Here it is:

diff --git a/tools/i2ctransfer.8 b/tools/i2ctransfer.8
index f6fb94a..28b3388 100644
--- a/tools/i2ctransfer.8
+++ b/tools/i2ctransfer.8
@@ -28,9 +28,11 @@ and a
 here.
 A transfer may consist of multiple messages and is started with a START condition and ends with a STOP condition as described in the I2C specification.
 Messages within the transfer are concatenated using the REPEATED START condition which is described there as well.
-Some devices keep their internal states for REPEATED START but reset them after a STOP.
-Also, you cannot be interrupted by another I2C master during one transfer, but it might happen between multiple transfers.
-This programm helps you to create proper transfers for your needs.
+There are some advantages of having multiple messages in one transfer.
+First, some devices keep their internal states for REPEATED START but reset them after a STOP.
+Second, you cannot get interrupted during one transfer, but it might happen between multiple transfers.
+Interruption could happen on hardware level by another I2C master on the bus, or at software level by another I2C user who got its transfer scheduled between yours.
+This program helps you to create proper transfers for your needs.
 
 .SH OPTIONS
 .TP
@@ -71,7 +73,10 @@ This number should correspond to one of the busses listed by
 .PP
 The next parameter is one or multiple
 .I desc
-blocks which is composed like this:
+blocks.
+The number of blocks is limited by the Linux Kernel and defined in I2C_RDWR_IOCTL_MAX_MSGS (42 as of v4.10).
+.I desc
+blocks are composed like this:
 
 .I {r|w}<length_of_message>[@address]
 
@@ -81,16 +86,17 @@ specifies if the message is read or write
 .TP
 .B <length_of_message>
 specifies the number of bytes read or written in this message.
-It is parsed as an unsigned 16 bit integer, but note that the Linux might apply an additional upper limit (8192 as of v4.10).
+It is parsed as an unsigned 16 bit integer, but note that the Linux Kernel apply an additional upper limit (8192 as of v4.10).
 .TP
 .B [@address]
-specifies the address of the chip to be accessed for this message, and is an integer.
+specifies the 7-bit address of the chip to be accessed for this message, and is an integer.
 If omitted, reuse the previous address.
 Normally, addresses outside the range of 0x03-0x77 and addresses with a kernel driver attached to them will be blocked.
 With
 .I -f
 (force), all addresses can be used.
 Be very careful when using that!
+10-bit addresses are currently not supported at all.
 
 .PP
 If the I2C message is a write, then a
@@ -112,7 +118,7 @@ increase value by 1 until end of message (i.e. 0+ means 0, 1, 2, ...)
 decrease value by 1 until end of message (i.e. 0xff- means 0xff, 0xfe, 0xfd, ...)
 .TP
 p
-use value as seed for an 8 bit pseudo random sequence (i.e. 0p means 0x00, 0x50, 0xb0, ..)
+use value as seed for an 8 bit pseudo random sequence (i.e. 0p means 0x00, 0x50, 0xb0, ...)
 
 .SH EXAMPLES
 .PP
@@ -124,7 +130,7 @@ On bus 0, from an EEPROM at address 0x50, read 8 byte from offset 0x64
 .RE
 .fi
 .PP
-For the same eeprom, at offset 0x42 write 0xff 0xfe .. 0xf0
+For the same EEPROM, at offset 0x42 write 0xff 0xfe ... 0xf0
 (one write message; first byte sets the memory pointer to 0x42, 0xff is the first data byte, all following data bytes are decreased by one):
 .nf
 .RS
diff --git a/tools/i2ctransfer.c b/tools/i2ctransfer.c
index ab8d0e9..0f7ddd5 100644
--- a/tools/i2ctransfer.c
+++ b/tools/i2ctransfer.c
@@ -49,10 +49,11 @@ static void help(void)
 		"  DATA are LENGTH bytes for a write message. They can be shortened by a suffix:\n"
 		"    = (keep value constant until LENGTH)\n"
 		"    + (increase value by 1 until LENGTH)\n"
-		"    - (decrease value by 1 until LENGTH)\n\n"
-		"Example (bus 0, read 8 byte at offset 0x64 from eeprom at 0x50):\n"
+		"    - (decrease value by 1 until LENGTH)\n"
+		"    p (use pseudo random generator until LENGTH with value as seed)\n\n"
+		"Example (bus 0, read 8 byte at offset 0x64 from EEPROM at 0x50):\n"
 		"  # i2ctransfer 0 w1@0x50 0x64 r8\n"
-		"Example (same eeprom, at offset 0x42 write 0xff 0xfe .. 0xf0):\n"
+		"Example (same EEPROM, at offset 0x42 write 0xff 0xfe ... 0xf0):\n"
 		"  # i2ctransfer 0 w17@0x50 0x42 0xff-\n");
 }

Attachment: signature.asc
Description: PGP signature