1Linux I2C fault injection
2=========================
3
4The GPIO based I2C bus master driver can be configured to provide fault
5injection capabilities. It is then meant to be connected to another I2C bus
6which is driven by the I2C bus master driver under test. The GPIO fault
7injection driver can create special states on the bus which the other I2C bus
8master driver should handle gracefully.
9
10Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an
11'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually
12mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO
13driven I2C bus. Each subdirectory will contain files to trigger the fault
14injection. They will be described now along with their intended use-cases.
15
16"scl"
17-----
18
19By reading this file, you get the current state of SCL. By writing, you can
20change its state to either force it low or to release it again. So, by using
21"echo 0 > scl" you force SCL low and thus, no communication will be possible
22because the bus master under test will not be able to clock. It should detect
23the condition of SCL being unresponsive and report an error to the upper
24layers.
25
26"sda"
27-----
28
29By reading this file, you get the current state of SDA. By writing, you can
30change its state to either force it low or to release it again. So, by using
31"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus
32master under test should detect this condition and trigger a bus recovery (see
33I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C
34core (see 'struct bus_recovery_info'). However, the bus recovery will not
35succeed because SDA is still pinned low until you manually release it again
36with "echo 1 > sda". A test with an automatic release can be done with the
37following class of fault injectors.
38
39Introduction to incomplete transfers
40------------------------------------
41
42The following fault injectors create situations where SDA will be held low by a
43device. Bus recovery should be able to fix these situations. But please note:
44there are I2C client devices which detect a stuck SDA on their side and release
45it on their own after a few milliseconds. Also, there might be an external
46device deglitching and monitoring the I2C bus. It could also detect a stuck SDA
47and will init a bus recovery on its own. If you want to implement bus recovery
48in a bus master driver, make sure you checked your hardware setup for such
49devices before. And always verify with a scope or logic analyzer!
50
51"incomplete_address_phase"
52--------------------------
53
54This file is write only and you need to write the address of an existing I2C
55client device to it. Then, a read transfer to this device will be started, but
56it will stop at the ACK phase after the address of the client has been
57transmitted. Because the device will ACK its presence, this results in SDA
58being pulled low by the device while SCL is high. So, similar to the "sda" file
59above, the bus master under test should detect this condition and try a bus
60recovery. This time, however, it should succeed and the device should release
61SDA after toggling SCL.
62
63"incomplete_write_byte"
64-----------------------
65
66Similar to above, this file is write only and you need to write the address of
67an existing I2C client device to it.
68
69The injector will again stop at one ACK phase, so the device will keep SDA low
70because it acknowledges data. However, there are two differences compared to
71'incomplete_address_phase':
72
73a) the message sent out will be a write message
74b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK.
75
76This is a highly delicate state, the device is set up to write any data to
77register 0x00 (if it has registers) when further clock pulses happen on SCL.
78This is why bus recovery (up to 9 clock pulses) must either check SDA or send
79additional STOP conditions to ensure the bus has been released. Otherwise
80random data will be written to a device!
81
82