soc: qcom: glink_pkt: Add glink packet driver documentation

Introduction

============

Glink packet drivers are companion adaptation driver which use the kernel APIs

to expose the Glink core logical channels as charecter devices to the

user-space clients.

The Glink core APIs are detailed in Documentation/arm/msm/glink.txt.

Software description

====================

Glink packet drivers supports the Glink core APIs to user-space client through

standard file operations like open, read, write, ioctl, poll and release etc.

The standard Linux permissions are used for the device node and SELinux does

further security checks.

    Device node [0..n]

           |

           |

  -------------------

 |  VFS Framework    |

  -------------------

    |             |

    |             |

  -------     -------

 | CDEV  |   | CDEV  |

 | Dev 0 |...| Dev n |

 ----------------------

|  Glink packet driver |

 ----------------------

           |

           |

    -----------------

   |                 |

   |   G-Link core   |

   |                 |

    -----------------

           |

           |

    To Remote System

The file operations map to the G-link client API as follows:

Open():

----------

The Open system call is mapped to glink_open() which opens a channel. The

expected channel configuration has to done through DT files. The full DT schema

is detailed in Documentation/devicetree/bindings/arm/msm/glinkpkt.txt.

Open on the glink packet character device is a blocking call which blocks until

the channel is fully open by both local processor and remote processor.

Clients can configure the blocking time through a device configurable parameter

defined per device.

The timeout value is specified in seconds with a default timeout of 1 second.

A negative value indicates an infinite wait.

Example:

# get open timeout value

	cat /sys/class/glinkpkt/device_name/open_timeout

# set to 20 seconds value

	echo 20 > /sys/class/glinkpkt/device_name/open_timeout

If the channel is not opened by remote processor or any other problem which

fails the channel to be ready will result in timeout and -ETIMEOUT will return

to client. Open on success returns the valid file descriptor to client and on

fail case standard Linux error codes.

The same device can be opened by multiple clients but passing the same file

descriptor from multiple threads may lead unexpected results.

Write():

----------

The Write system call is mapped to glink_tx() which transmits the data over the

glink channel.

Read():

----------

The Read system call consumes any pending data on the channel. Glink signals

incoming data through the glink_notify_rx() call back and the glink packet

driver queues the data internally and provides to client through read system

call. Once the Read is completed, the glink packet driver calls glink_rx_done()

API to notify the completion of receiving operation to Glink core.

                       +

       User-Space      |   Kernel-Space

                       |

                       |

+---------+            |                +----------+         +------------+

| Local   |            |                | GlinkPKT |         |            |

| Client  |            |                | Driver   |         | Glink core |

|         |            |                |          |         |            |

+---------+            |                +----------+         +------------+

                       |

    +                  |                     +                     +

    |                  |                     |                     |

    |    open()        |  glink_pkt_open()   |    glink_open()     |

    | +--------------> | +-----------------> | +-----------------> |

    |                  |                     |                     |

    |   File Handle[fd]|    Valid Fd         |    Handle           |

    | <--------------+ | <-----------------+ | <-----------------+ |

    |                  |                     |                     |

    |     Ioctl()      |                     |                     |

    |  QUEUE_RX_INTENT |  glink_pkt_ioctl()  | glink_queue_rx_intent()

    | +--------------> | +-----------------> | +-----------------> |

    |                  |                     |                     |

    |                  |                     |                     |

    | <----------------------------------------------------------+ |

    |                  |                     |                     |

    |     Read()       |  glink_pkt_read()   |                     |

    | +--------------> | +-----------------> | +---+               |

    |                  |                     |     |               |

    |                  |                 Wait for data             |

    |                  |                     | <---+               |

    |                  |                     |  glink_notify_rx()  |

    |                  |                     | <-----------------+ |

    |                  |   Wake-up read()    |                     |

    |                  |   copy_to_user()    |                     |

    |   read() return  | <-----------------+ |                     |

    | <--------------+ |                     |                     |

    +                  |                     +                     +

                       |

                       |

                       +

Clients can also poll on device node for POLLIN mask to get notification for

any incoming data. Clients have to call the GLINK_PKT_IOCTL_QUEUE_RX_INTENT

ioctl to queue the RX buffer to glink core in advance.

Release():

----------

The Release system call is mapped to glink_close() to close a channel and free

the resources.

Poll():

----------

The Poll system call provides waiting operation like wait for incoming data on

POLLIN mask and to get the TIOCM signal notification on POLLPRI mask. Clients

can wait on poll for POLLPRI mask to get any notification regarding TICOM

signals. In SSR case Poll call will return with POLLHUP mask and in this case

client has to close and re-open the port.

* POLLPRI - TIOCM bits changed

* POLLIN - RX data available

* POLLHUP - link is down due to either remote side closing or an SSR

Ioctl():

----------

Multiple ioctls are supported to get the TICOM signal status and to queue the

Rx intent with Glink core. Supported ioctls are TIOCMSET, TIOCMGET, TIOCMBIS,

TIOCMBIC and GLINK_PKT_IOCTL_QUEUE_RX_INTENT.

The GLINK_PKT_IOCTL_QUEUE_RX_INTENT ioctl is mapped to glink_queue_rx_intent()

API which queues an RX intent with Glink core.

SSR operation:

==============

On remote subsystem restart all open channels on that edge will be closed and

local clients have to close and re-open the channel to re-start the

communication. All blocking calls such as open, read and write will be returned

with -ENETRESET and the poll call will be return with the POLLHUP error codes.

Files:

==========

Documentation/devicetree/bindings/arm/msm/glinkpkt.txt

drivers/soc/qcom/msm_glink_pkt.c

Wakelock:

==========

By default, GLINK PKT will acquire a wakelock for 2 seconds. To optimize this

behavior, use the poll() function:

	1. Client calls poll() which blocks until data is available to read

	2. Data comes in, GLINK PKT grabs a wakelock and poll()is unblocked

	3. Client grabs wakelock to prevent system from suspending

	4. Client calls GLINK PKT read() to read the data

	5. GLINK PKT releases its wakelock

	6. Client Processes the data

	7. Client releases the wakelock

Logging:

==========

	cat /d/ipc_logging/glink_pkt/log_cont