Linux-i3c Archive on lore.kernel.org
 help / color / Atom feed
From: Vitor Soares <Vitor.Soares@synopsys.com>
To: linux-kernel@vger.kernel.org, linux-i3c@lists.infradead.org
Cc: Jose.Abreu@synopsys.com, corbet@lwn.net, Joao.Pinto@synopsys.com,
	arnd@arndb.de, wsa@the-dreams.de, gregkh@linuxfoundation.org,
	bbrezillon@kernel.org, Vitor Soares <Vitor.Soares@synopsys.com>,
	broonie@kernel.org
Subject: [PATCH v3 5/5] add i3cdev documentation
Date: Wed, 19 Feb 2020 01:20:43 +0100
Message-ID: <a6f65d23947070f52c43fee4a1427745ea675ae0.1582069402.git.vitor.soares@synopsys.com> (raw)
In-Reply-To: <cover.1582069402.git.vitor.soares@synopsys.com>
In-Reply-To: <cover.1582069402.git.vitor.soares@synopsys.com>

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

Signed-off-by: Vitor Soares <vitor.soares@synopsys.com>
---
 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


_______________________________________________
linux-i3c mailing list
linux-i3c@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-i3c

  parent reply index

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-19  0:20 [PATCH v3 0/5] Introduce i3c device userspace interface Vitor Soares
2020-02-19  0:20 ` [PATCH v3 1/5] i3c: master: export i3c_masterdev_type Vitor Soares
2020-02-19  0:20 ` [PATCH v3 2/5] i3c: master: export i3c_bus_type symbol Vitor Soares
2020-02-19  0:20 ` [PATCH v3 3/5] i3c: master: add i3c_for_each_dev helper Vitor Soares
2020-02-19  7:35   ` Greg KH
2020-02-21 11:47     ` Vitor Soares
2020-02-21 11:52       ` Greg KH
2020-02-21 12:59         ` Boris Brezillon
2020-02-21 16:44           ` Boris Brezillon
2020-02-21 16:45             ` Boris Brezillon
2020-02-21 17:19             ` Vitor Soares
2020-02-22  8:38             ` Boris Brezillon
2020-02-19  0:20 ` [PATCH v3 4/5] i3c: add i3cdev module to expose i3c dev in /dev Vitor Soares
2020-02-19  7:37   ` Greg KH
2020-02-19  8:45     ` Vitor Soares
2020-02-19  7:39   ` Greg KH
2020-02-21 11:50     ` Vitor Soares
2020-02-19  8:42   ` Greg KH
2020-02-21 22:32   ` Boris Brezillon
2020-02-24 11:04     ` Vitor Soares
2020-02-24 11:22       ` Boris Brezillon
2020-02-19  0:20 ` Vitor Soares [this message]
2020-02-19  0:46   ` [PATCH v3 5/5] add i3cdev documentation Vitor Soares
2020-02-19  4:34   ` Randy Dunlap
2020-02-21 10:31     ` Vitor Soares
2020-02-21 15:36       ` Randy Dunlap
2020-02-19  0:39 ` [PATCH v3 0/5] Introduce i3c device userspace interface Vitor Soares
2020-02-19  8:16   ` Boris Brezillon
2020-02-21 17:08     ` Vitor Soares
2020-02-21 17:41       ` Boris Brezillon
2020-02-24 10:53         ` Vitor Soares
2020-02-24 11:24           ` Boris Brezillon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=a6f65d23947070f52c43fee4a1427745ea675ae0.1582069402.git.vitor.soares@synopsys.com \
    --to=vitor.soares@synopsys.com \
    --cc=Joao.Pinto@synopsys.com \
    --cc=Jose.Abreu@synopsys.com \
    --cc=arnd@arndb.de \
    --cc=bbrezillon@kernel.org \
    --cc=broonie@kernel.org \
    --cc=corbet@lwn.net \
    --cc=gregkh@linuxfoundation.org \
    --cc=linux-i3c@lists.infradead.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=wsa@the-dreams.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-i3c Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-i3c/0 linux-i3c/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-i3c linux-i3c/ https://lore.kernel.org/linux-i3c \
		linux-i3c@lists.infradead.org
	public-inbox-index linux-i3c

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.infradead.lists.linux-i3c


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git