From: Vitor Soares <Vitor.Soares@synopsys.com>
To: Randy Dunlap <rdunlap@infradead.org>,
"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
"linux-i3c@lists.infradead.org" <linux-i3c@lists.infradead.org>
Cc: Jose Abreu <Jose.Abreu@synopsys.com>,
"corbet@lwn.net" <corbet@lwn.net>,
Joao Pinto <Joao.Pinto@synopsys.com>,
"arnd@arndb.de" <arnd@arndb.de>,
"wsa@the-dreams.de" <wsa@the-dreams.de>,
"gregkh@linuxfoundation.org" <gregkh@linuxfoundation.org>,
"bbrezillon@kernel.org" <bbrezillon@kernel.org>,
"broonie@kernel.org" <broonie@kernel.org>
Subject: RE: [PATCH v3 5/5] add i3cdev documentation
Date: Fri, 21 Feb 2020 10:31:35 +0000 [thread overview]
Message-ID: <CH2PR12MB42160E59DE750C4C4242E6E8AE120@CH2PR12MB4216.namprd12.prod.outlook.com> (raw)
In-Reply-To: <13770b93-d98b-81d7-0cab-92daf9151ee6@infradead.org>
Hi Randy,
From: Randy Dunlap <rdunlap@infradead.org>
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 <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
>
> 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
_______________________________________________
linux-i3c mailing list
linux-i3c@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-i3c
next prev parent reply other threads:[~2020-02-21 10:31 UTC|newest]
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 ` [PATCH v3 5/5] add i3cdev documentation Vitor Soares
2020-02-19 0:46 ` Vitor Soares
2020-02-19 4:34 ` Randy Dunlap
2020-02-21 10:31 ` Vitor Soares [this message]
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=CH2PR12MB42160E59DE750C4C4242E6E8AE120@CH2PR12MB4216.namprd12.prod.outlook.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=rdunlap@infradead.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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).