0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==========================
0004 MHI (Modem Host Interface)
0005 ==========================
0006
0007 This document provides information about the MHI protocol.
0008
0009 Overview
0010 ========
0011
0012 MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used
0013 by the host processors to control and communicate with modem devices over high
0014 speed peripheral buses or shared memory. Even though MHI can be easily adapted
0015 to any peripheral buses, it is primarily used with PCIe based devices. MHI
0016 provides logical channels over the physical buses and allows transporting the
0017 modem protocols, such as IP data packets, modem control messages, and
0018 diagnostics over at least one of those logical channels. Also, the MHI
0019 protocol provides data acknowledgment feature and manages the power state of the
0020 modems via one or more logical channels.
0021
0022 MHI Internals
0023 =============
0024
0025 MMIO
0026 ----
0027
0028 MMIO (Memory mapped IO) consists of a set of registers in the device hardware,
0029 which are mapped to the host memory space by the peripheral buses like PCIe.
0030 Following are the major components of MMIO register space:
0031
0032 MHI control registers: Access to MHI configurations registers
0033
0034 MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
0035 for downloading the firmware to the device before MHI initialization.
0036
0037 Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
0038 notify the device when there is new work to do.
0039
0040 Event Doorbell array: Associated with event context array, the Event Doorbell
0041 (DB) registers are used by the host to notify the device when new events are
0042 available.
0043
0044 Debug registers: A set of registers and counters used by the device to expose
0045 debugging information like performance, functional, and stability to the host.
0046
0047 Data structures
0048 ---------------
0049
0050 All data structures used by MHI are in the host system memory. Using the
0051 physical interface, the device accesses those data structures. MHI data
0052 structures and data buffers in the host system memory regions are mapped for
0053 the device.
0054
0055 Channel context array: All channel configurations are organized in channel
0056 context data array.
0057
0058 Transfer rings: Used by the host to schedule work items for a channel. The
0059 transfer rings are organized as a circular queue of Transfer Descriptors (TD).
0060
0061 Event context array: All event configurations are organized in the event context
0062 data array.
0063
0064 Event rings: Used by the device to send completion and state transition messages
0065 to the host
0066
0067 Command context array: All command configurations are organized in command
0068 context data array.
0069
0070 Command rings: Used by the host to send MHI commands to the device. The command
0071 rings are organized as a circular queue of Command Descriptors (CD).
0072
0073 Channels
0074 --------
0075
0076 MHI channels are logical, unidirectional data pipes between a host and a device.
0077 The concept of channels in MHI is similar to endpoints in USB. MHI supports up
0078 to 256 channels. However, specific device implementations may support less than
0079 the maximum number of channels allowed.
0080
0081 Two unidirectional channels with their associated transfer rings form a
0082 bidirectional data pipe, which can be used by the upper-layer protocols to
0083 transport application data packets (such as IP packets, modem control messages,
0084 diagnostics messages, and so on). Each channel is associated with a single
0085 transfer ring.
0086
0087 Transfer rings
0088 --------------
0089
0090 Transfers between the host and device are organized by channels and defined by
0091 Transfer Descriptors (TD). TDs are managed through transfer rings, which are
0092 defined for each channel between the device and host and reside in the host
0093 memory. TDs consist of one or more ring elements (or transfer blocks)::
0094
0095 [Read Pointer (RP)] ----------->[Ring Element] } TD
0096 [Write Pointer (WP)]- [Ring Element]
0097 - [Ring Element]
0098 --------->[Ring Element]
0099 [Ring Element]
0100
0101 Below is the basic usage of transfer rings:
0102
0103 * Host allocates memory for transfer ring.
0104 * Host sets the base pointer, read pointer, and write pointer in corresponding
0105 channel context.
0106 * Ring is considered empty when RP == WP.
0107 * Ring is considered full when WP + 1 == RP.
0108 * RP indicates the next element to be serviced by the device.
0109 * When the host has a new buffer to send, it updates the ring element with
0110 buffer information, increments the WP to the next element and rings the
0111 associated channel DB.
0112
0113 Event rings
0114 -----------
0115
0116 Events from the device to host are organized in event rings and defined by Event
0117 Descriptors (ED). Event rings are used by the device to report events such as
0118 data transfer completion status, command completion status, and state changes
0119 to the host. Event rings are the array of EDs that resides in the host
0120 memory. EDs consist of one or more ring elements (or transfer blocks)::
0121
0122 [Read Pointer (RP)] ----------->[Ring Element] } ED
0123 [Write Pointer (WP)]- [Ring Element]
0124 - [Ring Element]
0125 --------->[Ring Element]
0126 [Ring Element]
0127
0128 Below is the basic usage of event rings:
0129
0130 * Host allocates memory for event ring.
0131 * Host sets the base pointer, read pointer, and write pointer in corresponding
0132 channel context.
0133 * Both host and device has a local copy of RP, WP.
0134 * Ring is considered empty (no events to service) when WP + 1 == RP.
0135 * Ring is considered full of events when RP == WP.
0136 * When there is a new event the device needs to send, the device updates ED
0137 pointed by RP, increments the RP to the next element and triggers the
0138 interrupt.
0139
0140 Ring Element
0141 ------------
0142
0143 A Ring Element is a data structure used to transfer a single block
0144 of data between the host and the device. Transfer ring element types contain a
0145 single buffer pointer, the size of the buffer, and additional control
0146 information. Other ring element types may only contain control and status
0147 information. For single buffer operations, a ring descriptor is composed of a
0148 single element. For large multi-buffer operations (such as scatter and gather),
0149 elements can be chained to form a longer descriptor.
0150
0151 MHI Operations
0152 ==============
0153
0154 MHI States
0155 ----------
0156
0157 MHI_STATE_RESET
0158 ~~~~~~~~~~~~~~~
0159 MHI is in reset state after power-up or hardware reset. The host is not allowed
0160 to access device MMIO register space.
0161
0162 MHI_STATE_READY
0163 ~~~~~~~~~~~~~~~
0164 MHI is ready for initialization. The host can start MHI initialization by
0165 programming MMIO registers.
0166
0167 MHI_STATE_M0
0168 ~~~~~~~~~~~~
0169 MHI is running and operational in the device. The host can start channels by
0170 issuing channel start command.
0171
0172 MHI_STATE_M1
0173 ~~~~~~~~~~~~
0174 MHI operation is suspended by the device. This state is entered when the
0175 device detects inactivity at the physical interface within a preset time.
0176
0177 MHI_STATE_M2
0178 ~~~~~~~~~~~~
0179 MHI is in low power state. MHI operation is suspended and the device may
0180 enter lower power mode.
0181
0182 MHI_STATE_M3
0183 ~~~~~~~~~~~~
0184 MHI operation stopped by the host. This state is entered when the host suspends
0185 MHI operation.
0186
0187 MHI Initialization
0188 ------------------
0189
0190 After system boots, the device is enumerated over the physical interface.
0191 In the case of PCIe, the device is enumerated and assigned BAR-0 for
0192 the device's MMIO register space. To initialize the MHI in a device,
0193 the host performs the following operations:
0194
0195 * Allocates the MHI context for event, channel and command arrays.
0196 * Initializes the context array, and prepares interrupts.
0197 * Waits until the device enters READY state.
0198 * Programs MHI MMIO registers and sets device into MHI_M0 state.
0199 * Waits for the device to enter M0 state.
0200
0201 MHI Data Transfer
0202 -----------------
0203
0204 MHI data transfer is initiated by the host to transfer data to the device.
0205 Following are the sequence of operations performed by the host to transfer
0206 data to device:
0207
0208 * Host prepares TD with buffer information.
0209 * Host increments the WP of the corresponding channel transfer ring.
0210 * Host rings the channel DB register.
0211 * Device wakes up to process the TD.
0212 * Device generates a completion event for the processed TD by updating ED.
0213 * Device increments the RP of the corresponding event ring.
0214 * Device triggers IRQ to wake up the host.
0215 * Host wakes up and checks the event ring for completion event.
0216 * Host updates the WP of the corresponding event ring to indicate that the
0217 data transfer has been completed successfully.
0218
