Documentation/mhi/mhi.rst

1 .. SPDX-License-Identifier: GPL-2.0
17 modem protocols, such as IP data packets, modem control messages, and
19 protocol provides data acknowledgment feature and manages the power state of the
26 ----
47 Data structures
48 ---------------
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
56 context data array.
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).
62 data array.
68 context data array.
74 --------
76 MHI channels are logical, unidirectional data pipes between a host and a device.
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,
85 transfer ring.
87 Transfer rings
88 --------------
91 Transfer Descriptors (TD). TDs are managed through transfer rings, which are
93 memory. TDs consist of one or more ring elements (or transfer blocks)::
95         [Read Pointer (RP)] ----------->[Ring Element] } TD
96         [Write Pointer (WP)]-           [Ring Element]
97                              -          [Ring Element]
98                               --------->[Ring Element]
101 Below is the basic usage of transfer rings:
103 * Host allocates memory for transfer ring.
114 -----------
118 data transfer completion status, command completion status, and state changes
120 memory. EDs consist of one or more ring elements (or transfer blocks)::
122         [Read Pointer (RP)] ----------->[Ring Element] } ED
123         [Write Pointer (WP)]-           [Ring Element]
124                              -          [Ring Element]
125                               --------->[Ring Element]
141 ------------
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
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
188 ------------------
191 In the case of PCIe, the device is enumerated and assigned BAR-0 for
201 MHI Data Transfer
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
206 data to device:
209 * Host increments the WP of the corresponding channel transfer ring.
217   data transfer has been completed successfully.