Merge tag 'hsi-for-3.16' of git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-hsi into next

Each HSI port is supposed to have one child node, which

symbols the remote device connected to the HSI port. The

following properties are standardized for HSI clients:

Required HSI configuration properties:

- hsi-channel-ids:	A list of channel ids

- hsi-rx-mode:		Receiver Bit transmission mode ("stream" or "frame")

- hsi-tx-mode:		Transmitter Bit transmission mode ("stream" or "frame")

- hsi-mode:		May be used instead hsi-rx-mode and hsi-tx-mode if

			the transmission mode is the same for receiver and

			transmitter

- hsi-speed-kbps:	Max bit transmission speed in kbit/s

- hsi-flow:		RX flow type ("synchronized" or "pipeline")

- hsi-arb-mode:		Arbitration mode for TX frame ("round-robin", "priority")

Optional HSI configuration properties:

- hsi-channel-names:	A list with one name per channel specified in the

			hsi-channel-ids property

Device Tree node example for an HSI client:

hsi-controller {

	hsi-port {

		modem: hsi-client {

			compatible = "nokia,n900-modem";

			hsi-channel-ids = <0>, <1>, <2>, <3>;

			hsi-channel-names = "mcsaab-control",

					    "speech-control",

					    "speech-data",

					    "mcsaab-data";

			hsi-speed-kbps = <55000>;

			hsi-mode = "frame";

			hsi-flow = "synchronized";

			hsi-arb-mode = "round-robin";

			/* more client specific properties */

		};

	};

};

Nokia modem client bindings

The Nokia modem HSI client follows the common HSI client binding

and inherits all required properties. The following additional

properties are needed by the Nokia modem HSI client:

Required properties:

- compatible:		Should be one of

      "nokia,n900-modem"

- hsi-channel-names:	Should contain the following strings

      "mcsaab-control"

      "speech-control"

      "speech-data"

      "mcsaab-data"

- gpios:		Should provide a GPIO handler for each GPIO listed in

                        gpio-names

- gpio-names:		Should contain the following strings

      "cmt_apeslpx"

      "cmt_rst_rq"

      "cmt_en"

      "cmt_rst"

      "cmt_bsi"

- interrupts:		Should be IRQ handle for modem's reset indication

Example:

&ssi_port {

	modem: hsi-client {

		compatible = "nokia,n900-modem";

		pinctrl-names = "default";

		pinctrl-0 = <&modem_pins>;

		hsi-channel-ids = <0>, <1>, <2>, <3>;

		hsi-channel-names = "mcsaab-control",

				    "speech-control",

				    "speech-data",

				    "mcsaab-data";

		hsi-speed-kbps = <55000>;

		hsi-mode = "frame";

		hsi-flow = "synchronized";

		hsi-arb-mode = "round-robin";

		interrupts-extended = <&gpio3 8 IRQ_TYPE_EDGE_FALLING>; /* 72 */

		gpios = <&gpio3  6 GPIO_ACTIVE_HIGH>, /* 70 */

			<&gpio3  9 GPIO_ACTIVE_HIGH>, /* 73 */

			<&gpio3 10 GPIO_ACTIVE_HIGH>, /* 74 */

			<&gpio3 11 GPIO_ACTIVE_HIGH>, /* 75 */

			<&gpio5 29 GPIO_ACTIVE_HIGH>; /* 157 */

		gpio-names = "cmt_apeslpx",

			     "cmt_rst_rq",

			     "cmt_en",

			     "cmt_rst",

			     "cmt_bsi";

	};

};

OMAP SSI controller bindings

OMAP Synchronous Serial Interface (SSI) controller implements a legacy

variant of MIPI's High Speed Synchronous Serial Interface (HSI).

Required properties:

- compatible:		Should include "ti,omap3-ssi".

- reg-names:		Contains the values "sys" and "gdd" (in this order).

- reg:			Contains a matching register specifier for each entry

			in reg-names.

- interrupt-names:	Contains the value "gdd_mpu".

- interrupts: 		Contains matching interrupt information for each entry

			in interrupt-names.

- ranges:		Represents the bus address mapping between the main

			controller node and the child nodes below.

- clock-names:		Must include the following entries:

  "ssi_ssr_fck": The OMAP clock of that name

  "ssi_sst_fck": The OMAP clock of that name

  "ssi_ick": The OMAP clock of that name

- clocks:		Contains a matching clock specifier for each entry in

			clock-names.

- #address-cells:	Should be set to <1>

- #size-cells:		Should be set to <1>

Each port is represented as a sub-node of the ti,omap3-ssi device.

Required Port sub-node properties:

- compatible:		Should be set to the following value

			ti,omap3-ssi-port (applicable to OMAP34xx devices)

- reg-names:		Contains the values "tx" and "rx" (in this order).

- reg:			Contains a matching register specifier for each entry

			in reg-names.

- interrupt-parent	Should be a phandle for the interrupt controller

- interrupts:		Should contain interrupt specifiers for mpu interrupts

			0 and 1 (in this order).

- ti,ssi-cawake-gpio:	Defines which GPIO pin is used to signify CAWAKE

			events for the port. This is an optional board-specific

			property. If it's missing the port will not be

			enabled.

Example for Nokia N900:

ssi-controller@48058000 {

	compatible = "ti,omap3-ssi";

	/* needed until hwmod is updated to use the compatible string */

	ti,hwmods = "ssi";

	reg = <0x48058000 0x1000>,

	      <0x48059000 0x1000>;

	reg-names = "sys",

		    "gdd";

	interrupts = <55>;

	interrupt-names = "gdd_mpu";

	clocks = <&ssi_ssr_fck>,

		 <&ssi_sst_fck>,

		 <&ssi_ick>;

	clock-names = "ssi_ssr_fck",

		      "ssi_sst_fck",

		      "ssi_ick";

	#address-cells = <1>;

	#size-cells = <1>;

	ranges;

	ssi-port@4805a000 {

		compatible = "ti,omap3-ssi-port";

		reg = <0x4805a000 0x800>,

		      <0x4805a800 0x800>;

		reg-names = "tx",

			    "rx";

		interrupt-parent = <&intc>;

		interrupts = <67>,

			     <68>;

		ti,ssi-cawake-gpio = <&gpio5 23 GPIO_ACTIVE_HIGH>; /* 151 */

	}

	ssi-port@4805a000 {

		compatible = "ti,omap3-ssi-port";

		reg = <0x4805b000 0x800>,

		      <0x4805b800 0x800>;

		reg-names = "tx",

			    "rx";

		interrupt-parent = <&intc>;

		interrupts = <69>,

			     <70>;

		status = "disabled"; /* second port is not used on N900 */

	}

}

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

F:	fs/hpfs/

HSI SUBSYSTEM

M:	Sebastian Reichel <sre@debian.org>

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:	drivers/hsi/

F:	include/linux/hsi/

F:	include/uapi/linux/hsi/