Path: csiph.com!goblin2!goblin.stu.neva.ru!aioe.org!bofh.it!news.nic.it!robomod From: Jonathan Corbet Newsgroups: linux.kernel Subject: [PATCH 3/5] docs: Pull the HSI documentation together Date: Tue, 06 Sep 2016 17:30:03 +0200 Message-ID: References: X-Original-To: linux-doc@vger.kernel.org X-Mailer: git-send-email 2.7.4 Sender: robomod@news.nic.it List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Approved: robomod@news.nic.it Lines: 202 Organization: linux.* mail to news gateway X-Original-Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Daniel Vetter , Jonathan Corbet X-Original-Date: Tue, 6 Sep 2016 09:24:00 -0600 X-Original-Message-ID: <1473175442-13277-4-git-send-email-corbet@lwn.net> X-Original-References: <1473175442-13277-1-git-send-email-corbet@lwn.net> X-Original-Sender: linux-kernel-owner@vger.kernel.org Xref: csiph.com linux.kernel:1477537 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 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/ -- 2.7.4