• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# MIPI DSI
2
3
4## Overview
5
6The Display Serial Interface (DSI) is a specification stipulated by the Mobile Industry Processor Interface (MIPI) Alliance, aiming to reduce the cost of display controllers in a mobile device. It defines a serial bus and communication protocol among the host, the source of image data, and the target device. In this way, the DSI can send pixel data or commands to peripherals (usually LCDs or similar display devices) in serial mode, or reads information such as status and pixel from the peripherals.
7
8MIPI DSI is capable of working in both high speed (HS) mode and low power (LP) mode. All data lanes can only travel from the DSI host to a peripheral in HS mode, except the first data lane, which can also receive data such as status information and pixels from the peripheral in LP mode. The clock lane is dedicated to transmitting synchronization clock signals in HS mode.
9
10The figure below shows a simplified DSI interface. Conceptually, a DSI-compliant interface has the same features as interfaces complying with DBI-2 and DPI-2 standards. It sends pixels or commands to a peripheral and can read status or pixel information from the peripheral. The main difference is that the DSI serializes all pixel data, commands, and events that, in traditional interfaces, are conveyed to and from the peripheral on a parallel data bus with additional control signals.
11
12  **Figure 1** DSI TX and RX interfaces
13
14  ![image](figures/DSI-TX-RX_interface.png)
15
16
17## Available APIs
18
19  **Table 1** MIPI DSI APIs
20
21| Category| API|
22| -------- | -------- |
23| MIPI DSI configuration| -&nbsp;**MipiDsiSetCfg**: sets MIPI DSI attributes.<br>-&nbsp;**MipiDsiGetCfg**: obtains the MIPI DSI configuration.|
24| MIPI DSI device handle| -&nbsp;**MipiDsiOpen**: opens a MIPI DSI device handle.<br>-&nbsp;**MipiDsiClose**: closes a MIPI DSI device handle.|
25| MIPI DSI device mode| -&nbsp;**MipiDsiSetLpMode**: sets LP mode for a device.<br>-&nbsp;**MipiDsiSetHsMode**: sets HS mode for a device.|
26| MIPI DSI commands| -&nbsp;**MipiDsiTx**: sends commands to a display device.<br>- &nbsp;**MipiDsiRx**: reads data of the specified length.|
27
28> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>
29> All APIs described in this document can be called only in kernel mode.
30
31
32## Usage Guidelines
33
34
35### How to Use
36
37The figure below shows the general process of using the MIPI DSI driver APIs.
38
39  **Figure 2** Using MIPI DSI driver APIs
40
41  ![image](figures/using-MIPI-DSI-process.png)
42
43
44### Opening a MIPI DSI Device Handle
45
46Before performing MIPI DSI communication, open a MIPI DSI device handle by calling **MipiDsiOpen()**. This function returns the MIPI DSI device handle of the specified channel ID.
47
48
49```
50DevHandle MipiDsiOpen(uint8_t id);
51```
52
53  **Table 2** Description of MipiDsiOpen
54
55| **Parameter**| **Description**|
56| -------- | -------- |
57| id | MIPI DSI channel ID.|
58| **Return Value**| **Description**|
59| NULL | The operation failed.|
60| Device handle| The operation is successful. The MIPI DSI device handle of the specified channel ID (data type is **DevHandle**) is returned.|
61
62For example, open the MIPI DSI device handle of channel **0**:
63
64
65```
66DevHandle mipiDsiHandle = NULL;  /* Device handle */
67chnId = 0;      /* MIPI DSI channel ID */
68
69/* Open the MIPI DSI device handle. */
70mipiDsiHandle = MipiDsiOpen(chnId);
71if (mipiDsiHandle == NULL) {
72    HDF_LOGE("MipiDsiOpen: failed\n");
73    return;
74}
75```
76
77
78### Setting MIPI DSI Attributes
79
80- Call **MipiDsiSetCfg()** to set MIPI DSI attributes.
81
82  ```
83  int32_t MipiDsiSetCfg(DevHandle handle, struct MipiCfg *cfg);
84  ```
85
86    **Table 3** Description of MipiDsiSetCfg
87
88  | **Parameter**| **Description**|
89  | -------- | -------- |
90  | handle | MIPI DSI device handle.|
91  | cfg | Pointer to the buffer that stores the MIPI DSI configuration.|
92  | **Return Value**| **Description**|
93  | 0 | The operation is successful.|
94  | Negative value| The operation failed.|
95
96
97  ```
98  int32_t ret;
99  struct MipiCfg cfg = {0};
100
101  /* The display device configuration is as follows: */
102  cfg.lane = DSI_4_LANES;
103  cfg.mode = DSI_CMD_MODE;
104  cfg.burstMode = VIDEO_NON_BURST_MODE_SYNC_EVENTS;
105  cfg.format = FORMAT_RGB_24_BIT;
106  cfg.pixelClk = 174;
107  cfg.phyDataRate = 384;
108  cfg.timingInfo.hsaPixels = 50;
109  cfg.timingInfo.hbpPixels = 55;
110  cfg.timingInfo.hlinePixels = 1200;
111  cfg.timingInfo.yResLines = 1800;
112  cfg.timingInfo.vbpLines = 33;
113  cfg.timingInfo.vsaLines = 76;
114  cfg.timingInfo.vfpLines = 120;
115  cfg.timingInfo.xResPixels = 1342;
116  /* Set the display device configuration. */
117  ret = MipiDsiSetCfg(mipiDsiHandle, &cfg);
118  if (ret != 0) {
119      HDF_LOGE("%s: SetMipiCfg fail! ret=%d\n", __func__, ret);
120      return -1;
121  }
122  ```
123
124- Call **MipiDsiGetCfg()** to obtain the MIPI DSI configuration.
125
126  ```
127  int32_t MipiDsiGetCfg(DevHandle handle, struct MipiCfg *cfg);
128  ```
129
130    **Table 4** Description of MipiDsiGetCfg
131
132  | **Parameter**| **Description**|
133  | -------- | -------- |
134  | handle | MIPI DSI device handle.|
135  | cfg | Pointer to the buffer that stores the MIPI DSI configuration.|
136  | **Return Value**| **Description**|
137  | 0 | The operation is successful.|
138  | Negative value| The operation failed.|
139
140
141  ```
142  int32_t ret;
143  struct MipiCfg cfg;
144  memset(&cfg, 0, sizeof(struct MipiCfg));
145  ret = MipiDsiGetCfg(mipiDsiHandle, &cfg);
146  if (ret != HDF_SUCCESS) {
147      HDF_LOGE("%s: GetMipiCfg fail!\n", __func__);
148      return HDF_FAILURE;
149  }
150  ```
151
152
153### Sending Commands or Reading Data
154
155- Call **MipiDsiTx()** to send commands.
156
157  ```
158  int32_t MipiDsiTx(PalHandle handle, struct DsiCmdDesc *cmd);
159  ```
160
161    **Table 5** Description of MipiDsiTx
162
163  | **Parameter**| **Description**|
164  | -------- | -------- |
165  | handle | MIPI DSI device handle.|
166  | cmd | Pointer to the commands to send.|
167  | **Return Value**| **Description**|
168  | 0 | The operation is successful.|
169  | Negative value| The operation failed.|
170
171
172  ```
173  int32_t ret;
174  struct DsiCmdDesc *cmd = OsalMemCalloc(sizeof(struct DsiCmdDesc));
175  if (cmd == NULL) {
176      return HDF_FAILURE;
177  }
178  cmd->dtype = DTYPE_DCS_WRITE;
179  cmd->dlen = 1;
180  cmd->payload = OsalMemCalloc(sizeof(uint8_t));
181  if (cmd->payload == NULL) {
182      HdfFree(cmd);
183      return HDF_FAILURE;
184  }
185  *(cmd->payload) = DTYPE_GEN_LWRITE;
186  MipiDsiSetLpMode(mipiHandle);
187  ret = MipiDsiTx(mipiHandle, cmd);
188  MipiDsiSetHsMode(mipiHandle);
189  if (ret != HDF_SUCCESS) {
190      HDF_LOGE("%s: PalMipiDsiTx fail! ret=%d\n", __func__, ret);
191      HdfFree(cmd->payload);
192      HdfFree(cmd);
193      return HDF_FAILURE;
194  }
195  HdfFree(cmd->payload);
196  HdfFree(cmd);
197  ```
198
199- Call **MipiDsiRx()** to read data of the specified length.
200
201  ```
202  int32_t MipiDsiRx(DevHandle handle, struct DsiCmdDesc *cmd, uint32_t readLen, uint8_t *out);
203  ```
204
205    **Table 6** Description of MipiDsiRx
206
207  | **Parameter**| **Description**|
208  | -------- | -------- |
209  | handle | MIPI DSI device handle.|
210  | cmd | Pointer to the commands.|
211  | readLen | Length of the data to read.|
212  | out | Pointer to the buffer that stores the data read.|
213  | **Return Value**| **Description**|
214  | 0 | The operation is successful.|
215  | Negative value| The operation failed.|
216
217
218  ```
219  int32_t ret;
220  uint8_t readVal = 0;
221
222  struct DsiCmdDesc *cmdRead = OsalMemCalloc(sizeof(struct DsiCmdDesc));
223  if (cmdRead == NULL) {
224      return HDF_FAILURE;
225  }
226  cmdRead->dtype = DTYPE_DCS_READ;
227  cmdRead->dlen = 1;
228  cmdRead->payload = OsalMemCalloc(sizeof(uint8_t));
229  if (cmdRead->payload == NULL) {
230      HdfFree(cmdRead);
231      return HDF_FAILURE;
232  }
233  *(cmdRead->payload) = DDIC_REG_STATUS;
234  MipiDsiSetLpMode(mipiDsiHandle);
235  ret = MipiDsiRx(mipiDsiHandle, cmdRead, sizeof(readVal), &readVal);
236  MipiDsiSetHsMode(mipiDsiHandle);
237  if (ret != HDF_SUCCESS) {
238      HDF_LOGE("%s: MipiDsiRx fail! ret=%d\n", __func__, ret);
239      HdfFree(cmdRead->payload);
240      HdfFree(cmdRead);
241      return HDF_FAILURE;
242  }
243  HdfFree(cmdRead->payload);
244  HdfFree(cmdRead);
245  ```
246
247
248### Closing a MIPI DSI Device Handle
249
250Call **MipiDsiClose()** to close the MIPI DSI device handle after the operation is complete.
251
252
253```
254void MipiDsiClose(DevHandle handle);
255```
256
257This function releases the resources requested by **MipiDsiOpen**.
258
259  **Table 7** Description of MipiDsiClose
260
261| Parameter| Description|
262| -------- | -------- |
263| handle | MIPI DSI device handle.|
264
265
266```
267MipiDsiClose(mipiHandle); /* Close the MIPI DSI device handle. */
268```
269
270
271## Development Example
272
273The following is an example of using a MIPI DSI device:
274
275
276```
277#include "hdf.h"
278#include "mipi_dsi_if.h"
279
280void PalMipiDsiTestSample(void)
281{
282    uint8_t chnId;
283    int32_t ret;
284    DevHandle mipiDsiHandle = NULL;
285
286    /* Device channel ID */
287    chnId = 0;
288    /* Open the MIPI DSI device handle of the specified channel ID. */
289    mipiDsiHandle = MipiDsiOpen(chnId);
290    if (mipiDsiHandle == NULL) {
291        HDF_LOGE("MipiDsiOpen: failed!\n");
292        return;
293    }
294    /* Set MIPI DSI attributes. */
295    struct MipiCfg cfg = {0};
296    cfg.lane = DSI_4_LANES;
297    cfg.mode = DSI_CMD_MODE;
298    cfg.burstMode = VIDEO_NON_BURST_MODE_SYNC_EVENTS;
299    cfg.format = FORMAT_RGB_24_BIT;
300    cfg.pixelClk = 174;
301    cfg.phyDataRate = 384;
302    cfg.timingInfo.hsaPixels = 50;
303    cfg.timingInfo.hbpPixels = 55;
304    cfg.timingInfo.hlinePixels = 1200;
305    cfg.timingInfo.yResLines = 1800;
306    cfg.timingInfo.vbpLines = 33;
307    cfg.timingInfo.vsaLines = 76;
308    cfg.timingInfo.vfpLines = 120;
309    cfg.timingInfo.xResPixels = 1342;
310    /* Write the configuration. */
311    ret = MipiDsiSetCfg(mipiDsiHandle, &cfg);
312    if (ret != 0) {
313        HDF_LOGE("%s: SetMipiCfg fail! ret=%d\n", __func__, ret);
314        return;
315    }
316    /* Send the command for initializing the panel. */
317    struct DsiCmdDesc *cmd = OsalMemCalloc(sizeof(struct DsiCmdDesc));
318    if (cmd == NULL) {
319        return;
320    }
321    cmd->dtype = DTYPE_DCS_WRITE;
322    cmd->dlen = 1;
323    cmd->payload = OsalMemCalloc(sizeof(uint8_t));
324    if (cmd->payload == NULL) {
325        HdfFree(cmd);
326        return;
327    }
328    *(cmd->payload) = DTYPE_GEN_LWRITE;
329    MipiDsiSetLpMode(mipiHandle);
330    ret = MipiDsiTx(mipiHandle, cmd);
331    MipiDsiSetHsMode(mipiHandle);
332    if (ret != HDF_SUCCESS) {
333        HDF_LOGE("%s: MipiDsiTx fail! ret=%d\n", __func__, ret);
334        HdfFree(cmd->payload);
335        HdfFree(cmd);
336        return;
337    }
338    HdfFree(cmd->payload);
339    HdfFree(cmd);
340    /* Read data from the panel register. */
341    uint8_t readVal = 0;
342    struct DsiCmdDesc *cmdRead = OsalMemCalloc(sizeof(struct DsiCmdDesc));
343    if (cmdRead == NULL) {
344        return;
345    }
346    cmdRead->dtype = DTYPE_DCS_READ;
347    cmdRead->dlen = 1;
348    cmdRead->payload = OsalMemCalloc(sizeof(uint8_t));
349    if (cmdRead->payload == NULL) {
350        HdfFree(cmdRead);
351        return;
352    }
353    *(cmdRead->payload) = DDIC_REG_STATUS;
354    MipiDsiSetLpMode(mipiDsiHandle);
355    ret = MipiDsiRx(mipiDsiHandle, cmdRead, sizeof(readVal), &readVal);
356    MipiDsiSetHsMode(mipiDsiHandle);
357    if (ret != HDF_SUCCESS) {
358        HDF_LOGE("%s: MipiDsiRx fail! ret=%d\n", __func__, ret);
359        HdfFree(cmdRead->payload);
360        HdfFree(cmdRead);
361        return;
362    }
363    HdfFree(cmdRead->payload);
364    HdfFree(cmdRead);
365    /* Close the MIPI CSI device handle. */
366    MipiDsiClose(handle);
367}
368```
369