Documentation/i2c/slave-testunit-backend.rst

Source file repositories/reference/linux-study-clean/Documentation/i2c/slave-testunit-backend.rst

File Facts

System
Linux kernel
Corpus path
Documentation/i2c/slave-testunit-backend.rst
Extension
.rst
Size
7438 bytes
Lines
236
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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

Annotation

Implementation Notes