| 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. |
| |
| Signals: |
| ========== |
| Glink protocol provoide 32-bit control signal field to pass through for the |
| clients-specific signaling where as Glink packet driver client which are from |
| user space can use the signal filed as mentioned below. |
| |
| * 31:28 - Reserved for SMD RS-232 signals |
| * 27:16 - Pass through for client usage |
| * 15:0 - TICOM bits |
| |
| 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 |
| |