Messages in this thread | | | Subject | Re: [PATCH v14 3/4] docs: Add documentation for userspace client interface | From | Hemant Kumar <> | Date | Thu, 3 Dec 2020 13:37:03 -0800 |
| |
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
| |