# MIPI DSI


## 概述

- DSI（Display Serial Interface）是由移动行业处理器接口联盟（Mobile Industry Processor Interface (MIPI) Alliance）制定的规范，旨在降低移动设备中显示控制器的成本。它以串行的方式发送像素数据或指令给外设（通常是LCD或者类似的显示设备），或从外设中读取状态信息或像素信息；它定义了主机、图像数据源和目标设备之间的串行总线和通信协议。

- MIPI DSI具备高速模式和低速模式两种工作模式，全部数据通道都可以用于单向的高速传输，但只有第一个数据通道才可用于低速双向传输，从属端的状态信息、像素等是通过该数据通道返回。时钟通道专用于在高速传输数据的过程中传输同步时钟信号。

- 图1显示了简化的DSI接口。从概念上看，符合DSI的接口与基于DBI-2和DPI-2标准的接口具有相同的功能。它向外围设备传输像素或命令数据，并且可以从外围设备读取状态或像素信息。主要区别在于，DSI对所有像素数据、命令和事件进行序列化，而在传统接口中，这些像素数据、命令和事件通常需要附加控制信号才能在并行数据总线上传输。

    **图1** DSI发送、接收接口

    ![image](figures/DSI发送-接收接口.png "DSI发送-接收接口")


## 接口说明

  **表1** MIPI DSI API接口功能介绍

| 功能分类 | 接口名 | 
| -------- | -------- |
| 设置/获取当前MIPI&nbsp;DSI相关配置 | -&nbsp;MipiDsiSetCfg：设置MIPI&nbsp;DSI相关配置<br/>-&nbsp;MipiDsiGetCfg：获取当前MIPI&nbsp;DSI相关配置 | 
| 获取/释放MIPI&nbsp;DSI操作句柄 | -&nbsp;MipiDsiOpen：获取MIPI&nbsp;DSI操作句柄<br/>-&nbsp;MipiDsiClose：释放MIPI&nbsp;DSI操作句柄 | 
| 设置MIPI&nbsp;DSI进入Low&nbsp;power模式/High&nbsp;speed模式 | -&nbsp;MipiDsiSetLpMode：设置MIPI&nbsp;DSI进入Low&nbsp;power模式<br/>-&nbsp;MipiDsiSetHsMode：设置MIPI&nbsp;DSI进入High&nbsp;speed模式 | 
| MIPI&nbsp;DSI发送/回读指令 | -&nbsp;MipiDsiTx：MIPI&nbsp;DSI发送相应指令的接口<br/>-&nbsp;MipiDsiRx：MIPI&nbsp;DSI按期望长度回读的接口 | 

> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 本文涉及的所有接口，仅限内核态使用，不支持在用户态使用。


## 使用指导


### 使用流程

使用MIPI DSI的一般流程如下图所示。

  **图2** MIPI DSI使用流程图

  ![image](figures/MIPI-DSI使用流程图.png "MIPI-DSI使用流程图")


### 获取MIPI DSI操作句柄

在进行MIPI DSI进行通信前，首先要调用MipiDsiOpen获取操作句柄，该函数会返回指定通道ID的操作句柄。

  
```
DevHandle MipiDsiOpen(uint8_t id);
```

  **表2** MipiDsiOpen的参数和返回值描述

| **参数** | **参数描述** | 
| -------- | -------- |
| id | MIPI&nbsp;DSI通道ID | 
| **返回值** | **返回值描述** | 
| NULL | 获取失败 | 
| 设备句柄 | 获取到指令通道的操作句柄,&nbsp;类型为DevHandle | 

假设系统中的MIPI DSI通道为0，获取该通道操作句柄的示例如下：

  
```
DevHandle mipiDsiHandle = NULL;  /* 设备句柄 */
chnId = 0;      /* MIPI DSI通道ID */

/* 获取操作句柄 */
mipiDsiHandle = MipiDsiOpen(chnId);
if (mipiDsiHandle == NULL) {
    HDF_LOGE("MipiDsiOpen: failed\n");
    return;
}
```


### MIPI DSI相应配置

- 写入MIPI DSI配置
    
  ```
  int32_t MipiDsiSetCfg(DevHandle handle, struct MipiCfg *cfg);
  ```

    **表3** MipiDsiSetCfg的参数和返回值描述
  
  | **参数** | **参数描述** | 
  | -------- | -------- |
  | handle | 操作句柄 | 
  | cfg | MIPI&nbsp;DSI相应配置buf&nbsp;指针 | 
  | **返回值** | **返回值描述** | 
  | 0 | 设置成功 | 
  | 负数 | 设置失败 | 

    
  ```
  int32_t ret;
  struct MipiCfg cfg = {0};
  
  /* 当前对接的屏幕配置如下 */
  cfg.lane = DSI_4_LANES;
  cfg.mode = DSI_CMD_MODE;
  cfg.burstMode = VIDEO_NON_BURST_MODE_SYNC_EVENTS;
  cfg.format = FORMAT_RGB_24_BIT;
  cfg.pixelClk = 174;
  cfg.phyDataRate = 384;
  cfg.timingInfo.hsaPixels = 50;
  cfg.timingInfo.hbpPixels = 55;
  cfg.timingInfo.hlinePixels = 1200;
  cfg.timingInfo.yResLines = 1800;
  cfg.timingInfo.vbpLines = 33;
  cfg.timingInfo.vsaLines = 76;
  cfg.timingInfo.vfpLines = 120;
  cfg.timingInfo.xResPixels = 1342;
  /* 写入配置数据 */
  ret = MipiDsiSetCfg(mipiDsiHandle, &cfg);
  if (ret != 0) {
      HDF_LOGE("%s: SetMipiCfg fail! ret=%d\n", __func__, ret);
      return -1;
  }
  ```

- 获取当前MIPI DSI的配置
    
  ```
  int32_t MipiDsiGetCfg(DevHandle handle, struct MipiCfg *cfg);
  ```

    **表4** MipiDsiGetCfg的参数和返回值描述
  
  | **参数** | **参数描述** | 
  | -------- | -------- |
  | handle | 操作句柄 | 
  | cfg | MIPI&nbsp;DSI相应配置buf&nbsp;指针 | 
  | **返回值** | **返回值描述** | 
  | 0 | 获取成功 | 
  | 负数 | 获取失败 | 

    
  ```
  int32_t ret;
  struct MipiCfg cfg;
  memset(&cfg, 0, sizeof(struct MipiCfg));
  ret = MipiDsiGetCfg(mipiDsiHandle, &cfg);
  if (ret != HDF_SUCCESS) {
      HDF_LOGE("%s: GetMipiCfg fail!\n", __func__);
      return HDF_FAILURE;
  }
  ```


### 发送/回读控制指令

- 发送指令
    
  ```
  int32_t MipiDsiTx(PalHandle handle, struct DsiCmdDesc *cmd);
  ```

    **表5** MipiDsiTx的参数和返回值描述
  
  | **参数** | **参数描述** | 
  | -------- | -------- |
  | handle | 操作句柄 | 
  | cmd | 需要发送的指令数据指针 | 
  | **返回值** | **返回值描述** | 
  | 0 | 发送成功 | 
  | 负数 | 发送失败 | 

    
  ```
  int32_t ret;
  struct DsiCmdDesc *cmd = OsalMemCalloc(sizeof(struct DsiCmdDesc));
  if (cmd == NULL) {
      return HDF_FAILURE;
  }
  cmd->dtype = DTYPE_DCS_WRITE;
  cmd->dlen = 1;
  cmd->payload = OsalMemCalloc(sizeof(uint8_t));
  if (cmd->payload == NULL) {
      HdfFree(cmd);
      return HDF_FAILURE;
  }
  *(cmd->payload) = DTYPE_GEN_LWRITE;
  MipiDsiSetLpMode(mipiHandle);
  ret = MipiDsiTx(mipiHandle, cmd);
  MipiDsiSetHsMode(mipiHandle);
  if (ret != HDF_SUCCESS) {
      HDF_LOGE("%s: PalMipiDsiTx fail! ret=%d\n", __func__, ret);
      HdfFree(cmd->payload);
      HdfFree(cmd);
      return HDF_FAILURE;
  }
  HdfFree(cmd->payload);
  HdfFree(cmd);
  ```

- 回读指令
    
  ```
  int32_t MipiDsiRx(DevHandle handle, struct DsiCmdDesc *cmd, uint32_t readLen, uint8_t *out);
  ```

    **表6** MipiDsiRx的参数和返回值描述
  
  | **参数** | **参数描述** | 
  | -------- | -------- |
  | handle | 操作句柄 | 
  | cmd | 需要回读的指令数据指针 | 
  | readLen | 期望回读的数据长度 | 
  | out | 回读的数据buf指针 | 
  | **返回值** | **返回值描述** | 
  | 0 | 获取成功 | 
  | 负数 | 获取失败 | 

    
  ```
  int32_t ret;
  uint8_t readVal = 0;
  
  struct DsiCmdDesc *cmdRead = OsalMemCalloc(sizeof(struct DsiCmdDesc));
  if (cmdRead == NULL) {
      return HDF_FAILURE;
  }
  cmdRead->dtype = DTYPE_DCS_READ;
  cmdRead->dlen = 1;
  cmdRead->payload = OsalMemCalloc(sizeof(uint8_t));
  if (cmdRead->payload == NULL) {
      HdfFree(cmdRead);
      return HDF_FAILURE;
  }
  *(cmdRead->payload) = DDIC_REG_STATUS;
  MipiDsiSetLpMode(mipiDsiHandle);
  ret = MipiDsiRx(mipiDsiHandle, cmdRead, sizeof(readVal), &readVal);
  MipiDsiSetHsMode(mipiDsiHandle);
  if (ret != HDF_SUCCESS) {
      HDF_LOGE("%s: MipiDsiRx fail! ret=%d\n", __func__, ret);
      HdfFree(cmdRead->payload);
      HdfFree(cmdRead);
      return HDF_FAILURE;
  }
  HdfFree(cmdRead->payload);
  HdfFree(cmdRead);
  ```


### 释放MIPI DSI操作句柄

MIPI DSI使用完成之后，需要释放操作句柄，释放句柄的函数如下所示：

  
```
void MipiDsiClose(DevHandle handle);
```

该函数会释放掉由MipiDsiOpen申请的资源。

  **表7** MipiDsiClose的参数和返回值描述

| 参数 | 参数描述 | 
| -------- | -------- |
| handle | MIPI&nbsp;DSI操作句柄 | 

  
```
MipiDsiClose(mipiHandle); /* 释放掉MIPI DSI操作句柄 */
```


## 使用实例

MIPI DSI完整的使用示例如下所示：

  
```
#include "hdf.h"
#include "mipi_dsi_if.h"

void PalMipiDsiTestSample(void)
{
    uint8_t chnId;
    int32_t ret;  
    DevHandle mipiDsiHandle = NULL;
    
    /* 设备通道编号 */
    chnId = 0; 
    /* 获取操作句柄 */
    mipiDsiHandle = MipiDsiOpen(chnId);
    if (mipiDsiHandle == NULL) {
        HDF_LOGE("MipiDsiOpen: failed!\n");
        return;
    }
    /* 配置相应参数 */
    struct MipiCfg cfg = {0};
    cfg.lane = DSI_4_LANES;
    cfg.mode = DSI_CMD_MODE;
    cfg.burstMode = VIDEO_NON_BURST_MODE_SYNC_EVENTS;
    cfg.format = FORMAT_RGB_24_BIT;
    cfg.pixelClk = 174;                      
    cfg.phyDataRate = 384;                 
    cfg.timingInfo.hsaPixels = 50;
    cfg.timingInfo.hbpPixels = 55;
    cfg.timingInfo.hlinePixels = 1200;
    cfg.timingInfo.yResLines = 1800;
    cfg.timingInfo.vbpLines = 33;
    cfg.timingInfo.vsaLines = 76;
    cfg.timingInfo.vfpLines = 120;
    cfg.timingInfo.xResPixels = 1342;
    /* 写入配置数据 */
    ret = MipiDsiSetCfg(mipiDsiHandle, &cfg);
    if (ret != 0) {
        HDF_LOGE("%s: SetMipiCfg fail! ret=%d\n", __func__, ret);
        return;
    }
    /* 发送PANEL初始化指令 */
    struct DsiCmdDesc *cmd = OsalMemCalloc(sizeof(struct DsiCmdDesc));
    if (cmd == NULL) {
        return;
    }
    cmd->dtype = DTYPE_DCS_WRITE;
    cmd->dlen = 1;
    cmd->payload = OsalMemCalloc(sizeof(uint8_t));
    if (cmd->payload == NULL) {
        HdfFree(cmd);
        return;
    }
    *(cmd->payload) = DTYPE_GEN_LWRITE;
    MipiDsiSetLpMode(mipiHandle);
    ret = MipiDsiTx(mipiHandle, cmd);
    MipiDsiSetHsMode(mipiHandle);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: MipiDsiTx fail! ret=%d\n", __func__, ret);
        HdfFree(cmd->payload);
        HdfFree(cmd);
        return;
    }
    HdfFree(cmd->payload);
    HdfFree(cmd);
    /* 回读panel状态寄存器 */
    uint8_t readVal = 0;
    struct DsiCmdDesc *cmdRead = OsalMemCalloc(sizeof(struct DsiCmdDesc));
    if (cmdRead == NULL) {
        return;
    }
    cmdRead->dtype = DTYPE_DCS_READ;
    cmdRead->dlen = 1;
    cmdRead->payload = OsalMemCalloc(sizeof(uint8_t));
    if (cmdRead->payload == NULL) {
        HdfFree(cmdRead);
        return;
    }
    *(cmdRead->payload) = DDIC_REG_STATUS;
    MipiDsiSetLpMode(mipiDsiHandle);
    ret = MipiDsiRx(mipiDsiHandle, cmdRead, sizeof(readVal), &readVal);
    MipiDsiSetHsMode(mipiDsiHandle);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: MipiDsiRx fail! ret=%d\n", __func__, ret);
        HdfFree(cmdRead->payload);
        HdfFree(cmdRead);
        return;
    }
    HdfFree(cmdRead->payload);
    HdfFree(cmdRead);
    /* 释放MIPI DSI设备句柄 */
    MipiDsiClose(handle); 
}
```