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 23Or using firmware nodes. Here is a devicetree example (note this is only a 24debug device, so there are no official DT bindings):: 25 26 &i2c0 { 27 ... 28 29 testunit@30 { 30 compatible = "slave-testunit"; 31 reg = <(0x30 | I2C_OWN_SLAVE_ADDRESS)>; 32 }; 33 }; 34 35After that, you will have the device listening. Reading will return a single 36byte. Its value is 0 if the testunit is idle, otherwise the command number of 37the currently running command. 38 39When writing, the device consists of 4 8-bit registers and, except for some 40"partial" commands, all registers must be written to start a testcase, i.e. you 41usually write 4 bytes to the device. The registers are: 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 test 48 0x02, DATAH, configuration byte 2 for the test 49 0x03, DELAY, delay in n * 10ms until test is started 50 51Using 'i2cset' from the i2c-tools package, the generic command looks like:: 52 53 # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i 54 55DELAY is a generic parameter which will delay the execution of the test in CMD. 56While a command is running (including the delay), new commands will not be 57acknowledged. You need to wait until the old one is completed. 58 59The commands are described in the following section. An invalid command will 60result in the transfer not being acknowledged. 61 62Commands 63-------- 64 650x00 NOOP 66~~~~~~~~~ 67 68Reserved for future use. 69 700x01 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, highest bit currently unused) 83 - number of bytes to read 84 - n * 10ms 85 86Also needs master mode. This is useful to test if your bus master driver is 87handling multi-master correctly. You can trigger the testunit to read bytes 88from another device on the bus. If the bus master under test also wants to 89access the bus at the same time, the bus will be busy. Example to read 128 90bytes from device 0x50 after 50ms of delay:: 91 92 # i2cset -y 0 0x30 1 0x50 0x80 5 i 93 940x02 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 110Also needs master mode. This test will send an SMBUS_HOST_NOTIFY message to the 111host. Note that the status word is currently ignored in the Linux Kernel. 112Example to send a notification with status word 0x6442 after 10ms:: 113 114 # i2cset -y 0 0x30 2 0x42 0x64 1 i 115 116If the host controller supports HostNotify, this message with debug level 117should appear (Linux 6.11 and later):: 118 119 Detected HostNotify from address 0x30 120 1210x03 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 written) 134 - number of bytes to be sent back 135 - leave out, partial command! 136 137Partial command. This test will respond to a block process call as defined by 138the SMBus specification. The one data byte written specifies how many bytes 139will be sent back in the following read transfer. Note that in this read 140transfer, the testunit will prefix the length of the bytes to follow. So, if 141your host bus driver emulates SMBus calls like the majority does, it needs to 142support the I2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it. 143The returned data consists of the length first, and then of an array of bytes 144from length-1 to 0. Here is an example which emulates 145i2c_smbus_block_process_call() using i2ctransfer (you need i2c-tools v4.2 or 146later):: 147 148 # i2ctransfer -y 0 w3@0x30 3 1 0x10 r? 149 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 150 1510x04 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 167Partial command. After sending this command, the testunit will reply to a read 168message with a NUL terminated version string based on UTS_RELEASE. The first 169character is always a 'v' and the length of the version string is at maximum 170128 bytes. However, it will only respond if the read message is connected to 171the write message via repeated start. If your controller driver handles 172repeated 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 0x63 0x31 0x2d 0x30 0x30 0x30 0x30 ... 176 177If you have i2c-tools 4.4 or later, you can print out the data right away:: 178 179 # i2ctransfer -y -b 0 w3@0x30 4 0 0 r128 180 v6.11.0-rc1-00009-gd37a1b4d3fd0 181 182STOP/START combinations between the two messages will *not* work because they 183are not equivalent to a REPEATED START. As an example, this returns just the 184default response:: 185 186 # i2cset -y 0 0x30 4 0 0 i; i2cget -y 0 0x30 187 0x00 188 1890x05 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 I2C address) 202 - currently unused 203 - n * 10ms 204 205This test raises an interrupt via the SMBAlert pin which the host controller 206must handle. The pin must be connected to the testunit as a GPIO. GPIO access 207is not allowed to sleep. Currently, this can only be described using firmware 208nodes. So, for devicetree, you would add something like this to the testunit 209node:: 210 211 gpios = <&gpio1 24 GPIO_ACTIVE_LOW>; 212 213The following command will trigger the alert with a response of 0xc9 after 1 214second of delay:: 215 216 # i2cset -y 0 0x30 5 0xc9 0x00 100 i 217 218If the host controller supports SMBusAlert, this message with debug level 219should appear:: 220 221 smbus_alert 0-000c: SMBALERT# from dev 0x64, flag 1 222 223This message may appear more than once because the testunit is software not 224hardware and, thus, may not be able to react to the response of the host fast 225enough. The interrupt count should increase only by one, though:: 226 227 # cat /proc/interrupts | grep smbus_alert 228 93: 1 gpio-rcar 26 Edge smbus_alert 229 230If the host does not respond to the alert within 1 second, the test will be 231aborted and the testunit will report an error. 232 233For this test, the testunit will shortly drop its assigned address and listen 234on the SMBus Alert Response Address (0x0c). It will reassign its original 235address afterwards. 236