mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2024-12-29 09:13:38 +00:00
Documentation: i2c: testunit: use proper reST
This document is hardly readable when converted to HTML. Mark code sections as such and use tables to improve readability a lot. Some content has slightly been moved around, but no significant changes were made. Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
This commit is contained in:
Wolfram Sang
parent
f2661062f1
commit
256ed3108b
@ -16,9 +16,9 @@ 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:
|
||||
Instantiating the device is regular. Example for bus 0, address 0x30::
|
||||
|
||||
# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device
|
||||
# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device
|
||||
|
||||
After that, you will have a write-only device listening. Reads will just return
|
||||
an 8-bit version number of the testunit. When writing, the device consists of 4
|
||||
@ -26,14 +26,17 @@ an 8-bit version number of the testunit. When writing, the device consists of 4
|
||||
written to start a testcase, i.e. you usually write 4 bytes to the device. The
|
||||
registers are:
|
||||
|
||||
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
|
||||
.. csv-table::
|
||||
:header: "Offset", "Name", "Description"
|
||||
|
||||
Using 'i2cset' from the i2c-tools package, the generic command looks like:
|
||||
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
|
||||
|
||||
# i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i
|
||||
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
|
||||
@ -45,44 +48,83 @@ result in the transfer not being acknowledged.
|
||||
Commands
|
||||
--------
|
||||
|
||||
0x00 NOOP (reserved for future use)
|
||||
0x00 NOOP
|
||||
~~~~~~~~~
|
||||
|
||||
0x01 READ_BYTES (also needs master mode)
|
||||
DATAL - address to read data from (lower 7 bits, highest bit currently unused)
|
||||
DATAH - number of bytes to read
|
||||
Reserved for future use.
|
||||
|
||||
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:
|
||||
0x01 READ_BYTES
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
# i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
0x02 SMBUS_HOST_NOTIFY (also needs master mode)
|
||||
DATAL - low byte of the status word to send
|
||||
DATAH - high byte of the status word to send
|
||||
* - CMD
|
||||
- DATAL
|
||||
- DATAH
|
||||
- DELAY
|
||||
|
||||
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 after 10ms:
|
||||
* - 0x01
|
||||
- address to read data from (lower 7 bits, highest bit currently unused)
|
||||
- number of bytes to read
|
||||
- n * 10ms
|
||||
|
||||
# i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i
|
||||
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::
|
||||
|
||||
0x03 SMBUS_BLOCK_PROC_CALL (partial command)
|
||||
DATAL - must be '1', i.e. one further byte will be written
|
||||
DATAH - number of bytes to be sent back
|
||||
DELAY - not applicable, partial command!
|
||||
# i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i
|
||||
|
||||
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):
|
||||
0x02 SMBUS_HOST_NOTIFY
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
# i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r?
|
||||
0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00
|
||||
.. 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 after 10ms::
|
||||
|
||||
# i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i
|
||||
|
||||
0x03 SMBUS_BLOCK_PROC_CALL
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - CMD
|
||||
- DATAL
|
||||
- DATAH
|
||||
- DELAY
|
||||
|
||||
* - 0x03
|
||||
- must be '1', 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 0x03 0x01 0x10 r?
|
||||
0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00
|
||||
|
||||
Loading…
Reference in New Issue
Block a user