[linux.git] / Documentation / mhi / mhi.rst

.. SPDX-License-Identifier: GPL-2.0

==========================
MHI (Modem Host Interface)
==========================

This document provides information about the MHI protocol.

Overview
========

MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used
by the host processors to control and communicate with modem devices over high
speed peripheral buses or shared memory. Even though MHI can be easily adapted
to any peripheral buses, it is primarily used with PCIe based devices. MHI
provides logical channels over the physical buses and allows transporting the
modem protocols, such as IP data packets, modem control messages, and
diagnostics over at least one of those logical channels. Also, the MHI
protocol provides data acknowledgment feature and manages the power state of the
modems via one or more logical channels.

MHI Internals
=============

MMIO
----

MMIO (Memory mapped IO) consists of a set of registers in the device hardware,
which are mapped to the host memory space by the peripheral buses like PCIe.
Following are the major components of MMIO register space:

MHI control registers: Access to MHI configurations registers

MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
for downloading the firmware to the device before MHI initialization.

Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
notify the device when there is new work to do.

Event Doorbell array: Associated with event context array, the Event Doorbell
(DB) registers are used by the host to notify the device when new events are
available.

Debug registers: A set of registers and counters used by the device to expose
debugging information like performance, functional, and stability to the host.

Data structures
---------------

All data structures used by MHI are in the host system memory. Using the
physical interface, the device accesses those data structures. MHI data
structures and data buffers in the host system memory regions are mapped for
the device.

Channel context array: All channel configurations are organized in channel
context data array.

Transfer rings: Used by the host to schedule work items for a channel. The
transfer rings are organized as a circular queue of Transfer Descriptors (TD).

Event context array: All event configurations are organized in the event context
data array.

Event rings: Used by the device to send completion and state transition messages
to the host

Command context array: All command configurations are organized in command
context data array.

Command rings: Used by the host to send MHI commands to the device. The command
rings are organized as a circular queue of Command Descriptors (CD).

Channels
--------

MHI channels are logical, unidirectional data pipes between a host and a device.
The concept of channels in MHI is similar to endpoints in USB. MHI supports up
to 256 channels. However, specific device implementations may support less than
the maximum number of channels allowed.

Two unidirectional channels with their associated transfer rings form a
bidirectional data pipe, which can be used by the upper-layer protocols to
transport application data packets (such as IP packets, modem control messages,
diagnostics messages, and so on). Each channel is associated with a single
transfer ring.

Transfer rings
--------------

Transfers between the host and device are organized by channels and defined by
Transfer Descriptors (TD). TDs are managed through transfer rings, which are
defined for each channel between the device and host and reside in the host
memory. TDs consist of one or more ring elements (or transfer blocks)::

        [Read Pointer (RP)] ----------->[Ring Element] } TD
        [Write Pointer (WP)]-           [Ring Element]
                             -          [Ring Element]
                              --------->[Ring Element]
                                        [Ring Element]

Below is the basic usage of transfer rings:

* Host allocates memory for transfer ring.
* Host sets the base pointer, read pointer, and write pointer in corresponding
  channel context.
* Ring is considered empty when RP == WP.
* Ring is considered full when WP + 1 == RP.
* RP indicates the next element to be serviced by the device.
* When the host has a new buffer to send, it updates the ring element with
  buffer information, increments the WP to the next element and rings the
  associated channel DB.

Event rings
-----------

Events from the device to host are organized in event rings and defined by Event
Descriptors (ED). Event rings are used by the device to report events such as
data transfer completion status, command completion status, and state changes
to the host. Event rings are the array of EDs that resides in the host
memory. EDs consist of one or more ring elements (or transfer blocks)::

        [Read Pointer (RP)] ----------->[Ring Element] } ED
        [Write Pointer (WP)]-           [Ring Element]
                             -          [Ring Element]
                              --------->[Ring Element]
                                        [Ring Element]

Below is the basic usage of event rings:

* Host allocates memory for event ring.
* Host sets the base pointer, read pointer, and write pointer in corresponding
  channel context.
* Both host and device has a local copy of RP, WP.
* Ring is considered empty (no events to service) when WP + 1 == RP.
* Ring is considered full of events when RP == WP.
* When there is a new event the device needs to send, the device updates ED
  pointed by RP, increments the RP to the next element and triggers the
  interrupt.

Ring Element
------------

A Ring Element is a data structure used to transfer a single block
of data between the host and the device. Transfer ring element types contain a
single buffer pointer, the size of the buffer, and additional control
information. Other ring element types may only contain control and status
information. For single buffer operations, a ring descriptor is composed of a
single element. For large multi-buffer operations (such as scatter and gather),
elements can be chained to form a longer descriptor.

MHI Operations
==============

MHI States
----------

MHI_STATE_RESET
~~~~~~~~~~~~~~~
MHI is in reset state after power-up or hardware reset. The host is not allowed
to access device MMIO register space.

MHI_STATE_READY
~~~~~~~~~~~~~~~
MHI is ready for initialization. The host can start MHI initialization by
programming MMIO registers.

MHI_STATE_M0
~~~~~~~~~~~~
MHI is running and operational in the device. The host can start channels by
issuing channel start command.

MHI_STATE_M1
~~~~~~~~~~~~
MHI operation is suspended by the device. This state is entered when the
device detects inactivity at the physical interface within a preset time.

MHI_STATE_M2
~~~~~~~~~~~~
MHI is in low power state. MHI operation is suspended and the device may
enter lower power mode.

MHI_STATE_M3
~~~~~~~~~~~~
MHI operation stopped by the host. This state is entered when the host suspends
MHI operation.

MHI Initialization
------------------

After system boots, the device is enumerated over the physical interface.
In the case of PCIe, the device is enumerated and assigned BAR-0 for
the device's MMIO register space. To initialize the MHI in a device,
the host performs the following operations:

* Allocates the MHI context for event, channel and command arrays.
* Initializes the context array, and prepares interrupts.
* Waits until the device enters READY state.
* Programs MHI MMIO registers and sets device into MHI_M0 state.
* Waits for the device to enter M0 state.

MHI Data Transfer
-----------------

MHI data transfer is initiated by the host to transfer data to the device.
Following are the sequence of operations performed by the host to transfer
data to device:

* Host prepares TD with buffer information.
* Host increments the WP of the corresponding channel transfer ring.
* Host rings the channel DB register.
* Device wakes up to process the TD.
* Device generates a completion event for the processed TD by updating ED.
* Device increments the RP of the corresponding event ring.
* Device triggers IRQ to wake up the host.
* Host wakes up and checks the event ring for completion event.
* Host updates the WP of the corresponding event ring to indicate that the
  data transfer has been completed successfully.
Commit	Line	Data
9435dc3b MS	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	==========================
	4	MHI (Modem Host Interface)
	5	==========================
	6
	7	This document provides information about the MHI protocol.
	8
	9	Overview
	10	========
	11
	12	MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used
	13	by the host processors to control and communicate with modem devices over high
	14	speed peripheral buses or shared memory. Even though MHI can be easily adapted
	15	to any peripheral buses, it is primarily used with PCIe based devices. MHI
	16	provides logical channels over the physical buses and allows transporting the
	17	modem protocols, such as IP data packets, modem control messages, and
	18	diagnostics over at least one of those logical channels. Also, the MHI
	19	protocol provides data acknowledgment feature and manages the power state of the
	20	modems via one or more logical channels.
	21
	22	MHI Internals
	23	=============
	24
	25	MMIO
	26	----
	27
	28	MMIO (Memory mapped IO) consists of a set of registers in the device hardware,
	29	which are mapped to the host memory space by the peripheral buses like PCIe.
	30	Following are the major components of MMIO register space:
	31
	32	MHI control registers: Access to MHI configurations registers
	33
	34	MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
	35	for downloading the firmware to the device before MHI initialization.
	36
	37	Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
	38	notify the device when there is new work to do.
	39
	40	Event Doorbell array: Associated with event context array, the Event Doorbell
	41	(DB) registers are used by the host to notify the device when new events are
	42	available.
	43
	44	Debug registers: A set of registers and counters used by the device to expose
	45	debugging information like performance, functional, and stability to the host.
	46
	47	Data structures
	48	---------------
	49
	50	All data structures used by MHI are in the host system memory. Using the
	51	physical interface, the device accesses those data structures. MHI data
	52	structures and data buffers in the host system memory regions are mapped for
	53	the device.
	54
	55	Channel context array: All channel configurations are organized in channel
	56	context data array.
	57
	58	Transfer rings: Used by the host to schedule work items for a channel. The
	59	transfer rings are organized as a circular queue of Transfer Descriptors (TD).
	60
	61	Event context array: All event configurations are organized in the event context
	62	data array.
	63
	64	Event rings: Used by the device to send completion and state transition messages
65	to the host
66
67	Command context array: All command configurations are organized in command
68	context data array.
69
70	Command rings: Used by the host to send MHI commands to the device. The command
71	rings are organized as a circular queue of Command Descriptors (CD).
72
73	Channels
74	--------
75
76	MHI channels are logical, unidirectional data pipes between a host and a device.
77	The concept of channels in MHI is similar to endpoints in USB. MHI supports up
78	to 256 channels. However, specific device implementations may support less than
79	the maximum number of channels allowed.
80
81	Two unidirectional channels with their associated transfer rings form a
82	bidirectional data pipe, which can be used by the upper-layer protocols to
83	transport application data packets (such as IP packets, modem control messages,
84	diagnostics messages, and so on). Each channel is associated with a single
85	transfer ring.
86
87	Transfer rings
88	--------------
89
90	Transfers between the host and device are organized by channels and defined by
91	Transfer Descriptors (TD). TDs are managed through transfer rings, which are
92	defined for each channel between the device and host and reside in the host
93	memory. TDs consist of one or more ring elements (or transfer blocks)::
94
95	[Read Pointer (RP)] ----------->[Ring Element] } TD
96	[Write Pointer (WP)]- [Ring Element]
97	- [Ring Element]
98	--------->[Ring Element]
99	[Ring Element]
100
101	Below is the basic usage of transfer rings:
102
103	* Host allocates memory for transfer ring.
104	* Host sets the base pointer, read pointer, and write pointer in corresponding
105	channel context.
106	* Ring is considered empty when RP == WP.
107	* Ring is considered full when WP + 1 == RP.
108	* RP indicates the next element to be serviced by the device.
109	* When the host has a new buffer to send, it updates the ring element with
110	buffer information, increments the WP to the next element and rings the
111	associated channel DB.
112
113	Event rings
114	-----------
115
116	Events from the device to host are organized in event rings and defined by Event
117	Descriptors (ED). Event rings are used by the device to report events such as
118	data transfer completion status, command completion status, and state changes
119	to the host. Event rings are the array of EDs that resides in the host
120	memory. EDs consist of one or more ring elements (or transfer blocks)::
121
122	[Read Pointer (RP)] ----------->[Ring Element] } ED
123	[Write Pointer (WP)]- [Ring Element]
124	- [Ring Element]
125	--------->[Ring Element]
126	[Ring Element]
127
128	Below is the basic usage of event rings:
129
130	* Host allocates memory for event ring.
131	* Host sets the base pointer, read pointer, and write pointer in corresponding
132	channel context.
133	* Both host and device has a local copy of RP, WP.
134	* Ring is considered empty (no events to service) when WP + 1 == RP.
135	* Ring is considered full of events when RP == WP.
136	* When there is a new event the device needs to send, the device updates ED
137	pointed by RP, increments the RP to the next element and triggers the
138	interrupt.
139
140	Ring Element
141	------------
142
143	A Ring Element is a data structure used to transfer a single block
144	of data between the host and the device. Transfer ring element types contain a
145	single buffer pointer, the size of the buffer, and additional control
146	information. Other ring element types may only contain control and status
147	information. For single buffer operations, a ring descriptor is composed of a
148	single element. For large multi-buffer operations (such as scatter and gather),
149	elements can be chained to form a longer descriptor.
150
151	MHI Operations
152	==============
153
154	MHI States
155	----------
156
157	MHI_STATE_RESET
158	~~~~~~~~~~~~~~~
159	MHI is in reset state after power-up or hardware reset. The host is not allowed
160	to access device MMIO register space.
161
162	MHI_STATE_READY
163	~~~~~~~~~~~~~~~
164	MHI is ready for initialization. The host can start MHI initialization by
165	programming MMIO registers.
166
167	MHI_STATE_M0
168	~~~~~~~~~~~~
169	MHI is running and operational in the device. The host can start channels by
170	issuing channel start command.
171
172	MHI_STATE_M1
173	~~~~~~~~~~~~
174	MHI operation is suspended by the device. This state is entered when the
175	device detects inactivity at the physical interface within a preset time.
176
177	MHI_STATE_M2
178	~~~~~~~~~~~~
179	MHI is in low power state. MHI operation is suspended and the device may
180	enter lower power mode.
181
182	MHI_STATE_M3
183	~~~~~~~~~~~~
184	MHI operation stopped by the host. This state is entered when the host suspends
185	MHI operation.
186
187	MHI Initialization
188	------------------
189
190	After system boots, the device is enumerated over the physical interface.
191	In the case of PCIe, the device is enumerated and assigned BAR-0 for
192	the device's MMIO register space. To initialize the MHI in a device,
193	the host performs the following operations:
194
195	* Allocates the MHI context for event, channel and command arrays.
196	* Initializes the context array, and prepares interrupts.
197	* Waits until the device enters READY state.
198	* Programs MHI MMIO registers and sets device into MHI_M0 state.
199	* Waits for the device to enter M0 state.
200
201	MHI Data Transfer
202	-----------------
203
204	MHI data transfer is initiated by the host to transfer data to the device.
205	Following are the sequence of operations performed by the host to transfer
206	data to device:
207
208	* Host prepares TD with buffer information.
209	* Host increments the WP of the corresponding channel transfer ring.
210	* Host rings the channel DB register.
211	* Device wakes up to process the TD.
212	* Device generates a completion event for the processed TD by updating ED.
213	* Device increments the RP of the corresponding event ring.
214	* Device triggers IRQ to wake up the host.
215	* Host wakes up and checks the event ring for completion event.
216	* Host updates the WP of the corresponding event ring to indicate that the
217	data transfer has been completed successfully.
218