diff mbox

[3/3] docs: Pull HSI documentation together

Message ID 1471899463-5774-4-git-send-email-corbet@lwn.net
State Superseded
Headers show

Commit Message

Jonathan Corbet Aug. 22, 2016, 8:57 p.m. UTC 
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.

Cc: Sebastian Reichel <sre@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

---
 Documentation/driver-api/serial-interfaces.rst | 82 ++++++++++++++++++++++++--
 Documentation/hsi.txt                          | 75 -----------------------
 MAINTAINERS                                    |  2 +-
 3 files changed, 79 insertions(+), 80 deletions(-)

-- 
2.7.4

Comments

Jonathan Corbet Sept. 6, 2016, 3:12 p.m. UTC | #1 
On Tue, 23 Aug 2016 02:20:19 +0200
Sebastian Reichel <sre@kernel.org> wrote:

> Thanks for doing this. I like the resulting HTML. I'm a bit confused

> by the rendering of the struct sections, though. Initially I thought

> the blue box with "struct xyz" is an empty table (= there are no

> members).


[Getting back to this finally]

The theme needs a fair amount of work still; we've not put much effort
into making it look as good as it should.  Maybe that should be my next
project...

> Also I think it would be better to split serial-interfaces.rst into

> the different subsystems. It generates different sections anyways.


You're right, I shouldn't have tried to stick them together like that.
The next attempt, hitting an internet near you shortly, will split them
apart.

Thanks,

jon
diff mbox

Patch

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 <sre@kernel.org>
 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/