diff options
Diffstat (limited to 'Documentation/i2c/slave-testunit-backend.rst')
| -rw-r--r-- | Documentation/i2c/slave-testunit-backend.rst | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/Documentation/i2c/slave-testunit-backend.rst b/Documentation/i2c/slave-testunit-backend.rst new file mode 100644 index 000000000000..d752f433be07 --- /dev/null +++ b/Documentation/i2c/slave-testunit-backend.rst @@ -0,0 +1,235 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +Linux I2C slave testunit backend +================================ + +by Wolfram Sang <wsa@sang-engineering.com> in 2020 + +This backend can be used to trigger test cases for I2C bus masters which +require a remote device with certain capabilities (and which are usually not so +easy to obtain). Examples include multi-master testing, and SMBus Host Notify +testing. For some tests, the I2C slave controller must be able to switch +between master and slave mode because it needs to send data, too. + +Note that this is a device for testing and debugging. It should not be enabled +in a production build. And while there is some versioning and we try hard to +keep backward compatibility, there is no stable ABI guaranteed! + +Instantiating the device is regular. Example for bus 0, address 0x30:: + + # echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device + +Or using firmware nodes. Here is a devicetree example (note this is only a +debug device, so there are no official DT bindings):: + + &i2c0 { + ... + + testunit@30 { + compatible = "slave-testunit"; + reg = <(0x30 | I2C_OWN_SLAVE_ADDRESS)>; + }; + }; + +After that, you will have the device listening. Reading will return a single +byte. Its value is 0 if the testunit is idle, otherwise the command number of +the currently running command. + +When writing, the device consists of 4 8-bit registers and, except for some +"partial" commands, all registers must be written to start a testcase, i.e. you +usually write 4 bytes to the device. The registers are: + +.. csv-table:: + :header: "Offset", "Name", "Description" + + 0x00, CMD, which test to trigger + 0x01, DATAL, configuration byte 1 for the test + 0x02, DATAH, configuration byte 2 for the test + 0x03, DELAY, delay in n * 10ms until test is started + +Using 'i2cset' from the i2c-tools package, the generic command looks like:: + + # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i + +DELAY is a generic parameter which will delay the execution of the test in CMD. +While a command is running (including the delay), new commands will not be +acknowledged. You need to wait until the old one is completed. + +The commands are described in the following section. An invalid command will +result in the transfer not being acknowledged. + +Commands +-------- + +0x00 NOOP +~~~~~~~~~ + +Reserved for future use. + +0x01 READ_BYTES +~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - CMD + - DATAL + - DATAH + - DELAY + + * - 0x01 + - address to read data from (lower 7 bits, highest bit currently unused) + - number of bytes to read + - n * 10ms + +Also needs master mode. This is useful to test if your bus master driver is +handling multi-master correctly. You can trigger the testunit to read bytes +from another device on the bus. If the bus master under test also wants to +access the bus at the same time, the bus will be busy. Example to read 128 +bytes from device 0x50 after 50ms of delay:: + + # i2cset -y 0 0x30 1 0x50 0x80 5 i + +0x02 SMBUS_HOST_NOTIFY +~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - CMD + - DATAL + - DATAH + - DELAY + + * - 0x02 + - low byte of the status word to send + - high byte of the status word to send + - n * 10ms + +Also needs master mode. This test will send an SMBUS_HOST_NOTIFY message to the +host. Note that the status word is currently ignored in the Linux Kernel. +Example to send a notification with status word 0x6442 after 10ms:: + + # i2cset -y 0 0x30 2 0x42 0x64 1 i + +If the host controller supports HostNotify, this message with debug level +should appear (Linux 6.11 and later):: + + Detected HostNotify from address 0x30 + +0x03 SMBUS_BLOCK_PROC_CALL +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - CMD + - DATAL + - DATAH + - DELAY + + * - 0x03 + - 0x01 (i.e. one further byte will be written) + - number of bytes to be sent back + - leave out, partial command! + +Partial command. This test will respond to a block process call as defined by +the SMBus specification. The one data byte written specifies how many bytes +will be sent back in the following read transfer. Note that in this read +transfer, the testunit will prefix the length of the bytes to follow. So, if +your host bus driver emulates SMBus calls like the majority does, it needs to +support the I2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it. +The returned data consists of the length first, and then of an array of bytes +from length-1 to 0. Here is an example which emulates +i2c_smbus_block_process_call() using i2ctransfer (you need i2c-tools v4.2 or +later):: + + # i2ctransfer -y 0 w3@0x30 3 1 0x10 r? + 0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 + +0x04 GET_VERSION_WITH_REP_START +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - CMD + - DATAL + - DATAH + - DELAY + + * - 0x04 + - currently unused + - currently unused + - leave out, partial command! + +Partial command. After sending this command, the testunit will reply to a read +message with a NUL terminated version string based on UTS_RELEASE. The first +character is always a 'v' and the length of the version string is at maximum +128 bytes. However, it will only respond if the read message is connected to +the write message via repeated start. If your controller driver handles +repeated start correctly, this will work:: + + # i2ctransfer -y 0 w3@0x30 4 0 0 r128 + 0x76 0x36 0x2e 0x31 0x31 0x2e 0x30 0x2d 0x72 0x63 0x31 0x2d 0x30 0x30 0x30 0x30 ... + +If you have i2c-tools 4.4 or later, you can print out the data right away:: + + # i2ctransfer -y -b 0 w3@0x30 4 0 0 r128 + v6.11.0-rc1-00009-gd37a1b4d3fd0 + +STOP/START combinations between the two messages will *not* work because they +are not equivalent to a REPEATED START. As an example, this returns just the +default response:: + + # i2cset -y 0 0x30 4 0 0 i; i2cget -y 0 0x30 + 0x00 + +0x05 SMBUS_ALERT_REQUEST +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - CMD + - DATAL + - DATAH + - DELAY + + * - 0x05 + - response value (7 MSBs interpreted as I2C address) + - currently unused + - n * 10ms + +This test raises an interrupt via the SMBAlert pin which the host controller +must handle. The pin must be connected to the testunit as a GPIO. GPIO access +is not allowed to sleep. Currently, this can only be described using firmware +nodes. So, for devicetree, you would add something like this to the testunit +node:: + + gpios = <&gpio1 24 GPIO_ACTIVE_LOW>; + +The following command will trigger the alert with a response of 0xc9 after 1 +second of delay:: + + # i2cset -y 0 0x30 5 0xc9 0x00 100 i + +If the host controller supports SMBusAlert, this message with debug level +should appear:: + + smbus_alert 0-000c: SMBALERT# from dev 0x64, flag 1 + +This message may appear more than once because the testunit is software not +hardware and, thus, may not be able to react to the response of the host fast +enough. The interrupt count should increase only by one, though:: + + # cat /proc/interrupts | grep smbus_alert + 93: 1 gpio-rcar 26 Edge smbus_alert + +If the host does not respond to the alert within 1 second, the test will be +aborted and the testunit will report an error. + +For this test, the testunit will shortly drop its assigned address and listen +on the SMBus Alert Response Address (0x0c). It will reassign its original +address afterwards. |