diff options
Diffstat (limited to 'Documentation/i2c/slave-testunit-backend.rst')
| -rw-r--r-- | Documentation/i2c/slave-testunit-backend.rst | 237 |
1 files changed, 192 insertions, 45 deletions
diff --git a/Documentation/i2c/slave-testunit-backend.rst b/Documentation/i2c/slave-testunit-backend.rst index ecfc2abec32d..d752f433be07 100644 --- a/Documentation/i2c/slave-testunit-backend.rst +++ b/Documentation/i2c/slave-testunit-backend.rst @@ -16,24 +16,41 @@ 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: +Instantiating the device is regular. Example for bus 0, address 0x30:: -# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device + # echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device -After that, you will have a write-only device listening. Reads will just return -an 8-bit version number of the testunit. 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: +Or using firmware nodes. Here is a devicetree example (note this is only a +debug device, so there are no official DT bindings):: -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 + &i2c0 { + ... -Using 'i2cset' from the i2c-tools package, the generic command looks like: + testunit@30 { + compatible = "slave-testunit"; + reg = <(0x30 | I2C_OWN_SLAVE_ADDRESS)>; + }; + }; -# i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i +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 @@ -45,44 +62,174 @@ result in the transfer not being acknowledged. Commands -------- -0x00 NOOP (reserved for future use) +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:: -0x01 READ_BYTES (also needs master mode) - DATAL - address to read data from (lower 7 bits, highest bit currently unused) - DATAH - number of bytes to read + gpios = <&gpio1 24 GPIO_ACTIVE_LOW>; -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: +The following command will trigger the alert with a response of 0xc9 after 1 +second of delay:: -# i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i + # i2cset -y 0 0x30 5 0xc9 0x00 100 i -0x02 SMBUS_HOST_NOTIFY (also needs master mode) - DATAL - low byte of the status word to send - DATAH - high byte of the status word to send +If the host controller supports SMBusAlert, this message with debug level +should appear:: -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 after 10ms: + smbus_alert 0-000c: SMBALERT# from dev 0x64, flag 1 -# i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i +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:: -0x03 SMBUS_BLOCK_PROC_CALL (partial command) - DATAL - must be '1', i.e. one further byte will be written - DATAH - number of bytes to be sent back - DELAY - not applicable, partial command! + # cat /proc/interrupts | grep smbus_alert + 93: 1 gpio-rcar 26 Edge smbus_alert -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): +If the host does not respond to the alert within 1 second, the test will be +aborted and the testunit will report an error. -# i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r? -0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 +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. |