Linux I2C slave testunit backend

테스트 유닛의 목적, 생성과 레지스터

이 문서는 Wolfram Sang이 2020년에 작성했습니다. 이 백엔드는 특정 기능을 가진 원격 장치를 구하기 어려운 상황에서 I2C 버스 마스터의 테스트 사례를 유발하는 데 사용합니다. 다중 마스터와 SMBus Host Notify 시험이 대표적입니다.

일부 시험에서는 테스트 유닛도 데이터를 보내야 하므로 I2C 슬레이브 컨트롤러가 마스터 모드와 슬레이브 모드를 전환할 수 있어야 합니다.

이 장치는 시험과 디버깅 전용이므로 프로덕션 빌드에서 활성화하면 안 됩니다. 버전 관리가 있고 하위 호환성을 유지하려 노력하지만 안정 ABI는 보장되지 않습니다.

일반 슬레이브 장치처럼 생성할 수 있습니다. 버스 0, 주소 `0x30`의 예는 `slave-testunit 0x1030`을 `/sys/bus/i2c/devices/i2c-0/new_device`에 기록합니다.

# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device

펌웨어 노드로도 만들 수 있습니다. Device Tree 예제는 `&i2c0` 아래 `testunit@30` 노드를 두고 `compatible = "slave-testunit"`, `reg = <(0x30 | I2C_OWN_SLAVE_ADDRESS)>`를 지정합니다. 디버그 장치이므로 공식 DT 바인딩은 없습니다.

생성 뒤 장치는 버스를 수신합니다. 읽으면 한 바이트를 반환하며, 유휴 상태에서는 0이고 명령 실행 중에는 현재 명령 번호입니다.

쓰기 인터페이스는 8비트 레지스터 네 개로 구성됩니다. 일부 `partial` 명령을 제외하면 테스트를 시작하려면 네 레지스터를 모두 써야 하므로 보통 장치에 네 바이트를 씁니다.

`i2c-tools`의 `i2cset`을 사용할 때 일반 명령은 `i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i`입니다.

`DELAY`는 `CMD`의 실행을 늦추는 공통 매개변수입니다. 지연 시간을 포함해 명령이 실행 중이면 새 명령을 ACK하지 않으므로 기존 명령이 끝날 때까지 기다려야 합니다. 유효하지 않은 명령도 전송을 ACK하지 않습니다.

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

NOOP, READ_BYTES와 SMBUS_HOST_NOTIFY

명령 `0x00 NOOP`는 향후 사용을 위해 예약되어 있습니다.

`0x01 READ_BYTES`는 `DATAL`의 하위 7비트로 읽을 대상 주소를 지정하고, `DATAH`로 읽을 바이트 수를 지정하며, `DELAY`는 `n * 10ms`입니다. `DATAL`의 최상위 비트는 현재 사용하지 않습니다.

이 명령은 마스터 모드도 필요하며, 버스 마스터 드라이버가 다중 마스터 상황을 올바르게 처리하는지 시험하는 데 유용합니다. 테스트 유닛이 버스의 다른 장치에서 바이트를 읽도록 하고, 시험 대상 버스 마스터도 동시에 버스에 접근하면 bus busy 상황이 발생합니다.

50ms 뒤 주소 `0x50`에서 128바이트를 읽는 예는 `i2cset -y 0 0x30 1 0x50 0x80 5 i`입니다.

# i2cset -y 0 0x30 1 0x50 0x80 5 i

`0x02 SMBUS_HOST_NOTIFY`는 `DATAL`에 보낼 상태 워드의 하위 바이트, `DATAH`에 상위 바이트, `DELAY`에 `n * 10ms`를 지정합니다.

이 시험도 마스터 모드가 필요하며 호스트에 `SMBUS_HOST_NOTIFY` 메시지를 보냅니다. 현재 Linux 커널은 상태 워드를 무시합니다.

10ms 뒤 상태 워드 `0x6442`로 알림을 보내는 명령은 `i2cset -y 0 0x30 2 0x42 0x64 1 i`입니다.

# i2cset -y 0 0x30 2 0x42 0x64 1 i

호스트 컨트롤러가 HostNotify를 지원하면 Linux 6.11 이후 디버그 수준에서 `Detected HostNotify from address 0x30` 메시지가 나타나야 합니다.

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

SMBus 블록 프로세스 호출과 repeated start 검증

`0x03 SMBUS_BLOCK_PROC_CALL`은 partial 명령입니다. `DATAL`은 추가로 한 바이트를 쓴다는 뜻의 `0x01`, `DATAH`는 되돌려 보낼 바이트 수이며 `DELAY`는 생략합니다.

이 시험은 SMBus 규격의 block process call에 응답합니다. 쓰기 전송의 데이터 바이트 하나가 뒤따르는 읽기 전송에서 보낼 바이트 수를 지정합니다. 테스트 유닛은 읽기 응답 맨 앞에 뒤따를 데이터의 길이를 붙입니다.

대부분처럼 SMBus 호출을 에뮬레이션하는 호스트 버스 드라이버라면 `i2c_msg`의 `I2C_M_RECV_LEN` 플래그를 지원해야 합니다. 이 명령은 그 기능을 검증하는 좋은 테스트입니다.

반환 데이터는 먼저 길이, 이어서 `length - 1`부터 0까지 감소하는 바이트 배열입니다. `i2c-tools` v4.2 이상에서 `i2c_smbus_block_process_call()`을 에뮬레이션하는 예는 `i2ctransfer -y 0 w3@0x30 3 1 0x10 r?`이며, 길이 `0x10` 뒤에 `0x0f`부터 `0x00`까지 나옵니다.

# 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`도 partial 명령입니다. `DATAL`과 `DATAH`는 현재 사용하지 않고 `DELAY`는 생략합니다.

명령을 보낸 뒤 테스트 유닛은 `UTS_RELEASE` 기반의 NUL 종료 버전 문자열로 읽기 메시지에 응답합니다. 첫 문자는 항상 `v`이며 버전 문자열 길이는 최대 128바이트입니다.

단, 읽기 메시지가 repeated start로 쓰기 메시지에 연결되어야만 응답합니다. 컨트롤러 드라이버가 repeated start를 올바르게 처리하면 `i2ctransfer -y 0 w3@0x30 4 0 0 r128`로 버전 데이터가 반환됩니다.

`i2c-tools` 4.4 이상에서는 `-b` 옵션으로 데이터를 즉시 문자열로 출력할 수 있습니다. 예제 응답은 `v6.11.0-rc1-00009-gd37a1b4d3fd0`입니다.

# i2ctransfer -y -b 0 w3@0x30 4 0 0 r128
v6.11.0-rc1-00009-gd37a1b4d3fd0

두 메시지 사이의 STOP/START 조합은 REPEATED START와 같지 않으므로 동작하지 않습니다. `i2cset`을 끝낸 뒤 별도 `i2cget`을 실행하면 기본 응답 `0x00`만 반환합니다.

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

SMBus Alert Request 시험

`0x05 SMBUS_ALERT_REQUEST`는 SMBAlert 핀으로 인터럽트를 발생시켜 호스트 컨트롤러의 처리를 시험합니다. `DATAL`은 응답 값이며 상위 7비트를 I2C 주소로 해석하고, `DATAH`는 현재 사용하지 않으며, `DELAY`는 `n * 10ms`입니다.

SMBAlert 핀은 GPIO로 테스트 유닛에 연결해야 하며 GPIO 접근은 sleep할 수 없어야 합니다. 현재 이 배선은 펌웨어 노드로만 설명할 수 있습니다. Device Tree에서는 테스트 유닛 노드에 `gpios = <&gpio1 24 GPIO_ACTIVE_LOW>;`와 같은 속성을 추가합니다.

gpios = <&gpio1 24 GPIO_ACTIVE_LOW>;

1초 뒤 응답 `0xc9`로 alert를 발생시키는 명령은 `i2cset -y 0 0x30 5 0xc9 0x00 100 i`입니다.

# i2cset -y 0 0x30 5 0xc9 0x00 100 i

호스트 컨트롤러가 SMBusAlert를 지원하면 디버그 수준에서 `smbus_alert 0-000c: SMBALERT# from dev 0x64, flag 1` 메시지가 나타나야 합니다. `0xc9`의 상위 7비트는 주소 `0x64`, 최하위 비트는 flag 1로 해석됩니다.

테스트 유닛은 하드웨어가 아닌 소프트웨어이므로 호스트 응답에 충분히 빨리 반응하지 못해 로그가 여러 번 나타날 수 있습니다. 그래도 `/proc/interrupts`의 인터럽트 횟수는 하나만 증가해야 합니다.

호스트가 1초 안에 alert에 응답하지 않으면 시험을 중단하고 테스트 유닛이 오류를 보고합니다.

이 시험 동안 테스트 유닛은 잠시 원래 할당 주소를 내려놓고 SMBus Alert Response Address `0x0c`에서 수신합니다. 시험이 끝나면 원래 주소를 다시 할당합니다.

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.