Re: [PATCH v3 3/4] docs: Add documentation for user space client interface

[Manivannan Sadhasivam]

On Wed, Jun 24, 2020 at 06:52:20PM -0700, Hemant Kumar wrote:
> Hi Mani,
> 
> On 6/18/20 11:39 PM, Manivannan Sadhasivam wrote:
> > On Thu, Jun 11, 2020 at 11:13:43AM -0700, Hemant Kumar wrote:
> > > MHI user space client driver is creating device file node
> > > for user application to perform file operations. File
> > > operations are handled by MHI core driver. Currently
> > > Loopback MHI channel is supported by this driver.
> > > 
> > > Signed-off-by: Hemant Kumar <hemantk@xxxxxxxxxxxxxx>
> > > ---
> > >   Documentation/mhi/index.rst |  1 +
> > >   Documentation/mhi/uci.rst   | 19 +++++++++++++++++++
> > >   2 files changed, 20 insertions(+)
> > >   create mode 100644 Documentation/mhi/uci.rst
> > > 
> > > diff --git a/Documentation/mhi/index.rst b/Documentation/mhi/index.rst
> > > index 1d8dec3..c75a371 100644
> > > --- a/Documentation/mhi/index.rst
> > > +++ b/Documentation/mhi/index.rst
> > > @@ -9,6 +9,7 @@ MHI
> > >      mhi
> > >      topology
> > > +   uci
> > >   .. only::  subproject and html
> > > diff --git a/Documentation/mhi/uci.rst b/Documentation/mhi/uci.rst
> > > new file mode 100644
> > > index 0000000..a5c5c4f
> > > --- /dev/null
> > > +++ b/Documentation/mhi/uci.rst
> > > @@ -0,0 +1,19 @@
> > > +.. SPDX-License-Identifier: GPL-2.0
> > > +
> > > +=================================
> > > +User space Client Interface (UCI)
> > 
> > Stick to 'Userspace' everywhere.
> Done.
> > 
> > > +=================================
> > > +
> > > +UCI driver enables user space clients to communicate to external MHI devices
> > > +like modem and WLAN. It creates standard character device file nodes for user
> > 
> > UCI driver creates a single char device, isn't it?
> No, it is created per device name. For example Loopback has its own char
> device file node. if we add another channel for a new mhi device new device
> file node would be created.

Okay, then please add a line saying that there will be separate chardev nodes
for each channel specified.

> > 
> > > +space clients to perform open, read, write, pool and close file operations.
> > > +
> > 
> > poll? Btw, you need to mention explicitly how this char device can be used.
> > You are just mentioning standard file operations.
> Will fix poll.My idea was indeed to mention generic file operations so that
> we dont have to be specific with use case. Any userspace entity who wants to
> communicate over mhi can use the driver. Reason we have this driver is to
> abstract the mhi core specific details. Even for loopback use case,
> userspace can echo to device file node on one channel and get a same in
> response from another channel back. I can add more examples of
> other user space drivers use case if that helps.

Yes, just add couple of examples.

> > 
> > > +Device file node is created with format:-
> > > +
> > > +/dev/mhi_<controller_name>_<mhi_device_name>
> > > +
> > > +controller_name is the name of underlying bus used to transfer data.
> > 
> > underlying controller instance.
> Done.
> > 
> > > +mhi_device_name is the name of the MHI channel being used by MHI client
> > 
> > What do you mean by MHI client here? Are you referring to userspace client?
> yes. i can say "MHI client in userspace"?

Okay. The naming conventions used in MHI are a bit weird. So from the start
itself I stuck with some fixed names and client is one of them. The term client
itself refers to both client device and a driver used to talk to the device in
the host. So we should explicitly mention if it is a userspace client driver
or the client device.

Thanks,
Mani

> > 
> > > +to send or receive data using MHI protocol. MHI channels are statically
> > > +defined by MHI specification. Driver currently supports LOOPBACK channel
> > > +index 0 (Host to device) and 1 (Device to Host).
> > 
> > s/index/identifier
> Done.
> > 
> > And explain a bit on how this LOOPBACK channel is getting used.
> Done.
> > 
> > Thanks,
> > Mani
> > 
> > > -- 
> > > The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
> > > a Linux Foundation Collaborative Project
> > > 
> 
> -- 
> The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
> a Linux Foundation Collaborative Project