This section introduces the display DSI APIs including terms and acronyms, supported features, software architecture, how to use the APIs, DSI function groups, all enumerations, structures and functions. More...

Overview

This section introduces the display DSI APIs including terms and acronyms, supported features, software architecture, how to use the APIs, DSI function groups, all enumerations, structures and functions.

DSI is an optional output interface for the LCD engine. Add the compile option #define HAL_DISPLAY_LCD_MODULE_ENABLED in hal_feature_config.h to enable the LCD engine.

Terms and acronyms

Terms	Details
DSI	The Display Serial Interface is a specification by the Mobile Industry Processor Interface (MIPI). For more information, please refer to Display Serial Interface in Wikipedia.
BTA	The first data lane (lane 0) that travels from the DSI host to the DSI device is capable of a bus turnaround (BTA) operation that allows it to reverse transmission direction.
LP	Low power mode. In low power mode, the high speed clock is disabled and signal clocking information is embedded in the data. It is applied to send configuration information and commands.
HS	High-speed mode. This mode enables the high-speed clock that acts as the bit clock for the data lanes. HS mode is still designed to reduce power usage due to its low voltage signaling and parallel transfer ability.
TE	Synchronize signals sent from LCM to LCD engine to prevent tearing effect.
ULPS	Ultra Low Power State. The voltage of data lane and clock lane is 0 for power saving operations.
Spread spectrum	Spread spectrum is the method by which a signal generated with a particular bandwidth is deliberately spread in the frequency domain, resulting in a signal with a wider bandwidth. For more information, please refer to Spread spectrum in Wikipedia.
D-PHY	A flexible, low-cost, high speed serial interface solution for communication interconnection between components inside a mobile device that adheres to MIPI Alliance interface specifications.
PLL	A phase-locked loop or phase lock loop is a control system that generates an output signal to match to the input signal's phase. For more information, please refer to Phase-locked loop in Wikipedia.
ROI	Region of Interest, the region will be transferred, including width and height.
MTCMOS	Multi-threshold CMOS is a variation of CMOS chip technology that has transistors with multiple threshold voltages (Vth) in order to optimize delay or power. For more information, please refer toMulti-threshold CMOS in Wikipedia.

Supported features

Command mode transfer.
Send frame buffer to the LCM manually in command mode. Command mode saves transfer power and memory bandwidth.
External TE and Internal TE.
- External TE: Connect to the TE pin from LCM as input signal for MT2523.
- Internal TE: No need to connect to the TE pin from LCM as input signal for MT2523. MT2523 can get TE signals using BTA command.

How to use this driver

Call hal_display_lcd_init() and hal_display_dsi_init() to initialize the LCD and DSI hardware.
Call hal_display_lcd_config_roi() to set the ROI information.
Call hal_display_lcd_config_layer() to set the layer data.
Call blockwrite function from the LCM driver function table to start the transfer.

sample code:
hal_display_lcd_roi_output_t roi_para;
hal_display_lcd_layer_input_t layer_para;
ret = hal_display_lcd_init();
if (HAL_DISPLAY_LCD_STATUS_OK != ret) {
// Error handling
}
ret = hal_display_dsi_init();
if (HAL_DISPLAY_DSI_STATUS_OK != ret) {
// Error handling
}
// Configure the ROI.
ret = hal_display_lcd_config_roi(&roi_para);
if (HAL_DISPLAY_LCD_STATUS_OK != ret) {
// Error handling
}
// Configure the layer.
ret = hal_display_lcd_config_layer(&layer_data);
if (HAL_DISPLAY_LCD_STATUS_OK != ret) {
// Error handling
}
// Update the screen.
MainLCD->BlockWrite(startx, starty, endx, endy);
LCM driver:
LCD_Blockwrite()
{
// Set the ROI data to the LCM.
// Add this to start DMA mode.
hal_display_lcd_toggle_DMA();
data_array[0] = 0x002C3909;
hal_display_dsi_set_command_queue(data_array, 1, 1);
}

Functions
hal_display_dsi_status_t	hal_display_dsi_init (bool ssc_enable)
	This function initializes the DSI engine's hardware registers. More...

hal_display_dsi_status_t	hal_display_dsi_deinit (void)
	This function de-initializes the DSI engine's hardware registers. More...

hal_display_dsi_status_t	hal_display_dsi_power_on (void)
	This function enables the DSI engine power. More...

hal_display_dsi_status_t	hal_display_dsi_power_off (void)
	This function disables DSI engine power. More...

hal_display_dsi_status_t	hal_display_dsi_enable_te (void)
	This function enables the TE detection of DSI engine. More...

hal_display_dsi_status_t	hal_display_dsi_set_command_queue (uint32_t *pData, uint8_t size, bool forced_update)
	This function sets commands/data into command queue to send to the LCM driver IC. More...

hal_display_dsi_status_t	hal_display_dsi_set_command_queue_ex (uint32_t command, uint32_t size, uint32_t *data, bool forced_update)
	This function sets commands/data into command queue to send to the LCM driver IC. More...

hal_display_dsi_status_t	hal_display_dsi_read_register (uint8_t command, uint8_t *buffer, uint8_t size)
	This function reads data from the LCM driver IC. More...

hal_display_dsi_status_t	hal_display_dsi_enter_ulps (void)
	This function configures the DSI engine to enter the ULPS state. More...

hal_display_dsi_status_t	hal_display_dsi_exit_ulps (void)
	This function configures the DSI engine to exit the ULPS state. More...

hal_display_dsi_status_t	hal_display_dsi_set_dphy_timing (hal_display_dsi_dphy_timing_struct_t *timing)
	This function configures the DSI D-PHY timing. More...

hal_display_dsi_status_t	hal_display_dsi_set_clock (uint32_t pll_clock, bool ssc_enable)
	This function configures the DSI D-PHY timing automatically using the PLL clock speed. More...

hal_display_dsi_status_t	hal_display_dsi_set_transfer_mode (hal_display_dsi_transfer_mode_t mode)
	This function configures the transfer mode. More...

void	hal_dsiplay_dsi_start_bta_transfer (uint32_t command)

void	hal_display_dsi_start_bta_transfer (uint32_t command)
	This function starts the BTA type transfer. More...

void	hal_display_dsi_restore_callback (void)
	This function executes the restore function when exiting from deep sleep. More...

hal_display_dsi_status_t	hal_display_dsi_apply_setting (void)
	This function applies all settings to the DSI engine. More...

Modules
	Enum

	Struct

Function Documentation

hal_display_dsi_status_t hal_display_dsi_apply_setting ( void )

This function applies all settings to the DSI engine.

To save power, keep the MTCMOS mostly turned off. During the screen update, turn the MTCMOS on and then apply the settings to the DSI engine to ensure complete configuration.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

hal_display_dsi_status_t hal_display_dsi_deinit ( void )

This function de-initializes the DSI engine's hardware registers.

It disables the DSI engine.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation to de-initialize the DSI engine has failed.

hal_display_dsi_status_t hal_display_dsi_enable_te ( void )

This function enables the TE detection of DSI engine.

If the TE pin is connected to MT2523, the TE detection should be enabled to avoid a tearing-effect.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

hal_display_dsi_status_t hal_display_dsi_enter_ulps ( void )

This function configures the DSI engine to enter the ULPS state.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

hal_display_dsi_status_t hal_display_dsi_exit_ulps ( void )

This function configures the DSI engine to exit the ULPS state.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

hal_display_dsi_status_t hal_display_dsi_init ( bool ssc_enable )

This function initializes the DSI engine's hardware registers.

It sets the default transfer bit rate to 300Mbps.

Parameters

[in] ssc_enable specifies whether the spread spectrum is enabled.

Returns: To indicate whether this function call is successful or not. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_INITIALIZATION_FAILED, the DSI engine register initialization has failed. Call hal_display_dsi_power_on() before setting the DSI engine registers.

hal_display_dsi_status_t hal_display_dsi_power_off ( void )

This function disables DSI engine power.

After accessing registers of the DSI engine or transferring data in DMA mode, please turn the power off to avoid power leakage.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_POWER_FAILED, the operation to disable the power has failed.

hal_display_dsi_status_t hal_display_dsi_power_on ( void )

This function enables the DSI engine power.

Before accessing the registers of the DSI engine or transferring data in DMA mode, please turn the power on.

Returns: To indicate whether this function call is successful or not. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_POWER_FAILED, the operation to enable the power has failed.

hal_display_dsi_status_t hal_display_dsi_read_register	(	uint8_t	command,
		uint8_t *	buffer,
		uint8_t	size
	)

This function reads data from the LCM driver IC.

Parameters

[in]	command	is the read command to send.
[in]	buffer	is an array to store the data sent from the LCM driver IC.
[in]	size	is the number of bytes to read.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_READ_FAILED, the operation has failed, please check the input data.

void hal_display_dsi_restore_callback ( void )

This function executes the restore function when exiting from deep sleep.

Returns: None.

hal_display_dsi_status_t hal_display_dsi_set_clock	(	uint32_t	pll_clock,
		bool	ssc_enable
	)

This function configures the DSI D-PHY timing automatically using the PLL clock speed.

Parameters

[in]	pll_clock	is the PLL clock speed in MHz.
[in]	ssc_enable	specifies if the spread spectrum clock is enabled or not.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

hal_display_dsi_status_t hal_display_dsi_set_command_queue	(	uint32_t *	pData,
		uint8_t	size,
		bool	forced_update
	)

This function sets commands/data into command queue to send to the LCM driver IC.

Parameters

[in]	pData	is an array with commands and data.
[in]	size	is the size of the input array.
[in]	forced_update	specifies whether to send data to LCM driver IC immediately.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_COMMAND_QUEUE_FAILED, the operation has failed, please check the input data.

hal_display_dsi_status_t hal_display_dsi_set_command_queue_ex	(	uint32_t	command,
		uint32_t	size,
		uint32_t *	data,
		bool	forced_update
	)

This function sets commands/data into command queue to send to the LCM driver IC.

Parameters

[in]	command	is the command to send.
[in]	size	is the size of the data array.
[in]	data	is an array with data that should be sent based on the send command.
[in]	forced_update	specifies whether to send data to LCM driver IC immediately.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_COMMAND_QUEUE_FAILED, the operation has failed, please check the input data.

hal_display_dsi_status_t hal_display_dsi_set_dphy_timing ( hal_display_dsi_dphy_timing_struct_t * timing )

This function configures the DSI D-PHY timing.

Parameters

[in] timing specifies the DSI timing parameters, please refer to hal_display_dsi_dphy_timing_struct_t.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

hal_display_dsi_status_t hal_display_dsi_set_transfer_mode ( hal_display_dsi_transfer_mode_t mode )

This function configures the transfer mode.

Parameters

[in] mode is the transfer mode, please refer to hal_display_dsi_transfer_mode_t.

Returns: Indicates whether this function call is successful. HAL_DISPLAY_DSI_STATUS_OK, the operation completed successfully. HAL_DISPLAY_DSI_STATUS_ERROR, the operation has failed.

void hal_display_dsi_start_bta_transfer ( uint32_t command )

This function starts the BTA type transfer.

Add this function at the end of LCM blockwrite function to start transferring data and to use the internal TE.

Parameters

[in] command specifies the memory write command.

Returns: None.

void hal_dsiplay_dsi_start_bta_transfer ( uint32_t command )

Deprecated:: Please use hal_display_dsi_start_bta_transfer() instead.

This function starts the BTA type transfer. Add this function at the end of LCM blockwrite function to start transferring data and to use the internal TE.

Parameters

[in] command specifies the memory write command.

Returns: None.

Overview

Terms and acronyms

Supported features

How to use this driver

Functions

Modules

Function Documentation