1 /*
2 * Copyright (c) 2020 Teslabs Engineering S.L.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Public APIs for MIPI-DSI drivers
10 */
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_MIPI_DSI_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_MIPI_DSI_H_
14
15 /**
16 * @brief MIPI-DSI driver APIs
17 * @defgroup mipi_dsi_interface MIPI-DSI driver APIs
18 * @ingroup io_interfaces
19 * @{
20 */
21 #include <sys/types.h>
22 #include <zephyr/device.h>
23 #include <zephyr/dt-bindings/mipi_dsi/mipi_dsi.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /**
30 * @name MIPI-DSI DCS (Display Command Set)
31 * @{
32 */
33
34 #define MIPI_DCS_NOP 0x00U
35 #define MIPI_DCS_SOFT_RESET 0x01U
36 #define MIPI_DCS_GET_COMPRESSION_MODE 0x03U
37 #define MIPI_DCS_GET_DISPLAY_ID 0x04U
38 #define MIPI_DCS_GET_RED_CHANNEL 0x06U
39 #define MIPI_DCS_GET_GREEN_CHANNEL 0x07U
40 #define MIPI_DCS_GET_BLUE_CHANNEL 0x08U
41 #define MIPI_DCS_GET_DISPLAY_STATUS 0x09U
42 #define MIPI_DCS_GET_POWER_MODE 0x0AU
43 #define MIPI_DCS_GET_ADDRESS_MODE 0x0BU
44 #define MIPI_DCS_GET_PIXEL_FORMAT 0x0CU
45 #define MIPI_DCS_GET_DISPLAY_MODE 0x0DU
46 #define MIPI_DCS_GET_SIGNAL_MODE 0x0EU
47 #define MIPI_DCS_GET_DIAGNOSTIC_RESULT 0x0FU
48 #define MIPI_DCS_ENTER_SLEEP_MODE 0x10U
49 #define MIPI_DCS_EXIT_SLEEP_MODE 0x11U
50 #define MIPI_DCS_ENTER_PARTIAL_MODE 0x12U
51 #define MIPI_DCS_ENTER_NORMAL_MODE 0x13U
52 #define MIPI_DCS_EXIT_INVERT_MODE 0x20U
53 #define MIPI_DCS_ENTER_INVERT_MODE 0x21U
54 #define MIPI_DCS_SET_GAMMA_CURVE 0x26U
55 #define MIPI_DCS_SET_DISPLAY_OFF 0x28U
56 #define MIPI_DCS_SET_DISPLAY_ON 0x29U
57 #define MIPI_DCS_SET_COLUMN_ADDRESS 0x2AU
58 #define MIPI_DCS_SET_PAGE_ADDRESS 0x2BU
59 #define MIPI_DCS_WRITE_MEMORY_START 0x2CU
60 #define MIPI_DCS_WRITE_LUT 0x2DU
61 #define MIPI_DCS_READ_MEMORY_START 0x2EU
62 #define MIPI_DCS_SET_PARTIAL_ROWS 0x30U
63 #define MIPI_DCS_SET_PARTIAL_COLUMNS 0x31U
64 #define MIPI_DCS_SET_SCROLL_AREA 0x33U
65 #define MIPI_DCS_SET_TEAR_OFF 0x34U
66 #define MIPI_DCS_SET_TEAR_ON 0x35U
67 #define MIPI_DCS_SET_ADDRESS_MODE 0x36U
68 #define MIPI_DCS_SET_SCROLL_START 0x37U
69 #define MIPI_DCS_EXIT_IDLE_MODE 0x38U
70 #define MIPI_DCS_ENTER_IDLE_MODE 0x39U
71 #define MIPI_DCS_SET_PIXEL_FORMAT 0x3AU
72 #define MIPI_DCS_WRITE_MEMORY_CONTINUE 0x3CU
73 #define MIPI_DCS_SET_3D_CONTROL 0x3DU
74 #define MIPI_DCS_READ_MEMORY_CONTINUE 0x3EU
75 #define MIPI_DCS_GET_3D_CONTROL 0x3FU
76 #define MIPI_DCS_SET_VSYNC_TIMING 0x40U
77 #define MIPI_DCS_SET_TEAR_SCANLINE 0x44U
78 #define MIPI_DCS_GET_SCANLINE 0x45U
79 #define MIPI_DCS_SET_DISPLAY_BRIGHTNESS 0x51U
80 #define MIPI_DCS_GET_DISPLAY_BRIGHTNESS 0x52U
81 #define MIPI_DCS_WRITE_CONTROL_DISPLAY 0x53U
82 #define MIPI_DCS_GET_CONTROL_DISPLAY 0x54U
83 #define MIPI_DCS_WRITE_POWER_SAVE 0x55U
84 #define MIPI_DCS_GET_POWER_SAVE 0x56U
85 #define MIPI_DCS_SET_CABC_MIN_BRIGHTNESS 0x5EU
86 #define MIPI_DCS_GET_CABC_MIN_BRIGHTNESS 0x5FU
87 #define MIPI_DCS_READ_DDB_START 0xA1U
88 #define MIPI_DCS_READ_DDB_CONTINUE 0xA8U
89
90 #define MIPI_DCS_PIXEL_FORMAT_24BIT 0x77
91 #define MIPI_DCS_PIXEL_FORMAT_18BIT 0x66
92 #define MIPI_DCS_PIXEL_FORMAT_16BIT 0x55
93 #define MIPI_DCS_PIXEL_FORMAT_12BIT 0x33
94 #define MIPI_DCS_PIXEL_FORMAT_8BIT 0x22
95 #define MIPI_DCS_PIXEL_FORMAT_3BIT 0x11
96
97 /** @} */
98
99 /**
100 * @name MIPI-DSI Address mode register fields.
101 * @{
102 */
103
104 #define MIPI_DCS_ADDRESS_MODE_MIRROR_Y BIT(7)
105 #define MIPI_DCS_ADDRESS_MODE_MIRROR_X BIT(6)
106 #define MIPI_DCS_ADDRESS_MODE_SWAP_XY BIT(5)
107 #define MIPI_DCS_ADDRESS_MODE_REFRESH_BT BIT(4)
108 #define MIPI_DCS_ADDRESS_MODE_BGR BIT(3)
109 #define MIPI_DCS_ADDRESS_MODE_LATCH_RL BIT(2)
110 #define MIPI_DCS_ADDRESS_MODE_FLIP_X BIT(1)
111 #define MIPI_DCS_ADDRESS_MODE_FLIP_Y BIT(0)
112
113 /** @} */
114
115 /**
116 * @name MIPI-DSI Processor-to-Peripheral transaction types.
117 * @{
118 */
119
120 #define MIPI_DSI_V_SYNC_START 0x01U
121 #define MIPI_DSI_V_SYNC_END 0x11U
122 #define MIPI_DSI_H_SYNC_START 0x21U
123 #define MIPI_DSI_H_SYNC_END 0x31U
124 #define MIPI_DSI_COLOR_MODE_OFF 0x02U
125 #define MIPI_DSI_COLOR_MODE_ON 0x12U
126 #define MIPI_DSI_SHUTDOWN_PERIPHERAL 0x22U
127 #define MIPI_DSI_TURN_ON_PERIPHERAL 0x32U
128 #define MIPI_DSI_GENERIC_SHORT_WRITE_0_PARAM 0x03U
129 #define MIPI_DSI_GENERIC_SHORT_WRITE_1_PARAM 0x13U
130 #define MIPI_DSI_GENERIC_SHORT_WRITE_2_PARAM 0x23U
131 #define MIPI_DSI_GENERIC_READ_REQUEST_0_PARAM 0x04U
132 #define MIPI_DSI_GENERIC_READ_REQUEST_1_PARAM 0x14U
133 #define MIPI_DSI_GENERIC_READ_REQUEST_2_PARAM 0x24U
134 #define MIPI_DSI_DCS_SHORT_WRITE 0x05U
135 #define MIPI_DSI_DCS_SHORT_WRITE_PARAM 0x15U
136 #define MIPI_DSI_DCS_READ 0x06U
137 #define MIPI_DSI_SET_MAXIMUM_RETURN_PACKET_SIZE 0x37U
138 #define MIPI_DSI_END_OF_TRANSMISSION 0x08U
139 #define MIPI_DSI_NULL_PACKET 0x09U
140 #define MIPI_DSI_BLANKING_PACKET 0x19U
141 #define MIPI_DSI_GENERIC_LONG_WRITE 0x29U
142 #define MIPI_DSI_DCS_LONG_WRITE 0x39U
143 #define MIPI_DSI_LOOSELY_PACKED_PIXEL_STREAM_YCBCR20 0x0CU
144 #define MIPI_DSI_PACKED_PIXEL_STREAM_YCBCR24 0x1CU
145 #define MIPI_DSI_PACKED_PIXEL_STREAM_YCBCR16 0x2CU
146 #define MIPI_DSI_PACKED_PIXEL_STREAM_30 0x0DU
147 #define MIPI_DSI_PACKED_PIXEL_STREAM_36 0x1DU
148 #define MIPI_DSI_PACKED_PIXEL_STREAM_YCBCR12 0x3DU
149 #define MIPI_DSI_PACKED_PIXEL_STREAM_16 0x0EU
150 #define MIPI_DSI_PACKED_PIXEL_STREAM_18 0x1EU
151 #define MIPI_DSI_PIXEL_STREAM_3BYTE_18 0x2EU
152 #define MIPI_DSI_PACKED_PIXEL_STREAM_24 0x3EU
153
154 /** @} */
155
156 /** MIPI-DSI display timings. */
157 struct mipi_dsi_timings {
158 /** Horizontal active video. */
159 uint32_t hactive;
160 /** Horizontal front porch. */
161 uint32_t hfp;
162 /** Horizontal back porch. */
163 uint32_t hbp;
164 /** Horizontal sync length. */
165 uint32_t hsync;
166 /** Vertical active video. */
167 uint32_t vactive;
168 /** Vertical front porch. */
169 uint32_t vfp;
170 /** Vertical back porch. */
171 uint32_t vbp;
172 /** Vertical sync length. */
173 uint32_t vsync;
174 };
175
176 /**
177 * @name MIPI-DSI Device mode flags.
178 * @{
179 */
180
181 /** Video mode */
182 #define MIPI_DSI_MODE_VIDEO BIT(0)
183 /** Video burst mode */
184 #define MIPI_DSI_MODE_VIDEO_BURST BIT(1)
185 /** Video pulse mode */
186 #define MIPI_DSI_MODE_VIDEO_SYNC_PULSE BIT(2)
187 /** Enable auto vertical count mode */
188 #define MIPI_DSI_MODE_VIDEO_AUTO_VERT BIT(3)
189 /** Enable hsync-end packets in vsync-pulse and v-porch area */
190 #define MIPI_DSI_MODE_VIDEO_HSE BIT(4)
191 /** Disable hfront-porch area */
192 #define MIPI_DSI_MODE_VIDEO_HFP BIT(5)
193 /** Disable hback-porch area */
194 #define MIPI_DSI_MODE_VIDEO_HBP BIT(6)
195 /** Disable hsync-active area */
196 #define MIPI_DSI_MODE_VIDEO_HSA BIT(7)
197 /** Flush display FIFO on vsync pulse */
198 #define MIPI_DSI_MODE_VSYNC_FLUSH BIT(8)
199 /** Disable EoT packets in HS mode */
200 #define MIPI_DSI_MODE_EOT_PACKET BIT(9)
201 /** Device supports non-continuous clock behavior (DSI spec 5.6.1) */
202 #define MIPI_DSI_CLOCK_NON_CONTINUOUS BIT(10)
203 /** Transmit data in low power */
204 #define MIPI_DSI_MODE_LPM BIT(11)
205
206 /** @} */
207
208 /** MIPI-DSI device. */
209 struct mipi_dsi_device {
210 /** Number of data lanes. */
211 uint8_t data_lanes;
212 /** Display timings. */
213 struct mipi_dsi_timings timings;
214 /** Pixel format. */
215 uint32_t pixfmt;
216 /** Mode flags. */
217 uint32_t mode_flags;
218 };
219
220 /** MIPI-DSI read/write message. */
221 struct mipi_dsi_msg {
222 /** Payload data type. */
223 uint8_t type;
224 /** Flags controlling message transmission. */
225 uint16_t flags;
226 /** Command (only for DCS) */
227 uint8_t cmd;
228 /** Transmission buffer length. */
229 size_t tx_len;
230 /** Transmission buffer. */
231 const void *tx_buf;
232 /** Reception buffer length. */
233 size_t rx_len;
234 /** Reception buffer. */
235 void *rx_buf;
236 };
237
238 /** MIPI-DSI host driver API. */
239 __subsystem struct mipi_dsi_driver_api {
240 int (*attach)(const struct device *dev, uint8_t channel,
241 const struct mipi_dsi_device *mdev);
242 ssize_t (*transfer)(const struct device *dev, uint8_t channel,
243 struct mipi_dsi_msg *msg);
244 };
245
246 /**
247 * @brief Attach a new device to the MIPI-DSI bus.
248 *
249 * @param dev MIPI-DSI host device.
250 * @param channel Device channel (VID).
251 * @param mdev MIPI-DSI device description.
252 *
253 * @return 0 on success, negative on error
254 */
mipi_dsi_attach(const struct device * dev,uint8_t channel,const struct mipi_dsi_device * mdev)255 static inline int mipi_dsi_attach(const struct device *dev,
256 uint8_t channel,
257 const struct mipi_dsi_device *mdev)
258 {
259 const struct mipi_dsi_driver_api *api = (const struct mipi_dsi_driver_api *)dev->api;
260
261 return api->attach(dev, channel, mdev);
262 }
263
264 /**
265 * @brief Transfer data to/from a device attached to the MIPI-DSI bus.
266 *
267 * @param dev MIPI-DSI device.
268 * @param channel Device channel (VID).
269 * @param msg Message.
270 *
271 * @return Size of the transferred data on success, negative on error.
272 */
mipi_dsi_transfer(const struct device * dev,uint8_t channel,struct mipi_dsi_msg * msg)273 static inline ssize_t mipi_dsi_transfer(const struct device *dev,
274 uint8_t channel,
275 struct mipi_dsi_msg *msg)
276 {
277 const struct mipi_dsi_driver_api *api = (const struct mipi_dsi_driver_api *)dev->api;
278
279 return api->transfer(dev, channel, msg);
280 }
281
282 /**
283 * @brief MIPI-DSI generic read.
284 *
285 * @param dev MIPI-DSI host device.
286 * @param channel Device channel (VID).
287 * @param params Buffer containing request parameters.
288 * @param nparams Number of parameters.
289 * @param buf Buffer where read data will be stored.
290 * @param len Length of the reception buffer.
291 *
292 * @return Size of the read data on success, negative on error.
293 */
294 ssize_t mipi_dsi_generic_read(const struct device *dev, uint8_t channel,
295 const void *params, size_t nparams,
296 void *buf, size_t len);
297
298 /**
299 * @brief MIPI-DSI generic write.
300 *
301 * @param dev MIPI-DSI host device.
302 * @param channel Device channel (VID).
303 * @param buf Transmission buffer.
304 * @param len Length of the transmission buffer
305 *
306 * @return Size of the written data on success, negative on error.
307 */
308 ssize_t mipi_dsi_generic_write(const struct device *dev, uint8_t channel,
309 const void *buf, size_t len);
310
311 /**
312 * @brief MIPI-DSI DCS read.
313 *
314 * @param dev MIPI-DSI host device.
315 * @param channel Device channel (VID).
316 * @param cmd DCS command.
317 * @param buf Buffer where read data will be stored.
318 * @param len Length of the reception buffer.
319 *
320 * @return Size of the read data on success, negative on error.
321 */
322 ssize_t mipi_dsi_dcs_read(const struct device *dev, uint8_t channel,
323 uint8_t cmd, void *buf, size_t len);
324
325 /**
326 * @brief MIPI-DSI DCS write.
327 *
328 * @param dev MIPI-DSI host device.
329 * @param channel Device channel (VID).
330 * @param cmd DCS command.
331 * @param buf Transmission buffer.
332 * @param len Length of the transmission buffer
333 *
334 * @return Size of the written data on success, negative on error.
335 */
336 ssize_t mipi_dsi_dcs_write(const struct device *dev, uint8_t channel,
337 uint8_t cmd, const void *buf, size_t len);
338
339 #ifdef __cplusplus
340 }
341 #endif
342
343 /**
344 * @}
345 */
346
347 #endif /* ZEPHYR_INCLUDE_DRIVERS_MIPI_DSI_H_ */
348
