Messages in this thread Patch in this message | | | From | Vitor Soares <> | Subject | RE: [PATCH v3 5/5] add i3cdev documentation | Date | Fri, 21 Feb 2020 10:31:35 +0000 |
| |
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
| |