Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) Linux I2C slave testunit backend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) by Wolfram Sang <wsa@sang-engineering.com> in 2020
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) This backend can be used to trigger test cases for I2C bus masters which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) require a remote device with certain capabilities (and which are usually not so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) easy to obtain). Examples include multi-master testing, and SMBus Host Notify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) testing. For some tests, the I2C slave controller must be able to switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) between master and slave mode because it needs to send data, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Note that this is a device for testing and debugging. It should not be enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) in a production build. And while there is some versioning and we try hard to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) keep backward compatibility, there is no stable ABI guaranteed!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Instantiating the device is regular. Example for bus 0, address 0x30:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) # echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) After that, you will have a write-only device listening. Reads will just return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) an 8-bit version number of the testunit. When writing, the device consists of 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 8-bit registers and all must be written to start a testcase, i.e. you must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) always write 4 bytes to the device. The registers are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) 0x00 CMD   - which test to trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 0x01 DATAL - configuration byte 1 for the test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 0x02 DATAH - configuration byte 2 for the test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 0x03 DELAY - delay in n * 10ms until test is started
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Using 'i2cset' from the i2c-tools package, the generic command looks like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) # i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) DELAY is a generic parameter which will delay the execution of the test in CMD.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) While a command is running (including the delay), new commands will not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) acknowledged. You need to wait until the old one is completed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) The commands are described in the following section. An invalid command will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) result in the transfer not being acknowledged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) 0x00 NOOP (reserved for future use)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) 0x01 READ_BYTES (also needs master mode)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)    DATAL - address to read data from (lower 7 bits, highest bit currently unused)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)    DATAH - number of bytes to read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) This is useful to test if your bus master driver is handling multi-master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) correctly. You can trigger the testunit to read bytes from another device on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the bus. If the bus master under test also wants to access the bus at the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) time, the bus will be busy. Example to read 128 bytes from device 0x50 after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 50ms of delay:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) # i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) 0x02 SMBUS_HOST_NOTIFY (also needs master mode)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)    DATAL - low byte of the status word to send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)    DATAH - high byte of the status word to send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) This test will send an SMBUS_HOST_NOTIFY message to the host. Note that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) status word is currently ignored in the Linux Kernel. Example to send a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) notification after 10ms:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) # i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i