This section provides Fixed APIs(defined as Common Interface) to fully control the MediaTek UART HW. More...

Overview

This section provides Fixed APIs(defined as Common Interface) to fully control the MediaTek UART HW.

Functions
int	mtk_mhal_uart_enable_clk (struct mtk_uart_controller *ctlr)
	This function is used to enable UART clock. More...

int	mtk_mhal_uart_disable_clk (struct mtk_uart_controller *ctlr)
	This function is used to disable UART clock. More...

int	mtk_mhal_uart_sw_reset (struct mtk_uart_controller *ctlr)
	This function is used to reset UART. More...

int	mtk_mhal_uart_dumpreg (struct mtk_uart_controller *ctlr)
	This function is used to dump UART register. More...

int	mtk_mhal_uart_hw_init (struct mtk_uart_controller *ctlr)
	This function is used to initialize UART port. More...

int	mtk_mhal_uart_set_baudrate (struct mtk_uart_controller *ctlr)
	This function is used to change UART baudrate. More...

int	mtk_mhal_uart_set_format (struct mtk_uart_controller *ctlr)
	This function is used to set UART data format. More...

int	mtk_mhal_uart_set_hw_fc (struct mtk_uart_controller *ctlr, u8 hw_fc)
	This function is used to enable UART hardware flow control. More...

int	mtk_mhal_uart_disable_sw_fc (struct mtk_uart_controller *ctlr)
	This function is used to disable UART software flow control. More...

int	mtk_mhal_uart_set_sw_fc (struct mtk_uart_controller *ctlr, u8 xon1, u8 xoff1, u8 xon2, u8 xoff2, u8 escape_data)
	This function is used to configure UART software flow control. More...

int	mtk_mhal_uart_set_dma (struct mtk_uart_controller *ctlr, bool enable_dma)
	This function is used to set the DMA setting relative to the UART. More...

int	mtk_mhal_uart_clear_irq_status (struct mtk_uart_controller *ctlr)
	This function is used to get and clear UART IRQ. More...

int	mtk_mhal_uart_set_irq (struct mtk_uart_controller *ctlr, u8 int_flag)
	This function is used to set UART IRQ function. More...

int	mtk_mhal_uart_putc (struct mtk_uart_controller *ctlr, u8 data)
	This function is used to send one byte of data in PIO mode. More...

int	mtk_mhal_uart_getc (struct mtk_uart_controller *ctlr)
	This function is used to get data in PIO mode. More...

int	mtk_mhal_uart_getc_nowait (struct mtk_uart_controller *ctlr)
	This function is used to get data directly in PIO mode. More...

int	mtk_mhal_uart_allocate_dma_tx_ch (struct mtk_uart_controller *ctlr)
	This function is used to allocate UART DMA TX channel. More...

int	mtk_mhal_uart_allocate_dma_rx_ch (struct mtk_uart_controller *ctlr)
	This function is used to allocate UART DMA RX channel. More...

int	mtk_mhal_uart_release_dma_tx_ch (struct mtk_uart_controller *ctlr)
	This function is used to release UART DMA TX channel. More...

int	mtk_mhal_uart_release_dma_rx_ch (struct mtk_uart_controller *ctlr)
	This function is used to release UART DMA RX channel. More...

int	mtk_mhal_uart_dma_tx_config (struct mtk_uart_controller *ctlr)
	This function is used to config UART DMA TX channel. More...

int	mtk_mhal_uart_dma_rx_config (struct mtk_uart_controller *ctlr)
	This function is used to config UART DMA RX channel. More...

int	mtk_mhal_uart_start_dma_tx (struct mtk_uart_controller *ctlr)
	This function is used to start UART DMA TX transaction. More...

int	mtk_mhal_uart_start_dma_rx (struct mtk_uart_controller *ctlr)
	This function is used to start UART DMA RX transaction. More...

int	mtk_mhal_uart_stop_dma_tx (struct mtk_uart_controller *ctlr)
	This function is used to stop UART DMA TX transaction. More...

int	mtk_mhal_uart_stop_dma_rx (struct mtk_uart_controller *ctlr)
	This function is used to stop UART DMA RX transaction. More...

int	mtk_mhal_uart_update_dma_tx_info (struct mtk_uart_controller *ctlr)
	This function is used to update DMA TX information when TX fail. More...

int	mtk_mhal_uart_update_dma_rx_info (struct mtk_uart_controller *ctlr)
	This function is used to update DMA RX information when RX fail. More...

int	mtk_mhal_uart_dma_tx_callback_register (struct mtk_uart_controller ctlr, uart_dma_done_callback callback, void user_data)
	This defines the callback function prototype. More...

int	mtk_mhal_uart_dma_rx_callback_register (struct mtk_uart_controller ctlr, uart_dma_done_callback callback, void user_data)
	This defines the callback function prototype. More...

Function Documentation

int mtk_mhal_uart_enable_clk ( struct mtk_uart_controller * ctlr )

This function is used to enable UART clock.

Usage : This function is used to enable UART clock. OS-HAL must enable clock before accessing UART regsiter; otherwise, accessing UART register will fail.

Parameters

[in] ctlr : UART controller used with the device.

Returns: Return "0" if enable UART clock success.
Return -UART_EPTR if ctlr is NULL.

int mtk_mhal_uart_disable_clk ( struct mtk_uart_controller * ctlr )

This function is used to disable UART clock.

Usage : It needs to be called to disable clock.

Parameters

[in] ctlr : UART controller used with the device.

Returns: Return "0" if disable UART clock success.
Return -UART_EPTR if ctlr is NULL.

int mtk_mhal_uart_sw_reset ( struct mtk_uart_controller * ctlr )

This function is used to reset UART.

Usage : It needs to be called to reset UART.

Parameters

[in] ctlr : UART controller used with the device.

Returns: Return "0" if reset UART success.
Return -UART_EPTR if ctlr is NULL.

int mtk_mhal_uart_dumpreg ( struct mtk_uart_controller * ctlr )

This function is used to dump UART register.

Usage : It needs to be called to dump UART register value.

Parameters

[in] ctlr : UART controller used with the device.

Returns: Return "0" if dump UART register success.
Return -UART_EPTR if ctlr is NULL.

int mtk_mhal_uart_hw_init ( struct mtk_uart_controller * ctlr )

This function is used to initialize UART port.

Usage: OS-HAL driver should call it when opening UART. OS-HAL must ensure UART clock is enabled before calling this function.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate whether UART initialize success or not.
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_set_baudrate ( struct mtk_uart_controller * ctlr )

This function is used to change UART baudrate.

Usage: OS-HAL driver should call it when only change UART baudrate.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate whether UART config success or not.
If the return value is -UART_EINVAL, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_set_format ( struct mtk_uart_controller * ctlr )

This function is used to set UART data format.

Usage: OS-HAL driver should call it when only configuring UART data format.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate whether UART config success or not.
If the return value is -UART_EINVAL, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_set_hw_fc	(	struct mtk_uart_controller *	ctlr,
		u8	hw_fc
	)

This function is used to enable UART hardware flow control.

Usage: OS-HAL driver should call it when setting hardware flow control.

Parameters

[in]	ctlr	: UART controller used with the device.
[in]	hw_fc	: Hardware flow control feature; please refer to UART_EFR_HW_FC_XXX type definition.

Returns: To indicate whether setting hardware flow is successfull or not.
If the return value is -UART_EINVAL, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_disable_sw_fc ( struct mtk_uart_controller * ctlr )

This function is used to disable UART software flow control.

Usage: OS-HAL driver should call it when disabling software flow control.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate whether disable software flow is successfull or not.
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_set_sw_fc	(	struct mtk_uart_controller *	ctlr,
		u8	xon1,
		u8	xoff1,
		u8	xon2,
		u8	xoff2,
		u8	escape_data
	)

This function is used to configure UART software flow control.

Usage: OS-HAL driver should call it when configuring software flow control.

Parameters

[in]	ctlr	: UART controller used with the device.
[in]	xon1	: XON1 character for software flow control.
[in]	xoff1	: XOFF1 character for software flow control.
[in]	xon2	: XON2 character for software flow control.
[in]	xoff2	: XOFF2 character for software flow control.
[in]	escape_data	: Escape character for software flow control.

Returns: To indicate whether set software flow is successfull or not.
If the return value is -UART_EINVAL, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_set_dma	(	struct mtk_uart_controller *	ctlr,
		bool	enable_dma
	)

This function is used to set the DMA setting relative to the UART.

Usage: OS-HAL driver should call it when enabling the UART DMA mode.

Parameters

[in]	ctlr	: UART controller used with the device.
[in]	enable_dma	: enable or disable UART DMA mode.

Returns: To indicate whether set dma and handshake successfull or not.
If the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_clear_irq_status ( struct mtk_uart_controller * ctlr )

This function is used to get and clear UART IRQ.

Usage: OS-HAL driver should call it when get and clear UART IRQ.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate whether set IRQ successfull or not.
if the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success and return IRQ status.

int mtk_mhal_uart_set_irq	(	struct mtk_uart_controller *	ctlr,
		u8	int_flag
	)

This function is used to set UART IRQ function.

Usage: OS-HAL driver should call it when configuring UART IRQ.

Parameters

[in]	ctlr	: UART controller used with the device.
[in]	int_flag	: Set IRQ type or disable IRQ; please refer to UART_INT_XXX type definition.

Returns: To indicate whether set IRQ successfull or not.
if the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_putc	(	struct mtk_uart_controller *	ctlr,
		u8	data
	)

This function is used to send one byte of data in PIO mode.

Usage: OS-HAL driver should call it when transmitting one byte.

Parameters

[in]	ctlr	: UART controller used with the device.
[in]	data	: Output data.

Returns: To indicate send data successfull or not.
If the return value is -EINVAL, it means argument is invalid;
if the return value is -UART_EPTR, it means ctlr is NULL;
if the return value is 0, it means success.

int mtk_mhal_uart_getc ( struct mtk_uart_controller * ctlr )

This function is used to get data in PIO mode.

Usage: OS-HAL driver should call it when receiving one byte of data.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate get data successfull or not.
If the return value is -EINVAL, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success and return received data.

int mtk_mhal_uart_getc_nowait ( struct mtk_uart_controller * ctlr )

This function is used to get data directly in PIO mode.

Usage: OS-HAL driver should call it when receiving one byte of data.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate get data successfull or not.
If the return value is -EINVAL, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success and return received data.

int mtk_mhal_uart_allocate_dma_tx_ch ( struct mtk_uart_controller * ctlr )

This function is used to allocate UART DMA TX channel.

Usage: OS-HAL driver should call it to allocate DMA TX channel.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate allocate DMA channel successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_allocate_dma_rx_ch ( struct mtk_uart_controller * ctlr )

This function is used to allocate UART DMA RX channel.

Usage: OS-HAL driver should call it to allocate DMA RX channel.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate allocate DMA channel successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_release_dma_tx_ch ( struct mtk_uart_controller * ctlr )

This function is used to release UART DMA TX channel.

Usage: OS-HAL driver should call it to release DMA TX channel.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate release DMA channel successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_release_dma_rx_ch ( struct mtk_uart_controller * ctlr )

This function is used to release UART DMA RX channel.

Usage: OS-HAL driver should call it to release DMA RX channel.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate release DMA channel successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_dma_tx_config ( struct mtk_uart_controller * ctlr )

This function is used to config UART DMA TX channel.

Usage: OS-HAL driver should call it to config DMA TX channel.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate config DMA channel successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_dma_rx_config ( struct mtk_uart_controller * ctlr )

This function is used to config UART DMA RX channel.

Usage: OS-HAL driver should call it to config DMA RX channel.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate config DMA channel successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_start_dma_tx ( struct mtk_uart_controller * ctlr )

This function is used to start UART DMA TX transaction.

Usage: OS-HAL driver should call it to start DMA TX transaction.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate start DMA channel transaction successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_start_dma_rx ( struct mtk_uart_controller * ctlr )

This function is used to start UART DMA RX transaction.

Usage: OS-HAL driver should call it to start DMA RX transaction.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate start DMA channel transaction successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_stop_dma_tx ( struct mtk_uart_controller * ctlr )

This function is used to stop UART DMA TX transaction.

Usage: OS-HAL driver should call it to stop DMA TX transaction.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate stop DMA channel transaction successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_stop_dma_rx ( struct mtk_uart_controller * ctlr )

This function is used to stop UART DMA RX transaction.

Usage: OS-HAL driver should call it to stop DMA TX transaction.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate stop DMA channel transaction successfull or not.
If the return value is -UART_ENXIO, it means argument is invalid;
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_update_dma_tx_info ( struct mtk_uart_controller * ctlr )

This function is used to update DMA TX information when TX fail.

Usage: OS-HAL driver should call it when DMA TX transaction fail.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate update DMA channel information successfull or not.
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_update_dma_rx_info ( struct mtk_uart_controller * ctlr )

This function is used to update DMA RX information when RX fail.

Usage: OS-HAL driver should call it when DMA RX transaction fail.

Parameters

[in] ctlr : UART controller used with the device.

Returns: To indicate update DMA channel information successfull or not.
If the return value is -UART_EPTR, it means ctlr is NULL;
otherwise, it means success.

int mtk_mhal_uart_dma_tx_callback_register	(	struct mtk_uart_controller *	ctlr,
		uart_dma_done_callback	callback,
		void *	user_data
	)

This defines the callback function prototype.

It's used for DMA mode TX transaction.
Users should register a TX callback function when using UART DMA mode.
In DMA mode, once UART TX and DMA hardware completes transsaction, a DMA interrupt is triggered and a related user callback is called in the DMA interrupt service routine.
This typedef is used to describe the callback function that the user wants to call.

Parameters

[in]	ctlr	mtk_uart_controller pointer, it contains register base address, data transmission information and UART hardware information.
[in]	callback	The callback function given by OS-HAL which will be called in UART module DMA interrupt service routine.
[in]	user_data	A parameter given by OS-HAL and will be passed to users when the callback function is called.

Returns: Return "0" if callback registers success;
Return -UART_EPTR if ctlr or user_data is NULL;

int mtk_mhal_uart_dma_rx_callback_register	(	struct mtk_uart_controller *	ctlr,
		uart_dma_done_callback	callback,
		void *	user_data
	)

This defines the callback function prototype.

It's used for DMA mode RX transaction.
Users should register a RX callback function when using UART DMA mode.
In DMA mode, once UART RX and DMA hardware completes transsaction, a DMA interrupt is triggered and a related user callback is called in the DMA interrupt service routine.
This typedef is used to describe the callback function that the user wants to call.

Parameters

[in]	ctlr	mtk_uart_controller pointer, it contains register base address, data transmission information and UART hardware information.
[in]	callback	The callback function given by OS-HAL which will be called in UART module DMA interrupt service routine.
[in]	user_data	A parameter given by OS-HAL and will be passed to users when the callback function is called.

Returns: Return "0" if callback registers success;
Return -UART_EPTR if ctlr or user_data is NULL;

Overview

Functions

Function Documentation