0001 =========================
0002 Linux I2C fault injection
0003 =========================
0004
0005 The GPIO based I2C bus master driver can be configured to provide fault
0006 injection capabilities. It is then meant to be connected to another I2C bus
0007 which is driven by the I2C bus master driver under test. The GPIO fault
0008 injection driver can create special states on the bus which the other I2C bus
0009 master driver should handle gracefully.
0010
0011 Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an
0012 'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually
0013 mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO
0014 driven I2C bus. Each subdirectory will contain files to trigger the fault
0015 injection. They will be described now along with their intended use-cases.
0016
0017 Wire states
0018 ===========
0019
0020 "scl"
0021 -----
0022
0023 By reading this file, you get the current state of SCL. By writing, you can
0024 change its state to either force it low or to release it again. So, by using
0025 "echo 0 > scl" you force SCL low and thus, no communication will be possible
0026 because the bus master under test will not be able to clock. It should detect
0027 the condition of SCL being unresponsive and report an error to the upper
0028 layers.
0029
0030 "sda"
0031 -----
0032
0033 By reading this file, you get the current state of SDA. By writing, you can
0034 change its state to either force it low or to release it again. So, by using
0035 "echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus
0036 master under test should detect this condition and trigger a bus recovery (see
0037 I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C
0038 core (see 'struct bus_recovery_info'). However, the bus recovery will not
0039 succeed because SDA is still pinned low until you manually release it again
0040 with "echo 1 > sda". A test with an automatic release can be done with the
0041 "incomplete transfers" class of fault injectors.
0042
0043 Incomplete transfers
0044 ====================
0045
0046 The following fault injectors create situations where SDA will be held low by a
0047 device. Bus recovery should be able to fix these situations. But please note:
0048 there are I2C client devices which detect a stuck SDA on their side and release
0049 it on their own after a few milliseconds. Also, there might be an external
0050 device deglitching and monitoring the I2C bus. It could also detect a stuck SDA
0051 and will init a bus recovery on its own. If you want to implement bus recovery
0052 in a bus master driver, make sure you checked your hardware setup for such
0053 devices before. And always verify with a scope or logic analyzer!
0054
0055 "incomplete_address_phase"
0056 --------------------------
0057
0058 This file is write only and you need to write the address of an existing I2C
0059 client device to it. Then, a read transfer to this device will be started, but
0060 it will stop at the ACK phase after the address of the client has been
0061 transmitted. Because the device will ACK its presence, this results in SDA
0062 being pulled low by the device while SCL is high. So, similar to the "sda" file
0063 above, the bus master under test should detect this condition and try a bus
0064 recovery. This time, however, it should succeed and the device should release
0065 SDA after toggling SCL.
0066
0067 "incomplete_write_byte"
0068 -----------------------
0069
0070 Similar to above, this file is write only and you need to write the address of
0071 an existing I2C client device to it.
0072
0073 The injector will again stop at one ACK phase, so the device will keep SDA low
0074 because it acknowledges data. However, there are two differences compared to
0075 'incomplete_address_phase':
0076
0077 a) the message sent out will be a write message
0078 b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK.
0079
0080 This is a highly delicate state, the device is set up to write any data to
0081 register 0x00 (if it has registers) when further clock pulses happen on SCL.
0082 This is why bus recovery (up to 9 clock pulses) must either check SDA or send
0083 additional STOP conditions to ensure the bus has been released. Otherwise
0084 random data will be written to a device!
0085
0086 Lost arbitration
0087 ================
0088
0089 Here, we want to simulate the condition where the master under test loses the
0090 bus arbitration against another master in a multi-master setup.
0091
0092 "lose_arbitration"
0093 ------------------
0094
0095 This file is write only and you need to write the duration of the arbitration
0096 intereference (in µs, maximum is 100ms). The calling process will then sleep
0097 and wait for the next bus clock. The process is interruptible, though.
0098
0099 Arbitration lost is achieved by waiting for SCL going down by the master under
0100 test and then pulling SDA low for some time. So, the I2C address sent out
0101 should be corrupted and that should be detected properly. That means that the
0102 address sent out should have a lot of '1' bits to be able to detect corruption.
0103 There doesn't need to be a device at this address because arbitration lost
0104 should be detected beforehand. Also note, that SCL going down is monitored
0105 using interrupts, so the interrupt latency might cause the first bits to be not
0106 corrupted. A good starting point for using this fault injector on an otherwise
0107 idle bus is::
0108
0109 # echo 200 > lose_arbitration &
0110 # i2cget -y <bus_to_test> 0x3f
0111
0112 Panic during transfer
0113 =====================
0114
0115 This fault injector will create a Kernel panic once the master under test
0116 started a transfer. This usually means that the state machine of the bus master
0117 driver will be ungracefully interrupted and the bus may end up in an unusual
0118 state. Use this to check if your shutdown/reboot/boot code can handle this
0119 scenario.
0120
0121 "inject_panic"
0122 --------------
0123
0124 This file is write only and you need to write the delay between the detected
0125 start of a transmission and the induced Kernel panic (in µs, maximum is 100ms).
0126 The calling process will then sleep and wait for the next bus clock. The
0127 process is interruptible, though.
0128
0129 Start of a transfer is detected by waiting for SCL going down by the master
0130 under test. A good starting point for using this fault injector is::
0131
0132 # echo 0 > inject_panic &
0133 # i2cget -y <bus_to_test> <some_address>
0134
0135 Note that there doesn't need to be a device listening to the address you are
0136 using. Results may vary depending on that, though.
