Tests:I2C-bus-recovery

This document describes how to test if I2C bus recovery from the Linux I2C core was applied. A Renesas I2C IP core used on a Renesas Lager board serves as an example platform here. Note: Also read this page for an improved version of the recovery: Tests:I2C-bus-recovery-write-byte-fix

=Setup=

Kernel Version and Configuration
Support for this feature is expected to land upstream in v4.16. It is currently available in a topic branch:

git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux.git renesas/topic/rcar-i2c-recovery

The following kernel options need to be set in addition to the defconfig: CONFIG_I2C_GPIO=y CONFIG_I2C_GPIO_FAULT_INJECTOR=y

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:
 * 1) 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 I2C fault injection, an incomplete transfer to the audio codec resulted in the SDA line stuck low. It was concluded that "the audio codec does not have any timeout detection and there is no external chip to reactivate the bus. It is now the I2C bus masters turn to detect this condition and to recover the bus by toggling SCL."

=Testing I2C bus recovery= After booting, we activate the I2C GPIO fault injector: i2c-gpio i2c-8: using lines 979 (SDA) and 978 (SCL)
 * 1) echo 2 > /sys/devices/platform/i2c-11/current_master

Then, we switch I2C2 from the IIC to the I2C IP core, where bus recovery was implemented: i2c-rcar e6530000.i2c: probed
 * 1) echo 1 > /sys/devices/platform/i2c-12/current_master

Now, we create the stalled SDA case again using the I2C fault injector:
 * 1) cd /sys/kernel/debug/i2c-fault-injector/i2c-8/
 * 2) echo 0x12 > incomplete_transfer

Using a scope, we verify that SDA is stuck low and needs to be recovered:

Now, we try to read register 8 from the audio codec via the stalled I2C bus: 0xe1
 * 1) i2cget -y -f 2 0x12 8

So, we got a valid response from this read request. Using a scope, we see the following happening:

We see left of the markers that SCL was toggled until the audio codec released SDA again. There is one clock cycle done more than necessary. This is due to the fact that the I2C IP core can't read back the status of the SDA line, so we always have to perform the maximum number of clock cycles to be sure the line gets released. Nonetheless, the stuck SDA condition was detected and successfully recovered from.

Within the markers, we see that a valid STOP condition has been put onto the bus, to create a known bus state again. This is now possible because SDA was released by the device and can now be controlled by the master again.

Right of the markers, we see the originally intended I2C transfer which reads out register 8 from the audio codec without any problems. Also, the bus is in the correct idle state again after that transfer.

=Conclusion= It could be shown that the implementation of I2C bus recovery in the R-Car I2C driver using the I2C core helpers was able to recover from a stalled bus. Even though SDA was held low by a device in an inconsistent state, it was recovered and the whole bus was brought back to a known state. Note: Also read this page for an improved version of the recovery: Tests:I2C-bus-recovery-write-byte-fix