Overview

Data Structures
struct	_hal_uart_config
	UART configuration structure. More...

struct	_hal_uart_transfer
	UART transfer structure. More...

Macros
#define	UART_ADAPTER_NON_BLOCKING_MODE (1U)
	Enable or disable UART adapter non-blocking mode (1 - enable, 0 - disable)

#define	HAL_UART_ADAPTER_FIFO (1U)
	Enable or disable uart hardware FIFO mode (1 - enable, 0 - disable)

#define	HAL_UART_DMA_INIT_ENABLE (1U)
	Enable or disable uart DMA adapter int mode (1 - enable, 0 - disable)

#define	HAL_UART_DMA_IDLELINE_TIMEOUT (1U)
	Definition of uart dma adapter software idleline detection timeout value in ms. More...

#define	HAL_UART_HANDLE_SIZE (92U + HAL_UART_ADAPTER_LOWPOWER * 16U + HAL_UART_DMA_ENABLE * 4U)
	Definition of uart adapter handle size. More...

#define	UART_HANDLE_DEFINE(name) uint32_t name[((HAL_UART_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
	Definition of uart dma adapter handle size. More...

#define	HAL_UART_TRANSFER_MODE (0U)
	Whether enable transactional function of the UART. More...

Typedefs
typedef void *	hal_uart_handle_t
	The handle of uart adapter. More...

typedef void *	hal_uart_dma_handle_t
	The handle of uart dma adapter. More...

typedef enum _hal_uart_status	hal_uart_status_t
	UART status.

typedef enum _hal_uart_parity_mode	hal_uart_parity_mode_t
	UART parity mode. More...

typedef enum _hal_uart_stop_bit_count	hal_uart_stop_bit_count_t
	UART stop bit count. More...

typedef struct _hal_uart_config	hal_uart_config_t
	UART configuration structure. More...

typedef void(*	hal_uart_transfer_callback_t )(hal_uart_handle_t handle, hal_uart_status_t status, void *callbackParam)
	UART transfer callback function. More...

typedef struct _hal_uart_transfer	hal_uart_transfer_t
	UART transfer structure. More...

Enumerations
enum	_hal_uart_status { kStatus_HAL_UartSuccess = kStatus_Success, kStatus_HAL_UartTxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 1), kStatus_HAL_UartRxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 2), kStatus_HAL_UartTxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 3), kStatus_HAL_UartRxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 4), kStatus_HAL_UartBaudrateNotSupport, kStatus_HAL_UartProtocolError, kStatus_HAL_UartError = MAKE_STATUS(kStatusGroup_HAL_UART, 7) }
	UART status. More...

enum	_hal_uart_parity_mode { kHAL_UartParityDisabled = 0x0U, kHAL_UartParityEven = 0x2U, kHAL_UartParityOdd = 0x3U }
	UART parity mode. More...

enum	_hal_uart_stop_bit_count { kHAL_UartOneStopBit = 0U, kHAL_UartTwoStopBit = 1U }
	UART stop bit count. More...

Functions
hal_uart_status_t	HAL_UartEnterLowpower (hal_uart_handle_t handle)
	Prepares to enter low power consumption. More...

hal_uart_status_t	HAL_UartExitLowpower (hal_uart_handle_t handle)
	Restores from low power consumption. More...

void	HAL_UartIsrFunction (hal_uart_handle_t handle)
	UART IRQ handle function. More...

Initialization and deinitialization
hal_uart_status_t	HAL_UartInit (hal_uart_handle_t handle, const hal_uart_config_t *uart_config)
	Initializes a UART instance with the UART handle and the user configuration structure. More...

hal_uart_status_t	HAL_UartDeinit (hal_uart_handle_t handle)
	Deinitializes a UART instance. More...

Blocking bus Operations
hal_uart_status_t	HAL_UartReceiveBlocking (hal_uart_handle_t handle, uint8_t *data, size_t length)
	Reads RX data register using a blocking method. More...

hal_uart_status_t	HAL_UartSendBlocking (hal_uart_handle_t handle, const uint8_t *data, size_t length)
	Writes to the TX register using a blocking method. More...

Functional API with non-blocking mode.
Note The functional API and the transactional API cannot be used at the same time. The macro HAL_UART_TRANSFER_MODE is used to set which one will be used. If HAL_UART_TRANSFER_MODE is zero, the functional API with non-blocking mode will be used. Otherwise, transactional API will be used.
hal_uart_status_t	HAL_UartInstallCallback (hal_uart_handle_t handle, hal_uart_transfer_callback_t callback, void *callbackParam)
	Installs a callback and callback parameter. More...

hal_uart_status_t	HAL_UartReceiveNonBlocking (hal_uart_handle_t handle, uint8_t *data, size_t length)
	Receives a buffer of data using an interrupt method. More...

hal_uart_status_t	HAL_UartSendNonBlocking (hal_uart_handle_t handle, uint8_t *data, size_t length)
	Transmits a buffer of data using the interrupt method. More...

hal_uart_status_t	HAL_UartGetReceiveCount (hal_uart_handle_t handle, uint32_t *reCount)
	Gets the number of bytes that have been received. More...

hal_uart_status_t	HAL_UartGetSendCount (hal_uart_handle_t handle, uint32_t *seCount)
	Gets the number of bytes written to the UART TX register. More...

hal_uart_status_t	HAL_UartAbortReceive (hal_uart_handle_t handle)
	Aborts the interrupt-driven data receiving. More...

hal_uart_status_t	HAL_UartAbortSend (hal_uart_handle_t handle)
	Aborts the interrupt-driven data sending. More...

Data Structure Documentation

struct _hal_uart_config

Data Fields
uint32_t	srcClock_Hz
	Source clock.

uint32_t	baudRate_Bps
	Baud rate.

hal_uart_parity_mode_t	parityMode
	Parity mode, disabled (default), even, odd.

hal_uart_stop_bit_count_t	stopBitCount
	Number of stop bits, 1 stop bit (default) or 2 stop bits.

uint8_t	enableRx
	Enable RX.

uint8_t	enableTx
	Enable TX.

uint8_t	enableRxRTS
	Enable RX RTS.

uint8_t	enableTxCTS
	Enable TX CTS.

uint8_t	instance
	Instance (0 - UART0, 1 - UART1, ...), detail information please refer to the SOC corresponding RM. More...

Field Documentation

uint8_t _hal_uart_config::instance

Invalid instance value will cause initialization failure.

struct _hal_uart_transfer

Data Fields
uint8_t *	data
	The buffer of data to be transfer. More...

size_t	dataSize
	The byte count to be transfer. More...

Field Documentation

uint8_t* _hal_uart_transfer::data

size_t _hal_uart_transfer::dataSize

Macro Definition Documentation

#define HAL_UART_DMA_IDLELINE_TIMEOUT (1U)

#define HAL_UART_HANDLE_SIZE (92U + HAL_UART_ADAPTER_LOWPOWER * 16U + HAL_UART_DMA_ENABLE * 4U)

#define UART_HANDLE_DEFINE ( name ) uint32_t name[((HAL_UART_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

Defines the uart handle

This macro is used to define a 4 byte aligned uart handle. Then use "(hal_uart_handle_t)name" to get the uart handle.

The macro should be global and could be optional. You could also define uart handle by yourself.

This is an example,

* UART_HANDLE_DEFINE(uartHandle);

*

Parameters

name	The name string of the uart handle.

#define HAL_UART_TRANSFER_MODE (0U)

(0 - disable, 1 - enable)

Typedef Documentation

typedef void* hal_uart_handle_t

typedef void* hal_uart_dma_handle_t

typedef enum _hal_uart_parity_mode hal_uart_parity_mode_t

typedef enum _hal_uart_stop_bit_count hal_uart_stop_bit_count_t

typedef struct _hal_uart_config hal_uart_config_t

typedef void(* hal_uart_transfer_callback_t)(hal_uart_handle_t handle, hal_uart_status_t status, void *callbackParam)

typedef struct _hal_uart_transfer hal_uart_transfer_t

Enumeration Type Documentation

enum _hal_uart_status

Enumerator
kStatus_HAL_UartSuccess	Successfully.
kStatus_HAL_UartTxBusy	TX busy.
kStatus_HAL_UartRxBusy	RX busy.
kStatus_HAL_UartTxIdle	HAL UART transmitter is idle.
kStatus_HAL_UartRxIdle	HAL UART receiver is idle.
kStatus_HAL_UartBaudrateNotSupport	Baudrate is not support in current clock source.
kStatus_HAL_UartProtocolError	Error occurs for Noise, Framing, Parity, etc. For transactional transfer, The up layer needs to abort the transfer and then starts again
kStatus_HAL_UartError	Error occurs on HAL UART.

enum _hal_uart_parity_mode

Enumerator
kHAL_UartParityDisabled	Parity disabled.
kHAL_UartParityEven	Parity even enabled.
kHAL_UartParityOdd	Parity odd enabled.

enum _hal_uart_stop_bit_count

Enumerator
kHAL_UartOneStopBit	One stop bit.
kHAL_UartTwoStopBit	Two stop bits.

Function Documentation

hal_uart_status_t HAL_UartInit	(	hal_uart_handle_t	handle,
		const hal_uart_config_t *	uart_config
	)

This function configures the UART module with user-defined settings. The user can configure the configuration structure. The parameter handle is a pointer to point to a memory space of size HAL_UART_HANDLE_SIZE allocated by the caller. Example below shows how to use this API to configure the UART.

*   UART_HANDLE_DEFINE(g_UartHandle);
*   hal_uart_config_t config;
*   config.srcClock_Hz = 48000000;
*   config.baudRate_Bps = 115200U;
*   config.parityMode = kHAL_UartParityDisabled;
*   config.stopBitCount = kHAL_UartOneStopBit;
*   config.enableRx = 1;
*   config.enableTx = 1;
*   config.enableRxRTS = 0;
*   config.enableTxCTS = 0;
*   config.instance = 0;
*   HAL_UartInit((hal_uart_handle_t)g_UartHandle, &config);
*  

Parameters

handle	Pointer to point to a memory space of size HAL_UART_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: UART_HANDLE_DEFINE(handle); or uint32_t handle[((HAL_UART_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
uart_config	Pointer to user-defined configuration structure.

Return values

kStatus_HAL_UartBaudrateNotSupport	Baudrate is not support in current clock source.
kStatus_HAL_UartSuccess	UART initialization succeed

hal_uart_status_t HAL_UartDeinit ( hal_uart_handle_t handle )

This function waits for TX complete, disables TX and RX, and disables the UART clock.

Parameters

handle UART handle pointer.

Return values

kStatus_HAL_UartSuccess UART de-initialization succeed

hal_uart_status_t HAL_UartReceiveBlocking	(	hal_uart_handle_t	handle,
		uint8_t *	data,
		size_t	length
	)

This function polls the RX register, waits for the RX register to be full or for RX FIFO to have data, and reads data from the RX register.

Note: The function HAL_UartReceiveBlocking and the function HAL_UartTransferReceiveNonBlocking cannot be used at the same time. And, the function HAL_UartTransferAbortReceive cannot be used to abort the transmission of this function.

Parameters

handle	UART handle pointer.
data	Start address of the buffer to store the received data.
length	Size of the buffer.

Return values

kStatus_HAL_UartError	An error occurred while receiving data.
kStatus_HAL_UartParityError	A parity error occurred while receiving data.
kStatus_HAL_UartSuccess	Successfully received all data.

hal_uart_status_t HAL_UartSendBlocking	(	hal_uart_handle_t	handle,
		const uint8_t *	data,
		size_t	length
	)

This function polls the TX register, waits for the TX register to be empty or for the TX FIFO to have room and writes data to the TX buffer.

Note: The function HAL_UartSendBlocking and the function HAL_UartTransferSendNonBlocking cannot be used at the same time. And, the function HAL_UartTransferAbortSend cannot be used to abort the transmission of this function.

Parameters

handle	UART handle pointer.
data	Start address of the data to write.
length	Size of the data to write.

Return values

kStatus_HAL_UartSuccess Successfully sent all data.

hal_uart_status_t HAL_UartInstallCallback	(	hal_uart_handle_t	handle,
		hal_uart_transfer_callback_t	callback,
		void *	callbackParam
	)

This function is used to install the callback and callback parameter for UART module. When non-blocking sending or receiving finished, the adapter will notify the upper layer by the installed callback function. And the status is also passed as status parameter when the callback is called.

Parameters

handle	UART handle pointer.
callback	The callback function.
callbackParam	The parameter of the callback function.

Return values

kStatus_HAL_UartSuccess Successfully install the callback.

hal_uart_status_t HAL_UartReceiveNonBlocking	(	hal_uart_handle_t	handle,
		uint8_t *	data,
		size_t	length
	)

This function receives data using an interrupt method. This is a non-blocking function, which returns directly without waiting for all data to be received. The receive request is saved by the UART adapter. When the new data arrives, the receive request is serviced first. When all data is received, the UART adapter notifies the upper layer through a callback function and passes the status parameter kStatus_HAL_UartRxIdle.

Note: The function HAL_UartReceiveBlocking and the function HAL_UartReceiveNonBlocking cannot be used at the same time.

Parameters

handle	UART handle pointer.
data	Start address of the data to write.
length	Size of the data to write.

Return values

kStatus_HAL_UartSuccess	Successfully queue the transfer into transmit queue.
kStatus_HAL_UartRxBusy	Previous receive request is not finished.
kStatus_HAL_UartError	An error occurred.

hal_uart_status_t HAL_UartSendNonBlocking	(	hal_uart_handle_t	handle,
		uint8_t *	data,
		size_t	length
	)

This function sends data using an interrupt method. This is a non-blocking function, which returns directly without waiting for all data to be written to the TX register. When all data is written to the TX register in the ISR, the UART driver calls the callback function and passes the kStatus_HAL_UartTxIdle as status parameter.

Note: The function HAL_UartSendBlocking and the function HAL_UartSendNonBlocking cannot be used at the same time.

Parameters

handle	UART handle pointer.
data	Start address of the data to write.
length	Size of the data to write.

Return values

kStatus_HAL_UartSuccess	Successfully start the data transmission.
kStatus_HAL_UartTxBusy	Previous transmission still not finished; data not all written to TX register yet.
kStatus_HAL_UartError	An error occurred.

hal_uart_status_t HAL_UartGetReceiveCount	(	hal_uart_handle_t	handle,
		uint32_t *	reCount
	)

This function gets the number of bytes that have been received.

Parameters

handle	UART handle pointer.
reCount	Receive bytes count.

Return values

kStatus_HAL_UartError	An error occurred.
kStatus_Success	Get successfully through the parameter `count`.

hal_uart_status_t HAL_UartGetSendCount	(	hal_uart_handle_t	handle,
		uint32_t *	seCount
	)

This function gets the number of bytes written to the UART TX register by using the interrupt method.

Parameters

handle	UART handle pointer.
seCount	Send bytes count.

Return values

kStatus_HAL_UartError	An error occurred.
kStatus_Success	Get successfully through the parameter `count`.

hal_uart_status_t HAL_UartAbortReceive ( hal_uart_handle_t handle )

This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know how many bytes are not received yet.

Note: The function HAL_UartAbortReceive cannot be used to abort the transmission of the function HAL_UartReceiveBlocking.

Parameters

handle UART handle pointer.

Return values

kStatus_Success Get successfully abort the receiving.

hal_uart_status_t HAL_UartAbortSend ( hal_uart_handle_t handle )

This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out how many bytes are not sent out.

Note: The function HAL_UartAbortSend cannot be used to abort the transmission of the function HAL_UartSendBlocking.

Parameters

handle UART handle pointer.

Return values

kStatus_Success Get successfully abort the sending.

hal_uart_status_t HAL_UartEnterLowpower ( hal_uart_handle_t handle )

This function is used to prepare to enter low power consumption.

Parameters

handle UART handle pointer.

Return values

kStatus_HAL_UartSuccess	Successful operation.
kStatus_HAL_UartError	An error occurred.

hal_uart_status_t HAL_UartExitLowpower ( hal_uart_handle_t handle )

This function is used to restore from low power consumption.

Parameters

handle UART handle pointer.

Return values

kStatus_HAL_UartSuccess	Successful operation.
kStatus_HAL_UartError	An error occurred.

void HAL_UartIsrFunction ( hal_uart_handle_t handle )

This function handles the UART transmit and receive IRQ request.

Parameters

handle UART handle pointer.

Overview

Data Structures

Macros

Typedefs

Enumerations

Functions

Initialization and deinitialization

Blocking bus Operations

Functional API with non-blocking mode.

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation