Linux/Documentation/i2c/slave-testunit-backend.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0 2 2 3 ================================ 3 ================================ 4 Linux I2C slave testunit backend 4 Linux I2C slave testunit backend 5 ================================ 5 ================================ 6 6 7 by Wolfram Sang <wsa@sang-engineering.com> in 2 7 by Wolfram Sang <wsa@sang-engineering.com> in 2020 8 8 9 This backend can be used to trigger test cases 9 This backend can be used to trigger test cases for I2C bus masters which 10 require a remote device with certain capabilit 10 require a remote device with certain capabilities (and which are usually not so 11 easy to obtain). Examples include multi-master 11 easy to obtain). Examples include multi-master testing, and SMBus Host Notify 12 testing. For some tests, the I2C slave control 12 testing. For some tests, the I2C slave controller must be able to switch 13 between master and slave mode because it needs 13 between master and slave mode because it needs to send data, too. 14 14 15 Note that this is a device for testing and deb 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 16 in a production build. And while there is some versioning and we try hard to 17 keep backward compatibility, there is no stabl 17 keep backward compatibility, there is no stable ABI guaranteed! 18 18 19 Instantiating the device is regular. Example f !! 19 Instantiating the device is regular. Example for bus 0, address 0x30: 20 20 21 # echo "slave-testunit 0x1030" > /sys/bus/i2 !! 21 # echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device 22 22 23 Or using firmware nodes. Here is a devicetree !! 23 After that, you will have a write-only device listening. Reads will just return 24 debug device, so there are no official DT bind !! 24 an 8-bit version number of the testunit. When writing, the device consists of 4 >> 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: 25 28 26 &i2c0 { !! 29 0x00 CMD - which test to trigger 27 ... !! 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 28 33 29 testunit@30 { !! 34 Using 'i2cset' from the i2c-tools package, the generic command looks like: 30 compatible = "slave-testunit"; << 31 reg = <(0x30 | I2C_OWN_SLAVE_A << 32 }; << 33 }; << 34 35 35 After that, you will have the device listening !! 36 # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i 36 byte. Its value is 0 if the testunit is idle, << 37 the currently running command. << 38 << 39 When writing, the device consists of 4 8-bit r << 40 "partial" commands, all registers must be writ << 41 usually write 4 bytes to the device. The regis << 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 te << 48 0x02, DATAH, configuration byte 2 for the te << 49 0x03, DELAY, delay in n * 10ms until test is << 50 << 51 Using 'i2cset' from the i2c-tools package, the << 52 << 53 # i2cset -y <bus_num> <testunit_address> <CM << 54 37 55 DELAY is a generic parameter which will delay 38 DELAY is a generic parameter which will delay the execution of the test in CMD. 56 While a command is running (including the dela 39 While a command is running (including the delay), new commands will not be 57 acknowledged. You need to wait until the old o 40 acknowledged. You need to wait until the old one is completed. 58 41 59 The commands are described in the following se 42 The commands are described in the following section. An invalid command will 60 result in the transfer not being acknowledged. 43 result in the transfer not being acknowledged. 61 44 62 Commands 45 Commands 63 -------- 46 -------- 64 47 65 0x00 NOOP !! 48 0x00 NOOP (reserved for future use) 66 ~~~~~~~~~ << 67 << 68 Reserved for future use. << 69 << 70 0x01 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, << 83 - number of bytes to read << 84 - n * 10ms << 85 << 86 Also needs master mode. This is useful to test << 87 handling multi-master correctly. You can trigg << 88 from another device on the bus. If the bus mas << 89 access the bus at the same time, the bus will << 90 bytes from device 0x50 after 50ms of delay:: << 91 << 92 # i2cset -y 0 0x30 1 0x50 0x80 5 i << 93 << 94 0x02 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 << 110 Also needs master mode. This test will send an << 111 host. Note that the status word is currently i << 112 Example to send a notification with status wor << 113 << 114 # i2cset -y 0 0x30 2 0x42 0x64 1 i << 115 << 116 If the host controller supports HostNotify, th << 117 should appear (Linux 6.11 and later):: << 118 << 119 Detected HostNotify from address 0x30 << 120 << 121 0x03 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 writ << 134 - number of bytes to be sent back << 135 - leave out, partial command! << 136 << 137 Partial command. This test will respond to a b << 138 the SMBus specification. The one data byte wri << 139 will be sent back in the following read transf << 140 transfer, the testunit will prefix the length << 141 your host bus driver emulates SMBus calls like << 142 support the I2C_M_RECV_LEN flag of an i2c_msg. << 143 The returned data consists of the length first << 144 from length-1 to 0. Here is an example which e << 145 i2c_smbus_block_process_call() using i2ctransf << 146 later):: << 147 << 148 # i2ctransfer -y 0 w3@0x30 3 1 0x10 r? << 149 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 << 150 << 151 0x04 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 << 167 Partial command. After sending this command, t << 168 message with a NUL terminated version string b << 169 character is always a 'v' and the length of th << 170 128 bytes. However, it will only respond if th << 171 the write message via repeated start. If your << 172 repeated 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 << 176 << 177 If you have i2c-tools 4.4 or later, you can pr << 178 << 179 # i2ctransfer -y -b 0 w3@0x30 4 0 0 r128 << 180 v6.11.0-rc1-00009-gd37a1b4d3fd0 << 181 << 182 STOP/START combinations between the two messag << 183 are not equivalent to a REPEATED START. As an << 184 default response:: << 185 << 186 # i2cset -y 0 0x30 4 0 0 i; i2cget -y 0 0x30 << 187 0x00 << 188 << 189 0x05 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 I2 << 202 - currently unused << 203 - n * 10ms << 204 << 205 This test raises an interrupt via the SMBAlert << 206 must handle. The pin must be connected to the << 207 is not allowed to sleep. Currently, this can o << 208 nodes. So, for devicetree, you would add somet << 209 node:: << 210 << 211 gpios = <&gpio1 24 GPIO_ACTIVE_LOW>; << 212 << 213 The following command will trigger the alert w << 214 second of delay:: << 215 << 216 # i2cset -y 0 0x30 5 0xc9 0x00 100 i << 217 << 218 If the host controller supports SMBusAlert, th << 219 should appear:: << 220 << 221 smbus_alert 0-000c: SMBALERT# from dev 0x64, << 222 << 223 This message may appear more than once because << 224 hardware and, thus, may not be able to react t << 225 enough. The interrupt count should increase on << 226 << 227 # cat /proc/interrupts | grep smbus_alert << 228 93: 1 gpio-rcar 26 Edge smb << 229 49 230 If the host does not respond to the alert with !! 50 0x01 READ_BYTES (also needs master mode) 231 aborted and the testunit will report an error. !! 51 DATAL - address to read data from (lower 7 bits, highest bit currently unused) >> 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 >> 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): 232 86 233 For this test, the testunit will shortly drop !! 87 # i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r? 234 on the SMBus Alert Response Address (0x0c). It !! 88 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 235 address afterwards. <<

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/Documentation/i2c/slave-testunit-backend.rst

Diff markup

Differences between /Documentation/i2c/slave-testunit-backend.rst (Version linux-6.12-rc7) and /Documentation/i2c/slave-testunit-backend.rst (Version linux-6.10.14)

TOMOYO Linux Cross Reference Linux/Documentation/i2c/slave-testunit-backend.rst

Diff markup

Differences between /Documentation/i2c/slave-testunit-backend.rst (Version linux-6.12-rc7) and /Documentation/i2c/slave-testunit-backend.rst (Version linux-6.10.14)

TOMOYO Linux Cross Reference
Linux/Documentation/i2c/slave-testunit-backend.rst