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 21struct mipi_dsi_host; 22struct 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 */ 39struct 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 51bool mipi_dsi_packet_format_is_short(u8 type); 52bool 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 */ 62struct mipi_dsi_packet { 63 size_t size; 64 u8 header[4]; 65 size_t payload_length; 66 const u8 *payload; 67}; 68 69int 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 */ 90struct 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 */ 106struct 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 */ 119struct 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 */ 135struct 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 168enum 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 */ 186struct 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 */ 202struct 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 */ 221static 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 */ 245struct 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 */ 256int 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 */ 262int mipi_dsi_detach(struct mipi_dsi_device *dsi); 263int mipi_dsi_shutdown_peripheral(struct mipi_dsi_device *dsi); 264int mipi_dsi_turn_on_peripheral(struct mipi_dsi_device *dsi); 265int mipi_dsi_set_maximum_return_packet_size(struct mipi_dsi_device *dsi, 266 u16 value); 267 268ssize_t mipi_dsi_generic_write(struct mipi_dsi_device *dsi, const void *payload, 269 size_t size); 270ssize_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 */ 280enum 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 */ 303ssize_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 */ 318ssize_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 */ 330ssize_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 */ 339int 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 */ 347int 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 */ 357int 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 */ 367int 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 */ 376int 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 */ 385int 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 */ 394int 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 */ 403int 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 */ 414int 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 */ 425int 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 */ 435int 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 */ 445int 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 */ 456int 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 */ 466int 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 */ 476int 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 */ 487int mipi_dsi_dcs_get_display_brightness(struct mipi_dsi_device *dsi, 488 u16 *brightness); 489 490#endif /* MIPI_DSI_H */ 491