1I2C Target API test
2##################
3
4.. note:
5   See :ref:`coding_guideline_inclusive_language` for information about
6   plans to change the terminology used in this API.
7
8This test verifies I2C target driver implementations using two I2C
9controllers on a common bus.  The test is supported by a test-specific
10driver that simulates an EEPROM with an I2C bus target interface.  Data
11is pre-loaded into the simulated devices outside the I2C API, and the
12Zephyr application issues commands to one controller that are responded
13to by the simulated EEPROM connected through the other controller.
14
15This test was originally designed for I2C controllers that support both
16controller and target behavior simultaneously.  This is not true of all
17I2C controllers, so this behavior is now opt-in using
18CONFIG_APP_DUAL_ROLE_I2C.  However, the devicetree still must provide a
19second EEPROM just to identify the bus.
20
21In slightly more detail the test has these phases:
22
23* Use API specific to the simulated EEPROM to pre-populate the simulated
24  devices with device-specific content.
25* Register a simulated EEPROM as a I2C target device on a bus.  If
26  CONFIG_APP_DUAL_ROLE_I2C is selected, register both.
27
28* Issue commands on one bus controller (operating as the bus controller) and
29  verify that the data supplied by the other controller (target) match
30  the expected values given the content known to be present on the
31  simulated device.  If CONFIG_APP_DUAL_ROLE_I2C is selected, do this
32  with the roles reversed.
33
34Transfer of commands from one bus controller to the other is
35accomplished by hardware through having the SCL (and SDA) signals
36shorted to join the two buses.
37
38Presence of this required hardware configuration is identified by the
39`i2c_bus_short` fixture.  If the buses are not connected as required,
40or the controller driver has bugs, the test will fail one or more I2C
41transactions.
42