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 * @since 3.1
19 * @version 0.1.0
20 * @ingroup io_interfaces
21 * @{
22 */
23 #include <errno.h>
24 #include <sys/types.h>
25 #include <zephyr/device.h>
26 #include <zephyr/display/mipi_display.h>
27 #include <zephyr/dt-bindings/mipi_dsi/mipi_dsi.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /** MIPI-DSI display timings. */
34 struct mipi_dsi_timings {
35 /** Horizontal active video. */
36 uint32_t hactive;
37 /** Horizontal front porch. */
38 uint32_t hfp;
39 /** Horizontal back porch. */
40 uint32_t hbp;
41 /** Horizontal sync length. */
42 uint32_t hsync;
43 /** Vertical active video. */
44 uint32_t vactive;
45 /** Vertical front porch. */
46 uint32_t vfp;
47 /** Vertical back porch. */
48 uint32_t vbp;
49 /** Vertical sync length. */
50 uint32_t vsync;
51 };
52
53 /**
54 * @name MIPI-DSI Device mode flags.
55 * @{
56 */
57
58 /** Video mode */
59 #define MIPI_DSI_MODE_VIDEO BIT(0)
60 /** Video burst mode */
61 #define MIPI_DSI_MODE_VIDEO_BURST BIT(1)
62 /** Video pulse mode */
63 #define MIPI_DSI_MODE_VIDEO_SYNC_PULSE BIT(2)
64 /** Enable auto vertical count mode */
65 #define MIPI_DSI_MODE_VIDEO_AUTO_VERT BIT(3)
66 /** Enable hsync-end packets in vsync-pulse and v-porch area */
67 #define MIPI_DSI_MODE_VIDEO_HSE BIT(4)
68 /** Disable hfront-porch area */
69 #define MIPI_DSI_MODE_VIDEO_HFP BIT(5)
70 /** Disable hback-porch area */
71 #define MIPI_DSI_MODE_VIDEO_HBP BIT(6)
72 /** Disable hsync-active area */
73 #define MIPI_DSI_MODE_VIDEO_HSA BIT(7)
74 /** Flush display FIFO on vsync pulse */
75 #define MIPI_DSI_MODE_VSYNC_FLUSH BIT(8)
76 /** Disable EoT packets in HS mode */
77 #define MIPI_DSI_MODE_EOT_PACKET BIT(9)
78 /** Device supports non-continuous clock behavior (DSI spec 5.6.1) */
79 #define MIPI_DSI_CLOCK_NON_CONTINUOUS BIT(10)
80 /** Transmit data in low power */
81 #define MIPI_DSI_MODE_LPM BIT(11)
82
83 /** @} */
84
85 /** MIPI-DSI device. */
86 struct mipi_dsi_device {
87 /** Number of data lanes. */
88 uint8_t data_lanes;
89 /** Display timings. */
90 struct mipi_dsi_timings timings;
91 /** Pixel format. */
92 uint32_t pixfmt;
93 /** Mode flags. */
94 uint32_t mode_flags;
95 };
96
97 /*
98 * Per message flag to indicate the message must be sent
99 * using Low Power Mode instead of controller default.
100 */
101 #define MIPI_DSI_MSG_USE_LPM BIT(0x0)
102
103 /** MIPI-DSI read/write message. */
104 struct mipi_dsi_msg {
105 /** Payload data type. */
106 uint8_t type;
107 /** Flags controlling message transmission. */
108 uint16_t flags;
109 /** Command (only for DCS) */
110 uint8_t cmd;
111 /** Transmission buffer length. */
112 size_t tx_len;
113 /** Transmission buffer. */
114 const void *tx_buf;
115 /** Reception buffer length. */
116 size_t rx_len;
117 /** Reception buffer. */
118 void *rx_buf;
119 };
120
121 /** MIPI-DSI host driver API. */
122 __subsystem struct mipi_dsi_driver_api {
123 int (*attach)(const struct device *dev, uint8_t channel,
124 const struct mipi_dsi_device *mdev);
125 ssize_t (*transfer)(const struct device *dev, uint8_t channel,
126 struct mipi_dsi_msg *msg);
127 int (*detach)(const struct device *dev, uint8_t channel,
128 const struct mipi_dsi_device *mdev);
129 };
130
131 /**
132 * @brief Attach a new device to the MIPI-DSI bus.
133 *
134 * @param dev MIPI-DSI host device.
135 * @param channel Device channel (VID).
136 * @param mdev MIPI-DSI device description.
137 *
138 * @return 0 on success, negative on error
139 */
mipi_dsi_attach(const struct device * dev,uint8_t channel,const struct mipi_dsi_device * mdev)140 static inline int mipi_dsi_attach(const struct device *dev,
141 uint8_t channel,
142 const struct mipi_dsi_device *mdev)
143 {
144 const struct mipi_dsi_driver_api *api = (const struct mipi_dsi_driver_api *)dev->api;
145
146 return api->attach(dev, channel, mdev);
147 }
148
149 /**
150 * @brief Transfer data to/from a device attached to the MIPI-DSI bus.
151 *
152 * @param dev MIPI-DSI device.
153 * @param channel Device channel (VID).
154 * @param msg Message.
155 *
156 * @return Size of the transferred data on success, negative on error.
157 */
mipi_dsi_transfer(const struct device * dev,uint8_t channel,struct mipi_dsi_msg * msg)158 static inline ssize_t mipi_dsi_transfer(const struct device *dev,
159 uint8_t channel,
160 struct mipi_dsi_msg *msg)
161 {
162 const struct mipi_dsi_driver_api *api = (const struct mipi_dsi_driver_api *)dev->api;
163
164 return api->transfer(dev, channel, msg);
165 }
166
167 /**
168 * @brief MIPI-DSI generic read.
169 *
170 * @param dev MIPI-DSI host device.
171 * @param channel Device channel (VID).
172 * @param params Buffer containing request parameters.
173 * @param nparams Number of parameters.
174 * @param buf Buffer where read data will be stored.
175 * @param len Length of the reception buffer.
176 *
177 * @return Size of the read data on success, negative on error.
178 */
179 ssize_t mipi_dsi_generic_read(const struct device *dev, uint8_t channel,
180 const void *params, size_t nparams,
181 void *buf, size_t len);
182
183 /**
184 * @brief MIPI-DSI generic write.
185 *
186 * @param dev MIPI-DSI host device.
187 * @param channel Device channel (VID).
188 * @param buf Transmission buffer.
189 * @param len Length of the transmission buffer
190 *
191 * @return Size of the written data on success, negative on error.
192 */
193 ssize_t mipi_dsi_generic_write(const struct device *dev, uint8_t channel,
194 const void *buf, size_t len);
195
196 /**
197 * @brief MIPI-DSI DCS read.
198 *
199 * @param dev MIPI-DSI host device.
200 * @param channel Device channel (VID).
201 * @param cmd DCS command.
202 * @param buf Buffer where read data will be stored.
203 * @param len Length of the reception buffer.
204 *
205 * @return Size of the read data on success, negative on error.
206 */
207 ssize_t mipi_dsi_dcs_read(const struct device *dev, uint8_t channel,
208 uint8_t cmd, void *buf, size_t len);
209
210 /**
211 * @brief MIPI-DSI DCS write.
212 *
213 * @param dev MIPI-DSI host device.
214 * @param channel Device channel (VID).
215 * @param cmd DCS command.
216 * @param buf Transmission buffer.
217 * @param len Length of the transmission buffer
218 *
219 * @return Size of the written data on success, negative on error.
220 */
221 ssize_t mipi_dsi_dcs_write(const struct device *dev, uint8_t channel,
222 uint8_t cmd, const void *buf, size_t len);
223
224
225 /**
226 * @brief Detach a device from the MIPI-DSI bus
227 *
228 * @param dev MIPI-DSI host device.
229 * @param channel Device channel (VID).
230 * @param mdev MIPI-DSI device description.
231 *
232 * @return 0 on success, negative on error
233 */
mipi_dsi_detach(const struct device * dev,uint8_t channel,const struct mipi_dsi_device * mdev)234 static inline int mipi_dsi_detach(const struct device *dev,
235 uint8_t channel,
236 const struct mipi_dsi_device *mdev)
237 {
238 const struct mipi_dsi_driver_api *api = (const struct mipi_dsi_driver_api *)dev->api;
239
240 if (api->detach == NULL) {
241 return -ENOSYS;
242 }
243
244 return api->detach(dev, channel, mdev);
245 }
246
247 #ifdef __cplusplus
248 }
249 #endif
250
251 /**
252 * @}
253 */
254
255 #endif /* ZEPHYR_INCLUDE_DRIVERS_MIPI_DSI_H_ */
256
