From patchwork Tue Sep 6 15:24:00 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 75543 Delivered-To: patch@linaro.org Received: by 10.140.106.11 with SMTP id d11csp607059qgf; Tue, 6 Sep 2016 08:26:09 -0700 (PDT) X-Received: by 10.98.88.131 with SMTP id m125mr73012717pfb.63.1473175569189; Tue, 06 Sep 2016 08:26:09 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id w6si32478057pab.78.2016.09.06.08.26.08; Tue, 06 Sep 2016 08:26:09 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756314AbcIFP0F (ORCPT + 27 others); Tue, 6 Sep 2016 11:26:05 -0400 Received: from tex.lwn.net ([70.33.254.29]:58051 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934981AbcIFPYa (ORCPT ); Tue, 6 Sep 2016 11:24:30 -0400 Received: from tpad.localdomain (localhost.localdomain [127.0.0.1]) by vena.lwn.net (Postfix) with ESMTP id C0FD0154003E; Tue, 6 Sep 2016 09:24:27 -0600 (MDT) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Daniel Vetter , Jonathan Corbet Subject: [PATCH 3/5] docs: Pull the HSI documentation together Date: Tue, 6 Sep 2016 09:24:00 -0600 Message-Id: <1473175442-13277-4-git-send-email-corbet@lwn.net> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1473175442-13277-1-git-send-email-corbet@lwn.net> References: <1473175442-13277-1-git-send-email-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The HSI subsystem documentation was split across hsi.txt and the device-drivers docbook. Now that the latter has been converted to Sphinx, pull in the HSI document so that it's all in one place. Acked-by: Sebastian Reichel Signed-off-by: Jonathan Corbet --- Documentation/driver-api/serial-interfaces.rst | 82 ++++++++++++++++++++++++-- Documentation/hsi.txt | 75 ----------------------- MAINTAINERS | 2 +- 3 files changed, 79 insertions(+), 80 deletions(-) delete mode 100644 Documentation/hsi.txt -- 2.7.4 diff --git a/Documentation/driver-api/serial-interfaces.rst b/Documentation/driver-api/serial-interfaces.rst index d0d65e58c14b..07c58971a322 100644 --- a/Documentation/driver-api/serial-interfaces.rst +++ b/Documentation/driver-api/serial-interfaces.rst @@ -102,10 +102,84 @@ i2c_adapter devices which don't support those I2C operations. High Speed Synchronous Serial Interface (HSI) ============================================= -High Speed Synchronous Serial Interface (HSI) is a serial interface -mainly used for connecting application engines (APE) with cellular modem -engines (CMT) in cellular handsets. HSI provides multiplexing for up to -16 logical channels, low-latency and full duplex communication. +1. Introduction +--------------- + +High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +that is optimized for die-level interconnect between an Application Processor +and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and +implemented by multiple vendors since then. + +The HSI interface supports full duplex communication over multiple channels +(typically 8) and is capable of reaching speeds up to 200 Mbit/s. + +The serial protocol uses two signals, DATA and FLAG as combined data and clock +signals and an additional READY signal for flow control. An additional WAKE +signal can be used to wakeup the chips from standby modes. The signals are +commonly prefixed by AC for signals going from the application die to the +cellular die and CA for signals going the other way around. + +:: + + +------------+ +---------------+ + | Cellular | | Application | + | Die | | Die | + | | - - - - - - CAWAKE - - - - - - >| | + | T|------------ CADATA ------------>|R | + | X|------------ CAFLAG ------------>|X | + | |<----------- ACREADY ------------| | + | | | | + | | | | + | |< - - - - - ACWAKE - - - - - - -| | + | R|<----------- ACDATA -------------|T | + | X|<----------- ACFLAG -------------|X | + | |------------ CAREADY ----------->| | + | | | | + | | | | + +------------+ +---------------+ + +2. HSI Subsystem in Linux +------------------------- + +In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. +The hsi subsystem contains drivers for hsi controllers including support for +multi-port controllers and provides a generic API for using the HSI ports. + +It also contains HSI client drivers, which make use of the generic API to +implement a protocol used on the HSI interface. These client drivers can +use an arbitrary number of channels. + +3. hsi-char Device +------------------ + +Each port automatically registers a generic client driver called hsi_char, +which provides a charecter device for userspace representing the HSI port. +It can be used to communicate via HSI from userspace. Userspace may +configure the hsi_char device using the following ioctl commands: + +HSC_RESET + flush the HSI port + +HSC_SET_PM + enable or disable the client. + +HSC_SEND_BREAK + send break + +HSC_SET_RX + set RX configuration + +HSC_GET_RX + get RX configuration + +HSC_SET_TX + set TX configuration + +HSC_GET_TX + get TX configuration + +The kernel HSI API +------------------ .. kernel-doc:: include/linux/hsi/hsi.h :internal: diff --git a/Documentation/hsi.txt b/Documentation/hsi.txt deleted file mode 100644 index 6ac6cd51852a..000000000000 --- a/Documentation/hsi.txt +++ /dev/null @@ -1,75 +0,0 @@ -HSI - High-speed Synchronous Serial Interface - -1. Introduction -~~~~~~~~~~~~~~~ - -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, -that is optimized for die-level interconnect between an Application Processor -and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and -implemented by multiple vendors since then. - -The HSI interface supports full duplex communication over multiple channels -(typically 8) and is capable of reaching speeds up to 200 Mbit/s. - -The serial protocol uses two signals, DATA and FLAG as combined data and clock -signals and an additional READY signal for flow control. An additional WAKE -signal can be used to wakeup the chips from standby modes. The signals are -commonly prefixed by AC for signals going from the application die to the -cellular die and CA for signals going the other way around. - -+------------+ +---------------+ -| Cellular | | Application | -| Die | | Die | -| | - - - - - - CAWAKE - - - - - - >| | -| T|------------ CADATA ------------>|R | -| X|------------ CAFLAG ------------>|X | -| |<----------- ACREADY ------------| | -| | | | -| | | | -| |< - - - - - ACWAKE - - - - - - -| | -| R|<----------- ACDATA -------------|T | -| X|<----------- ACFLAG -------------|X | -| |------------ CAREADY ----------->| | -| | | | -| | | | -+------------+ +---------------+ - -2. HSI Subsystem in Linux -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. -The hsi subsystem contains drivers for hsi controllers including support for -multi-port controllers and provides a generic API for using the HSI ports. - -It also contains HSI client drivers, which make use of the generic API to -implement a protocol used on the HSI interface. These client drivers can -use an arbitrary number of channels. - -3. hsi-char Device -~~~~~~~~~~~~~~~~~~ - -Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. -It can be used to communicate via HSI from userspace. Userspace may -configure the hsi_char device using the following ioctl commands: - -* HSC_RESET: - - flush the HSI port - -* HSC_SET_PM - - enable or disable the client. - -* HSC_SEND_BREAK - - send break - -* HSC_SET_RX - - set RX configuration - -* HSC_GET_RX - - get RX configuration - -* HSC_SET_TX - - set TX configuration - -* HSC_GET_TX - - get TX configuration diff --git a/MAINTAINERS b/MAINTAINERS index 810723537aa5..769a2fd4af72 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -5606,7 +5606,7 @@ M: Sebastian Reichel T: git git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-hsi.git S: Maintained F: Documentation/ABI/testing/sysfs-bus-hsi -F: Documentation/hsi.txt +F: Documentation/device-drivers/serial-interfaces.rst F: drivers/hsi/ F: include/linux/hsi/ F: include/uapi/linux/hsi/