Commit | Line | Data |
---|---|---|
a8335c64 WS |
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 2020 | |
8 | ||
9 | This backend can be used to trigger test cases for I2C bus masters which | |
10 | require a remote device with certain capabilities (and which are usually not so | |
11 | easy to obtain). Examples include multi-master testing, and SMBus Host Notify | |
12 | testing. For some tests, the I2C slave controller must be able to switch | |
13 | between master and slave mode because it needs to send data, too. | |
14 | ||
15 | Note that this is a device for testing and debugging. It should not be enabled | |
16 | in a production build. And while there is some versioning and we try hard to | |
17 | keep backward compatibility, there is no stable ABI guaranteed! | |
18 | ||
19 | Instantiating 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 | ||
35baff67 WS |
23 | After that, you will have a write-only device listening. Reads will just return |
24 | an 8-bit version number of the testunit. When writing, the device consists of 4 | |
b39ab96a WS |
25 | 8-bit registers and, except for some "partial" commands, all registers must be |
26 | written to start a testcase, i.e. you usually write 4 bytes to the device. The | |
27 | registers are: | |
a8335c64 WS |
28 | |
29 | 0x00 CMD - which test to trigger | |
30 | 0x01 DATAL - configuration byte 1 for the test | |
31 | 0x02 DATAH - configuration byte 2 for the test | |
32 | 0x03 DELAY - delay in n * 10ms until test is started | |
33 | ||
34 | Using 'i2cset' from the i2c-tools package, the generic command looks like: | |
35 | ||
36 | # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i | |
37 | ||
38 | DELAY is a generic parameter which will delay the execution of the test in CMD. | |
35baff67 WS |
39 | While a command is running (including the delay), new commands will not be |
40 | acknowledged. You need to wait until the old one is completed. | |
41 | ||
a8335c64 WS |
42 | The commands are described in the following section. An invalid command will |
43 | result in the transfer not being acknowledged. | |
44 | ||
45 | Commands | |
46 | -------- | |
47 | ||
48 | 0x00 NOOP (reserved for future use) | |
49 | ||
50 | 0x01 READ_BYTES (also needs master mode) | |
35baff67 | 51 | DATAL - address to read data from (lower 7 bits, highest bit currently unused) |
a8335c64 WS |
52 | DATAH - number of bytes to read |
53 | ||
54 | This is useful to test if your bus master driver is handling multi-master | |
55 | correctly. You can trigger the testunit to read bytes from another device on | |
56 | the bus. If the bus master under test also wants to access the bus at the same | |
57 | time, the bus will be busy. Example to read 128 bytes from device 0x50 after | |
58 | 50ms of delay: | |
59 | ||
60 | # i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i | |
61 | ||
62 | 0x02 SMBUS_HOST_NOTIFY (also needs master mode) | |
63 | DATAL - low byte of the status word to send | |
64 | DATAH - high byte of the status word to send | |
65 | ||
66 | This test will send an SMBUS_HOST_NOTIFY message to the host. Note that the | |
67 | status word is currently ignored in the Linux Kernel. Example to send a | |
68 | notification after 10ms: | |
69 | ||
70 | # i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i | |
b39ab96a WS |
71 | |
72 | 0x03 SMBUS_BLOCK_PROC_CALL (partial command) | |
73 | DATAL - must be '1', i.e. one further byte will be written | |
74 | DATAH - number of bytes to be sent back | |
75 | DELAY - not applicable, partial command! | |
76 | ||
77 | This test will respond to a block process call as defined by the SMBus | |
78 | specification. The one data byte written specifies how many bytes will be sent | |
79 | back in the following read transfer. Note that in this read transfer, the | |
80 | testunit will prefix the length of the bytes to follow. So, if your host bus | |
81 | driver emulates SMBus calls like the majority does, it needs to support the | |
82 | I2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it. The returned | |
83 | data consists of the length first, and then of an array of bytes from length-1 | |
84 | to 0. Here is an example which emulates i2c_smbus_block_process_call() using | |
85 | i2ctransfer (you need i2c-tools v4.2 or later): | |
86 | ||
87 | # i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r? | |
88 | 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 |