1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * MIPI DSI Bus
4  *
5  * Copyright (C) 2012-2013, Samsung Electronics, Co., Ltd.
6  * Copyright (C) 2018 STMicroelectronics - All Rights Reserved
7  * Author(s): Andrzej Hajda <a.hajda@samsung.com>
8  *            Yannick Fertre <yannick.fertre@st.com>
9  *            Philippe Cornu <philippe.cornu@st.com>
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License version 2 as
13  * published by the Free Software Foundation.
14  */
15 #ifndef MIPI_DSI_H
16 #define MIPI_DSI_H
17 
18 #include <mipi_display.h>
19 #include <linux/bitops.h>
20 
21 struct mipi_dsi_host;
22 struct mipi_dsi_device;
23 
24 /* request ACK from peripheral */
25 #define MIPI_DSI_MSG_REQ_ACK	BIT(0)
26 /* use Low Power Mode to transmit message */
27 #define MIPI_DSI_MSG_USE_LPM	BIT(1)
28 
29 /**
30  * struct mipi_dsi_msg - read/write DSI buffer
31  * @channel: virtual channel id
32  * @type: payload data type
33  * @flags: flags controlling this message transmission
34  * @tx_len: length of @tx_buf
35  * @tx_buf: data to be written
36  * @rx_len: length of @rx_buf
37  * @rx_buf: data to be read, or NULL
38  */
39 struct mipi_dsi_msg {
40 	u8 channel;
41 	u8 type;
42 	u16 flags;
43 
44 	size_t tx_len;
45 	const void *tx_buf;
46 
47 	size_t rx_len;
48 	void *rx_buf;
49 };
50 
51 bool mipi_dsi_packet_format_is_short(u8 type);
52 bool mipi_dsi_packet_format_is_long(u8 type);
53 
54 /**
55  * struct mipi_dsi_packet - represents a MIPI DSI packet in protocol format
56  * @size: size (in bytes) of the packet
57  * @header: the four bytes that make up the header (Data ID, Word Count or
58  *     Packet Data, and ECC)
59  * @payload_length: number of bytes in the payload
60  * @payload: a pointer to a buffer containing the payload, if any
61  */
62 struct mipi_dsi_packet {
63 	size_t size;
64 	u8 header[4];
65 	size_t payload_length;
66 	const u8 *payload;
67 };
68 
69 int mipi_dsi_create_packet(struct mipi_dsi_packet *packet,
70 			   const struct mipi_dsi_msg *msg);
71 
72 /**
73  * struct mipi_dsi_host_ops - DSI bus operations
74  * @attach: attach DSI device to DSI host
75  * @detach: detach DSI device from DSI host
76  * @transfer: transmit a DSI packet
77  *
78  * DSI packets transmitted by .transfer() are passed in as mipi_dsi_msg
79  * structures. This structure contains information about the type of packet
80  * being transmitted as well as the transmit and receive buffers. When an
81  * error is encountered during transmission, this function will return a
82  * negative error code. On success it shall return the number of bytes
83  * transmitted for write packets or the number of bytes received for read
84  * packets.
85  *
86  * Note that typically DSI packet transmission is atomic, so the .transfer()
87  * function will seldomly return anything other than the number of bytes
88  * contained in the transmit buffer on success.
89  */
90 struct mipi_dsi_host_ops {
91 	int (*attach)(struct mipi_dsi_host *host,
92 		      struct mipi_dsi_device *dsi);
93 	int (*detach)(struct mipi_dsi_host *host,
94 		      struct mipi_dsi_device *dsi);
95 	ssize_t (*transfer)(struct mipi_dsi_host *host,
96 			    const struct mipi_dsi_msg *msg);
97 };
98 
99 /**
100  * struct mipi_dsi_phy_timing - DSI host phy timings
101  * @data_hs2lp: High Speed to Low Speed Data Transition Time
102  * @data_lp2hs: Low Speed to High Speed Data Transition Time
103  * @clk_hs2lp: High Speed to Low Speed Clock Transition Time
104  * @clk_lp2hs: Low Speed to High Speed Clock Transition Time
105  */
106 struct mipi_dsi_phy_timing {
107 	u16 data_hs2lp;
108 	u16 data_lp2hs;
109 	u16 clk_hs2lp;
110 	u16 clk_lp2hs;
111 };
112 
113 /**
114  * struct mipi_dsi_phy_ops - DSI host physical operations
115  * @init: initialized host physical part
116  * @get_lane_mbps: get lane bitrate per lane (mbps)
117  * @post_set_mode: operation that should after set mode
118  */
119 struct mipi_dsi_phy_ops {
120 	int (*init)(void *priv_data);
121 	int (*get_lane_mbps)(void *priv_data, struct display_timing *timings,
122 			     u32 lanes, u32 format, unsigned int *lane_mbps);
123 	void (*post_set_mode)(void *priv_data,  unsigned long mode_flags);
124 	int (*get_timing)(void *priv_data, unsigned int lane_mbps,
125 			  struct mipi_dsi_phy_timing *timing);
126 	void (*get_esc_clk_rate)(void *priv_data, unsigned int *esc_clk_rate);
127 };
128 
129 /**
130  * struct mipi_dsi_host - DSI host device
131  * @dev: driver model device node for this DSI host
132  * @ops: DSI host operations
133  * @list: list management
134  */
135 struct mipi_dsi_host {
136 	struct device *dev;
137 	const struct mipi_dsi_host_ops *ops;
138 	struct list_head list;
139 };
140 
141 /* DSI mode flags */
142 
143 /* video mode */
144 #define MIPI_DSI_MODE_VIDEO		BIT(0)
145 /* video burst mode */
146 #define MIPI_DSI_MODE_VIDEO_BURST	BIT(1)
147 /* video pulse mode */
148 #define MIPI_DSI_MODE_VIDEO_SYNC_PULSE	BIT(2)
149 /* enable auto vertical count mode */
150 #define MIPI_DSI_MODE_VIDEO_AUTO_VERT	BIT(3)
151 /* enable hsync-end packets in vsync-pulse and v-porch area */
152 #define MIPI_DSI_MODE_VIDEO_HSE		BIT(4)
153 /* disable hfront-porch area */
154 #define MIPI_DSI_MODE_VIDEO_HFP		BIT(5)
155 /* disable hback-porch area */
156 #define MIPI_DSI_MODE_VIDEO_HBP		BIT(6)
157 /* disable hsync-active area */
158 #define MIPI_DSI_MODE_VIDEO_HSA		BIT(7)
159 /* flush display FIFO on vsync pulse */
160 #define MIPI_DSI_MODE_VSYNC_FLUSH	BIT(8)
161 /* disable EoT packets in HS mode */
162 #define MIPI_DSI_MODE_EOT_PACKET	BIT(9)
163 /* device supports non-continuous clock behavior (DSI spec 5.6.1) */
164 #define MIPI_DSI_CLOCK_NON_CONTINUOUS	BIT(10)
165 /* transmit data in low power */
166 #define MIPI_DSI_MODE_LPM		BIT(11)
167 
168 enum mipi_dsi_pixel_format {
169 	MIPI_DSI_FMT_RGB888,
170 	MIPI_DSI_FMT_RGB666,
171 	MIPI_DSI_FMT_RGB666_PACKED,
172 	MIPI_DSI_FMT_RGB565,
173 };
174 
175 #define DSI_DEV_NAME_SIZE		20
176 
177 /**
178  * struct mipi_dsi_device_info - template for creating a mipi_dsi_device
179  * @type: DSI peripheral chip type
180  * @channel: DSI virtual channel assigned to peripheral
181  * @node: pointer to OF device node or NULL
182  *
183  * This is populated and passed to mipi_dsi_device_new to create a new
184  * DSI device
185  */
186 struct mipi_dsi_device_info {
187 	char type[DSI_DEV_NAME_SIZE];
188 	u32 channel;
189 	struct device_node *node;
190 };
191 
192 /**
193  * struct mipi_dsi_device - DSI peripheral device
194  * @host: DSI host for this peripheral
195  * @dev: driver model device node for this peripheral
196  * @name: DSI peripheral chip type
197  * @channel: virtual channel assigned to the peripheral
198  * @format: pixel format for video mode
199  * @lanes: number of active data lanes
200  * @mode_flags: DSI operation mode related flags
201  */
202 struct mipi_dsi_device {
203 	struct mipi_dsi_host *host;
204 	struct udevice *dev;
205 
206 	char name[DSI_DEV_NAME_SIZE];
207 	unsigned int channel;
208 	unsigned int lanes;
209 	enum mipi_dsi_pixel_format format;
210 	unsigned long mode_flags;
211 };
212 
213 /**
214  * mipi_dsi_pixel_format_to_bpp - obtain the number of bits per pixel for any
215  *                                given pixel format defined by the MIPI DSI
216  *                                specification
217  * @fmt: MIPI DSI pixel format
218  *
219  * Returns: The number of bits per pixel of the given pixel format.
220  */
mipi_dsi_pixel_format_to_bpp(enum mipi_dsi_pixel_format fmt)221 static inline int mipi_dsi_pixel_format_to_bpp(enum mipi_dsi_pixel_format fmt)
222 {
223 	switch (fmt) {
224 	case MIPI_DSI_FMT_RGB888:
225 	case MIPI_DSI_FMT_RGB666:
226 		return 24;
227 
228 	case MIPI_DSI_FMT_RGB666_PACKED:
229 		return 18;
230 
231 	case MIPI_DSI_FMT_RGB565:
232 		return 16;
233 	}
234 
235 	return -EINVAL;
236 }
237 
238 /**
239  * struct mipi_dsi_panel_plat - DSI panel platform data
240  * @device: DSI peripheral device
241  * @lanes: number of active data lanes
242  * @format: pixel format for video mode
243  * @mode_flags: DSI operation mode related flags
244  */
245 struct mipi_dsi_panel_plat {
246 	struct mipi_dsi_device *device;
247 	unsigned int lanes;
248 	enum mipi_dsi_pixel_format format;
249 	unsigned long mode_flags;
250 };
251 
252 /**
253  * mipi_dsi_attach - attach a DSI device to its DSI host
254  * @dsi: DSI peripheral
255  */
256 int mipi_dsi_attach(struct mipi_dsi_device *dsi);
257 
258 /**
259  * mipi_dsi_detach - detach a DSI device from its DSI host
260  * @dsi: DSI peripheral
261  */
262 int mipi_dsi_detach(struct mipi_dsi_device *dsi);
263 int mipi_dsi_shutdown_peripheral(struct mipi_dsi_device *dsi);
264 int mipi_dsi_turn_on_peripheral(struct mipi_dsi_device *dsi);
265 int mipi_dsi_set_maximum_return_packet_size(struct mipi_dsi_device *dsi,
266 					    u16 value);
267 
268 ssize_t mipi_dsi_generic_write(struct mipi_dsi_device *dsi, const void *payload,
269 			       size_t size);
270 ssize_t mipi_dsi_generic_read(struct mipi_dsi_device *dsi, const void *params,
271 			      size_t num_params, void *data, size_t size);
272 
273 /**
274  * enum mipi_dsi_dcs_tear_mode - Tearing Effect Output Line mode
275  * @MIPI_DSI_DCS_TEAR_MODE_VBLANK: the TE output line consists of V-Blanking
276  *    information only
277  * @MIPI_DSI_DCS_TEAR_MODE_VHBLANK : the TE output line consists of both
278  *    V-Blanking and H-Blanking information
279  */
280 enum mipi_dsi_dcs_tear_mode {
281 	MIPI_DSI_DCS_TEAR_MODE_VBLANK,
282 	MIPI_DSI_DCS_TEAR_MODE_VHBLANK,
283 };
284 
285 #define MIPI_DSI_DCS_POWER_MODE_DISPLAY BIT(2)
286 #define MIPI_DSI_DCS_POWER_MODE_NORMAL  BIT(3)
287 #define MIPI_DSI_DCS_POWER_MODE_SLEEP   BIT(4)
288 #define MIPI_DSI_DCS_POWER_MODE_PARTIAL BIT(5)
289 #define MIPI_DSI_DCS_POWER_MODE_IDLE    BIT(6)
290 
291 /**
292  * mipi_dsi_dcs_write_buffer() - transmit a DCS command with payload
293  * @dsi: DSI peripheral device
294  * @data: buffer containing data to be transmitted
295  * @len: size of transmission buffer
296  *
297  * This function will automatically choose the right data type depending on
298  * the command payload length.
299  *
300  * Return: The number of bytes successfully transmitted or a negative error
301  * code on failure.
302  */
303 ssize_t mipi_dsi_dcs_write_buffer(struct mipi_dsi_device *dsi,
304 				  const void *data, size_t len);
305 
306 /**
307  * mipi_dsi_dcs_write() - send DCS write command
308  * @dsi: DSI peripheral device
309  * @cmd: DCS command
310  * @data: buffer containing the command payload
311  * @len: command payload length
312  *
313  * This function will automatically choose the right data type depending on
314  * the command payload length.
315 
316  * code on failure.
317  */
318 ssize_t mipi_dsi_dcs_write(struct mipi_dsi_device *dsi, u8 cmd,
319 			   const void *data, size_t len);
320 
321 /**
322  * mipi_dsi_dcs_read() - send DCS read request command
323  * @dsi: DSI peripheral device
324  * @cmd: DCS command
325  * @data: buffer in which to receive data
326  * @len: size of receive buffer
327  *
328  * Return: The number of bytes read or a negative error code on failure.
329  */
330 ssize_t mipi_dsi_dcs_read(struct mipi_dsi_device *dsi, u8 cmd, void *data,
331 			  size_t len);
332 
333 /**
334  * mipi_dsi_dcs_nop() - send DCS nop packet
335  * @dsi: DSI peripheral device
336  *
337  * Return: 0 on success or a negative error code on failure.
338  */
339 int mipi_dsi_dcs_nop(struct mipi_dsi_device *dsi);
340 
341 /**
342  * mipi_dsi_dcs_soft_reset() - perform a software reset of the display module
343  * @dsi: DSI peripheral device
344  *
345  * Return: 0 on success or a negative error code on failure.
346  */
347 int mipi_dsi_dcs_soft_reset(struct mipi_dsi_device *dsi);
348 
349 /**
350  * mipi_dsi_dcs_get_power_mode() - query the display module's current power
351  *    mode
352  * @dsi: DSI peripheral device
353  * @mode: return location for the current power mode
354  *
355  * Return: 0 on success or a negative error code on failure.
356  */
357 int mipi_dsi_dcs_get_power_mode(struct mipi_dsi_device *dsi, u8 *mode);
358 
359 /**
360  * mipi_dsi_dcs_get_pixel_format() - gets the pixel format for the RGB image
361  *    data used by the interface
362  * @dsi: DSI peripheral device
363  * @format: return location for the pixel format
364  *
365  * Return: 0 on success or a negative error code on failure.
366  */
367 int mipi_dsi_dcs_get_pixel_format(struct mipi_dsi_device *dsi, u8 *format);
368 
369 /**
370  * mipi_dsi_dcs_enter_sleep_mode() - disable all unnecessary blocks inside the
371  *    display module except interface communication
372  * @dsi: DSI peripheral device
373  *
374  * Return: 0 on success or a negative error code on failure.
375  */
376 int mipi_dsi_dcs_enter_sleep_mode(struct mipi_dsi_device *dsi);
377 
378 /**
379  * mipi_dsi_dcs_exit_sleep_mode() - enable all blocks inside the display
380  *    module
381  * @dsi: DSI peripheral device
382  *
383  * Return: 0 on success or a negative error code on failure.
384  */
385 int mipi_dsi_dcs_exit_sleep_mode(struct mipi_dsi_device *dsi);
386 
387 /**
388  * mipi_dsi_dcs_set_display_off() - stop displaying the image data on the
389  *    display device
390  * @dsi: DSI peripheral device
391  *
392  * Return: 0 on success or a negative error code on failure.
393  */
394 int mipi_dsi_dcs_set_display_off(struct mipi_dsi_device *dsi);
395 
396 /**
397  * mipi_dsi_dcs_set_display_on() - start displaying the image data on the
398  *    display device
399  * @dsi: DSI peripheral device
400  *
401  * Return: 0 on success or a negative error code on failure
402  */
403 int mipi_dsi_dcs_set_display_on(struct mipi_dsi_device *dsi);
404 
405 /**
406  * mipi_dsi_dcs_set_column_address() - define the column extent of the frame
407  *    memory accessed by the host processor
408  * @dsi: DSI peripheral device
409  * @start: first column of frame memory
410  * @end: last column of frame memory
411  *
412  * Return: 0 on success or a negative error code on failure.
413  */
414 int mipi_dsi_dcs_set_column_address(struct mipi_dsi_device *dsi, u16 start,
415 				    u16 end);
416 /**
417  * mipi_dsi_dcs_set_page_address() - define the page extent of the frame
418  *    memory accessed by the host processor
419  * @dsi: DSI peripheral device
420  * @start: first page of frame memory
421  * @end: last page of frame memory
422  *
423  * Return: 0 on success or a negative error code on failure.
424  */
425 int mipi_dsi_dcs_set_page_address(struct mipi_dsi_device *dsi, u16 start,
426 				  u16 end);
427 
428 /**
429  * mipi_dsi_dcs_set_tear_off() - turn off the display module's Tearing Effect
430  *    output signal on the TE signal line
431  * @dsi: DSI peripheral device
432  *
433  * Return: 0 on success or a negative error code on failure
434  */
435 int mipi_dsi_dcs_set_tear_off(struct mipi_dsi_device *dsi);
436 
437 /**
438  * mipi_dsi_dcs_set_tear_on() - turn on the display module's Tearing Effect
439  *    output signal on the TE signal line.
440  * @dsi: DSI peripheral device
441  * @mode: the Tearing Effect Output Line mode
442  *
443  * Return: 0 on success or a negative error code on failure
444  */
445 int mipi_dsi_dcs_set_tear_on(struct mipi_dsi_device *dsi,
446 			     enum mipi_dsi_dcs_tear_mode mode);
447 
448 /**
449  * mipi_dsi_dcs_set_pixel_format() - sets the pixel format for the RGB image
450  *    data used by the interface
451  * @dsi: DSI peripheral device
452  * @format: pixel format
453  *
454  * Return: 0 on success or a negative error code on failure.
455  */
456 int mipi_dsi_dcs_set_pixel_format(struct mipi_dsi_device *dsi, u8 format);
457 
458 /**
459  * mipi_dsi_dcs_set_tear_scanline() - set the scanline to use as trigger for
460  *    the Tearing Effect output signal of the display module
461  * @dsi: DSI peripheral device
462  * @scanline: scanline to use as trigger
463  *
464  * Return: 0 on success or a negative error code on failure
465  */
466 int mipi_dsi_dcs_set_tear_scanline(struct mipi_dsi_device *dsi, u16 scanline);
467 
468 /**
469  * mipi_dsi_dcs_set_display_brightness() - sets the brightness value of the
470  *    display
471  * @dsi: DSI peripheral device
472  * @brightness: brightness value
473  *
474  * Return: 0 on success or a negative error code on failure.
475  */
476 int mipi_dsi_dcs_set_display_brightness(struct mipi_dsi_device *dsi,
477 					u16 brightness);
478 
479 /**
480  * mipi_dsi_dcs_get_display_brightness() - gets the current brightness value
481  *    of the display
482  * @dsi: DSI peripheral device
483  * @brightness: brightness value
484  *
485  * Return: 0 on success or a negative error code on failure.
486  */
487 int mipi_dsi_dcs_get_display_brightness(struct mipi_dsi_device *dsi,
488 					u16 *brightness);
489 
490 #endif /* MIPI_DSI_H */
491