Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) MHI (Modem Host Interface)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) This document provides information about the MHI protocol.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) MHI is a protocol developed by Qualcomm Innovation Center, Inc. It is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) by the host processors to control and communicate with modem devices over high
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) speed peripheral buses or shared memory. Even though MHI can be easily adapted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) to any peripheral buses, it is primarily used with PCIe based devices. MHI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) provides logical channels over the physical buses and allows transporting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) modem protocols, such as IP data packets, modem control messages, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) diagnostics over at least one of those logical channels. Also, the MHI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) protocol provides data acknowledgment feature and manages the power state of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) modems via one or more logical channels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) MHI Internals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) MMIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) MMIO (Memory mapped IO) consists of a set of registers in the device hardware,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) which are mapped to the host memory space by the peripheral buses like PCIe.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) Following are the major components of MMIO register space:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) MHI control registers: Access to MHI configurations registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) MHI BHI registers: BHI (Boot Host Interface) registers are used by the host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) for downloading the firmware to the device before MHI initialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) Channel Doorbell array: Channel Doorbell (DB) registers used by the host to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) notify the device when there is new work to do.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) Event Doorbell array: Associated with event context array, the Event Doorbell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) (DB) registers are used by the host to notify the device when new events are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) Debug registers: A set of registers and counters used by the device to expose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) debugging information like performance, functional, and stability to the host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) Data structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) All data structures used by MHI are in the host system memory. Using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) physical interface, the device accesses those data structures. MHI data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) structures and data buffers in the host system memory regions are mapped for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) Channel context array: All channel configurations are organized in channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) context data array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) Transfer rings: Used by the host to schedule work items for a channel. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) transfer rings are organized as a circular queue of Transfer Descriptors (TD).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) Event context array: All event configurations are organized in the event context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) data array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) Event rings: Used by the device to send completion and state transition messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) to the host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) Command context array: All command configurations are organized in command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) context data array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) Command rings: Used by the host to send MHI commands to the device. The command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) rings are organized as a circular queue of Command Descriptors (CD).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) Channels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) MHI channels are logical, unidirectional data pipes between a host and a device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) The concept of channels in MHI is similar to endpoints in USB. MHI supports up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) to 256 channels. However, specific device implementations may support less than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) the maximum number of channels allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) Two unidirectional channels with their associated transfer rings form a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) bidirectional data pipe, which can be used by the upper-layer protocols to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) transport application data packets (such as IP packets, modem control messages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) diagnostics messages, and so on). Each channel is associated with a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) transfer ring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) Transfer rings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) Transfers between the host and device are organized by channels and defined by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) Transfer Descriptors (TD). TDs are managed through transfer rings, which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) defined for each channel between the device and host and reside in the host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) memory. TDs consist of one or more ring elements (or transfer blocks)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)         [Read Pointer (RP)] ----------->[Ring Element] } TD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)         [Write Pointer (WP)]-           [Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)                              -          [Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)                               --------->[Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)                                         [Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) Below is the basic usage of transfer rings:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) * Host allocates memory for transfer ring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) * Host sets the base pointer, read pointer, and write pointer in corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)   channel context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) * Ring is considered empty when RP == WP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) * Ring is considered full when WP + 1 == RP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * RP indicates the next element to be serviced by the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) * When the host has a new buffer to send, it updates the ring element with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)   buffer information, increments the WP to the next element and rings the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)   associated channel DB.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) Event rings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Events from the device to host are organized in event rings and defined by Event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Descriptors (ED). Event rings are used by the device to report events such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) data transfer completion status, command completion status, and state changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) to the host. Event rings are the array of EDs that resides in the host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) memory. EDs consist of one or more ring elements (or transfer blocks)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)         [Read Pointer (RP)] ----------->[Ring Element] } ED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)         [Write Pointer (WP)]-           [Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)                              -          [Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)                               --------->[Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)                                         [Ring Element]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Below is the basic usage of event rings:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) * Host allocates memory for event ring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) * Host sets the base pointer, read pointer, and write pointer in corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)   channel context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) * Both host and device has a local copy of RP, WP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) * Ring is considered empty (no events to service) when WP + 1 == RP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) * Ring is considered full of events when RP == WP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) * When there is a new event the device needs to send, the device updates ED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)   pointed by RP, increments the RP to the next element and triggers the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)   interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Ring Element
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) A Ring Element is a data structure used to transfer a single block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) of data between the host and the device. Transfer ring element types contain a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) single buffer pointer, the size of the buffer, and additional control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) information. Other ring element types may only contain control and status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) information. For single buffer operations, a ring descriptor is composed of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) single element. For large multi-buffer operations (such as scatter and gather),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) elements can be chained to form a longer descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) MHI Operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) MHI States
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) MHI_STATE_RESET
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) ~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) MHI is in reset state after power-up or hardware reset. The host is not allowed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) to access device MMIO register space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) MHI_STATE_READY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) ~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) MHI is ready for initialization. The host can start MHI initialization by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) programming MMIO registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) MHI_STATE_M0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) MHI is running and operational in the device. The host can start channels by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) issuing channel start command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) MHI_STATE_M1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) MHI operation is suspended by the device. This state is entered when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) device detects inactivity at the physical interface within a preset time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) MHI_STATE_M2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) MHI is in low power state. MHI operation is suspended and the device may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) enter lower power mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) MHI_STATE_M3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) MHI operation stopped by the host. This state is entered when the host suspends
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) MHI operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) MHI Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) After system boots, the device is enumerated over the physical interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) In the case of PCIe, the device is enumerated and assigned BAR-0 for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) the device's MMIO register space. To initialize the MHI in a device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) the host performs the following operations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) * Allocates the MHI context for event, channel and command arrays.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) * Initializes the context array, and prepares interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) * Waits until the device enters READY state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) * Programs MHI MMIO registers and sets device into MHI_M0 state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) * Waits for the device to enter M0 state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) MHI Data Transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) MHI data transfer is initiated by the host to transfer data to the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Following are the sequence of operations performed by the host to transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) data to device:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) * Host prepares TD with buffer information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) * Host increments the WP of the corresponding channel transfer ring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) * Host rings the channel DB register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) * Device wakes up to process the TD.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) * Device generates a completion event for the processed TD by updating ED.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) * Device increments the RP of the corresponding event ring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) * Device triggers IRQ to wake up the host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) * Host wakes up and checks the event ring for completion event.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) * Host updates the WP of the corresponding event ring to indicate that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)   data transfer has been completed successfully.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)