diff options
Diffstat (limited to 'Documentation/i2c/slave-mqueue-backend.rst')
| -rw-r--r-- | Documentation/i2c/slave-mqueue-backend.rst | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/Documentation/i2c/slave-mqueue-backend.rst b/Documentation/i2c/slave-mqueue-backend.rst new file mode 100644 index 000000000000..2d0d06d8df9d --- /dev/null +++ b/Documentation/i2c/slave-mqueue-backend.rst @@ -0,0 +1,124 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Linux I2C slave message queue backend +===================================== + +:Author: Haiyue Wang <haiyue.wang@linux.intel.com> + +Some protocols over I2C/SMBus are designed for bi-directional transferring +messages by using I2C Master Write protocol. This requires that both sides +of the communication have slave addresses. + +Like MCTP (Management Component Transport Protocol) and IPMB (Intelligent +Platform Management Bus), they both require that the userspace can receive +messages from i2c dirvers under slave mode. + +This I2C slave mqueue (message queue) backend is used to receive and queue +messages from the remote i2c intelligent device; and it will add the target +slave address (with R/W# bit is always 0) into the message at the first byte, +so that userspace can use this byte to dispatch the messages into different +handling modules. Also, like IPMB, the address byte is in its message format, +it needs it to do checksum. + +For messages are time related, so this backend will flush the oldest message +to queue the newest one. + +Link +---- +`Intelligent Platform Management Bus +Communications Protocol Specification +<https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmp-spec-v1.0.pdf>`_ + +`Management Component Transport Protocol (MCTP) +SMBus/I2C Transport Binding Specification +<https://www.dmtf.org/sites/default/files/standards/documents/DSP0237_1.1.0.pdf>`_ + +How to use +---------- +For example, the I2C5 bus has slave address 0x10, the below command will create +the related message queue interface: + + echo slave-mqueue 0x1010 > /sys/bus/i2c/devices/i2c-5/new_device + +Then you can dump the messages like this: + + hexdump -C /sys/bus/i2c/devices/5-1010/slave-mqueue + +Code Example +------------ +*Note: call 'lseek' before 'read', this is a requirement from kernfs' design.* + +:: + + #include <sys/types.h> + #include <sys/stat.h> + #include <unistd.h> + #include <poll.h> + #include <time.h> + #include <fcntl.h> + #include <stdio.h> + + int main(int argc, char *argv[]) + { + int i, r; + struct pollfd pfd; + struct timespec ts; + unsigned char data[256]; + + pfd.fd = open(argv[1], O_RDONLY | O_NONBLOCK); + if (pfd.fd < 0) + return -1; + + pfd.events = POLLPRI; + + while (1) { + r = poll(&pfd, 1, 5000); + + if (r < 0) + break; + + if (r == 0 || !(pfd.revents & POLLPRI)) + continue; + + lseek(pfd.fd, 0, SEEK_SET); + r = read(pfd.fd, data, sizeof(data)); + if (r <= 0) + continue; + + clock_gettime(CLOCK_MONOTONIC, &ts); + printf("[%ld.%.9ld] :", ts.tv_sec, ts.tv_nsec); + for (i = 0; i < r; i++) + printf(" %02x", data[i]); + printf("\n"); + } + + close(pfd.fd); + + return 0; + } + +Result +------ +*./a.out "/sys/bus/i2c/devices/5-1010/slave-mqueue"* + +:: + + [10183.232500449] : 20 18 c8 2c 78 01 5b + [10183.479358348] : 20 18 c8 2c 78 01 5b + [10183.726556812] : 20 18 c8 2c 78 01 5b + [10183.972605863] : 20 18 c8 2c 78 01 5b + [10184.220124772] : 20 18 c8 2c 78 01 5b + [10184.467764166] : 20 18 c8 2c 78 01 5b + [10193.233421784] : 20 18 c8 2c 7c 01 57 + [10193.480273460] : 20 18 c8 2c 7c 01 57 + [10193.726788733] : 20 18 c8 2c 7c 01 57 + [10193.972781945] : 20 18 c8 2c 7c 01 57 + [10194.220487360] : 20 18 c8 2c 7c 01 57 + [10194.468089259] : 20 18 c8 2c 7c 01 57 + [10203.233433099] : 20 18 c8 2c 80 01 53 + [10203.481058715] : 20 18 c8 2c 80 01 53 + [10203.727610472] : 20 18 c8 2c 80 01 53 + [10203.974044856] : 20 18 c8 2c 80 01 53 + [10204.220734634] : 20 18 c8 2c 80 01 53 + [10204.468461664] : 20 18 c8 2c 80 01 53 |