1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup MIPI DSI 11 * @{ 12 * 13 * @brief Defines standard MIPI DSI APIs for display driver development. 14 * 15 * This MIPI DSI module abstracts MIPI DSI capabilities of different system platforms to provide stable APIs 16 * for display driver development. You can use this module to obtain/release the MIPI DSI device handle, 17 * initialize the MIPI DSI device, and send/receive commands that interact with display peripherals. 18 * 19 * @since 1.0 20 */ 21 22 /** 23 * @file mipi_dsi_if.h 24 * 25 * @brief Declares standard MIPI DSI APIs for display driver development. 26 * 27 * 28 * 29 * @since 1.0 30 */ 31 32 #ifndef MIPI_DSI_IF_H 33 #define MIPI_DSI_IF_H 34 35 #include "platform_if.h" 36 37 #ifdef __cplusplus 38 #if __cplusplus 39 extern "C" { 40 #endif 41 #endif /* __cplusplus */ 42 43 /** 44 * @brief Enumerates the supported DSI operation modes. 45 * 46 * You can specify the operation mode via {@link MipiDsiSetCfg}. 47 * 48 * @since 1.0 49 */ 50 enum DsiMode { 51 /** Invalid mode */ 52 DSI_NONE = 0, 53 /** Video mode */ 54 DSI_VIDEO_MODE, 55 /** Command mode */ 56 DSI_CMD_MODE, 57 }; 58 59 /** 60 * @brief Enumerates the number of data lanes connected to the DSI device. 61 * 62 * You can specify the number of data lanes via {@link MipiDsiSetCfg}. 63 * 64 * @since 1.0 65 */ 66 enum DsiLane { 67 /** One data lane is connected to the display device. */ 68 DSI_1_LANES = 1, 69 /** Two data lanes are connected to the display device. */ 70 DSI_2_LANES, 71 /** Three data lanes are connected to the display device */ 72 DSI_3_LANES, 73 /** Four data lanes are connected to the display device. */ 74 DSI_4_LANES, 75 }; 76 77 /** 78 * @brief Enumerates the synchronization modes used for data transmission in Video mode. 79 * This enumeration is invalid in Command mode. 80 * 81 * You can specify the synchronization mode via {@link MipiDsiSetCfg}. 82 * 83 * @since 1.0 84 */ 85 enum DsiBurstMode { 86 /** Pixel data is transferred efficiently using a time-compressed burst format, 87 leaving more time during a scan line for low power (LP) mode and reducing the DSI power consumption. */ 88 VIDEO_BURST_MODE = 0x0, 89 /** Peripherals can accurately reproduce original video timing, including synchronization pulse widths. */ 90 VIDEO_NON_BURST_MODE_SYNC_PULSES = 0x1, 91 /** Peripherals can accurately reproduce original video timing, 92 but accurate synchronization pulse widths are not required. */ 93 VIDEO_NON_BURST_MODE_SYNC_EVENTS = 0x2, 94 }; 95 96 /** 97 * @brief Enumerates the output DSI image data formats. 98 * 99 * You can specify the image data format via {@link MipiDsiSetCfg}. 100 * 101 * @since 1.0 102 */ 103 enum DsiOutFormat { 104 /** 16-bit RGB */ 105 FORMAT_RGB_16_BIT = 0x0, 106 /** 18-bit RGB */ 107 FORMAT_RGB_18_BIT = 0x1, 108 /** 24-bit RGB */ 109 FORMAT_RGB_24_BIT = 0x2, 110 /** 8-bit YUV420 */ 111 FORMAT_YUV420_8_BIT_NORMAL = 0x3, 112 /** Legacy-version 8-bit YUV420 */ 113 FORMAT_YUV420_8_BIT_LEGACY = 0x4, 114 /** 8-bit YUV422 */ 115 FORMAT_YUV422_8_BIT = 0x5, 116 /** Invalid value */ 117 FORMAT_BUTT 118 }; 119 120 /** 121 * @brief Defines the MIPI DSI timing information. 122 * 123 * Before image data transmission, you must specify the timing parameters 124 * to ensure that images can be correctly displayed on the screen. 125 * 126 * @since 1.0 127 */ 128 struct DsiTimingInfo { 129 /** Effective pixels in the X direction, that is, resolution of the peer screen in the X direction */ 130 uint16_t xPixels; 131 /** Horizontal sync active (HSA) pixels in the X direction, which is specified based on the peer screen */ 132 uint16_t hsaPixels; 133 /** Horizontal back porch (HBP) pixels in the X direction, which is specified based on the peer screen */ 134 uint16_t hbpPixels; 135 /** Total number of pixels in the X direction. The value is equal to 136 the sum value of <b>xResPixels</b>, <b>hsaPixels</b>, <b>hbpPixels</b>, and <b>hfpPixels</b>. */ 137 uint16_t hlinePixels; 138 /** Vertical sync active (VSA) lines in the Y direction, which is specified based on the peer screen */ 139 uint16_t vsaLines; 140 /** Vertical back porch (VBP) lines in the Y direction, which is specified based on the peer screen */ 141 uint16_t vbpLines; 142 /** Vertical front porch (VFP) lines in the Y direction, which is specified based on the peer screen */ 143 uint16_t vfpLines; 144 /** Effective lines in the Y direction, that is, resolution of the peer screen in the Y direction */ 145 uint16_t ylines; 146 /** Number of bytes of the command for writing memory. 147 This parameter is invalid in Video mode and is set to xPixels in Command mode. */ 148 uint16_t edpiCmdSize; 149 }; 150 151 /** 152 * @brief Defines MIPI DSI configuration parameters. 153 * 154 * Before image data transmission, you must set MIPI DSI configuration parameters to ensure 155 * that images can be correctly displayed on the screen. 156 * 157 * @since 1.0 158 */ 159 struct MipiCfg { 160 /** Number of MIPI DSI lanes connected to the display device */ 161 enum DsiLane lane; 162 /** Refresh mode (Video mode or Command mode) supported by the display device */ 163 enum DsiMode mode; 164 /** Synchronous mode of the display device, which is valid only in Video mode */ 165 enum DsiBurstMode burstMode; 166 /** Format of the output DSI image data. For details, see {@link DsiOutFormat}. */ 167 enum DsiOutFormat format; 168 /** MIPI DSI timing information, which is set based on the display device requirements */ 169 struct DsiTimingInfo timing; 170 /** MIPI DSI clock (unit: Mbit/s) */ 171 uint32_t phyDataRate; 172 /** Pixel clock output by the MIPI DSI (unit: kHz) */ 173 uint32_t pixelClk; 174 }; 175 176 /** 177 * @brief Defines a MIPI DSI command. 178 * 179 * 180 * 181 * @since 1.0 182 */ 183 struct DsiCmdDesc { 184 /** MIPI data type. For details about available values, see the MIPI protocol. */ 185 uint16_t dataType; 186 /** Delay required after the command is sent, in ms */ 187 uint16_t delay; 188 /** Length of the transferred data */ 189 uint16_t dataLen; 190 /** Pointer to the data to be transferred */ 191 uint8_t *payload; 192 }; 193 194 /** 195 * @brief Obtains the MIPI DSI device handle with a specified channel ID. 196 * 197 * @param id Indicates the MIPI DSI channel ID. 198 * 199 * @return Returns the MIPI DSI device handle if the operation is successful; returns <b>NULL</b> otherwise. 200 * 201 * @since 1.0 202 */ 203 DevHandle MipiDsiOpen(uint8_t id); 204 205 /** 206 * @brief Releases the MIPI DSI device handle. 207 * 208 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 209 * 210 * @since 1.0 211 */ 212 void MipiDsiClose(DevHandle handle); 213 214 /** 215 * @brief Sets configuration parameters for a MIPI DSI device. 216 * 217 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 218 * @param cfg Indicates the pointer to the configuration parameters. 219 * 220 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 221 * 222 * @since 1.0 223 */ 224 int32_t MipiDsiSetCfg(DevHandle handle, struct MipiCfg *cfg); 225 226 /** 227 * @brief Obtains the configuration parameters of a MIPI DSI device. 228 * 229 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 230 * @param cfg Indicates the pointer to the configuration parameters. 231 * 232 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 233 * 234 * @since 1.0 235 */ 236 int32_t MipiDsiGetCfg(DevHandle handle, struct MipiCfg *cfg); 237 238 /** 239 * @brief Sets LP mode for a MIPI DSI device. 240 * 241 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 242 * 243 * @since 1.0 244 */ 245 void MipiDsiSetLpMode(DevHandle handle); 246 247 /** 248 * @brief Sets the high-speed (HS) mode for a MIPI DSI device. 249 * 250 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 251 * 252 * @since 1.0 253 */ 254 void MipiDsiSetHsMode(DevHandle handle); 255 256 /** 257 * @brief Sends a display command set (DCS) command used for sending the initial parameters of a peripheral. 258 * 259 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 260 * @param cmd Indicates the pointer to the command to be sent. 261 * 262 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 263 * 264 * @since 1.0 265 */ 266 int32_t MipiDsiTx(DevHandle handle, struct DsiCmdDesc *cmd); 267 268 /** 269 * @brief Receives a DCS command used for reading data, such as the status and parameters of a peripheral 270 * 271 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 272 * @param cmd Indicates the pointer to the command to be received. 273 * @param readLen Indicates the length of the data to read, in bytes. 274 * @param out Indicates the pointer to the read data. 275 * 276 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 277 * 278 * @since 1.0 279 */ 280 int32_t MipiDsiRx(DevHandle handle, struct DsiCmdDesc *cmd, int32_t readLen, uint8_t *out); 281 282 /** 283 * @brief attach a DSI device to its DSI host 284 * 285 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 286 * @param name Indicates the name of a peripheral. 287 * 288 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 289 * 290 * @since 1.0 291 */ 292 int32_t MipiDsiAttach(DevHandle handle, uint8_t *name); 293 294 /** 295 * @brief Sets additional parameters for a MIPI DSI device. 296 * 297 * @param handle Indicates the MIPI DSI device handle obtained via {@link MipiDsiOpen}. 298 * @param panelData Indicates the pointer to the additional parameters. 299 * 300 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 301 * 302 * @since 1.0 303 */ 304 int32_t MipiDsiSetDrvData(DevHandle handle, void *panelData); 305 306 #ifdef __cplusplus 307 #if __cplusplus 308 } 309 #endif 310 #endif /* __cplusplus */ 311 312 #endif /* MIPI_DSI_IF_H */ 313