RE: [PATCH v3 5/5] add i3cdev documentation

From: Vitor Soares
Date: Tue Feb 18 2020 - 19:46:43 EST


Hi Jonathan,


From: Vitor Soares <vitor.soares@xxxxxxxxxxxx>
Date: Wed, Feb 19, 2020 at 00:20:43

> This patch add documentation for the userspace API of i3cdev module.
>

I just realize now that I missed the commit message, it should be:
userspace-api: i3c: add i3cdev documentation

I will do next time.

> Signed-off-by: Vitor Soares <vitor.soares@xxxxxxxxxxxx>
> ---
> Documentation/userspace-api/i3c/i3cdev.rst | 116 +++++++++++++++++++++++++++++
> 1 file changed, 116 insertions(+)
> create mode 100644 Documentation/userspace-api/i3c/i3cdev.rst
>
> diff --git a/Documentation/userspace-api/i3c/i3cdev.rst b/Documentation/userspace-api/i3c/i3cdev.rst
> new file mode 100644
> index 0000000..ada269f
> --- /dev/null
> +++ b/Documentation/userspace-api/i3c/i3cdev.rst
> @@ -0,0 +1,116 @@
> +====================
> +I3C Device Interface
> +====================
> +
> +I3C devices have the flexibility of being accessed from userspace, as well
> +through the conventional use of kernel drivers. Userspace access, although
> +limited to private SDR I3C transfers, provides the advantage of simplifying
> +the implementation of straightforward communication protocols, applicable to
> +scenarios where transfers are dedicated such for sensor bring-up scenarios
> +(prototyping environments) or for microcontroller slave communication
> +implementation.
> +
> +The major device number is dynamically attributed and it's all reserved for
> +the i3c devices. By default, the i3cdev module only exposes the i3c devices
> +without device driver bind and aren't of master type in sort of character
> +device file under /dev/bus/i3c/ folder. They are identified through its
> +<bus id>-<Provisional ID> same way they can be found in /sys/bus/i3c/devices/.
> +::
> +
> +# ls -l /dev/bus/i3c/
> +total 0
> +crw------- 1 root root 248, 0 Jan 1 00:22 0-6072303904d2
> +crw------- 1 root root 248, 1 Jan 1 00:22 0-b7405ba00929
> +
> +The simplest way to use this interface is to not have an I3C device bound to
> +a kernel driver, this can be achieved by not have the kernel driver loaded or
> +using the Sysfs to unbind the kernel driver from the device.
> +
> +BASIC CHARACTER DEVICE API
> +===============================
> +For now, the API has only support private SDR read and write transfers.
> +Those transaction can be achieved by the following:
> +
> +``read(file, buffer, sizeof(buffer))``
> + The standard read() operation will work as a simple transaction of private
> + SDR read data followed a stop.
> + Return the number of bytes read on success, and a negative error otherwise.
> +
> +``write(file, buffer, sizeof(buffer))``
> + The standard write() operation will work as a simple transaction of private
> + SDR write data followed a stop.
> + Return the number of bytes written on success, and a negative error otherwise.
> +
> +``ioctl(file, I3C_IOC_PRIV_XFER(nxfers), struct i3c_ioc_priv_xfer *xfers)``
> + It combines read/write transactions without a stop in between.
> + Return 0 on success, and a negative error otherwise.
> +
> +NOTES:
> + - According to the MIPI I3C Protocol is the I3C slave that terminates the read
> + transaction otherwise Master can abort early on ninth (T) data bit of each
> + SDR data word.
> +
> + - Normal open() and close() operations on /dev/bus/i3c/<bus>-<provisional id>
> + files work as you would expect.
> +
> + - As documented in cdev_del() if a device was already open during
> + i3cdev_detach, the read(), write() and ioctl() fops will still be callable
> + yet they will return -EACCES.
> +
> +C EXAMPLE
> +=========
> +Working with I3C devices is much like working with files. You will need to open
> +a file descriptor, do some I/O operations with it, and then close it.
> +
> +The following header files should be included in an I3C program::
> +
> +#include <fcntl.h>
> +#include <unistd.h>
> +#include <sys/ioctl.h>
> +#include <linux/types.h>
> +#include <linux/i3c/i3cdev.h>
> +
> +To work with an I3C device, the application must open the driver, made
> +available at the device node::
> +
> + int file;
> +
> + file = open("/dev/bus/i3c/0-6072303904d2", O_RDWR);
> + if (file < 0)
> + exit(1);
> +
> +Now the file is opened, we can perform the operations available::
> +
> + /* Write function */
> + uint_t8 buf[] = {0x00, 0xde, 0xad, 0xbe, 0xef}
> + if (write(file, buf, 5) != 5) {
> + /* ERROR HANDLING: I3C transaction failed */
> + }
> +
> + /* Read function */
> + ret = read(file, buf, 5);
> + If (ret < 0) {
> + /* ERROR HANDLING: I3C transaction failed */
> + } else {
> + /* Iterate over buf[] to get the read data */
> + }
> +
> + /* IOCTL function */
> + struct i3c_ioc_priv_xfer xfers[2];
> +
> + uint8_t tx_buf[] = {0x00, 0xde, 0xad, 0xbe, 0xef};
> + uint8_t rx_buf[10];
> +
> + xfers[0].data = (uintptr_t)tx_buf;
> + xfers[0].len = 5;
> + xfers[0].rnw = 0;
> + xfers[1].data = (uintptr_t)rx_buf;
> + xfers[1].len = 10;
> + xfers[1].rnw = 1;
> +
> + if (ioctl(file, I3C_IOC_PRIV_XFER(2), xfers) < 0)
> + /* ERROR HANDLING: I3C transaction failed */
> +
> +The device can be closed when the open file descriptor is no longer required::
> +
> + close(file);
> \ No newline at end of file
> --
> 2.7.4

Best regards,
Vitor Soares