Documentation/mhi/mhi.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 MHI (Modem Host Interface)
13 by the host processors to control and communicate with modem devices over high
26 ----
29 which are mapped to the host memory space by the peripheral buses like PCIe.
34 MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
37 Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
41 (DB) registers are used by the host to notify the device when new events are
45 debugging information like performance, functional, and stability to the host.
48 ---------------
50 All data structures used by MHI are in the host system memory. Using the
52 structures and data buffers in the host system memory regions are mapped for
58 Transfer rings: Used by the host to schedule work items for a channel. The
65 to the host
67 Command context array: All command configurations are organized in command
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).
74 --------
76 MHI channels are logical, unidirectional data pipes between a host and a device.
82 bidirectional data pipe, which can be used by the upper-layer protocols to
88 --------------
90 Transfers between the host and device are organized by channels and defined by
92 defined for each channel between the device and host and reside in the host
95         [Read Pointer (RP)] ----------->[Ring Element] } TD
96         [Write Pointer (WP)]-           [Ring Element]
97                              -          [Ring Element]
98                               --------->[Ring Element]
103 * Host allocates memory for transfer ring.
104 * Host sets the base pointer, read pointer, and write pointer in corresponding
109 * When the host has a new buffer to send, it updates the ring element with
114 -----------
116 Events from the device to host are organized in event rings and defined by Event
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
122         [Read Pointer (RP)] ----------->[Ring Element] } ED
123         [Write Pointer (WP)]-           [Ring Element]
124                              -          [Ring Element]
125                               --------->[Ring Element]
130 * Host allocates memory for event ring.
131 * Host sets the base pointer, read pointer, and write pointer in corresponding
133 * Both host and device has a local copy of RP, WP.
141 ------------
144 of data between the host and the device. Transfer ring element types contain a
148 single element. For large multi-buffer operations (such as scatter and gather),
155 ----------
159 MHI is in reset state after power-up or hardware reset. The host is not allowed
164 MHI is ready for initialization. The host can start MHI initialization by
169 MHI is running and operational in the device. The host can start channels by
170 issuing channel start command.
184 MHI operation stopped by the host. This state is entered when the host suspends
188 ------------------
191 In the case of PCIe, the device is enumerated and assigned BAR-0 for
193 the host performs the following operations:
195 * Allocates the MHI context for event, channel and command arrays.
202 -----------------
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
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.
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