Module to declare HAL UART protocol. More...

Data Structures
struct	hal_uart_config_t
	HAL UART configuration structure. More...

struct	hal_uart_descriptor_t
	This structure defines the UART module operation. More...

Macros
#define	MAX_QUEUE_LENGTH 0xffffu
	Maximum size in bytes of input and output buffers.

#define	MAX_TX_CHUNK_SIZE UCHAR_MAX
	Maximum size in bytes of data can be stored in hardware unit output buffer.

Typedefs
typedef void(*	hal_uart_handler_t )(uint32_t channel, size_t char_count)
	User-side handler of UART read and write events. More...

typedef void(*	hal_uart_error_handler_t )(uint32_t channel, hal_uart_error_t error_id)
	User-side handler for UART error events. More...

Enumerations
enum	hal_uart_baudrate_t { HAL_UART_BAUDRATE_38400, HAL_UART_BAUDRATE_115200, HAL_UART_BAUDRATE_230400 }
	UART baudrate. More...

enum	hal_uart_parity_t { HAL_UART_PARITY_NONE, HAL_UART_PARITY_EVEN }
	UART parity check. More...

enum	hal_uart_flow_control_t { HAL_UART_FLOW_CONTROL_DISABLED, HAL_UART_FLOW_CONTROL_ENABLED }
	UART flow control. More...

enum	hal_uart_char_size_t { HAL_UART_FIVE_BITS_CHAR = 5, HAL_UART_SIX_BITS_CHAR, HAL_UART_SEVEN_BITS_CHAR, HAL_UART_EIGHT_BITS_CHAR }
	UART character size settings. More...

enum	hal_uart_stop_bits_t { HAL_UART_ONE_STOP_BIT, HAL_UART_ONEHALF_STOP_BITS, HAL_UART_TWO_STOP_BITS }
	UART stop bits settings. More...

enum	hal_uart_error_t { HAL_UART_ERROR_NONE = 0, HAL_UART_ERROR_TX_OVERFLOW = 252, HAL_UART_ERROR_RX_OVERFLOW = 253, HAL_UART_ERROR_RX_UNDERFLOW = 254, HAL_UART_ERROR_HW_ERROR = 255 }
	Represents error source for the UART driver. There might be other values, representing clearer elaborating of error statuses, if this module is used with Windows or Linux. More...

Functions
hal_uart_error_t	hal_uart_open (const hal_uart_config_t config, const hal_uart_descriptor_t descriptor)
	Configures UART interface using input parameter. More...

void	hal_uart_write (const hal_uart_descriptor_t descriptor, const uint8_t data, const size_t length)
	Sends data in a non-blocking way. More...

void	hal_uart_puts (const hal_uart_descriptor_t descriptor, const char s)
	Sends a null-terminated C-string in a non-blocking way. More...

void	hal_uart_read (const hal_uart_descriptor_t descriptor, uint8_t data, const size_t length)
	Receives data in a non-blocking way. More...

size_t	hal_uart_read_buffer_size_get (const hal_uart_descriptor_t *descriptor)
	Returns number of bytes available to read from the income buffer of the driver. More...

size_t	hal_uart_write_buffer_size_get (const hal_uart_descriptor_t *descriptor)
	Returns number of bytes available to write to the outgoing buffer of the driver. More...

hal_uart_error_t	hal_uart_close (const hal_uart_descriptor_t *descriptor)
	This function deallocates resources previously allocated by hal_uart_open. More...

Detailed Description

Module to declare HAL UART protocol.

The UART module implements the standard UART driver API. This includes open/close via hal_uart_open(), hal_uart_close(), read/write via hal_uart_read(), hal_uart_write() routines, and hal_uart_puts() for sending a null-terminated string in a non-blocking way. The user also can get some info about the available bytes for read/write via hal_uart_read_buffer_size_get() and hal_uart_write_buffer_size_get(). This implies that the user may register read/write buffers to use for buffered input/output and handler routines that will be called upon read/written characters. Also the most popular settings of the UART driver are supported: different baudrates, parity checks, flow control, character size, and stop bits.

Typedef Documentation

typedef void(* hal_uart_error_handler_t)(uint32_t channel, hal_uart_error_t error_id)

User-side handler for UART error events.

Parameters

[in]	channel	event channel number.
[in]	error_id	call reason.

typedef void(* hal_uart_handler_t)(uint32_t channel, size_t char_count)

User-side handler of UART read and write events.

Parameters

[in]	channel	event channel number.
[in]	char_count	number of characters successfully sent before entering the callback function.

Enumeration Type Documentation

enum hal_uart_baudrate_t

UART baudrate.

Enumerator
HAL_UART_BAUDRATE_38400	38400 bits per second.
HAL_UART_BAUDRATE_115200	115200 bits per second.
HAL_UART_BAUDRATE_230400	230400 bits per second.

enum hal_uart_char_size_t

UART character size settings.

Enumerator
HAL_UART_FIVE_BITS_CHAR	5 bits character.
HAL_UART_SIX_BITS_CHAR	6 bits character.
HAL_UART_SEVEN_BITS_CHAR	7 bits character.
HAL_UART_EIGHT_BITS_CHAR	8 bits character.

enum hal_uart_error_t

Represents error source for the UART driver. There might be other values, representing clearer elaborating of error statuses, if this module is used with Windows or Linux.

Enumerator
HAL_UART_ERROR_NONE	Success.
HAL_UART_ERROR_TX_OVERFLOW	This error happens when amount of elements in the transmitter ring buffer exceeds its size. All the data above limit is not placed into buffer.
HAL_UART_ERROR_RX_OVERFLOW	This error happens when amount of elements in the receiver ring buffer exceeds its size. All the unread data is overwritten with new received data.
HAL_UART_ERROR_RX_UNDERFLOW	This error happens when the user-side software tries to read more elements than it is available in the receive buffer. The user-side buffer will be filled with all available characters and then the error handler is started.
HAL_UART_ERROR_HW_ERROR	There is some unrecoverable error in hardware.

enum hal_uart_flow_control_t

UART flow control.

Enumerator
HAL_UART_FLOW_CONTROL_DISABLED	Flow control is disabled.
HAL_UART_FLOW_CONTROL_ENABLED	Flow control is enabled.

enum hal_uart_parity_t

UART parity check.

Enumerator
HAL_UART_PARITY_NONE	Do not check parity.
HAL_UART_PARITY_EVEN	Check even parity.

enum hal_uart_stop_bits_t

UART stop bits settings.

Enumerator
HAL_UART_ONE_STOP_BIT	1 stop bit.
HAL_UART_ONEHALF_STOP_BITS	1.5 stop bits.
HAL_UART_TWO_STOP_BITS	2 stop bits.

Function Documentation

hal_uart_error_t hal_uart_close ( const hal_uart_descriptor_t * descriptor )

This function deallocates resources previously allocated by hal_uart_open.

Parameters

[in] descriptor pointer to driver structure.

Returns: Return status of operation.

hal_uart_error_t hal_uart_open	(	const hal_uart_config_t *	config,
		const hal_uart_descriptor_t *	descriptor
	)

Configures UART interface using input parameter.

Parameters

[in]	config	pointer to a config struct.
[in]	descriptor	pointer to a descriptor struct.

Returns: Return status of operation.

void hal_uart_puts	(	const hal_uart_descriptor_t *	descriptor,
		const char *	s
	)

Sends a null-terminated C-string in a non-blocking way.

Parameters

[in]	descriptor	pointer to the UART module operation structure.
[in]	s	null-terminated string to send.

void hal_uart_read	(	const hal_uart_descriptor_t *	descriptor,
		uint8_t *	data,
		const size_t	length
	)

Receives data in a non-blocking way.

Parameters

[in]	descriptor	pointer to the UART module operation structure.
[out]	data	pointer to the user-side buffer used to receive data.
[in]	length	number of bytes to receive.

If descriptor has a non-null read_buffer_ptr, then this function is used to copy input characters from it to data. If read_buffer_ptr is NULL, then this function ignores all inputs.

size_t hal_uart_read_buffer_size_get ( const hal_uart_descriptor_t * descriptor )

Returns number of bytes available to read from the income buffer of the driver.

Parameters

[in] descriptor pointer to driver structure.

Returns: Number of bytes available to read.

void hal_uart_write	(	const hal_uart_descriptor_t *	descriptor,
		const uint8_t *	data,
		const size_t	length
	)

Sends data in a non-blocking way.

Parameters

[in]	descriptor	pointer to the UART module operation structure.
[in]	data	pointer to the user-side buffer of output data.
[in]	length	number of bytes to transmit.

If descriptor has a non-null write_buffer_ptr then this function will use it as a temporary buffer and will copy input data to it before starting transmit. If descriptor has the NULL write_buffer_ptr, then the user-side code is responsible to retain data until write_handler is called.

size_t hal_uart_write_buffer_size_get ( const hal_uart_descriptor_t * descriptor )

Returns number of bytes available to write to the outgoing buffer of the driver.

Parameters

[in] descriptor pointer to driver structure.

Returns: Number of bytes available to write.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation