1.. SPDX-License-Identifier: GPL-2.0
2
3================================
4Linux I2C slave testunit backend
5================================
6
7by Wolfram Sang <wsa@sang-engineering.com> in 2020
8
9This backend can be used to trigger test cases for I2C bus masters which
10require a remote device with certain capabilities (and which are usually not so
11easy to obtain). Examples include multi-master testing, and SMBus Host Notify
12testing. For some tests, the I2C slave controller must be able to switch
13between master and slave mode because it needs to send data, too.
14
15Note that this is a device for testing and debugging. It should not be enabled
16in a production build. And while there is some versioning and we try hard to
17keep backward compatibility, there is no stable ABI guaranteed!
18
19Instantiating the device is regular. Example for bus 0, address 0x30:
20
21# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device
22
23After that, you will have a write-only device listening. Reads will just return
24an 8-bit version number of the testunit. When writing, the device consists of 4
258-bit registers and all must be written to start a testcase, i.e. you must
26always write 4 bytes to the device. The registers are:
27
280x00 CMD   - which test to trigger
290x01 DATAL - configuration byte 1 for the test
300x02 DATAH - configuration byte 2 for the test
310x03 DELAY - delay in n * 10ms until test is started
32
33Using 'i2cset' from the i2c-tools package, the generic command looks like:
34
35# i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i
36
37DELAY is a generic parameter which will delay the execution of the test in CMD.
38While a command is running (including the delay), new commands will not be
39acknowledged. You need to wait until the old one is completed.
40
41The commands are described in the following section. An invalid command will
42result in the transfer not being acknowledged.
43
44Commands
45--------
46
470x00 NOOP (reserved for future use)
48
490x01 READ_BYTES (also needs master mode)
50   DATAL - address to read data from (lower 7 bits, highest bit currently unused)
51   DATAH - number of bytes to read
52
53This is useful to test if your bus master driver is handling multi-master
54correctly. You can trigger the testunit to read bytes from another device on
55the bus. If the bus master under test also wants to access the bus at the same
56time, the bus will be busy. Example to read 128 bytes from device 0x50 after
5750ms of delay:
58
59# i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i
60
610x02 SMBUS_HOST_NOTIFY (also needs master mode)
62   DATAL - low byte of the status word to send
63   DATAH - high byte of the status word to send
64
65This test will send an SMBUS_HOST_NOTIFY message to the host. Note that the
66status word is currently ignored in the Linux Kernel. Example to send a
67notification after 10ms:
68
69# i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i
70