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, except for some "partial" commands, all registers must be 26written to start a testcase, i.e. you usually write 4 bytes to the device. The 27registers are: 28 29.. csv-table:: 30 :header: "Offset", "Name", "Description" 31 32 0x00, CMD, which test to trigger 33 0x01, DATAL, configuration byte 1 for the test 34 0x02, DATAH, configuration byte 2 for the test 35 0x03, DELAY, delay in n * 10ms until test is started 36 37Using 'i2cset' from the i2c-tools package, the generic command looks like:: 38 39 # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i 40 41DELAY is a generic parameter which will delay the execution of the test in CMD. 42While a command is running (including the delay), new commands will not be 43acknowledged. You need to wait until the old one is completed. 44 45The commands are described in the following section. An invalid command will 46result in the transfer not being acknowledged. 47 48Commands 49-------- 50 510x00 NOOP 52~~~~~~~~~ 53 54Reserved for future use. 55 560x01 READ_BYTES 57~~~~~~~~~~~~~~~ 58 59.. list-table:: 60 :header-rows: 1 61 62 * - CMD 63 - DATAL 64 - DATAH 65 - DELAY 66 67 * - 0x01 68 - address to read data from (lower 7 bits, highest bit currently unused) 69 - number of bytes to read 70 - n * 10ms 71 72Also needs master mode. This is useful to test if your bus master driver is 73handling multi-master correctly. You can trigger the testunit to read bytes 74from another device on the bus. If the bus master under test also wants to 75access the bus at the same time, the bus will be busy. Example to read 128 76bytes from device 0x50 after 50ms of delay:: 77 78 # i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i 79 800x02 SMBUS_HOST_NOTIFY 81~~~~~~~~~~~~~~~~~~~~~~ 82 83.. list-table:: 84 :header-rows: 1 85 86 * - CMD 87 - DATAL 88 - DATAH 89 - DELAY 90 91 * - 0x02 92 - low byte of the status word to send 93 - high byte of the status word to send 94 - n * 10ms 95 96Also needs master mode. This test will send an SMBUS_HOST_NOTIFY message to the 97host. Note that the status word is currently ignored in the Linux Kernel. 98Example to send a notification after 10ms:: 99 100 # i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i 101 102If the host controller supports HostNotify, this message with debug level 103should appear (Linux 6.11 and later):: 104 105 Detected HostNotify from address 0x30 106 1070x03 SMBUS_BLOCK_PROC_CALL 108~~~~~~~~~~~~~~~~~~~~~~~~~~ 109 110.. list-table:: 111 :header-rows: 1 112 113 * - CMD 114 - DATAL 115 - DATAH 116 - DELAY 117 118 * - 0x03 119 - must be '1', i.e. one further byte will be written 120 - number of bytes to be sent back 121 - leave out, partial command! 122 123Partial command. This test will respond to a block process call as defined by 124the SMBus specification. The one data byte written specifies how many bytes 125will be sent back in the following read transfer. Note that in this read 126transfer, the testunit will prefix the length of the bytes to follow. So, if 127your host bus driver emulates SMBus calls like the majority does, it needs to 128support the I2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it. 129The returned data consists of the length first, and then of an array of bytes 130from length-1 to 0. Here is an example which emulates 131i2c_smbus_block_process_call() using i2ctransfer (you need i2c-tools v4.2 or 132later):: 133 134 # i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r? 135 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 136