MHI (Modem Host Interface)

MHI protocol

이 문서는 MHI(Modem Host Interface) protocol에 관한 정보를 제공합니다.

.. SPDX-License-Identifier: GPL-2.0

==========================
MHI (Modem Host Interface)
==========================

This document provides information about the MHI protocol.

개요

MHI는 Qualcomm Innovation Center, Inc.가 개발한 protocol입니다. Host processor가 고속 peripheral bus 또는 shared memory를 통해 modem device를 제어하고 통신하는 데 사용합니다. 여러 peripheral bus에 쉽게 적용할 수 있지만 주로 PCIe 기반 device에서 사용합니다.

MHI는 physical bus 위에 logical channel을 제공하며 IP data packet, modem control message, diagnostic 같은 modem protocol을 하나 이상의 logical channel로 운반합니다. 또한 data acknowledgment 기능을 제공하고 하나 이상의 logical channel을 통해 modem의 power state를 관리합니다.

Overview
========

MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used
by the host processors to control and communicate with modem devices over high
speed peripheral buses or shared memory. Even though MHI can be easily adapted
to any peripheral buses, it is primarily used with PCIe based devices. MHI
provides logical channels over the physical buses and allows transporting the
modem protocols, such as IP data packets, modem control messages, and
diagnostics over at least one of those logical channels. Also, the MHI
protocol provides data acknowledgment feature and manages the power state of the
modems via one or more logical channels.

MMIO register 공간

MMIO(Memory mapped IO)는 device hardware의 register 집합이며 PCIe 같은 peripheral bus가 host memory 공간에 mapping합니다. 주요 구성 요소는 다음과 같습니다.

• MHI control register: MHI configuration register에 접근합니다.
• MHI BHI register: BHI(Boot Host Interface) register는 MHI 초기화 전에 host가 firmware를 device로 내려보낼 때 사용합니다.
• Channel Doorbell array: 새 작업이 있음을 host가 device에 알리는 Channel Doorbell(DB) register입니다.
• Event Doorbell array: event context array와 연결되며 새 event를 사용할 수 있음을 host가 device에 알리는 Event Doorbell(DB) register입니다.
• Debug register: device가 performance, function, stability 같은 debugging 정보를 host에 공개하는 register와 counter 집합입니다.

MHI Internals
=============

MMIO
----

MMIO (Memory mapped IO) consists of a set of registers in the device hardware,
which are mapped to the host memory space by the peripheral buses like PCIe.
Following are the major components of MMIO register space:

MHI control registers: Access to MHI configurations registers

MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
for downloading the firmware to the device before MHI initialization.

Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
notify the device when there is new work to do.

Event Doorbell array: Associated with event context array, the Event Doorbell
(DB) registers are used by the host to notify the device when new events are
available.

Debug registers: A set of registers and counters used by the device to expose
debugging information like performance, functional, and stability to the host.

Host memory의 data structure

MHI가 사용하는 모든 data structure는 host system memory에 있습니다. Device는 physical interface를 통해 이 structure에 접근하며, host memory 영역의 MHI data structure와 data buffer는 device가 접근할 수 있도록 mapping됩니다.

• Channel context array: 모든 channel configuration을 channel context data array에 구성합니다.
• Transfer ring: host가 channel 작업 항목을 schedule합니다. Transfer Descriptor(TD)의 circular queue로 구성됩니다.
• Event context array: 모든 event configuration을 event context data array에 구성합니다.
• Event ring: device가 completion과 state transition message를 host에 보냅니다.
• Command context array: 모든 command configuration을 command context data array에 구성합니다.
• Command ring: host가 MHI command를 device에 보냅니다. Command Descriptor(CD)의 circular queue로 구성됩니다.

Data structures
---------------

All data structures used by MHI are in the host system memory. Using the
physical interface, the device accesses those data structures. MHI data
structures and data buffers in the host system memory regions are mapped for
the device.

Channel context array: All channel configurations are organized in channel
context data array.

Transfer rings: Used by the host to schedule work items for a channel. The
transfer rings are organized as a circular queue of Transfer Descriptors (TD).

Event context array: All event configurations are organized in the event context
data array.

Event rings: Used by the device to send completion and state transition messages
to the host

Command context array: All command configurations are organized in command
context data array.

Command rings: Used by the host to send MHI commands to the device. The command
rings are organized as a circular queue of Command Descriptors (CD).

Logical channel

MHI channel은 host와 device 사이의 logical·unidirectional data pipe입니다. USB endpoint와 비슷하며 MHI는 최대 256개 channel을 지원하지만 실제 device 구현은 그보다 적을 수 있습니다.

서로 반대 방향인 두 unidirectional channel과 각각의 transfer ring을 묶으면 bidirectional data pipe가 됩니다. Upper-layer protocol은 이를 통해 IP packet, modem control message, diagnostic message 같은 application data를 운반합니다. 각 channel에는 transfer ring 하나가 연결됩니다.

Channels
--------

MHI channels are logical, unidirectional data pipes between a host and a device.
The concept of channels in MHI is similar to endpoints in USB. MHI supports up
to 256 channels. However, specific device implementations may support less than
the maximum number of channels allowed.

Two unidirectional channels with their associated transfer rings form a
bidirectional data pipe, which can be used by the upper-layer protocols to
transport application data packets (such as IP packets, modem control messages,
diagnostics messages, and so on). Each channel is associated with a single
transfer ring.

Transfer ring

Host와 device 사이의 transfer는 channel별로 구성되며 Transfer Descriptor(TD)로 정의됩니다. 각 channel의 transfer ring이 TD를 관리하고 host memory에 위치합니다. TD는 하나 이상의 ring element, 즉 transfer block으로 구성됩니다.

• Host가 transfer ring용 memory를 할당합니다.
• 해당 channel context에 base pointer, read pointer, write pointer를 설정합니다.
• RP == WP이면 ring은 비어 있습니다.
• WP + 1 == RP이면 ring은 가득 찼습니다.
• RP는 device가 다음에 처리할 element를 가리킵니다.
• 새 buffer를 보낼 때 host는 ring element에 buffer 정보를 기록하고 WP를 다음 element로 증가시킨 뒤 연결된 channel DB를 울립니다.

Transfer rings
--------------

Transfers between the host and device are organized by channels and defined by
Transfer Descriptors (TD). TDs are managed through transfer rings, which are
defined for each channel between the device and host and reside in the host
memory. TDs consist of one or more ring elements (or transfer blocks)::

        [Read Pointer (RP)] ----------->[Ring Element] } TD
        [Write Pointer (WP)]-           [Ring Element]
                             -          [Ring Element]
                              --------->[Ring Element]
                                        [Ring Element]

Below is the basic usage of transfer rings:

* Host allocates memory for transfer ring.
* Host sets the base pointer, read pointer, and write pointer in corresponding
  channel context.
* Ring is considered empty when RP == WP.
* Ring is considered full when WP + 1 == RP.
* RP indicates the next element to be serviced by the device.
* When the host has a new buffer to send, it updates the ring element with
  buffer information, increments the WP to the next element and rings the
  associated channel DB.

Event ring

Device에서 host로 향하는 event는 event ring에 구성되고 Event Descriptor(ED)로 정의됩니다. Device는 data transfer 완료 상태, command 완료 상태, state 변경을 host에 보고합니다. Host memory에 있는 ED array이며 ED는 하나 이상의 ring element, 즉 transfer block으로 구성됩니다.

• Host가 event ring용 memory를 할당합니다.
• 해당 channel context에 base pointer, read pointer, write pointer를 설정합니다.
• Host와 device가 각각 RP와 WP의 local copy를 가집니다.
• WP + 1 == RP이면 처리할 event가 없어 ring이 비어 있습니다.
• RP == WP이면 event로 ring이 가득 찼습니다.
• 새 event가 생기면 device가 RP가 가리키는 ED를 갱신하고 RP를 다음 element로 증가시킨 뒤 interrupt를 발생시킵니다.

Event rings
-----------

Events from the device to host are organized in event rings and defined by Event
Descriptors (ED). Event rings are used by the device to report events such as
data transfer completion status, command completion status, and state changes
to the host. Event rings are the array of EDs that resides in the host
memory. EDs consist of one or more ring elements (or transfer blocks)::

        [Read Pointer (RP)] ----------->[Ring Element] } ED
        [Write Pointer (WP)]-           [Ring Element]
                             -          [Ring Element]
                              --------->[Ring Element]
                                        [Ring Element]

Below is the basic usage of event rings:

* Host allocates memory for event ring.
* Host sets the base pointer, read pointer, and write pointer in corresponding
  channel context.
* Both host and device has a local copy of RP, WP.
* Ring is considered empty (no events to service) when WP + 1 == RP.
* Ring is considered full of events when RP == WP.
* When there is a new event the device needs to send, the device updates ED
  pointed by RP, increments the RP to the next element and triggers the
  interrupt.

Ring element

Ring Element는 host와 device 사이에서 data block 하나를 전달하는 data structure입니다. Transfer ring element는 buffer pointer 하나, buffer 크기, 추가 control 정보를 담습니다. 다른 ring element 유형은 control과 status 정보만 담을 수 있습니다.

Single-buffer 작업의 ring descriptor는 element 하나로 구성됩니다. Scatter/gather 같은 큰 multi-buffer 작업은 여러 element를 연결해 더 긴 descriptor를 만듭니다.

Ring Element
------------

A Ring Element is a data structure used to transfer a single block
of data between the host and the device. Transfer ring element types contain a
single buffer pointer, the size of the buffer, and additional control
information. Other ring element types may only contain control and status
information. For single buffer operations, a ring descriptor is composed of a
single element. For large multi-buffer operations (such as scatter and gather),
elements can be chained to form a longer descriptor.

MHI state

`MHI_STATE_RESET`: power-up 또는 hardware reset 뒤의 reset 상태입니다. Host는 device MMIO register 공간에 접근할 수 없습니다.

`MHI_STATE_READY`: 초기화 준비 상태입니다. Host는 MMIO register를 programming해 MHI 초기화를 시작할 수 있습니다.

`MHI_STATE_M0`: MHI가 device에서 실행 중이며 동작 가능한 상태입니다. Host는 channel start command로 channel을 시작할 수 있습니다.

`MHI_STATE_M1`: device가 MHI 동작을 suspend한 상태입니다. Physical interface에서 미리 정한 시간 동안 activity가 없으면 진입합니다.

`MHI_STATE_M2`: low-power 상태입니다. MHI 동작은 suspend되고 device는 더 낮은 power mode로 들어갈 수 있습니다.

`MHI_STATE_M3`: host가 MHI 동작을 중지한 상태입니다. Host가 MHI 동작을 suspend할 때 진입합니다.

MHI Operations
==============

MHI States
----------

MHI_STATE_RESET
~~~~~~~~~~~~~~~
MHI is in reset state after power-up or hardware reset. The host is not allowed
to access device MMIO register space.

MHI_STATE_READY
~~~~~~~~~~~~~~~
MHI is ready for initialization. The host can start MHI initialization by
programming MMIO registers.

MHI_STATE_M0
~~~~~~~~~~~~
MHI is running and operational in the device. The host can start channels by
issuing channel start command.

MHI_STATE_M1
~~~~~~~~~~~~
MHI operation is suspended by the device. This state is entered when the
device detects inactivity at the physical interface within a preset time.

MHI_STATE_M2
~~~~~~~~~~~~
MHI is in low power state. MHI operation is suspended and the device may
enter lower power mode.

MHI_STATE_M3
~~~~~~~~~~~~
MHI operation stopped by the host. This state is entered when the host suspends
MHI operation.

MHI 초기화

System boot 뒤 device가 physical interface에서 enumerate됩니다. PCIe에서는 device를 enumerate하고 MMIO register 공간에 BAR-0을 할당합니다. Host의 초기화 절차는 다음과 같습니다.

• Event, channel, command array용 MHI context를 할당합니다.
• Context array를 초기화하고 interrupt를 준비합니다.
• Device가 READY state에 들어갈 때까지 기다립니다.
• MHI MMIO register를 programming하고 device를 MHI_M0 state로 설정합니다.
• Device가 M0 state에 들어갈 때까지 기다립니다.

MHI Initialization
------------------

After system boots, the device is enumerated over the physical interface.
In the case of PCIe, the device is enumerated and assigned BAR-0 for
the device's MMIO register space. To initialize the MHI in a device,
the host performs the following operations:

* Allocates the MHI context for event, channel and command arrays.
* Initializes the context array, and prepares interrupts.
* Waits until the device enters READY state.
* Programs MHI MMIO registers and sets device into MHI_M0 state.
* Waits for the device to enter M0 state.

MHI data transfer

Device로 data를 보내는 MHI transfer는 host가 시작합니다. Host와 device는 다음 순서로 동작합니다.

• Host가 buffer 정보를 담은 TD를 준비합니다.
• 해당 channel transfer ring의 WP를 증가시킵니다.
• Host가 channel DB register를 울립니다.
• Device가 깨어나 TD를 처리합니다.
• Device가 ED를 갱신해 처리한 TD의 completion event를 만듭니다.
• Device가 해당 event ring의 RP를 증가시킵니다.
• Device가 IRQ를 발생시켜 host를 깨웁니다.
• Host가 깨어나 event ring에서 completion event를 확인합니다.
• Host가 해당 event ring의 WP를 갱신해 data transfer가 성공적으로 끝났음을 나타냅니다.

MHI Data Transfer
-----------------

MHI data transfer is initiated by the host to transfer data to the device.
Following are the sequence of operations performed by the host to transfer
data to device:

* Host prepares TD with buffer information.
* Host increments the WP of the corresponding channel transfer ring.
* Host rings the channel DB register.
* Device wakes up to process the TD.
* Device generates a completion event for the processed TD by updating ED.
* Device increments the RP of the corresponding event ring.
* Device triggers IRQ to wake up the host.
* Host wakes up and checks the event ring for completion event.
* Host updates the WP of the corresponding event ring to indicate that the
  data transfer has been completed successfully.