High Speed Synchronous Serial Interface (HSI)¶

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 ----------->|               |
|            |                                 |               |
|            |                                 |               |
+------------+                                 +---------------+

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.

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¶

struct hsi_channel¶: channel resource used by the hsi clients

Definition

struct hsi_channel {
  unsigned int id;
  const char * name;
};

Members

id: Channel number
name: Channel name

struct hsi_config¶: Configuration for RX/TX HSI modules

Definition

struct hsi_config {
  unsigned int mode;
  struct hsi_channel * channels;
  unsigned int num_channels;
  unsigned int num_hw_channels;
  unsigned int speed;
  union {unnamed_union};
};

Members

mode: Bit transmission mode (STREAM or FRAME)
channels: Channel resources used by the client
num_channels: Number of channel resources
num_hw_channels: Number of channels the transceiver is configured for [1..16]
speed: Max bit transmission speed (Kbit/s)
{unnamed_union}: anonymous

struct hsi_board_info¶: HSI client board info

Definition

struct hsi_board_info {
  const char * name;
  unsigned int hsi_id;
  unsigned int port;
  struct hsi_config tx_cfg;
  struct hsi_config rx_cfg;
  void * platform_data;
  struct dev_archdata * archdata;
};

Members

name: Name for the HSI device
hsi_id: HSI controller id where the client sits
port: Port number in the controller where the client sits
tx_cfg: HSI TX configuration
rx_cfg: HSI RX configuration
platform_data: Platform related data
archdata: Architecture-dependent device data

struct hsi_client¶: HSI client attached to an HSI port

Definition

struct hsi_client {
  struct device device;
  struct hsi_config tx_cfg;
  struct hsi_config rx_cfg;
};

Members

device: Driver model representation of the device
tx_cfg: HSI TX configuration
rx_cfg: HSI RX configuration

struct hsi_client_driver¶: Driver associated to an HSI client

Definition

struct hsi_client_driver {
  struct device_driver driver;
};

Members

driver: Driver model representation of the driver

struct hsi_msg¶: HSI message descriptor

Definition

struct hsi_msg {
  struct list_head link;
  struct hsi_client * cl;
  struct sg_table sgt;
  void * context;
  void (* complete) (struct hsi_msg *msg);
  void (* destructor) (struct hsi_msg *msg);
  int status;
  unsigned int actual_len;
  unsigned int channel;
  unsigned int ttype:1;
  unsigned int break_frame:1;
};

Members

link: Free to use by the current descriptor owner
cl: HSI device client that issues the transfer
sgt: Head of the scatterlist array
context: Client context data associated to the transfer
complete: Transfer completion callback
destructor: Destructor to free resources when flushing
status: Status of the transfer when completed
actual_len: Actual length of data transferred on completion
channel: Channel were to TX/RX the message
ttype: Transfer type (TX if set, RX otherwise)
break_frame: if true HSI will send/receive a break frame. Data buffers are ignored in the request.

struct hsi_port¶: HSI port device

Definition

struct hsi_port {
  struct device device;
  struct hsi_config tx_cfg;
  struct hsi_config rx_cfg;
  unsigned int num;
  unsigned int shared:1;
  int claimed;
  struct mutex lock;
  int (* async) (struct hsi_msg *msg);
  int (* setup) (struct hsi_client *cl);
  int (* flush) (struct hsi_client *cl);
  int (* start_tx) (struct hsi_client *cl);
  int (* stop_tx) (struct hsi_client *cl);
  int (* release) (struct hsi_client *cl);
  struct blocking_notifier_head n_head;
};

Members

device: Driver model representation of the device
tx_cfg: Current TX path configuration
rx_cfg: Current RX path configuration
num: Port number
shared: Set when port can be shared by different clients
claimed: Reference count of clients which claimed the port
lock: Serialize port claim
async: Asynchronous transfer callback
setup: Callback to set the HSI client configuration
flush: Callback to clean the HW state and destroy all pending transfers
start_tx: Callback to inform that a client wants to TX data
stop_tx: Callback to inform that a client no longer wishes to TX data
release: Callback to inform that a client no longer uses the port
n_head: Notifier chain for signaling port events to the clients.

struct hsi_controller¶: HSI controller device

Definition

struct hsi_controller {
  struct device device;
  struct module * owner;
  unsigned int id;
  unsigned int num_ports;
  struct hsi_port ** port;
};

Members

device: Driver model representation of the device
owner: Pointer to the module owning the controller
id: HSI controller ID
num_ports: Number of ports in the HSI controller
port: Array of HSI ports

unsigned int hsi_id(struct hsi_client * cl)¶: Get HSI controller ID associated to a client

Parameters

struct hsi_client * cl: Pointer to a HSI client

Description

Return the controller id where the client is attached to

unsigned int hsi_port_id(struct hsi_client * cl)¶: Gets the port number a client is attached to

Parameters

struct hsi_client * cl: Pointer to HSI client

Description

Return the port number associated to the client

int hsi_setup(struct hsi_client * cl)¶: Configure the client’s port

Parameters

struct hsi_client * cl: Pointer to the HSI client

Description

When sharing ports, clients should either relay on a single client setup or have the same setup for all of them.