Tests:I2C-bus-recovery-write-byte-fix

This document describes how to test if I2C bus recovery was fixed to not accidently write bytes during recovery. A Renesas I2C IP core used on a Renesas Lager board serves as an example platform here.

Setup

Kernel Version and Configuration

Support for this feature is expected to land upstream in v4.19. It is currently available in a topic branch:

git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux.git renesas/i2c/recovery/write-byte-fix

The following kernel options need to be set in addition to the defconfig:

CONFIG_I2C_GPIO=y
CONFIG_I2C_GPIO_FAULT_INJECTOR=y

Hardware Environment

Lager/r8a7790 (R-Car H2 SoC)

You need to connect the pins:

EXIO_C 78 <-> EXIO_A 58 (for SCL)
EXIO_C 80 <-> EXIO_A 60 (for SDA)

This will connect the I2C1 and the I2C2 bus. We will use the I2C demultiplexer at runtime to switch I2C1 to GPIO:

# echo 2 > /sys/devices/platform/i2c-11/current_master

Software Environment

A busybox with standard commands like cd, cat, echo is needed. Also, i2cget from the i2c-tools package should be available.

Previous state

As documented in the test page for Tests:I2C-bus-recovery, the bus recovery mechanism of the Linux I2C core was able to resurrect a stalled bus. However, the implementation had a flaw which could lead to accidental writes to a device during recovery. To demonstrate this, a new fault injector was implemented. For a summary about I2C fault injection, have a look here: Tests:I2C-fault-injection

To get to the previous state using the above branch, checkout to the new fault injector only:

$ git checkout 0cab20ea89061a0783071317353dcc1099e8d786

The Renesas I2C IP core is special, because it cannot read the SDA status directly, only set SDA. This leads to an undesired write when the following sequence of commands is executed:

Setup fault injector on the Renesas Lager board:

# echo 2 > /sys/devices/platform/i2c-11/current_master
i2c-gpio i2c-8: using lines 979 (SDA) and 978 (SCL)
# echo 1 > /sys/devices/platform/i2c-12/current_master
i2c-rcar e6530000.i2c: probed
# cd /sys/kernel/debug/i2c-fault-injector/i2c-8/

Check original value of register 0 from device 0x12. It is 0x00 now:

# i2cget -y -f 2 0x12 0
0x00

Use the incomplete_write_byte fault injector. Then, read register 8 to enforce bus recovery. Note that the read value from register 8 succeeds, so the stalled bus has been corrected. Also, the register value 0xe1 is correct:

# echo 0x12 > incomplete_write_byte
# i2cget -y -f 2 0x12 8
0xe1

But if we read out register 0 again, it has been modified to 0xff! Which is the result of having SDA high all the time while clocking SCL:

# i2cget -y -f 2 0x12 0
0xff

Here is a scope of that scenario:

You can even see the device acknowledging the sent byte.

Fixed state

The above issue got fixed in the beforementioned branch. The solution was:

If we cannot read SDA to bail out early, create a STOP condition on the bus to ensure devices don not misinterpret the SCL toggling.

Here is a scope showing the difference, note how the SDA line looks now:

If you repeat the above commands now with the fix applied, the final read of register 0 now shows the unmodified value again:

# i2cget -y -f 2 0x12 0
0x00

Conclusion

It could be shown that the implementation of I2C bus recovery could cause unwanted writes in a worst case scenario. It could also be shown that a fix was applied to prevent this from happening.