Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Sender: hemantk=codeaurora.org@mg.codeaurora.org
DMARC-Filter: OpenDMARC Filter v1.3.2 smtp.codeaurora.org 96B51C433C6
Subject: Re: [PATCH v14 3/4] docs: Add documentation for userspace client
 interface
To:     jhugo@codeaurora.org
Cc:     manivannan.sadhasivam@linaro.org, gregkh@linuxfoundation.org,
        linux-arm-msm@vger.kernel.org, linux-kernel@vger.kernel.org,
        bbhatt@codeaurora.org, loic.poulain@linaro.org,
        netdev@vger.kernel.org, hemantk=codeaurora.org@codeaurora.org
References: <1606877991-26368-1-git-send-email-hemantk@codeaurora.org>
 <1606877991-26368-4-git-send-email-hemantk@codeaurora.org>
 <86747d3a0e8555ee5369aaa3cb2ff947@codeaurora.org>
From:   Hemant Kumar <hemantk@codeaurora.org>
Message-ID: <7debf28b-e8d1-aba2-ae23-e47fa09e4f46@codeaurora.org>
Date:   Thu, 3 Dec 2020 13:37:03 -0800
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
MIME-Version: 1.0
In-Reply-To: <86747d3a0e8555ee5369aaa3cb2ff947@codeaurora.org>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 8bit
Precedence: bulk

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