tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: Add documentation for MHI bus
MHI (Modem Host Interface) is a communication protocol used by the
host processors to control and communicate with modems over a high
speed peripheral bus or shared memory. The MHI protocol has been
designed and developed by Qualcomm Innovation Center, Inc., for use
in their modems. This commit adds the documentation for the bus and
the implementation in Linux kernel.
This is based on the patch submitted by Sujeev Dias:
https://lkml.org/lkml/2018/7/9/987
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Sujeev Dias <sdias@codeaurora.org>
Signed-off-by: Siddartha Mohanadoss <smohanad@codeaurora.org>
[mani: converted to .rst and splitted the patch]
Signed-off-by: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
Reviewed-by: Jeffrey Hugo <jhugo@codeaurora.org>
Link: https://lore.kernel.org/r/20200220095854.4804-2-manivannan.sadhasivam@linaro.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Manivannan Sadhasivam
and committed by
Greg Kroah-Hartman
9435dc3b
87292bca
+297
+1
Documentation/index.rst
+1
Documentation/index.rst
+18
Documentation/mhi/index.rst
+18
Documentation/mhi/index.rst
+218
Documentation/mhi/mhi.rst
+218
Documentation/mhi/mhi.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
==========================
4
+
MHI (Modem Host Interface)
5
+
==========================
6
+
7
+
This document provides information about the MHI protocol.
8
+
9
+
Overview
10
+
========
11
+
12
+
MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used
13
+
by the host processors to control and communicate with modem devices over high
14
+
speed peripheral buses or shared memory. Even though MHI can be easily adapted
15
+
to any peripheral buses, it is primarily used with PCIe based devices. MHI
16
+
provides logical channels over the physical buses and allows transporting the
17
+
modem protocols, such as IP data packets, modem control messages, and
18
+
diagnostics over at least one of those logical channels. Also, the MHI
19
+
protocol provides data acknowledgment feature and manages the power state of the
20
+
modems via one or more logical channels.
21
+
22
+
MHI Internals
23
+
=============
24
+
25
+
MMIO
26
+
----
27
+
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 the peripheral buses like PCIe.
30
+
Following are the major components of MMIO register space:
31
+
32
+
MHI control registers: Access to MHI configurations registers
33
+
34
+
MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
35
+
for downloading the firmware to the device before MHI initialization.
36
+
37
+
Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
38
+
notify the device when there is new work to do.
39
+
40
+
Event 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
42
+
available.
43
+
44
+
Debug registers: A set of registers and counters used by the device to expose
45
+
debugging information like performance, functional, and stability to the host.
46
+
47
+
Data structures
48
+
---------------
49
+
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
53
+
the device.
54
+
55
+
Channel context array: All channel configurations are organized in channel
56
+
context data array.
57
+
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).
60
+
61
+
Event context array: All event configurations are organized in the event context
62
+
data array.
63
+
64
+
Event rings: Used by the device to send completion and state transition messages
65
+
to the host
66
+
67
+
Command context array: All command configurations are organized in command
68
+
context data array.
69
+
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).
72
+
73
+
Channels
74
+
--------
75
+
76
+
MHI channels are logical, unidirectional data pipes between a host and a device.
77
+
The concept of channels in MHI is similar to endpoints in USB. MHI supports up
78
+
to 256 channels. However, specific device implementations may support less than
79
+
the maximum number of channels allowed.
80
+
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,
84
+
diagnostics messages, and so on). Each channel is associated with a single
85
+
transfer ring.
86
+
87
+
Transfer rings
88
+
--------------
89
+
90
+
Transfers between the host and device are organized by channels and defined by
91
+
Transfer Descriptors (TD). TDs are managed through transfer rings, which are
92
+
defined for each channel between the device and host and reside in the host
93
+
memory. 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
+
101
+
Below 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
+
113
+
Event rings
114
+
-----------
115
+
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 device to report events such as
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
120
+
memory. 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
+
128
+
Below 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
+
140
+
Ring Element
141
+
------------
142
+
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
145
+
single buffer pointer, the size of the buffer, and additional control
146
+
information. Other ring element types may only contain control and status
147
+
information. For single buffer operations, a ring descriptor is composed of a
148
+
single element. For large multi-buffer operations (such as scatter and gather),
149
+
elements can be chained to form a longer descriptor.
150
+
151
+
MHI Operations
152
+
==============
153
+
154
+
MHI States
155
+
----------
156
+
157
+
MHI_STATE_RESET
158
+
~~~~~~~~~~~~~~~
159
+
MHI is in reset state after power-up or hardware reset. The host is not allowed
160
+
to access device MMIO register space.
161
+
162
+
MHI_STATE_READY
163
+
~~~~~~~~~~~~~~~
164
+
MHI is ready for initialization. The host can start MHI initialization by
165
+
programming MMIO registers.
166
+
167
+
MHI_STATE_M0
168
+
~~~~~~~~~~~~
169
+
MHI is running and operational in the device. The host can start channels by
170
+
issuing channel start command.
171
+
172
+
MHI_STATE_M1
173
+
~~~~~~~~~~~~
174
+
MHI operation is suspended by the device. This state is entered when the
175
+
device detects inactivity at the physical interface within a preset time.
176
+
177
+
MHI_STATE_M2
178
+
~~~~~~~~~~~~
179
+
MHI is in low power state. MHI operation is suspended and the device may
180
+
enter lower power mode.
181
+
182
+
MHI_STATE_M3
183
+
~~~~~~~~~~~~
184
+
MHI operation stopped by the host. This state is entered when the host suspends
185
+
MHI operation.
186
+
187
+
MHI Initialization
188
+
------------------
189
+
190
+
After system boots, the device is enumerated over the physical interface.
191
+
In the case of PCIe, the device is enumerated and assigned BAR-0 for
192
+
the device's MMIO register space. To initialize the MHI in a device,
193
+
the 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
+
201
+
MHI Data Transfer
202
+
-----------------
203
+
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:
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
+
+60
Documentation/mhi/topology.rst
+60
Documentation/mhi/topology.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
============
4
+
MHI Topology
5
+
============
6
+
7
+
This document provides information about the MHI topology modeling and
8
+
representation in the kernel.
9
+
10
+
MHI Controller
11
+
--------------
12
+
13
+
MHI controller driver manages the interaction with the MHI client devices
14
+
such as the external modems and WiFi chipsets. It is also the MHI bus master
15
+
which is in charge of managing the physical link between the host and device.
16
+
It is however not involved in the actual data transfer as the data transfer
17
+
is taken care by the physical bus such as PCIe. Each controller driver exposes
18
+
channels and events based on the client device type.
19
+
20
+
Below are the roles of the MHI controller driver:
21
+
22
+
* Turns on the physical bus and establishes the link to the device
23
+
* Configures IRQs, IOMMU, and IOMEM
24
+
* Allocates struct mhi_controller and registers with the MHI bus framework
25
+
with channel and event configurations using mhi_register_controller.
26
+
* Initiates power on and shutdown sequence
27
+
* Initiates suspend and resume power management operations of the device.
28
+
29
+
MHI Device
30
+
----------
31
+
32
+
MHI device is the logical device which binds to a maximum of two MHI channels
33
+
for bi-directional communication. Once MHI is in powered on state, the MHI
34
+
core will create MHI devices based on the channel configuration exposed
35
+
by the controller. There can be a single MHI device for each channel or for a
36
+
couple of channels.
37
+
38
+
Each supported device is enumerated in::
39
+
40
+
/sys/bus/mhi/devices/
41
+
42
+
MHI Driver
43
+
----------
44
+
45
+
MHI driver is the client driver which binds to one or more MHI devices. The MHI
46
+
driver sends and receives the upper-layer protocol packets like IP packets,
47
+
modem control messages, and diagnostics messages over MHI. The MHI core will
48
+
bind the MHI devices to the MHI driver.
49
+
50
+
Each supported driver is enumerated in::
51
+
52
+
/sys/bus/mhi/drivers/
53
+
54
+
Below are the roles of the MHI driver:
55
+
56
+
* Registers the driver with the MHI bus framework using mhi_driver_register.
57
+
* Prepares the device for transfer by calling mhi_prepare_for_transfer.
58
+
* Initiates data transfer by calling mhi_queue_transfer.
59
+
* Once the data transfer is finished, calls mhi_unprepare_from_transfer to
60
+
end data transfer.