1.. SPDX-License-Identifier: GPL-2.0 2 3========================== 4MHI (Modem Host Interface) 5========================== 6 7This document provides information about the MHI protocol. 8 9Overview 10======== 11 12MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used 13by the host processors to control and communicate with modem devices over high 14speed peripheral buses or shared memory. Even though MHI can be easily adapted 15to any peripheral buses, it is primarily used with PCIe based devices. MHI 16provides logical channels over the physical buses and allows transporting the 17modem protocols, such as IP data packets, modem control messages, and 18diagnostics over at least one of those logical channels. Also, the MHI 19protocol provides data acknowledgment feature and manages the power state of the 20modems via one or more logical channels. 21 22MHI Internals 23============= 24 25MMIO 26---- 27 28MMIO (Memory mapped IO) consists of a set of registers in the device hardware, 29which are mapped to the host memory space by the peripheral buses like PCIe. 30Following are the major components of MMIO register space: 31 32MHI control registers: Access to MHI configurations registers 33 34MHI BHI registers: BHI (Boot Host Interface) registers are used by the host 35for downloading the firmware to the device before MHI initialization. 36 37Channel Doorbell array: Channel Doorbell (DB) registers used by the host to 38notify the device when there is new work to do. 39 40Event 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 42available. 43 44Debug registers: A set of registers and counters used by the device to expose 45debugging information like performance, functional, and stability to the host. 46 47Data structures 48--------------- 49 50All data structures used by MHI are in the host system memory. Using the 51physical interface, the device accesses those data structures. MHI data 52structures and data buffers in the host system memory regions are mapped for 53the device. 54 55Channel context array: All channel configurations are organized in channel 56context data array. 57 58Transfer rings: Used by the host to schedule work items for a channel. The 59transfer rings are organized as a circular queue of Transfer Descriptors (TD). 60 61Event context array: All event configurations are organized in the event context 62data array. 63 64Event rings: Used by the device to send completion and state transition messages 65to the host 66 67Command context array: All command configurations are organized in command 68context data array. 69 70Command rings: Used by the host to send MHI commands to the device. The command 71rings are organized as a circular queue of Command Descriptors (CD). 72 73Channels 74-------- 75 76MHI channels are logical, unidirectional data pipes between a host and a device. 77The concept of channels in MHI is similar to endpoints in USB. MHI supports up 78to 256 channels. However, specific device implementations may support less than 79the maximum number of channels allowed. 80 81Two unidirectional channels with their associated transfer rings form a 82bidirectional data pipe, which can be used by the upper-layer protocols to 83transport application data packets (such as IP packets, modem control messages, 84diagnostics messages, and so on). Each channel is associated with a single 85transfer ring. 86 87Transfer rings 88-------------- 89 90Transfers between the host and device are organized by channels and defined by 91Transfer Descriptors (TD). TDs are managed through transfer rings, which are 92defined for each channel between the device and host and reside in the host 93memory. 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 101Below 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 113Event rings 114----------- 115 116Events from the device to host are organized in event rings and defined by Event 117Descriptors (ED). Event rings are used by the device to report events such as 118data transfer completion status, command completion status, and state changes 119to the host. Event rings are the array of EDs that resides in the host 120memory. 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 128Below 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 140Ring Element 141------------ 142 143A Ring Element is a data structure used to transfer a single block 144of data between the host and the device. Transfer ring element types contain a 145single buffer pointer, the size of the buffer, and additional control 146information. Other ring element types may only contain control and status 147information. For single buffer operations, a ring descriptor is composed of a 148single element. For large multi-buffer operations (such as scatter and gather), 149elements can be chained to form a longer descriptor. 150 151MHI Operations 152============== 153 154MHI States 155---------- 156 157MHI_STATE_RESET 158~~~~~~~~~~~~~~~ 159MHI is in reset state after power-up or hardware reset. The host is not allowed 160to access device MMIO register space. 161 162MHI_STATE_READY 163~~~~~~~~~~~~~~~ 164MHI is ready for initialization. The host can start MHI initialization by 165programming MMIO registers. 166 167MHI_STATE_M0 168~~~~~~~~~~~~ 169MHI is running and operational in the device. The host can start channels by 170issuing channel start command. 171 172MHI_STATE_M1 173~~~~~~~~~~~~ 174MHI operation is suspended by the device. This state is entered when the 175device detects inactivity at the physical interface within a preset time. 176 177MHI_STATE_M2 178~~~~~~~~~~~~ 179MHI is in low power state. MHI operation is suspended and the device may 180enter lower power mode. 181 182MHI_STATE_M3 183~~~~~~~~~~~~ 184MHI operation stopped by the host. This state is entered when the host suspends 185MHI operation. 186 187MHI Initialization 188------------------ 189 190After system boots, the device is enumerated over the physical interface. 191In the case of PCIe, the device is enumerated and assigned BAR-0 for 192the device's MMIO register space. To initialize the MHI in a device, 193the 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 201MHI Data Transfer 202----------------- 203 204MHI data transfer is initiated by the host to transfer data to the device. 205Following are the sequence of operations performed by the host to transfer 206data 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 219