Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   Vitor Soares <Vitor.Soares@synopsys.com>
To:     "corbet@lwn.net" <corbet@lwn.net>
CC:     Joao Pinto <Joao.Pinto@synopsys.com>,
        Jose Abreu <Jose.Abreu@synopsys.com>,
        "bbrezillon@kernel.org" <bbrezillon@kernel.org>,
        "gregkh@linuxfoundation.org" <gregkh@linuxfoundation.org>,
        "wsa@the-dreams.de" <wsa@the-dreams.de>,
        "arnd@arndb.de" <arnd@arndb.de>,
        "broonie@kernel.org" <broonie@kernel.org>,
        Vitor Soares <Vitor.Soares@synopsys.com>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        "linux-i3c@lists.infradead.org" <linux-i3c@lists.infradead.org>
Subject: RE: [PATCH v3 5/5] add i3cdev documentation
Thread-Topic: [PATCH v3 5/5] add i3cdev documentation
Thread-Index: AQHV5rqGOSLM4YN16UyYKJplE7dG56ghrNgQ
Date:   Wed, 19 Feb 2020 00:46:37 +0000
Message-ID: <CH2PR12MB4216C24416E37DE80F0A5A8CAE100@CH2PR12MB4216.namprd12.prod.outlook.com>
References: <cover.1582069402.git.vitor.soares@synopsys.com>
 <a6f65d23947070f52c43fee4a1427745ea675ae0.1582069402.git.vitor.soares@synopsys.com>
In-Reply-To: <a6f65d23947070f52c43fee4a1427745ea675ae0.1582069402.git.vitor.soares@synopsys.com>
Accept-Language: en-US
Content-Language: en-US
received-spf: None (protection.outlook.com: synopsys.com does not designate
 permitted sender hosts)
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-Network-Message-Id: 466dd169-1731-4d74-d846-08d7b4d52d5a
X-MS-Exchange-CrossTenant-originalarrivaltime: 19 Feb 2020 00:46:37.6613
 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: c33c9f88-1eb7-4099-9700-16013fd9e8aa
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: GZyU3Ph0VGLKtVS49TD+m2wzw+WPSbj0s/sX/ZhwJ7c/G1QEwGM/b+SOtw3NjK6JOUTZtX4buGWe+eQQJqSrpg==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CH2PR12MB4295
X-OriginatorOrg: synopsys.com
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Hi Jonathan,


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

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

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@synopsys.com>
> ---
>  Documentation/userspace-api/i3c/i3cdev.rst | 116 +++++++++++++++++++++++=
++++++
>  1 file changed, 116 insertions(+)
>  create mode 100644 Documentation/userspace-api/i3c/i3cdev.rst
>=20
> diff --git a/Documentation/userspace-api/i3c/i3cdev.rst b/Documentation/u=
serspace-api/i3c/i3cdev.rst
> new file mode 100644
> index 0000000..ada269f
> --- /dev/null
> +++ b/Documentation/userspace-api/i3c/i3cdev.rst
> @@ -0,0 +1,116 @@
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +I3C Device Interface
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +I3C devices have the flexibility of being accessed from userspace, as we=
ll
> +through the conventional use of kernel drivers. Userspace access, althou=
gh
> +limited to private SDR I3C transfers, provides the advantage of simplify=
ing
> +the implementation of straightforward communication protocols, applicabl=
e to
> +scenarios where transfers are dedicated such for sensor bring-up scenari=
os
> +(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 devi=
ces
> +without device driver bind and aren't of master type in sort of characte=
r
> +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/dev=
ices/.
> +::
> +
> +# 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 boun=
d to
> +a kernel driver, this can be achieved by not have the kernel driver load=
ed or
> +using the Sysfs to unbind the kernel driver from the device.
> +
> +BASIC CHARACTER DEVICE API
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D
> +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 pri=
vate
> +  SDR read data followed a stop.
> +  Return the number of bytes read on success, and a negative error other=
wise.
> +
> +``write(file, buffer, sizeof(buffer))``
> +  The standard write() operation will work as a simple transaction of pr=
ivate
> +  SDR write data followed a stop.
> +  Return the number of bytes written on success, and a negative error ot=
herwise.
> +
> +``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 o=
f each
> +    SDR data word.
> +
> +  - Normal open() and close() operations on /dev/bus/i3c/<bus>-<provisio=
nal 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 ca=
llable
> +    yet they will return -EACCES.
> +
> +C EXAMPLE
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +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 =3D 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[] =3D {0x00, 0xde, 0xad, 0xbe, 0xef}
> +  if (write(file, buf, 5) !=3D 5) {
> +    /* ERROR HANDLING: I3C transaction failed */
> +  }
> +
> +  /*  Read function */
> +  ret =3D 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[] =3D {0x00, 0xde, 0xad, 0xbe, 0xef};
> +  uint8_t rx_buf[10];
> +
> +  xfers[0].data =3D (uintptr_t)tx_buf;
> +  xfers[0].len =3D 5;
> +  xfers[0].rnw =3D 0;
> +  xfers[1].data =3D (uintptr_t)rx_buf;
> +  xfers[1].len =3D 10;
> +  xfers[1].rnw =3D 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 requ=
ired::
> +
> +  close(file);
> \ No newline at end of file
> --=20
> 2.7.4

Best regards,
Vitor Soares