lkml.org 
[lkml]   [2020]   [Dec]   [3]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH v14 3/4] docs: Add documentation for userspace client interface
From
Date
Hi Jeff

On 12/3/20 12:38 PM, jhugo@codeaurora.org wrote:
> On 2020-12-01 19:59, Hemant Kumar wrote:
>> MHI userspace client driver is creating device file node
>> for user application to perform file operations. File
>> operations are handled by MHI core driver. Currently
>> QMI MHI channel is supported by this driver.
>>
>> Signed-off-by: Hemant Kumar <hemantk@codeaurora.org>
>
> Two minor nits below.  With those -
> Reviewed-by: Jeffrey Hugo <jhugo@codeaurora.org>
>
>> ---
>>  Documentation/mhi/index.rst |  1 +
>>  Documentation/mhi/uci.rst   | 94
>> +++++++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 95 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..9603f92
>> --- /dev/null
>> +++ b/Documentation/mhi/uci.rst
>> @@ -0,0 +1,94 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +=================================
>> +Userspace Client Interface (UCI)
>> +=================================
>> +
>> +UCI driver enables userspace clients to communicate to external MHI
>> devices
>> +like modem and WLAN. UCI driver probe creates standard character
>> device file
>> +nodes for userspace clients to perform open, read, write, poll and
>> release file
>> +operations. UCI device object represents UCI device file node which gets
>> +instantiated as part of MHI UCI driver probe. UCI channel object
>> represents
>> +MHI uplink or downlink channel.
>> +
>> +Operations
>> +==========
>> +
>> +open
>> +----
>> +
>> +Instantiates UCI channel object and starts MHI channels to move it to
>> running
>> +state. Inbound buffers are queued to downlink channel transfer ring.
>> Every
>> +subsequent open() increments UCI device reference count as well as
>> UCI channel
>> +reference count.
>> +
>> +read
>> +----
>> +
>> +When data transfer is completed on downlink channel, transfer ring
>> element
>> +buffer is copied to pending list. Reader is unblocked and data is
>> copied to
>> +userspace buffer. Transfer ring element buffer is queued back to
>> downlink
>> +channel transfer ring.
>> +
>> +write
>> +-----
>> +
>> +Write buffer is queued to uplink channel transfer ring if ring is not
>> full. Upon
>> +uplink transfer completion buffer is freed.
>> +
>> +poll
>> +----
>> +
>> +Returns EPOLLIN | EPOLLRDNORM mask if pending list has buffers to be
>> read by
>> +userspace. Returns EPOLLOUT | EPOLLWRNORM mask if MHI uplink channel
>> transfer
>> +ring is not empty. Returns EPOLLERR when UCI driver is removed.
>
> ring is not empty.  When the uplink channel transfer ring is non-empty,
> more
> data may be sent to the device. Returns EPOLLERR when UCI driver is
> removed.
Done
>
>> +
>> +release
>> +-------
>> +
>> +Decrements UCI device reference count and UCI channel reference count
>> upon last
>> +release(). UCI channel clean up is performed. MHI channel moves to
>> disable
>> +state and inbound buffers are freed.
>
> Decrements UCI device reference count and UCI channel reference count.
> Upon last
> release() UCI channel clean up is performed. MHI channel moves to disable
> state and inbound buffers are freed.
Done.
>
>> +
>> +Usage
>> +=====
>> +
>> +Device file node is created with format:-
>> +
>> +/dev/<mhi_device_name>
>> +
>> +mhi_device_name includes mhi controller name and the name of the MHI
>> channel
>> +being used by MHI client in userspace to send or receive data using MHI
>> +protocol.
>> +
>> +There is a separate character device file node created for each channel
>> +specified in MHI device id table. MHI channels are statically defined
>> by MHI
>> +specification. The list of supported channels is in the channel list
>> variable
>> +of mhi_device_id table in UCI driver.
>> +
>> +Qualcomm MSM Interface(QMI) Channel
>> +-----------------------------------
>> +
>> +Qualcomm MSM Interface(QMI) is a modem control messaging protocol
>> used to
>> +communicate between software components in the modem and other
>> peripheral
>> +subsystems. QMI communication is of request/response type or an
>> unsolicited
>> +event type. libqmi is userspace MHI client which communicates to a
>> QMI service
>> +using UCI device. It sends a QMI request to a QMI service using MHI
>> channel 14
>> +or 16. QMI response is received using MHI channel 15 or 17
>> respectively. libqmi
>> +is a glib-based library for talking to WWAN modems and devices which
>> speaks QMI
>> +protocol. For more information about libqmi please refer
>> +https://www.freedesktop.org/wiki/Software/libqmi/
>> +
>> +Usage Example
>> +~~~~~~~~~~~~~
>> +
>> +QMI command to retrieve device mode
>> +$ sudo qmicli -d /dev/mhi0_QMI --dms-get-model
>> +[/dev/mhi0_QMI] Device model retrieved:
>> +    Model: 'FN980m'
>> +
>> +Other Use Cases
>> +---------------
>> +
>> +Getting MHI device specific diagnostics information to userspace MHI
>> diagnostic
>> +client using DIAG channel 4 (Host to device) and 5 (Device to Host).

Thanks,
Hemant
--
The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
a Linux Foundation Collaborative Project

\
 
 \ /
  Last update: 2020-12-03 22:39    [W:5.119 / U:0.004 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site