1 =========================
2 Linux I2C fault injection
3 =========================
4
5 The GPIO based I2C bus master driver can be co
6 injection capabilities. It is then meant to be
7 which is driven by the I2C bus master driver u
8 injection driver can create special states on
9 master driver should handle gracefully.
10
11 Once the Kconfig option I2C_GPIO_FAULT_INJECTO
12 'i2c-fault-injector' subdirectory in the Kerne
13 mounted at /sys/kernel/debug. There will be a
14 driven I2C bus. Each subdirectory will contain
15 injection. They will be described now along wi
16
17 Wire states
18 ===========
19
20 "scl"
21 -----
22
23 By reading this file, you get the current stat
24 change its state to either force it low or to
25 "echo 0 > scl" you force SCL low and thus, no
26 because the bus master under test will not be
27 the condition of SCL being unresponsive and re
28 layers.
29
30 "sda"
31 -----
32
33 By reading this file, you get the current stat
34 change its state to either force it low or to
35 "echo 0 > sda" you force SDA low and thus, dat
36 master under test should detect this condition
37 I2C specification version 4, section 3.1.16) u
38 core (see 'struct bus_recovery_info'). However
39 succeed because SDA is still pinned low until
40 with "echo 1 > sda". A test with an automatic
41 "incomplete transfers" class of fault injector
42
43 Incomplete transfers
44 ====================
45
46 The following fault injectors create situation
47 device. Bus recovery should be able to fix the
48 there are I2C client devices which detect a st
49 it on their own after a few milliseconds. Also
50 device deglitching and monitoring the I2C bus.
51 and will init a bus recovery on its own. If yo
52 in a bus master driver, make sure you checked
53 devices before. And always verify with a scope
54
55 "incomplete_address_phase"
56 --------------------------
57
58 This file is write only and you need to write
59 client device to it. Then, a read transfer to
60 it will stop at the ACK phase after the addres
61 transmitted. Because the device will ACK its p
62 being pulled low by the device while SCL is hi
63 above, the bus master under test should detect
64 recovery. This time, however, it should succee
65 SDA after toggling SCL.
66
67 "incomplete_write_byte"
68 -----------------------
69
70 Similar to above, this file is write only and
71 an existing I2C client device to it.
72
73 The injector will again stop at one ACK phase,
74 because it acknowledges data. However, there a
75 'incomplete_address_phase':
76
77 a) the message sent out will be a write messag
78 b) after the address byte, a 0x00 byte will be
79
80 This is a highly delicate state, the device is
81 register 0x00 (if it has registers) when furth
82 This is why bus recovery (up to 9 clock pulses
83 additional STOP conditions to ensure the bus h
84 random data will be written to a device!
85
86 Lost arbitration
87 ================
88
89 Here, we want to simulate the condition where
90 bus arbitration against another master in a mu
91
92 "lose_arbitration"
93 ------------------
94
95 This file is write only and you need to write
96 interference (in µs, maximum is 100ms). The c
97 and wait for the next bus clock. The process i
98
99 Arbitration lost is achieved by waiting for SC
100 test and then pulling SDA low for some time. S
101 should be corrupted and that should be detecte
102 address sent out should have a lot of '1' bits
103 There doesn't need to be a device at this addr
104 should be detected beforehand. Also note, that
105 using interrupts, so the interrupt latency mig
106 corrupted. A good starting point for using thi
107 idle bus is::
108
109 # echo 200 > lose_arbitration &
110 # i2cget -y <bus_to_test> 0x3f
111
112 Panic during transfer
113 =====================
114
115 This fault injector will create a Kernel panic
116 started a transfer. This usually means that th
117 driver will be ungracefully interrupted and th
118 state. Use this to check if your shutdown/rebo
119 scenario.
120
121 "inject_panic"
122 --------------
123
124 This file is write only and you need to write
125 start of a transmission and the induced Kernel
126 The calling process will then sleep and wait f
127 process is interruptible, though.
128
129 Start of a transfer is detected by waiting for
130 under test. A good starting point for using t
131
132 # echo 0 > inject_panic &
133 # i2cget -y <bus_to_test> <some_address>
134
135 Note that there doesn't need to be a device li
136 using. Results may vary depending on that, tho
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.