Add support for message modifier flags
v2 cover Add support for message modifier flags
I2C messages can be modified with a set of flags covered by the protocol mangling and the skip repeated start functionalities. This series add support for such flags to i2cdetect and i2ctransfer.
The first patch shows the support of protocol mangling and repeated start skipping in the output of 'i2cdetect -F'.
The second patch adds the parsing of optional flags to i2ctransfer message description. Those command-line flags then set the i2c message flags alongside the read/write flag.
I wrote these changes to test the insertion of I2C_M_STOP flag in multi-message transactions with i2ctransfer, but the other flags can be useful for various test scenarios.
The patches use defines that have been present in the kernel since v3.6 released in 2012. If compatibility with older kernel is required, we will need to wrap some of them with #ifndef ... #endif.
Maybe a minimum kernel version can be documented in the README?
---
Changes in v2:
- Document the flags in i2ctransfer.8 man page.
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Benoît Monin (2):
i2cdetect: Display mangling and nostart support
i2ctransfer: Add optional message modifier flags
tools/i2cdetect.c | 4 ++++ tools/i2ctransfer.8 | 26 +++++++++++++++++++++++++- tools/i2ctransfer.c | 34 +++++++++++++++++++++++++--------- 3 files changed, 54 insertions(+), 10 deletions(-)
---
base-commit: ea51da725b743da00b894dfdc4ab189f5a51e90e
change-id: 20251127-msg-flags-3d2b2da9ae28
Best regards,
Signature · 3 lines
Benoît Monin, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
PATCH v2 1/2 i2cdetect: Display mangling and nostart support
Show the support of protocol mangling and repeated start elision in the list of fonctionnalities displayed with '-F'.
--- tools/i2cdetect.c | 4 ++++ 1 file changed, 4 insertions(+)
tools/i2cdetect.c +4 -0
@@ -165,6 +165,10 @@ static const struct func all_func[] = { { .value = I2C_FUNC_SLAVE, .name = "Target mode" },#endif + { .value = I2C_FUNC_PROTOCOL_MANGLING, + .name = "Protocol mangling" }, + { .value = I2C_FUNC_NOSTART, + .name = "Skip repeated start" }, { .value = 0, .name = "" } };
Signature · 1 line
2.52.0
PATCH v2 2/2 i2ctransfer: Add optional message modifier flags
In reply to Benoît MoninAllow setting protocol mangling and repeated start elision flags of an i2c message with a set of optional command-line flags. These optional flags are parsed at the beginning of the DESC field up to a read or write flag.
For example, to read one byte from address 0x50 followed by a stop, then write two bytes at 0x54 on bus 0, one would call i2ctransfer as follow:
i2ctransfer 0 pr1@0x50 w2@0x54 0x10 0x20
Since the new flags are optional, this patch preserves the compatibility of the i2ctransfer syntax.
--- tools/i2ctransfer.8 | 26 +++++++++++++++++++++++++- tools/i2ctransfer.c | 34 +++++++++++++++++++++++++--------- 2 files changed, 50 insertions(+), 10 deletions(-)
tools/i2ctransfer.8 +25 -1
@@ -96,8 +96,11 @@ The number of blocks is limited by the Linux Kernel and defined by I2C_RDWR_IOCT .I desc blocks are composed like this: -.I {r|w}<length_of_message>[@address] +.I [inpst]{r|w}<length_of_message>[@address] +.TP +.B [inpst] +specifies optional MESSAGE MODIFIER FLAGS. See the section below for details. .TP .B {r|w} specifies if the message is read or write
@@ -141,6 +144,27 @@ decrease value by 1 until end of message (i.e. 0xff- means 0xff, 0xfe, 0xfd, ... p use value as seed for an 8 bit pseudo random sequence (i.e. 0p means 0x00, 0x50, 0xb0, ...) +.SH "MESSAGE MODIFIER FLAGS" +.PP +These optional flags can be used to change the handling of a message when it is sent on the bus. +Note that not all flags (or any) may be supported by your particular hardware. + +.TP +.B i +ignore NACK from client, treat them as ACK. +.TP +.B n +in a read message, master ACK/NACK bit is skipped. +.TP +.B p +emit a STOP after the message. +.TP +.B s +skip repeated start. +.TP +.B t +toggle read/write bit. + .SH EXAMPLES .PP On bus 0, from an EEPROM at address 0x50, read 8 byte from offset 0x64
tools/i2ctransfer.c +25 -9
@@ -52,9 +52,16 @@ static void help(void)" -V version info\n" " -y yes to all confirmations\n" " I2CBUS is an integer or an I2C bus name\n" -" DESC describes the transfer in the form: {r|w}LENGTH[@address]\n" -" 1) read/write-flag 2) LENGTH (range 0-65535, or '?')\n" -" 3) I2C address (use last one if omitted)\n" +" DESC describes the transfer in the form: [inpst]{r|w}LENGTH[@address]\n" +" 1) optional message modifier flags\n" +" i: ignore NACK from client\n" +" n: no master ACK/NACK bit in a read message\n" +" p: emit a STOP after the message\n" +" s: skip repeated start\n" +" t: toggle read/write bit\n" +" 2) mandatory read/write flag\n" +" 3) LENGTH (range 0-65535, or '?')\n" +" 4) I2C address (use last one if omitted)\n" " 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"
@@ -202,12 +209,21 @@ int main(int argc, char *argv[])case PARSE_GET_DESC : flags =0 ; -switch (*arg_ptr++) { -case 'r' : flags |=I2C_M_RD ;break ; -case 'w' :break ; -default : -fprintf (stderr,"Error: Invalid direction\n" ); - goto err_out_with_arg; +for (int done =0 ; !done; ) { +switch (*arg_ptr++) { +/* optional flags */ +case 'i' : flags |=I2C_M_IGNORE_NAK ;break ; +case 'n' : flags |=I2C_M_NO_RD_ACK ;break ; +case 'p' : flags |=I2C_M_STOP ;break ; +case 's' : flags |=I2C_M_NOSTART ;break ; +case 't' : flags |=I2C_M_REV_DIR_ADDR ;break ; +/* mandatory flags */ +case 'r' : flags |=I2C_M_RD ; done =1 ;break ; +case 'w' : done =1 ;break ; +default : +fprintf (stderr,"Error: Invalid flag\n" ); + goto err_out_with_arg; + } }if (*arg_ptr =='?' ) {
Signature · 1 line
2.52.0
Hi Benoît,
Quoted 5 lines
The patches use defines that have been present in the kernel since v3.6 released in 2012. If compatibility with older kernel is required, we will need to wrap some of them with #ifndef ... #endif.
Maybe a minimum kernel version can be documented in the README?
I'd rather have a little ifdeffery here. It should not be much, let's have a look in the actual patches.
Re: [PATCH i2c-tools v2 1/2] i2cdetect: Display mangling and nostart support
In reply to Benoît Monintools/i2cdetect.c static const struct func all_func[] = { · line 171
Quoted 9 lines
tools/i2cdetect.c +4
-0@@ -165,6 +165,10 @@ static const struct func all_func[] = { { .value = I2C_FUNC_SLAVE, .name = "Target mode" }, #endif + { .value = I2C_FUNC_PROTOCOL_MANGLING, + .name = "Protocol mangling" }, + { .value = I2C_FUNC_NOSTART, + .name = "Skip repeated start" },
As we can see from entries above, the ifdeffery wouldn't be too bad for those two, I'd think.
Re: [PATCH i2c-tools v2 2/2] i2ctransfer: Add optional message modifier flags
In reply to Benoît Monintools/i2ctransfer.8 The number of blocks is limited by the Linux Kernel and defined by I2C_RDWR_IOCT · line 103
Quoted 12 lines
tools/i2ctransfer.8 +4
-1@@ -96,8 +96,11 @@ The number of blocks is limited by the Linux Kernel and defined by I2C_RDWR_IOCT .I desc blocks are composed like this: -.I {r|w}<length_of_message>[@address] +.I [inpst]{r|w}<length_of_message>[@address] +.TP +.B [inpst] +specifies optional MESSAGE MODIFIER FLAGS. See the section below for details.
The documentation needs just a slight update like "if supported". It depends not only on the Linux version but the controller driver anyhow.
Quoted 8 lines
tools/i2ctransfer.8 +1
-3+++ b/tools/i2ctransfer.c@@ -52,9 +52,16 @@ static void help(void) " -V version info\n" " -y yes to all confirmations\n" " I2CBUS is an integer or an I2C bus name\n" - " DESC describes the transfer in the form: {r|w}LENGTH[@address]\n" - " 1) read/write-flag 2) LENGTH (range 0-65535, or '?')\n" - " 3) I2C address (use last one if omitted)\n"
tools/i2ctransfer.8 static void help(void) · line 64
Quoted 10 lines
tools/i2ctransfer.8 +10
-0+ " DESC describes the transfer in the form: [inpst]{r|w}LENGTH[@address]\n" + " 1) optional message modifier flags\n" + " i: ignore NACK from client\n" + " n: no master ACK/NACK bit in a read message\n" + " p: emit a STOP after the message\n" + " s: skip repeated start\n" + " t: toggle read/write bit\n" + " 2) mandatory read/write flag\n" + " 3) LENGTH (range 0-65535, or '?')\n" + " 4) I2C address (use last one if omitted)\n"
Same here. I think the help text can be static by saying "if supported"
Quoted 11 lines
tools/i2ctransfer.8 +0
-4" 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"@@ -202,12 +209,21 @@ int main(int argc, char *argv[]) case PARSE_GET_DESC: flags = 0; - switch (*arg_ptr++) { - case 'r': flags |= I2C_M_RD; break; - case 'w': break; - default:
tools/i2ctransfer.8 int main(int argc, char *argv[]) · line 219
Quoted 10 lines
tools/i2ctransfer.8 +8
-2- fprintf(stderr, "Error: Invalid direction\n"); - goto err_out_with_arg; + for (int done = 0; !done; ) { + switch (*arg_ptr++) { + /* optional flags */ + case 'i': flags |= I2C_M_IGNORE_NAK; break; + case 'n': flags |= I2C_M_NO_RD_ACK; break; + case 'p': flags |= I2C_M_STOP; break; + case 's': flags |= I2C_M_NOSTART; break; + case 't': flags |= I2C_M_REV_DIR_ADDR; break;
Brainstorming here: maybe a macro could help:
case 'i': add_flag_if_supported(flags, I2C_M_IGNORE_NAK);
?
Thanks and happy hacking,
Wolfram
Re: [PATCH i2c-tools v2 2/2] i2ctransfer: Add optional message modifier flags
On Tuesday, 13 January 2026 at 18:33:53 CET, Wolfram Sang wrote:
[...]
Quoted 24 lines
Quoted 11 lines
tools/i2ctransfer.c +0
-4" 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" @@ -202,12 +209,21 @@ int main(int argc, char *argv[])case PARSE_GET_DESC : flags =0 ; -switch (*arg_ptr++) { -case 'r' : flags |=I2C_M_RD ;break ; -case 'w' :break ; -default :tools/i2ctransfer.c int main(int argc, char *argv[]) · line 219
Quoted 10 lines
tools/i2ctransfer.c +8
-2-fprintf (stderr,"Error: Invalid direction\n" ); - goto err_out_with_arg; +for (int done =0 ; !done; ) { +switch (*arg_ptr++) { +/* optional flags */ +case 'i' : flags |=I2C_M_IGNORE_NAK ;break ; +case 'n' : flags |=I2C_M_NO_RD_ACK ;break ; +case 'p' : flags |=I2C_M_STOP ;break ; +case 's' : flags |=I2C_M_NOSTART ;break ; +case 't' : flags |=I2C_M_REV_DIR_ADDR ;break ;Brainstorming here: maybe a macro could help:
Quoted 4 lines
case 'i': add_flag_if_supported(flags, I2C_M_IGNORE_NAK);?
I am having a hard time coming up with something here. There is the __is_defined() macro in the kernel source[1], it only returns 0 or 1, not the value of the define.
Maybe defining as zero the flags that are undefined would be acceptable? E.g.
#ifndef I2C_M_IGNORE_NAK
#define I2C_M_IGNORE_NAK 0
#endif
Or you have another idea?
[1]: https://elixir.bootlin.com/linux/v6.19-rc5/source/tools/include/linux/kconfig.h#L35
Thanks for the review!
Signature · 1 line
Benoît
Hi Benoït, hi Wolfram,
Quoted 7 lines · Benoît Monin
I2C messages can be modified with a set of flags covered by the protocol mangling and the skip repeated start functionalities. This series add support for such flags to i2cdetect and i2ctransfer.
The first patch shows the support of protocol mangling and repeated start skipping in the output of 'i2cdetect -F'.
Quoted 7 lines
The second patch adds the parsing of optional flags to i2ctransfer message description. Those command-line flags then set the i2c message flags alongside the read/write flag.
I wrote these changes to test the insertion of
I2C_M_STOPflag in multi-message transactions with i2ctransfer, but the other flags can be useful for various test scenarios.
Out of curiosity, did you have an actual scenario where you needed to do this? Protocol mangling is supposed to be rarely needed and avoided as much as possible.
Quoted 5 lines
The patches use defines that have been present in the kernel since v3.6 released in 2012. If compatibility with older kernel is required, we will need to wrap some of them with #ifndef ... #endif.
Maybe a minimum kernel version can be documented in the README?
Be careful if you do. Kernel versions are a very broad indicator, distribution kernel maintainers keep backporting features so an older kernel can actually support something when its version suggests it wouldn't. A kernel version should always be complemented with the actual feature or flag so that users can look it up if needed.
Quoted 12 lines
Signed-off-by Benoît Monin <[email protected]>---
Changes in v2:
- Document the flags in i2ctransfer.8 man page.
- Link to v1: https://lore.kernel.org/r/[email protected]---
Benoît Monin (2):
i2cdetect: Display mangling and nostart support
i2ctransfer: Add optional message modifier flags
Quoted 7 lines
tools/i2cdetect.c | 4 ++++ tools/i2ctransfer.8 | 26 +++++++++++++++++++++++++- tools/i2ctransfer.c | 34 +++++++++++++++++++++++++--------- 3 files changed, 54 insertions(+), 10 deletions(-)---
base-commit:ea51da725b743da00b894dfdc4ab189f5a51e90e
change-id: 20251127-msg-flags-3d2b2da9ae28
I have read Wolfram's review of your patch set (thanks Wolfram!) and must say I agree with everything he wrote.
Signature · 2 lines
Jean Delvare SUSE L3 Support
Re: [PATCH i2c-tools v2 2/2] i2ctransfer: Add optional message modifier flags
In reply to Benoît Monintools/i2ctransfer.c int main(int argc, char *argv[]) · line 212
Quoted 11 lines · Benoît Monin
tools/i2ctransfer.c +1
-6@@ -202,12 +209,21 @@ int main(int argc, char *argv[])case PARSE_GET_DESC : flags =0 ; -switch (*arg_ptr++) { -case 'r' : flags |=I2C_M_RD ;break ; -case 'w' :break ; -default : -fprintf (stderr,"Error: Invalid direction\n" ); - goto err_out_with_arg; +for (int done =0 ; !done; ) {
For compatibility with older C compilers, please declare "done" at the beginning of the while loop.
tools/i2ctransfer.c int main(int argc, char *argv[]) · line 220
Quoted 8 lines
tools/i2ctransfer.c +8
-0+switch (*arg_ptr++) { +/* optional flags */ +case 'i' : flags |=I2C_M_IGNORE_NAK ;break ; +case 'n' : flags |=I2C_M_NO_RD_ACK ;break ; +case 'p' : flags |=I2C_M_STOP ;break ; +case 's' : flags |=I2C_M_NOSTART ;break ; +case 't' : flags |=I2C_M_REV_DIR_ADDR ;break ; +/* mandatory flags */
I would write "mandatory direction flag" (singular because only one can and must be present).
Quoted 10 lines
tools/i2ctransfer.c +6
-0+case 'r' : flags |=I2C_M_RD ; done =1 ;break ; +case 'w' : done =1 ;break ; +default : +fprintf (stderr,"Error: Invalid flag\n" ); + goto err_out_with_arg; + } }if (*arg_ptr =='?' ) {
Signature · 2 lines
Jean Delvare SUSE L3 Support
Re: [PATCH i2c-tools v2 2/2] i2ctransfer: Add optional message modifier flags
In reply to Benoît MoninHi Benoît,
Quoted 34 lines · Benoît Monin
On Tuesday, 13 January 2026 at 18:33:53 CET, Wolfram Sang wrote:
[...]Quoted 24 lines
Quoted 11 lines
tools/i2ctransfer.c +0
-4" 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" @@ -202,12 +209,21 @@ int main(int argc, char *argv[])case PARSE_GET_DESC : flags =0 ; -switch (*arg_ptr++) { -case 'r' : flags |=I2C_M_RD ;break ; -case 'w' :break ; -default :tools/i2ctransfer.c int main(int argc, char *argv[]) · line 219
Quoted 10 lines
tools/i2ctransfer.c +8
-2-fprintf (stderr,"Error: Invalid direction\n" ); - goto err_out_with_arg; +for (int done =0 ; !done; ) { +switch (*arg_ptr++) { +/* optional flags */ +case 'i' : flags |=I2C_M_IGNORE_NAK ;break ; +case 'n' : flags |=I2C_M_NO_RD_ACK ;break ; +case 'p' : flags |=I2C_M_STOP ;break ; +case 's' : flags |=I2C_M_NOSTART ;break ; +case 't' : flags |=I2C_M_REV_DIR_ADDR ;break ;Brainstorming here: maybe a macro could help:
Quoted 4 lines
case 'i': add_flag_if_supported(flags, I2C_M_IGNORE_NAK);?
I am having a hard time coming up with something here. There is the
__is_defined()macro in the kernel source[1], it only returns 0 or 1, not the value of the define.
Quoted 6 lines
Maybe defining as zero the flags that are undefined would be acceptable? E.g.
#ifndef
I2C_M_IGNORE_NAK
#defineI2C_M_IGNORE_NAK0
#endif
I don't think that's a good idea, because then you would simply ignore the flag that was passed by the user if it's not supported? If so, this is bad user experience. If the user asks for something unsupported, the tool should report the lack of support, and fail.
Quoted 1 line
Or you have another idea?
I honestly think that a bunch of ifdefs in this part of the code would work just fine and be acceptable. We don't plan to add more flags in the future, and I think that's better than preprocessor magic which may work or break depending on the compiler.
Something like:
/* optional flags */ case 'i': #ifdef I2C_M_IGNORE_NAK flags |= I2C_M_IGNORE_NAK; #else fprintf(stderr, "Error: Unsupported flag '%c'\n", 'i'); #endif break; case 'n': #ifdef I2C_M_NO_RD_ACK flags |= I2C_M_NO_RD_ACK; #else fprintf(stderr, "Error: Unsupported flag '%c'\n", 'n'); #endif break; case 'p': #ifdef I2C_M_STOP flags |= I2C_M_STOP; #else fprintf(stderr, "Error: Unsupported flag '%c'\n", 'p'); #endif break; case 's': #ifdef I2C_M_NOSTART flags |= I2C_M_NOSTART; #else fprintf(stderr, "Error: Unsupported flag '%c'\n", 's'); #endif break; case 't': #ifdef I2C_M_REV_DIR_ADDR flags |= I2C_M_REV_DIR_ADDR; #else fprintf(stderr, "Error: Unsupported flag '%c'\n", 't'); #endif break;
That being said, I think you also need a second level of support check. The above only checks if the flags are defined in the kernel headers, which should generally correspond to the flags being supported by the kernel. But just because the flags are known to the kernel, doesn't mean that the i2c adapter you are operating on, supports protocol mangling.
So I believe that you also need to extend check_funcs() to return the supported functionality, and then check for I2C_FUNC_PROTOCOL_MANGLING and I2C_FUNC_NOSTART after parsing the optional flags. If mangling flags are passed by the user but the adapter's driver does not support protocol mangling, the tool should report the incompatibility and stop.
Signature · 2 lines
Jean Delvare SUSE L3 Support
Hi Jean,
Quoted 14 lines · Jean Delvare
Hi Benoït, hi Wolfram,
Quoted 11 lines · Benoît Monin
I2C messages can be modified with a set of flags covered by the protocol mangling and the skip repeated start functionalities. This series add support for such flags to i2cdetect and i2ctransfer.
The first patch shows the support of protocol mangling and repeated start skipping in the output of 'i2cdetect -F'.
The second patch adds the parsing of optional flags to i2ctransfer message description. Those command-line flags then set the i2c message flags alongside the read/write flag.
Quoted 8 lines
Quoted 3 lines
I wrote these changes to test the insertion of
I2C_M_STOPflag in multi-message transactions with i2ctransfer, but the other flags can be useful for various test scenarios.Out of curiosity, did you have an actual scenario where you needed to do this? Protocol mangling is supposed to be rarely needed and avoided as much as possible.
My only need was to have a way to set the I2C_M_STOP flag, but since I started modifying i2ctransfer, adding the other flags was not much additional work.
If you think that some of the flags should not be exposed by i2ctransfer, I can remove them.
Quoted 4 lines
Quoted 4 lines
The patches use defines that have been present in the kernel since v3.6 released in 2012. If compatibility with older kernel is required, we will need to wrap some of them with #ifndef ... #endif.
Quoted 8 lines
Quoted 1 line
Maybe a minimum kernel version can be documented in the README?
Be careful if you do. Kernel versions are a very broad indicator, distribution kernel maintainers keep backporting features so an older kernel can actually support something when its version suggests it wouldn't. A kernel version should always be complemented with the actual feature or flag so that users can look it up if needed.
True. I will go with #ifdef instead, as you and Wolfram proposed. And I will add a check against the adapter functionalities.
[...]
Thanks for the review!
Signature · 3 lines
Benoît Monin, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Quoted 11 lines · Benoît Monin
Quoted 4 lines · Jean Delvare
Out of curiosity, did you have an actual scenario where you needed to do this? Protocol mangling is supposed to be rarely needed and avoided as much as possible.
My only need was to have a way to set the
I2C_M_STOPflag, but since I started modifying i2ctransfer, adding the other flags was not much additional work.If you think that some of the flags should not be exposed by i2ctransfer, I can remove them.
I was just curious, I have no objection to including them all in i2ctransfer. Maybe someone else will need them in the future.
It might be a good idea to mention in the man page that these flags should be used carefully though. They are a deviation from the standard and devices may react badly if they do not expect that.
Signature · 2 lines
Jean Delvare SUSE L3 Support