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