1 /*
2  * Copyright (c) 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016-2017, 2020-2021 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 
9 #ifndef _FSL_SSD1963_H_
10 #define _FSL_SSD1963_H_
11 
12 #include "fsl_dbi.h"
13 
14 /*!
15  * @addtogroup ssd1963
16  * @{
17  */
18 
19 /*
20  * Change log:
21  *
22  *   1.1.2
23  *     - Fix MISRA 2012 issues.
24  *
25  *   1.1.1
26  *     - Support RGB565/RGB888/BGR565/BGR888.
27  *
28  *   1.1.0
29  *     - Add 8-bit data bus support. Currently support 8-bit and 16bit data bus,
30  *       configured by the macro SSD1963_DATA_WITDH.
31  *     - Remove the dependency on flexio_mcu_lcd driver.
32  *     - Add more generic functions SSD1963_ReadMemory and SSD1963_WriteMemory.
33  *     - Remove the function SSD1963_WriteSamePixels.
34  *     - Change the video memory access functions to non-blocking functions.
35  *
36  *   1.0.0
37  *     - Initial version
38  */
39 
40 /*******************************************************************************
41  * Definitions
42  ******************************************************************************/
43 
44 /*! @brief Data width between host and SSD1963 controller, only supports 8 and 16. */
45 #ifndef SSD1963_DATA_WITDH
46 #define SSD1963_DATA_WITDH (16U)
47 #endif
48 
49 /*! @brief SSD1963 command. */
50 #define SSD1963_NOP                      0x00U
51 #define SSD1963_SOFT_RESET               0x01U
52 #define SSD1963_GET_POWER_MODE           0x0AU
53 #define SSD1963_GET_ADDRESS_MODE         0x0BU
54 #define SSD1963_GET_DISPLAY_MODE         0x0DU
55 #define SSD1963_GET_TEAR_EFFECT_STATUS   0x0EU
56 #define SSD1963_ENTER_SLEEP_MODE         0x10U
57 #define SSD1963_EXIT_SLEEP_MODE          0x11U
58 #define SSD1963_ENTER_PARTIAL_MODE       0x12U
59 #define SSD1963_ENTER_NORMAL_MODE        0x13U
60 #define SSD1963_EXIT_INVERT_MODE         0x20U
61 #define SSD1963_ENTER_INVERT_MODE        0x21U
62 #define SSD1963_SET_GAMMA_CURVE          0x26U
63 #define SSD1963_SET_DISPLAY_OFF          0x28U
64 #define SSD1963_SET_DISPLAY_ON           0x29U
65 #define SSD1963_SET_COLUMN_ADDRESS       0x2AU
66 #define SSD1963_SET_PAGE_ADDRESS         0x2BU
67 #define SSD1963_WRITE_MEMORY_START       0x2CU
68 #define SSD1963_READ_MEMORY_START        0x2EU
69 #define SSD1963_SET_PARTIAL_AREA         0x30U
70 #define SSD1963_SET_SCROLL_AREA          0x33U
71 #define SSD1963_SET_TEAR_OFF             0x34U
72 #define SSD1963_SET_TEAR_ON              0x35U
73 #define SSD1963_SET_ADDRESS_MODE         0x36U
74 #define SSD1963_SET_SCROLL_START         0x37U
75 #define SSD1963_EXIT_IDLE_MODE           0x38U
76 #define SSD1963_ENTER_IDLE_MODE          0x39U
77 #define SSD1963_WRITE_MEMORY_CONTINUE    0x3CU
78 #define SSD1963_READ_MEMORY_CONTINUE     0x3EU
79 #define SSD1963_SET_TEAR_SCANLINE        0x44U
80 #define SSD1963_GET_SCANLINE             0x45U
81 #define SSD1963_READ_DDB                 0xA1U
82 #define SSD1963_SET_LCD_MODE             0xB0U
83 #define SSD1963_GET_LCD_MODE             0xB1U
84 #define SSD1963_SET_HORI_PERIOD          0xB4U
85 #define SSD1963_GET_HORI_PERIOD          0xB5U
86 #define SSD1963_SET_VERT_PERIOD          0xB6U
87 #define SSD1963_GET_VERT_PERIOD          0xB7U
88 #define SSD1963_SET_GPIO_CONF            0xB8U
89 #define SSD1963_GET_GPIO_CONF            0xB9U
90 #define SSD1963_SET_GPIO_VALUE           0xBAU
91 #define SSD1963_GET_GPIO_STATUS          0xBBU
92 #define SSD1963_SET_POST_PROC            0xBCU
93 #define SSD1963_GET_POST_PROC            0xBDU
94 #define SSD1963_SET_PWM_CONF             0xBEU
95 #define SSD1963_GET_PWM_CONF             0xBFU
96 #define SSD1963_GET_LCD_GEN0             0xC0U
97 #define SSD1963_SET_LCD_GEN0             0xC1U
98 #define SSD1963_GET_LCD_GEN1             0xC2U
99 #define SSD1963_SET_LCD_GEN1             0xC3U
100 #define SSD1963_GET_LCD_GEN2             0xC4U
101 #define SSD1963_SET_LCD_GEN2             0xC5U
102 #define SSD1963_GET_LCD_GEN3             0xC6U
103 #define SSD1963_SET_LCD_GEN3             0xC7U
104 #define SSD1963_SET_GPIO0_ROP            0xC8U
105 #define SSD1963_GET_GPIO0_ROP            0xC9U
106 #define SSD1963_SET_GPIO1_ROP            0xCAU
107 #define SSD1963_GET_GPIO1_ROP            0xCBU
108 #define SSD1963_SET_GPIO2_ROP            0xCCU
109 #define SSD1963_GET_GPIO2_ROP            0xCDU
110 #define SSD1963_SET_GPIO3_ROP            0xCEU
111 #define SSD1963_GET_GPIO3_ROP            0xCFU
112 #define SSD1963_SET_DBC_CONF             0xD0U
113 #define SSD1963_GET_DBC_CONF             0xD1U
114 #define SSD1963_SET_DBC_TH               0xD4U
115 #define SSD1963_GET_DBC_TH               0xD5U
116 #define SSD1963_SET_PLL                  0xE0U
117 #define SSD1963_SET_PLL_MN               0xE2U
118 #define SSD1963_GET_PLL_MN               0xE3U
119 #define SSD1963_GET_PLL_STATUS           0xE4U
120 #define SSD1963_SET_DEEP_SLEEP           0xE5U
121 #define SSD1963_SET_LSHIFT_FREQ          0xE6U
122 #define SSD1963_GET_LSHIFT_FREQ          0xE7U
123 #define SSD1963_SET_PIXEL_DATA_INTERFACE 0xF0U
124 #define SSD1963_GET_PIXEL_DATA_INTERFACE 0xF1U
125 
126 #define SSD1963_ADDR_MODE_FLIP_VERT           (1U << 0)
127 #define SSD1963_ADDR_MODE_FLIP_HORZ           (1U << 1)
128 #define SSD1963_ADDR_MODE_LATCH_RIGHT_TO_LEFT (1U << 2)
129 #define SSD1963_ADDR_MODE_BGR                 (1U << 3)
130 #define SSD1963_ADDR_MODE_REFRESH_BOTTOM_UP   (1U << 4)
131 #define SSD1963_ADDR_MODE_PAG_COL_ADDR_ORDER  (1U << 5)
132 #define SSD1963_ADDR_MODE_COL_ADDR_ORDER      (1U << 6)
133 #define SSD1963_ADDR_MODE_PAGE_ADDR_ORDER     (1U << 7)
134 
135 /*! @brief ssd1963 handle. */
136 typedef struct _ssd1963_handle
137 {
138     uint8_t addrMode;              /*!< The parameter of set_address_mode and get_address_mode. */
139     uint16_t panelWidth;           /*!< Width of the panel. */
140     uint16_t panelHeight;          /*!< Height of the panel. */
141     const dbi_xfer_ops_t *xferOps; /*!< Bus transfer operations. */
142     void *xferOpsData;             /*!< Data used for transfer operations. */
143 } ssd1963_handle_t;
144 
145 /*! @brief SSD1963 TFT interface timing polarity flags. */
146 enum _ssd1963_polarity_flags
147 {
148     kSSD1963_HsyncActiveHigh            = (1U << 1U), /*!< Set then the HSYNC will be active high. */
149     kSSD1963_VsyncActiveHigh            = (1U << 0U), /*!< Set then the VSYNC will be active high. */
150     kSSD1963_LatchDataInClockRisingEdge = (1U << 2U), /*!< Set then the data latched in clock rising edge. */
151 };
152 
153 /*! @brief The data width between SSD1963 and TFT panel. */
154 typedef enum _ssd1963_panel_data_width
155 {
156     kSSD1963_PanelData18Bit = 0 << 5, /*!< 18-bit panel data. */
157     kSSD1963_PanelData24Bit = 1 << 5, /*!< 24-bit panel data. */
158 } ssd1963_panel_data_width_t;
159 
160 /*!
161  * @brief The pixel data interface format.
162  * Currently only supports such formats
163  *  - 16-bits interface, pixel format BGR565, every pixel is sent by one cycle.
164  *  - 8-bits interface, pixel format BGR888, every pixel is sent by 3 cycles.
165  */
166 typedef enum _ssd1963_pixel_interface
167 {
168 #if (8 == SSD1963_DATA_WITDH)
169     kSSD1963_PixelInterface8BitBGR888 = 0,               /*!< 8-bits interface, pixel format BGR888, deprecated.
170                                                               Use kSSD1963_BGR888 instead. */
171     kSSD1963_BGR888 = kSSD1963_PixelInterface8BitBGR888, /*!< 8-bits interface, pixel format BGR888. */
172     kSSD1963_RGB888 = 1,                                 /*!< 8-bits interface, pixel format BGR888. */
173 #else
174     kSSD1963_PixelInterface16Bit565 = 0,               /*!< 16-bits interface, pixel format BGR565, deprecated.
175                                                      Use kSSD1963_RGB565 instead  */
176     kSSD1963_RGB565 = kSSD1963_PixelInterface16Bit565, /*!< 16-bits interface, pixel format RGB565. */
177     kSSD1963_BGR565 = 1,                               /*!< 16-bits interface, pixel format BGR565. */
178 #endif
179 } ssd1963_pixel_interface_t;
180 
181 /*! @brief Initailize structure of ssd1963 */
182 typedef struct _ssd1963_config
183 {
184     uint32_t pclkFreq_Hz;                      /*!< Pixel clock (LSHIFT clock) frequency in Hz. */
185     ssd1963_pixel_interface_t pixelInterface;  /*!< Pixel interface format. */
186     ssd1963_panel_data_width_t panelDataWidth; /*!< Panel data width. */
187     uint8_t polarityFlags;                     /*!< OR'ed value of @ref _ssd1963_polarity_flags. */
188     uint16_t panelWidth;                       /*!< How many pixels per line. */
189     uint16_t panelHeight;                      /*!< How many lines per panel. */
190     uint16_t hsw;                              /*!< HSYNC pulse width. */
191     uint16_t hfp;                              /*!< Horizontal front porch. */
192     uint16_t hbp;                              /*!< Horizontal back porch. */
193     uint16_t vsw;                              /*!< VSYNC pulse width. */
194     uint16_t vfp;                              /*!< Vrtical front porch. */
195     uint16_t vbp;                              /*!< Vertical back porch. */
196 } ssd1963_config_t;
197 
198 /*! @brief SSD1963 flip mode. */
199 typedef enum _ssd1963_flip_mode
200 {
201     kSSD1963_FlipNone       = 0U,                          /*!< No flip. */
202     kSSD1963_FlipVertical   = SSD1963_ADDR_MODE_FLIP_VERT, /*!< Flip vertical, set_address_mode A[0] */
203     kSSD1963_FlipHorizontal = SSD1963_ADDR_MODE_FLIP_HORZ, /*!< Flip horizontal, set_address_mode A[1] */
204     kSSD1963_FlipBoth =
205         SSD1963_ADDR_MODE_FLIP_VERT | SSD1963_ADDR_MODE_FLIP_HORZ, /*!< Flip both vertical and horizontal. */
206 } ssd1963_flip_mode_t;
207 
208 /*!
209  * @brief SSD1963 orientation mode.
210  * After setting the orientation mode, the accress order from host processor to
211  * frame buffer will be changed.
212  */
213 typedef enum _ssd1963_orientation_mode_t
214 {
215     kSSD1963_Orientation0 = 0U, /*!< Rotate 0 degree. */
216     kSSD1963_Orientation90 =
217         SSD1963_ADDR_MODE_PAGE_ADDR_ORDER | SSD1963_ADDR_MODE_PAG_COL_ADDR_ORDER, /*!< Rotate 90 degree. */
218     kSSD1963_Orientation180 =
219         SSD1963_ADDR_MODE_PAGE_ADDR_ORDER | SSD1963_ADDR_MODE_COL_ADDR_ORDER, /*!< Rotate 180 degree. */
220     kSSD1963_Orientation270 =
221         SSD1963_ADDR_MODE_COL_ADDR_ORDER | SSD1963_ADDR_MODE_PAG_COL_ADDR_ORDER, /*!< Rotate 270 degree. */
222 } ssd1963_orientation_mode_t;
223 
224 /*******************************************************************************
225  * API
226  ******************************************************************************/
227 #if defined(__cplusplus)
228 extern "C" {
229 #endif
230 
231 /*!
232  * @brief Initailize the SSD1963.
233  *
234  * This function configures the SSD1963 contoller, and setups the interface
235  * between LCD panel. This function does not turn on the display, application
236  * could turn on the display after filling the frame buffer.
237  *
238  * @param handle SSD1963 handle structure.
239  * @param config Pointer to the SSD1963 configuration structure.
240  * @param xferOps DBI interface transfer operation functions.
241  * @param xferOpsData Private data used by the DBI interface.
242  * @param srcClock_Hz The external reference clock(XTAL or CLK) frequency in Hz.
243  *
244  * @retval kStatus_Success Initailize successfully.
245  * @retval kStatus_InvalidArgument Initailize failed because of invalid argument.
246  */
247 status_t SSD1963_Init(ssd1963_handle_t *handle,
248                       const ssd1963_config_t *config,
249                       const dbi_xfer_ops_t *xferOps,
250                       void *xferOpsData,
251                       uint32_t srcClock_Hz);
252 
253 /*!
254  * @brief Set the memory access done callback.
255  *
256  * @param handle SSD1963 handle structure.
257  * @param callback Callback function when the video memory operation finished.
258  *        the video memory functions include @ref SSD1963_WriteMemory,
259  *        @ref SSD1963_ReadMemory, @ref SSD1963_WritePixels, and @ref SSD1963_ReadPixels
260  *        these functions are non-blocking functions, upper layer is notified
261  *        by this callback function after transfer done.
262  * @param userData Parameter of @ref memDoneCallback.
263  */
264 void SSD1963_SetMemoryDoneCallback(ssd1963_handle_t *handle, dbi_mem_done_callback_t callback, void *userData);
265 
266 /*!
267  * @brief Deinitailize the SSD1963.
268  *
269  * @param handle SSD1963 handle structure.
270  */
271 void SSD1963_Deinit(ssd1963_handle_t *handle);
272 
273 /*!
274  * @brief Set display on.
275  *
276  * @param handle SSD1963 handle structure.
277  */
278 status_t SSD1963_StartDisplay(ssd1963_handle_t *handle);
279 
280 /*!
281  * @brief Set display off.
282  *
283  * @param handle SSD1963 handle structure.
284  */
285 status_t SSD1963_StopDisplay(ssd1963_handle_t *handle);
286 
287 /*!
288  * @brief Set display flip mode.
289  *
290  * @param handle SSD1963 handle structure.
291  * @param mode The flip mode.
292  */
293 status_t SSD1963_SetFlipMode(ssd1963_handle_t *handle, ssd1963_flip_mode_t mode);
294 
295 /*!
296  * @brief Set display orientation mode.
297  *
298  * @param handle SSD1963 handle structure.
299  * @param mode The orientation mode.
300  */
301 status_t SSD1963_SetOrientationMode(ssd1963_handle_t *handle, ssd1963_orientation_mode_t mode);
302 
303 /*!
304  * @brief Set the backlight value.
305  *
306  * @param handle SSD1963 handle structure.
307  * @param value Backlight value, must be in the range of 0 to 255.
308  */
309 status_t SSD1963_SetBackLight(ssd1963_handle_t *handle, uint8_t value);
310 
311 /*!
312  * @brief Select area to read or write.
313  *
314  * @param handle SSD1963 handle structure.
315  * @param startX Start point X coordination.
316  * @param startY Start point Y coordination.
317  * @param endX End point X coordination.
318  * @param endY End point Y coordination.
319  */
320 status_t SSD1963_SelectArea(ssd1963_handle_t *handle, uint16_t startX, uint16_t startY, uint16_t endX, uint16_t endY);
321 
322 #if (16 == SSD1963_DATA_WITDH)
323 /*!
324  * @brief Read pixel data from the selected area.
325  *
326  * This function reads pixel data to the area selected by the function
327  * @ref SSD1963_SelectArea. The pixel data will be read from the start of
328  * the area, it could not read the pixels out of the selected area.
329  *
330  * @param handle SSD1963 handle structure.
331  * @param pixels Pointer to the memory to save the read pixels.
332  * @param length Length of the pixel array @p pixels.
333  * @note This function should only be used when @ref kSSD1963_PixelInterface16Bit565
334  * used.
335  * @deprecated Use @ref SSD1963_ReadMemory instead, note the @p length of this function
336  * is pixel count, and the @p length of @ref SSD1963_ReadMemory is byte count.
337  */
338 status_t SSD1963_ReadPixels(ssd1963_handle_t *handle, uint16_t *pixels, uint32_t length);
339 
340 /*!
341  * @brief Write pixel data to the selected area.
342  *
343  * This function writes pixel data to the area selected by the function
344  * @ref SSD1963_SelectArea. The pixel data will be written from the start of
345  * the area, if the pixel data written is larger than the area size, the part
346  * out of range will be ignored.
347  *
348  * @param handle SSD1963 handle structure.
349  * @param pixels Pointer to the pixels to write.
350  * @param length Length of the pixel array @p pixels.
351  * @note This function should only be used when @ref kSSD1963_PixelInterface16Bit565
352  * used.
353  * @deprecated Use @ref SSD1963_WriteMemory instead, note the @p length of this function
354  * is pixel count, and the @p length of @ref SSD1963_WriteMemory is byte count.
355  */
356 status_t SSD1963_WritePixels(ssd1963_handle_t *handle, const uint16_t *pixels, uint32_t length);
357 #endif
358 
359 /*!
360  * @brief Read pixel data from the selected area in controller memory.
361  *
362  * This function reads pixel data to the area selected by the function
363  * @ref SSD1963_SelectArea. The pixel data will be read from the start of
364  * the area, it could not read the pixels out of the selected area.
365  *
366  * @param handle SSD1963 handle structure.
367  * @param data Pointer to the memory to save the read pixels.
368  * @param length Length of the data to read (in byte).
369  */
370 status_t SSD1963_ReadMemory(ssd1963_handle_t *handle, uint8_t *data, uint32_t length);
371 
372 /*!
373  * @brief Write pixel data to the selected area.
374  *
375  * This function writes pixel data to the area selected by the function
376  * @ref SSD1963_SelectArea. The pixel data will be written from the start of
377  * the area, if the pixel data written is larger than the area size, the part
378  * out of range will be ignored.
379  *
380  * @param handle SSD1963 handle structure.
381  * @param data Pointer to the pixels to write.
382  * @param length Length of the data to write (in byte).
383  */
384 status_t SSD1963_WriteMemory(ssd1963_handle_t *handle, const uint8_t *data, uint32_t length);
385 
386 /*!
387  * @brief Enable or disable tear effect signal.
388  *
389  * @param handle SSD1963 handle structure.
390  * @param enable Pass in true to enable, false to disable.
391  */
392 status_t SSD1963_EnableTearEffect(ssd1963_handle_t *handle, bool enable);
393 
394 /*!
395  * @brief Set the pixel format.
396  *
397  * @param handle SSD1963 handle structure.
398  * @param pixelFormat Pixel format to set.
399  */
400 status_t SSD1963_SetPixelFormat(ssd1963_handle_t *handle, ssd1963_pixel_interface_t pixelFormat);
401 
402 #if defined(__cplusplus)
403 }
404 #endif
405 
406 /*! @} */
407 
408 #endif /* _FSL_SSD1963_H_ */
409