# Usage Guidelines
- [How to Use](#section8982671284)
- [Obtaining a MIPI DSI Device Handle](#section57982569176)
- [Setting MIPI DSI Configuration Parameters](#section5935410201815)
- [Sending/Receiving the Pointer to a Command](#section611661316194)
- [Releasing the MIPI DSI Device Handle](#section217313211199)
## How to Use
[Figure 1](#fig99821771782) shows the process of using a MIPI DSI device.
**Figure 1** Process of using a MIPI DSI device
## Obtaining a MIPI DSI Device Handle
Before performing MIPI DSI communication, obtain a MIPI DSI device handle by calling **MipiDsiOpen**. This function returns a MIPI DSI device handle with a specified channel ID.
DevHandle MipiDsiOpen\(uint8\_t id\);
**Table 1** Description of **MipiDsiOpen**
Parameter
Description
id
MIPI DSI channel ID.
Return Value
Description
NULL
Failed to obtain the MIPI DSI channel ID.
Device handle
MIPI DSI device handle with a specified channel ID, whose data type is DevHandle.
The following example shows how to obtain a MIPI DSI device handle with the channel ID **0**:
```
DevHandle mipiDsiHandle = NULL; /* Device handle */
chnId = 0; /* MIPI DSI channel ID */
/* Obtain the MIPI DSI device handle based on a specified channel ID. */
mipiDsiHandle = MipiDsiOpen(chnId);
if (mipiDsiHandle == NULL) {
HDF_LOGE("MipiDsiOpen: failed\n");
return;
}
```
## Setting MIPI DSI Configuration Parameters
- Set MIPI DSI configuration parameters by calling the following function:
int32\_t MipiDsiSetCfg\(DevHandle handle, struct MipiCfg \*cfg\);
**Table 2** Description of **MipiDsiSetCfg**
Parameter
Description
handle
MIPI DSI device handle
cfg
Pointer to MIPI DSI configuration parameters
Return Value
Description
0
Succeeded in setting MIPI DSI configuration parameters.
Negative value
Failed to set MIPI DSI configuration parameters.
```
int32_t ret;
struct MipiCfg cfg = {0};
/* Configuration parameters of the connected device are as follows: */
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;
/* Set MIPI DSI configuration parameters. */
ret = MipiDsiSetCfg(g_handle, &cfg);
if (ret != 0) {
HDF_LOGE("%s: SetMipiCfg fail! ret=%d\n", __func__, ret);
return -1;
}
```
- Obtain MIPI DSI configuration parameters by calling the following function:
int32\_t MipiDsiGetCfg\(DevHandle handle, struct MipiCfg \*cfg\);
**Table 3** Description of **MipiDsiGetCfg**
Parameter
Description
handle
MIPI DSI device handle
cfg
Pointer to MIPI DSI configuration parameters
Return Value
Description
0
Succeeded in obtaining MIPI DSI configuration parameters.
Negative value
Failed to obtain MIPI DSI configuration parameters.
```
int32_t ret;
struct MipiCfg cfg;
memset(&cfg, 0, sizeof(struct MipiCfg));
ret = MipiDsiGetCfg(g_handle, &cfg);
if (ret != HDF_SUCCESS) {
HDF_LOGE("%s: GetMipiCfg fail!\n", __func__);
return HDF_FAILURE;
}
```
## Sending/Receiving the Pointer to a Command
- Send the pointer to a specified command by calling the following function:
int32\_t MipiDsiTx\(PalHandle handle, struct DsiCmdDesc \*cmd\);
**Table 4** Description of **MipiDsiTx**
Parameter
Description
handle
MIPI DSI device handle
cmd
Pointer to the command to be sent
Return Value
Description
0
Succeeded in sending the specified command.
Negative value
Failed to send the specified command.
```
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);
```
- Receive a specified command by calling the following function:
int32\_t MipiDsiRx\(DevHandle handle, struct DsiCmdDesc \*cmd, uint32\_t readLen, uint8\_t \*out\);
**Table 5** Description of **MipiDsiRx**
Parameter
Description
handle
MIPI DSI device handle
cmd
Pointer to the command to be received
readLen
Length of the data to read.
out
Pointer to the read data.
Return Value
Description
0
Succeeded in receiving the specified command.
Negative value
Failed to receive the specified command.
```
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(g_handle);
ret = MipiDsiRx(g_handle, cmdRead, sizeof(readVal), &readVal);
MipiDsiSetHsMode(g_handle);
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);
```
## Releasing the MIPI DSI Device Handle
After the MIPI DSI communication, release the MIPI DSI device handle by calling the following function:
void MipiDsiClose\(DevHandle handle\);
This function releases the resources requested by **MipiDsiOpen**.
**Table 6** Description of **MipiDsiClose**