11297Salm.. SPDX-License-Identifier: GPL-2.0 21297Salm 31297Salm================================ 41297SalmLinux I2C slave testunit backend 51297Salm================================ 61297Salm 71297Salmby Wolfram Sang <wsa@sang-engineering.com> in 2020 81297Salm 91297SalmThis backend can be used to trigger test cases for I2C bus masters which 101297Salmrequire a remote device with certain capabilities (and which are usually not so 111297Salmeasy to obtain). Examples include multi-master testing, and SMBus Host Notify 121297Salmtesting. For some tests, the I2C slave controller must be able to switch 131297Salmbetween master and slave mode because it needs to send data, too. 141297Salm 151297SalmNote that this is a device for testing and debugging. It should not be enabled 161297Salmin a production build. And while there is some versioning and we try hard to 171297Salmkeep backward compatibility, there is no stable ABI guaranteed! 181297Salm 191297SalmInstantiating the device is regular. Example for bus 0, address 0x30: 201297Salm 211297Salm# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device 221297Salm 231297SalmAfter that, you will have a write-only device listening. Reads will just return 241297Salman 8-bit version number of the testunit. When writing, the device consists of 4 251297Salm8-bit registers and, except for some "partial" commands, all registers must be 261297Salmwritten to start a testcase, i.e. you usually write 4 bytes to the device. The 271297Salmregisters are: 281297Salm 291297Salm0x00 CMD - which test to trigger 3027963Ssteve0x01 DATAL - configuration byte 1 for the test 3120420Ssteve0x02 DATAH - configuration byte 2 for the test 3227963Ssteve0x03 DELAY - delay in n * 10ms until test is started 3327963Ssteve 3450471SpeterUsing 'i2cset' from the i2c-tools package, the generic command looks like: 3527963Ssteve 361297Salm# i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i 371297Salm 3867183SbrianDELAY is a generic parameter which will delay the execution of the test in CMD. 3967183SbrianWhile a command is running (including the delay), new commands will not be 401297Salmacknowledged. You need to wait until the old one is completed. 411297Salm 421297SalmThe commands are described in the following section. An invalid command will 431297Salmresult in the transfer not being acknowledged. 441297Salm 451297SalmCommands 461297Salm-------- 471297Salm 481297Salm0x00 NOOP (reserved for future use) 491297Salm 501297Salm0x01 READ_BYTES (also needs master mode) 511297Salm DATAL - address to read data from (lower 7 bits, highest bit currently unused) 521297Salm DATAH - number of bytes to read 531297Salm 541297SalmThis is useful to test if your bus master driver is handling multi-master 551297Salmcorrectly. You can trigger the testunit to read bytes from another device on 561297Salmthe bus. If the bus master under test also wants to access the bus at the same 571297Salmtime, the bus will be busy. Example to read 128 bytes from device 0x50 after 581297Salm50ms of delay: 591297Salm 601297Salm# i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i 611297Salm 621297Salm0x02 SMBUS_HOST_NOTIFY (also needs master mode) 631297Salm DATAL - low byte of the status word to send 641297Salm DATAH - high byte of the status word to send 651297Salm 661297SalmThis test will send an SMBUS_HOST_NOTIFY message to the host. Note that the 671297Salmstatus word is currently ignored in the Linux Kernel. Example to send a 681297Salmnotification after 10ms: 691297Salm 701297Salm# i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i 711297Salm 721297Salm0x03 SMBUS_BLOCK_PROC_CALL (partial command) 731297Salm DATAL - must be '1', i.e. one further byte will be written 741297Salm DATAH - number of bytes to be sent back 751297Salm DELAY - not applicable, partial command! 761297Salm 771297SalmThis test will respond to a block process call as defined by the SMBus 781297Salmspecification. The one data byte written specifies how many bytes will be sent 791297Salmback in the following read transfer. Note that in this read transfer, the 801297Salmtestunit will prefix the length of the bytes to follow. So, if your host bus 811297Salmdriver emulates SMBus calls like the majority does, it needs to support the 821297SalmI2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it. The returned 831297Salmdata consists of the length first, and then of an array of bytes from length-1 841297Salmto 0. Here is an example which emulates i2c_smbus_block_process_call() using 851297Salmi2ctransfer (you need i2c-tools v4.2 or later): 861297Salm 871297Salm# i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r? 881297Salm0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 891297Salm