[v3,5/5] add i3cdev documentation

Commit Message

Vitor Soares Feb. 19, 2020, 12:20 a.m. UTC

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

Signed-off-by: Vitor Soares <[e-mail]>
---
 Documentation/userspace-api/i3c/i3cdev.rst | 116 +++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 Documentation/userspace-api/i3c/i3cdev.rst

Comments

Vitor Soares Feb. 19, 2020, 12:46 a.m. UTC | #1

Hi Jonathan,


From: Vitor Soares <[e-mail]>
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 <[e-mail]>
> ---
>  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

Randy Dunlap Feb. 19, 2020, 4:34 a.m. UTC | #2

On 2/18/20 4:20 PM, Vitor Soares wrote:
> This patch add documentation for the userspace API of i3cdev module.
> 
> Signed-off-by: Vitor Soares <[e-mail]>
> ---
>  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

                                          allocated (?)

> +the i3c devices. By default, the i3cdev module only exposes the i3c devices

       I3C                                                         I3C

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

IMO:                              s/folder/directory/ or sub-directory

> +<bus id>-<Provisional ID> same way they can be found in /sys/bus/i3c/devices/.

                             in the same way

> +::
> +
> +# 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

            driver. This                 by not having

> +using the Sysfs to unbind the kernel driver from the device.

         the sysfs interface to unbind

> +
> +BASIC CHARACTER DEVICE API
> +===============================
> +For now, the API has only support private SDR read and write transfers.

                        only support for private

For the unfamiliar, what is this "SDR"?  (thanks)

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

                                          it is the I3C slave

> +    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);

better indentation?

> +
> +Now the file is opened, we can perform the operations available::
> +
> +  /* Write function */
> +  uint_t8  buf[] = {0x00, 0xde, 0xad, 0xbe, 0xef}

I can't find uint_t8.  Where is it located?
and the braces should end with a ';'.

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

Please fix that warning. ^^^^^

Vitor Soares Feb. 21, 2020, 10:31 a.m. UTC | #3

Hi Randy,

From: Randy Dunlap <[e-mail]>
Date: Wed, Feb 19, 2020 at 04:34:00

> On 2/18/20 4:20 PM, Vitor Soares wrote:
> > This patch add documentation for the userspace API of i3cdev module.
> > 
> > Signed-off-by: Vitor Soares <[e-mail]>
> > ---
> >  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
> 
>                                           allocated (?)
> 
> > +the i3c devices. By default, the i3cdev module only exposes the i3c devices
> 
>        I3C                                                         I3C
> 
> > +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
> 
> IMO:                              s/folder/directory/ or sub-directory
> 
> > +<bus id>-<Provisional ID> same way they can be found in /sys/bus/i3c/devices/.
> 
>                              in the same way
> 
> > +::
> > +
> > +# 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
> 
>             driver. This                 by not having
> 
> > +using the Sysfs to unbind the kernel driver from the device.
> 
>          the sysfs interface to unbind
> 
> > +
> > +BASIC CHARACTER DEVICE API
> > +===============================
> > +For now, the API has only support private SDR read and write transfers.
> 
>                         only support for private
> 
> For the unfamiliar, what is this "SDR"?  (thanks)

SDR stands for Single Data Rate. In I3C we can also have High Data Rate 
(HDR) modes:
  - Double Data Rate (HDR-DDR);
  - Ternary Symbol Legacy (HDR-TSL)
  - Ternary Symbol for Pure Bus (no I2C devices present on the bus)

Should I use Single Data Rate instead SDR  for the first time?

> 
> > +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
> 
>                                           it is the I3C slave
> 
> > +    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);
> 
> better indentation?
> 
> > +
> > +Now the file is opened, we can perform the operations available::
> > +
> > +  /* Write function */
> > +  uint_t8  buf[] = {0x00, 0xde, 0xad, 0xbe, 0xef}
> 
> I can't find uint_t8.  Where is it located?

Typo ☹.

> and the braces should end with a ';'.
> 
> > +  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
> 
> Please fix that warning. ^^^^^
> 
> 
> -- 
> ~Randy

Thanks for your feedback. I will address them next version.


Best regards,
Vitor Soares

Randy Dunlap Feb. 21, 2020, 3:36 p.m. UTC | #4

On 2/21/20 2:31 AM, Vitor Soares wrote:
>>> +BASIC CHARACTER DEVICE API
>>> +===============================
>>> +For now, the API has only support private SDR read and write transfers.
>>                         only support for private
>>
>> For the unfamiliar, what is this "SDR"?  (thanks)
> SDR stands for Single Data Rate. In I3C we can also have High Data Rate 
> (HDR) modes:
>   - Double Data Rate (HDR-DDR);
>   - Ternary Symbol Legacy (HDR-TSL)
>   - Ternary Symbol for Pure Bus (no I2C devices present on the bus)
> 
> Should I use Single Data Rate instead SDR  for the first time?

Yes, please.

thanks.

Patch

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