1 .. SPDX-License-Identifier: GPL-2.0
2
3 ================================
4 Linux I2C slave testunit backend
5 ================================
6
7 by Wolfram Sang <wsa@sang-engineering.com> in 2
8
9 This backend can be used to trigger test cases
10 require a remote device with certain capabilit
11 easy to obtain). Examples include multi-master
12 testing. For some tests, the I2C slave control
13 between master and slave mode because it needs
14
15 Note that this is a device for testing and deb
16 in a production build. And while there is some
17 keep backward compatibility, there is no stabl
18
19 Instantiating the device is regular. Example f
20
21 # echo "slave-testunit 0x1030" > /sys/bus/i2
22
23 Or using firmware nodes. Here is a devicetree
24 debug device, so there are no official DT bind
25
26 &i2c0 {
27 ...
28
29 testunit@30 {
30 compatible = "slave-testunit";
31 reg = <(0x30 | I2C_OWN_SLAVE_A
32 };
33 };
34
35 After that, you will have the device listening
36 byte. Its value is 0 if the testunit is idle,
37 the currently running command.
38
39 When writing, the device consists of 4 8-bit r
40 "partial" commands, all registers must be writ
41 usually write 4 bytes to the device. The regis
42
43 .. csv-table::
44 :header: "Offset", "Name", "Description"
45
46 0x00, CMD, which test to trigger
47 0x01, DATAL, configuration byte 1 for the te
48 0x02, DATAH, configuration byte 2 for the te
49 0x03, DELAY, delay in n * 10ms until test is
50
51 Using 'i2cset' from the i2c-tools package, the
52
53 # i2cset -y <bus_num> <testunit_address> <CM
54
55 DELAY is a generic parameter which will delay
56 While a command is running (including the dela
57 acknowledged. You need to wait until the old o
58
59 The commands are described in the following se
60 result in the transfer not being acknowledged.
61
62 Commands
63 --------
64
65 0x00 NOOP
66 ~~~~~~~~~
67
68 Reserved for future use.
69
70 0x01 READ_BYTES
71 ~~~~~~~~~~~~~~~
72
73 .. list-table::
74 :header-rows: 1
75
76 * - CMD
77 - DATAL
78 - DATAH
79 - DELAY
80
81 * - 0x01
82 - address to read data from (lower 7 bits,
83 - number of bytes to read
84 - n * 10ms
85
86 Also needs master mode. This is useful to test
87 handling multi-master correctly. You can trigg
88 from another device on the bus. If the bus mas
89 access the bus at the same time, the bus will
90 bytes from device 0x50 after 50ms of delay::
91
92 # i2cset -y 0 0x30 1 0x50 0x80 5 i
93
94 0x02 SMBUS_HOST_NOTIFY
95 ~~~~~~~~~~~~~~~~~~~~~~
96
97 .. list-table::
98 :header-rows: 1
99
100 * - CMD
101 - DATAL
102 - DATAH
103 - DELAY
104
105 * - 0x02
106 - low byte of the status word to send
107 - high byte of the status word to send
108 - n * 10ms
109
110 Also needs master mode. This test will send an
111 host. Note that the status word is currently i
112 Example to send a notification with status wor
113
114 # i2cset -y 0 0x30 2 0x42 0x64 1 i
115
116 If the host controller supports HostNotify, th
117 should appear (Linux 6.11 and later)::
118
119 Detected HostNotify from address 0x30
120
121 0x03 SMBUS_BLOCK_PROC_CALL
122 ~~~~~~~~~~~~~~~~~~~~~~~~~~
123
124 .. list-table::
125 :header-rows: 1
126
127 * - CMD
128 - DATAL
129 - DATAH
130 - DELAY
131
132 * - 0x03
133 - 0x01 (i.e. one further byte will be writ
134 - number of bytes to be sent back
135 - leave out, partial command!
136
137 Partial command. This test will respond to a b
138 the SMBus specification. The one data byte wri
139 will be sent back in the following read transf
140 transfer, the testunit will prefix the length
141 your host bus driver emulates SMBus calls like
142 support the I2C_M_RECV_LEN flag of an i2c_msg.
143 The returned data consists of the length first
144 from length-1 to 0. Here is an example which e
145 i2c_smbus_block_process_call() using i2ctransf
146 later)::
147
148 # i2ctransfer -y 0 w3@0x30 3 1 0x10 r?
149 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08
150
151 0x04 GET_VERSION_WITH_REP_START
152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153
154 .. list-table::
155 :header-rows: 1
156
157 * - CMD
158 - DATAL
159 - DATAH
160 - DELAY
161
162 * - 0x04
163 - currently unused
164 - currently unused
165 - leave out, partial command!
166
167 Partial command. After sending this command, t
168 message with a NUL terminated version string b
169 character is always a 'v' and the length of th
170 128 bytes. However, it will only respond if th
171 the write message via repeated start. If your
172 repeated start correctly, this will work::
173
174 # i2ctransfer -y 0 w3@0x30 4 0 0 r128
175 0x76 0x36 0x2e 0x31 0x31 0x2e 0x30 0x2d 0x72
176
177 If you have i2c-tools 4.4 or later, you can pr
178
179 # i2ctransfer -y -b 0 w3@0x30 4 0 0 r128
180 v6.11.0-rc1-00009-gd37a1b4d3fd0
181
182 STOP/START combinations between the two messag
183 are not equivalent to a REPEATED START. As an
184 default response::
185
186 # i2cset -y 0 0x30 4 0 0 i; i2cget -y 0 0x30
187 0x00
188
189 0x05 SMBUS_ALERT_REQUEST
190 ~~~~~~~~~~~~~~~~~~~~~~~~
191
192 .. list-table::
193 :header-rows: 1
194
195 * - CMD
196 - DATAL
197 - DATAH
198 - DELAY
199
200 * - 0x05
201 - response value (7 MSBs interpreted as I2
202 - currently unused
203 - n * 10ms
204
205 This test raises an interrupt via the SMBAlert
206 must handle. The pin must be connected to the
207 is not allowed to sleep. Currently, this can o
208 nodes. So, for devicetree, you would add somet
209 node::
210
211 gpios = <&gpio1 24 GPIO_ACTIVE_LOW>;
212
213 The following command will trigger the alert w
214 second of delay::
215
216 # i2cset -y 0 0x30 5 0xc9 0x00 100 i
217
218 If the host controller supports SMBusAlert, th
219 should appear::
220
221 smbus_alert 0-000c: SMBALERT# from dev 0x64,
222
223 This message may appear more than once because
224 hardware and, thus, may not be able to react t
225 enough. The interrupt count should increase on
226
227 # cat /proc/interrupts | grep smbus_alert
228 93: 1 gpio-rcar 26 Edge smb
229
230 If the host does not respond to the alert with
231 aborted and the testunit will report an error.
232
233 For this test, the testunit will shortly drop
234 on the SMBus Alert Response Address (0x0c). It
235 address afterwards.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.