Documentation/i2c/slave-testunit-backend.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ================================
   4 Linux I2C slave testunit backend
   5 ================================
   6
   7 by Wolfram Sang <[email protected]> in 2020
   8
   9 This backend can be used to trigger test cases for I2C bus masters which
  10 require a remote device with certain capabilities (and which are usually not so
  11 easy to obtain). Examples include multi-master testing, and SMBus Host Notify
  12 testing. For some tests, the I2C slave controller must be able to switch
  13 between master and slave mode because it needs to send data, too.
  14
  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 versioning and we try hard to
  17 keep backward compatibility, there is no stable ABI guaranteed!
  18
  19 Instantiating 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
  23 After that, you will have a write-only device listening. Reads will just return
  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:
  28
  29 .. csv-table::
  30   :header: "Offset", "Name", "Description"
  31
  32   0x00, CMD, which test to trigger
  33   0x01, DATAL, configuration byte 1 for the test
  34   0x02, DATAH, configuration byte 2 for the test
  35   0x03, DELAY, delay in n * 10ms until test is started
  36
  37 Using 'i2cset' from the i2c-tools package, the generic command looks like::
  38
  39   # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i
  40
  41 DELAY is a generic parameter which will delay the execution of the test in CMD.
  42 While a command is running (including the delay), new commands will not be
  43 acknowledged. You need to wait until the old one is completed.
  44
  45 The commands are described in the following section. An invalid command will
  46 result in the transfer not being acknowledged.
  47
  48 Commands
  49 --------
  50
  51 0x00 NOOP
  52 ~~~~~~~~~
  53
  54 Reserved for future use.
  55
  56 0x01 READ_BYTES
  57 ~~~~~~~~~~~~~~~
  58
  59 .. list-table::
  60   :header-rows: 1
  61
  62   * - CMD
  63     - DATAL
  64     - DATAH
  65     - DELAY
  66
  67   * - 0x01
  68     - address to read data from (lower 7 bits, highest bit currently unused)
  69     - number of bytes to read
  70     - n * 10ms
  71
  72 Also needs master mode. This is useful to test if your bus master driver is
  73 handling multi-master correctly. You can trigger the testunit to read bytes
  74 from another device on the bus. If the bus master under test also wants to
  75 access the bus at the same time, the bus will be busy. Example to read 128
  76 bytes from device 0x50 after 50ms of delay::
  77
  78   # i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i
  79
  80 0x02 SMBUS_HOST_NOTIFY
  81 ~~~~~~~~~~~~~~~~~~~~~~
  82
  83 .. list-table::
  84   :header-rows: 1
  85
  86   * - CMD
  87     - DATAL
  88     - DATAH
  89     - DELAY
  90
  91   * - 0x02
  92     - low byte of the status word to send
  93     - high byte of the status word to send
  94     - n * 10ms
  95
  96 Also needs master mode. This test will send an SMBUS_HOST_NOTIFY message to the
  97 host. Note that the status word is currently ignored in the Linux Kernel.
  98 Example to send a notification after 10ms::
  99
 100   # i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i
 101
 102 If the host controller supports HostNotify, this message with debug level
 103 should appear (Linux 6.11 and later)::
 104
 105   Detected HostNotify from address 0x30
 106
 107 0x03 SMBUS_BLOCK_PROC_CALL
 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 109
 110 .. list-table::
 111   :header-rows: 1
 112
 113   * - CMD
 114     - DATAL
 115     - DATAH
 116     - DELAY
 117
 118   * - 0x03
 119     - must be '1', i.e. one further byte will be written
 120     - number of bytes to be sent back
 121     - leave out, partial command!
 122
 123 Partial command. This test will respond to a block process call as defined by
 124 the SMBus specification. The one data byte written specifies how many bytes
 125 will be sent back in the following read transfer. Note that in this read
 126 transfer, the testunit will prefix the length of the bytes to follow. So, if
 127 your host bus driver emulates SMBus calls like the majority does, it needs to
 128 support the I2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it.
 129 The returned data consists of the length first, and then of an array of bytes
 130 from length-1 to 0. Here is an example which emulates
 131 i2c_smbus_block_process_call() using i2ctransfer (you need i2c-tools v4.2 or
 132 later)::
 133
 134   # i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r?
 135   0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00