Generic UART Driver. More...

Detailed Description

Generic UART Driver.

This driver abstracts a generic UART (Universal Asynchronous Receiver Transmitter) peripheral, the API is designed to be:

Unbuffered and copy-less, transfers are always directly performed from/to the application-level buffers without extra copy operations.
Asynchronous, the API is always non blocking.
Callbacks capable, operations completion and other events are notified using callbacks.

Special hardware features like deep hardware buffers, DMA transfers are hidden to the user but fully supportable by the low level implementations.
This driver model is best used where communication events are meant to drive an higher level state machine, as example:

RS485 drivers.
Multipoint network drivers.
Serial protocol decoders.

If your application requires a synchronous buffered driver then the Serial Driver should be used instead.

Precondition: In order to use the UART driver the HAL_USE_UART option must be enabled in halconf.h.

Driver State Machine

The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

Transmitter sub State Machine

The follow diagram describes the transmitter state machine, this diagram is valid while the driver is in the UART_READY state. This state machine is automatically reset to the TX_IDLE state each time the driver enters the UART_READY state.

Receiver sub State Machine

The follow diagram describes the receiver state machine, this diagram is valid while the driver is in the UART_READY state. This state machine is automatically reset to the RX_IDLE state each time the driver enters the UART_READY state.

Collaboration diagram for UART Driver:

UART status flags
#define	UART_NO_ERROR 0
	No pending conditions.
#define	UART_PARITY_ERROR 4
	Parity error happened.
#define	UART_FRAMING_ERROR 8
	Framing error happened.
#define	UART_OVERRUN_ERROR 16
	Overflow happened.
#define	UART_NOISE_ERROR 32
	Noise on the line.
#define	UART_BREAK_DETECTED 64
	Break detected.

UART error conditions
#define	UART_ERR_NOT_ACTIVE (size_t)-1

UART configuration options
#define	UART_USE_WAIT FALSE
	Enables synchronous APIs.
#define	UART_USE_MUTUAL_EXCLUSION FALSE
	Enables the `uartAcquireBus()` and `uartReleaseBus()` APIs.

Low level driver helper macros
#define	_uart_wakeup_tx1_isr(uartp)
	Wakes up the waiting thread in case of early TX complete.
#define	_uart_wakeup_tx2_isr(uartp)
	Wakes up the waiting thread in case of late TX complete.
#define	_uart_wakeup_rx_complete_isr(uartp)
	Wakes up the waiting thread in case of RX complete.
#define	_uart_wakeup_rx_error_isr(uartp)
	Wakes up the waiting thread in case of RX error.
#define	_uart_wakeup_rx_cm_isr(uartp)
	Wakes up the waiting thread in case of RX character match.
#define	_uart_wakeup_rx_timeout_isr(uartp)
	Wakes up the waiting thread in case of RX timeout.
#define	_uart_tx1_isr_code(uartp)
	Common ISR code for early TX.
#define	_uart_tx2_isr_code(uartp)
	Common ISR code for late TX.
#define	_uart_rx_complete_isr_code(uartp)
	Common ISR code for RX complete.
#define	_uart_rx_error_isr_code(uartp, errors)
	Common ISR code for RX error.
#define	_uart_rx_idle_code(uartp)
	Common ISR code for RX on idle.
#define	_uart_timeout_isr_code(uartp)
	Timeout ISR code for receiver.
#define	_uart_rx_char_match_isr_code(uartp)
	Character match ISR code for receiver.

PLATFORM configuration options
#define	PLATFORM_UART_USE_UART1 FALSE
	UART driver enable switch.

Data Structures
struct	hal_uart_config
	Driver configuration structure. More...
struct	hal_uart_driver
	Structure representing an UART driver. More...

Typedefs
typedef uint32_t	uartflags_t
	UART driver condition flags type.
typedef struct hal_uart_driver	UARTDriver
	Type of structure representing an UART driver.
typedef void(*	uartcb_t) (UARTDriver *uartp)
	Generic UART notification callback type.
typedef void(*	uartccb_t) (UARTDriver *uartp, uint16_t c)
	Character received UART notification callback type.
typedef void(*	uartecb_t) (UARTDriver *uartp, uartflags_t e)
	Receive error UART notification callback type.
typedef struct hal_uart_config	UARTConfig
	Driver configuration structure.

Enumerations
enum	uartstate_t { UART_UNINIT = 0 , UART_STOP = 1 , UART_READY = 2 }
	Driver state machine possible states. More...
enum	uarttxstate_t { UART_TX_IDLE = 0 , UART_TX_ACTIVE = 1 , UART_TX_COMPLETE = 2 }
	Transmitter state machine states. More...
enum	uartrxstate_t { UART_RX_IDLE = 0 , UART_RX_ACTIVE = 1 , UART_RX_COMPLETE = 2 }
	Receiver state machine states. More...

Functions
void	uartInit (void)
	UART Driver initialization.
void	uartObjectInit (UARTDriver *uartp)
	Initializes the standard part of a `UARTDriver` structure.
msg_t	uartStart (UARTDriver uartp, const UARTConfig config)
	Configures and activates the UART peripheral.
void	uartStop (UARTDriver *uartp)
	Deactivates the UART peripheral.
void	uartStartSend (UARTDriver uartp, size_t n, const void txbuf)
	Starts a transmission on the UART peripheral.
void	uartStartSendI (UARTDriver uartp, size_t n, const void txbuf)
	Starts a transmission on the UART peripheral.
size_t	uartStopSend (UARTDriver *uartp)
	Stops any ongoing transmission.
size_t	uartStopSendI (UARTDriver *uartp)
	Stops any ongoing transmission.
void	uartStartReceive (UARTDriver uartp, size_t n, void rxbuf)
	Starts a receive operation on the UART peripheral.
void	uartStartReceiveI (UARTDriver uartp, size_t n, void rxbuf)
	Starts a receive operation on the UART peripheral.
size_t	uartStopReceive (UARTDriver *uartp)
	Stops any ongoing receive operation.
size_t	uartStopReceiveI (UARTDriver *uartp)
	Stops any ongoing receive operation.
msg_t	uartSendTimeout (UARTDriver uartp, size_t np, const void *txbuf, sysinterval_t timeout)
	Performs a transmission on the UART peripheral.
msg_t	uartSendFullTimeout (UARTDriver uartp, size_t np, const void *txbuf, sysinterval_t timeout)
	Performs a transmission on the UART peripheral.
msg_t	uartReceiveTimeout (UARTDriver uartp, size_t np, void *rxbuf, sysinterval_t timeout)
	Performs a receive operation on the UART peripheral.
void	uartAcquireBus (UARTDriver *uartp)
	Gains exclusive access to the UART bus.
void	uartReleaseBus (UARTDriver *uartp)
	Releases exclusive access to the UART bus.
void	uart_lld_init (void)
	Low level UART driver initialization.
void	uart_lld_start (UARTDriver *uartp)
	Configures and activates the UART peripheral.
void	uart_lld_stop (UARTDriver *uartp)
	Deactivates the UART peripheral.
void	uart_lld_start_send (UARTDriver uartp, size_t n, const void txbuf)
	Starts a transmission on the UART peripheral.
size_t	uart_lld_stop_send (UARTDriver *uartp)
	Stops any ongoing transmission.
void	uart_lld_start_receive (UARTDriver uartp, size_t n, void rxbuf)
	Starts a receive operation on the UART peripheral.
size_t	uart_lld_stop_receive (UARTDriver *uartp)
	Stops any ongoing receive operation.

Variables
UARTDriver	UARTD1
	UART1 driver identifier.

Macro Definition Documentation

◆ UART_NO_ERROR

#define UART_NO_ERROR 0

No pending conditions.

Definition at line 38 of file hal_uart.h.

◆ UART_PARITY_ERROR

#define UART_PARITY_ERROR 4

Parity error happened.

Definition at line 39 of file hal_uart.h.

◆ UART_FRAMING_ERROR

#define UART_FRAMING_ERROR 8

Framing error happened.

Definition at line 40 of file hal_uart.h.

◆ UART_OVERRUN_ERROR

#define UART_OVERRUN_ERROR 16

Overflow happened.

Definition at line 41 of file hal_uart.h.

◆ UART_NOISE_ERROR

#define UART_NOISE_ERROR 32

Noise on the line.

Definition at line 42 of file hal_uart.h.

◆ UART_BREAK_DETECTED

#define UART_BREAK_DETECTED 64

Break detected.

Definition at line 43 of file hal_uart.h.

◆ UART_ERR_NOT_ACTIVE

#define UART_ERR_NOT_ACTIVE (size_t)-1

Definition at line 50 of file hal_uart.h.

Referenced by uartStopReceive(), uartStopReceiveI(), uartStopSend(), and uartStopSendI().

◆ UART_USE_WAIT

#define UART_USE_WAIT FALSE

Enables synchronous APIs.

Note: Disabling this option saves both code and data space.

Definition at line 66 of file hal_uart.h.

◆ UART_USE_MUTUAL_EXCLUSION

#define UART_USE_MUTUAL_EXCLUSION FALSE

Enables the uartAcquireBus() and uartReleaseBus() APIs.

Note: Disabling this option saves both code and data space.

Definition at line 74 of file hal_uart.h.

◆ _uart_wakeup_tx1_isr

#define _uart_wakeup_tx1_isr ( uartp )

Value:

  {                                       \
  if ((uartp)->early == true) {                                             \
    osalSysLockFromISR();                                                   \
    osalThreadResumeI(&(uartp)->threadtx, MSG_OK);                          \
    osalSysUnlockFromISR();                                                 \
  }                                                                         \
}

Wakes up the waiting thread in case of early TX complete.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 131 of file hal_uart.h.

◆ _uart_wakeup_tx2_isr

#define _uart_wakeup_tx2_isr ( uartp )

Value:

  {                                       \
  if ((uartp)->early == false) {                                            \
    osalSysLockFromISR();                                                   \
    osalThreadResumeI(&(uartp)->threadtx, MSG_OK);                          \
    osalSysUnlockFromISR();                                                 \
  }                                                                         \
}

Wakes up the waiting thread in case of late TX complete.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 150 of file hal_uart.h.

◆ _uart_wakeup_rx_complete_isr

#define _uart_wakeup_rx_complete_isr ( uartp )

Value:

  {                               \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(uartp)->threadrx, MSG_OK);                            \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread in case of RX complete.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 169 of file hal_uart.h.

◆ _uart_wakeup_rx_error_isr

#define _uart_wakeup_rx_error_isr ( uartp )

Value:

  {                                  \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(uartp)->threadrx, MSG_RESET);                         \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread in case of RX error.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 186 of file hal_uart.h.

◆ _uart_wakeup_rx_cm_isr

#define _uart_wakeup_rx_cm_isr ( uartp )

Value:

  {                                     \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(uartp)->threadrx, MSG_TIMEOUT);                       \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread in case of RX character match.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 203 of file hal_uart.h.

◆ _uart_wakeup_rx_timeout_isr

#define _uart_wakeup_rx_timeout_isr ( uartp )

Value:

  {                                \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(uartp)->threadrx, MSG_TIMEOUT);                       \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread in case of RX timeout.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 220 of file hal_uart.h.

◆ _uart_tx1_isr_code

#define _uart_tx1_isr_code ( uartp )

Value:

  {                                         \
  (uartp)->txstate = UART_TX_COMPLETE;                                      \
  if ((uartp)->config->txend1_cb != NULL) {                                 \
    (uartp)->config->txend1_cb(uartp);                                      \
  }                                                                         \
  if ((uartp)->txstate == UART_TX_COMPLETE) {                               \
    (uartp)->txstate = UART_TX_IDLE;                                        \
  }                                                                         \
  _uart_wakeup_tx1_isr(uartp);                                              \
}

Common ISR code for early TX.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 243 of file hal_uart.h.

◆ _uart_tx2_isr_code

#define _uart_tx2_isr_code ( uartp )

Value:

  {                                         \
  if ((uartp)->config->txend2_cb != NULL) {                                 \
    (uartp)->config->txend2_cb(uartp);                                      \
  }                                                                         \
  _uart_wakeup_tx2_isr(uartp);                                              \
}

Common ISR code for late TX.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 268 of file hal_uart.h.

◆ _uart_rx_complete_isr_code

#define _uart_rx_complete_isr_code ( uartp )

Value:

  {                                 \
  (uartp)->rxstate = UART_RX_COMPLETE;                                      \
  if ((uartp)->config->rxend_cb != NULL) {                                  \
    (uartp)->config->rxend_cb(uartp);                                       \
  }                                                                         \
  if ((uartp)->rxstate == UART_RX_COMPLETE) {                               \
    (uartp)->rxstate = UART_RX_IDLE;                                        \
    uart_enter_rx_idle_loop(uartp);                                         \
  }                                                                         \
  _uart_wakeup_rx_complete_isr(uartp);                                      \
}

Common ISR code for RX complete.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 289 of file hal_uart.h.

◆ _uart_rx_error_isr_code

#define _uart_rx_error_isr_code	(		uartp,
			errors )

Value:

  {                            \
  if ((uartp)->config->rxerr_cb != NULL) {                                  \
    (uartp)->config->rxerr_cb(uartp, errors);                               \
  }                                                                         \
  _uart_wakeup_rx_error_isr(uartp);                                         \
}

Common ISR code for RX error.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	errors	mask of errors to be reported

Function Class:: Not an API, this function is for internal use only.

Definition at line 316 of file hal_uart.h.

◆ _uart_rx_idle_code

#define _uart_rx_idle_code ( uartp )

Value:

  {                                         \
  if ((uartp)->config->rxchar_cb != NULL)                                   \
    (uartp)->config->rxchar_cb(uartp, (uartp)->rxbuf);                      \
}

Common ISR code for RX on idle.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 337 of file hal_uart.h.

◆ _uart_timeout_isr_code

#define _uart_timeout_isr_code ( uartp )

Value:

  {                                     \
  if ((uartp)->config->timeout_cb != NULL) {                                \
    (uartp)->config->timeout_cb(uartp);                                     \
  }                                                                         \
  _uart_wakeup_rx_timeout_isr(uartp);                                       \
}

Timeout ISR code for receiver.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 356 of file hal_uart.h.

◆ _uart_rx_char_match_isr_code

#define _uart_rx_char_match_isr_code ( uartp )

Value:

  {                               \
  if ((uartp)->config->rx_cm_cb != NULL) {                                  \
    (uartp)->config->rx_cm_cb(uartp);                                       \
  }                                                                         \
  _uart_wakeup_rx_cm_isr(uartp);                                            \
}

Character match ISR code for receiver.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 377 of file hal_uart.h.

◆ PLATFORM_UART_USE_UART1

#define PLATFORM_UART_USE_UART1 FALSE

UART driver enable switch.

If set to TRUE the support for UART1 is included.

Note: The default is FALSE.

Definition at line 48 of file hal_uart_lld.h.

Typedef Documentation

◆ uartflags_t

typedef uint32_t uartflags_t

UART driver condition flags type.

Definition at line 63 of file hal_uart_lld.h.

◆ UARTDriver

typedef struct hal_uart_driver UARTDriver

Type of structure representing an UART driver.

Definition at line 68 of file hal_uart_lld.h.

◆ uartcb_t

typedef void(* uartcb_t) (UARTDriver *uartp)

Generic UART notification callback type.

Parameters

[in] uartp pointer to the UARTDriver object

Definition at line 75 of file hal_uart_lld.h.

◆ uartccb_t

typedef void(* uartccb_t) (UARTDriver *uartp, uint16_t c)

Character received UART notification callback type.

Parameters

[in]	uartp	pointer to the `UARTDriver` object triggering the callback
[in]	c	received character

Definition at line 84 of file hal_uart_lld.h.

◆ uartecb_t

typedef void(* uartecb_t) (UARTDriver *uartp, uartflags_t e)

Receive error UART notification callback type.

Parameters

[in]	uartp	pointer to the `UARTDriver` object triggering the callback
[in]	e	receive error mask

Definition at line 93 of file hal_uart_lld.h.

◆ UARTConfig

typedef struct hal_uart_config UARTConfig

Driver configuration structure.

Note: Implementations may extend this structure to contain more, architecture dependent, fields.

Enumeration Type Documentation

◆ uartstate_t

enum uartstate_t

Driver state machine possible states.

Enumerator
UART_UNINIT	Not initialized.
UART_STOP	Stopped.
UART_READY	Ready.

Definition at line 89 of file hal_uart.h.

◆ uarttxstate_t

enum uarttxstate_t

Transmitter state machine states.

Enumerator
UART_TX_IDLE	Not transmitting.
UART_TX_ACTIVE	Transmitting.
UART_TX_COMPLETE	Buffer complete.

Definition at line 98 of file hal_uart.h.

◆ uartrxstate_t

enum uartrxstate_t

Receiver state machine states.

Enumerator
UART_RX_IDLE	Not receiving.
UART_RX_ACTIVE	Receiving.
UART_RX_COMPLETE	Buffer complete.

Definition at line 107 of file hal_uart.h.

Function Documentation

◆ uartInit()

void uartInit ( void )

UART Driver initialization.

Note: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:: Object or module nitializer function.

Definition at line 56 of file hal_uart.c.

References uart_lld_init().

Referenced by halInit().

Here is the call graph for this function:

◆ uartObjectInit()

void uartObjectInit ( UARTDriver * uartp )

Initializes the standard part of a UARTDriver structure.

Parameters

[out] uartp pointer to the UARTDriver object

Function Class:: Object or module nitializer function.

Definition at line 68 of file hal_uart.c.

References hal_uart_driver::config, hal_uart_driver::early, hal_uart_driver::mutex, osalMutexObjectInit(), hal_uart_driver::rxstate, hal_uart_driver::state, hal_uart_driver::threadrx, hal_uart_driver::threadtx, hal_uart_driver::txstate, UART_RX_IDLE, UART_STOP, and UART_TX_IDLE.

Referenced by uart_lld_init().

Here is the call graph for this function:

◆ uartStart()

msg_t uartStart	(	UARTDriver *	uartp,
		const UARTConfig *	config )

Configures and activates the UART peripheral.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	config	pointer to the `UARTConfig` object

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 98 of file hal_uart.c.

References hal_uart_driver::config, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), hal_uart_driver::state, uart_lld_start(), UART_READY, and UART_STOP.

Here is the call graph for this function:

◆ uartStop()

void uartStop ( UARTDriver * uartp )

Deactivates the UART peripheral.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 135 of file hal_uart.c.

References hal_uart_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), hal_uart_driver::rxstate, hal_uart_driver::state, hal_uart_driver::txstate, uart_lld_stop(), UART_READY, UART_RX_IDLE, UART_STOP, and UART_TX_IDLE.

Here is the call graph for this function:

◆ uartStartSend()

void uartStartSend	(	UARTDriver *	uartp,
		size_t	n,
		const void *	txbuf )

Starts a transmission on the UART peripheral.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	n	number of data frames to send
[in]	txbuf	the pointer to the transmit buffer

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 164 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), hal_uart_driver::state, hal_uart_driver::txstate, uart_lld_start_send(), UART_READY, and UART_TX_ACTIVE.

Here is the call graph for this function:

◆ uartStartSendI()

void uartStartSendI	(	UARTDriver *	uartp,
		size_t	n,
		const void *	txbuf )

Starts a transmission on the UART peripheral.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.; This function has to be invoked from a lock zone.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	n	number of data frames to send
[in]	txbuf	the pointer to the transmit buffer

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 189 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, hal_uart_driver::state, hal_uart_driver::txstate, uart_lld_start_send(), UART_READY, and UART_TX_ACTIVE.

Here is the call graph for this function:

◆ uartStopSend()

size_t uartStopSend ( UARTDriver * uartp )

Stops any ongoing transmission.

Note: Stopping a transmission also suppresses the transmission callbacks.

Parameters

[in] uartp pointer to the UARTDriver object

Returns: The number of data frames not transmitted by the stopped transmit operation.

Return values

UART_ERR_NOT_ACTIVE if there was no transmit operation in progress.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 212 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), hal_uart_driver::state, hal_uart_driver::txstate, UART_ERR_NOT_ACTIVE, uart_lld_stop_send(), UART_READY, UART_TX_ACTIVE, and UART_TX_IDLE.

Here is the call graph for this function:

◆ uartStopSendI()

size_t uartStopSendI ( UARTDriver * uartp )

Stops any ongoing transmission.

Note: Stopping a transmission also suppresses the transmission callbacks.; This function has to be invoked from a lock zone.

Parameters

[in] uartp pointer to the UARTDriver object

Returns: The number of data frames not transmitted by the stopped transmit operation.

Return values

UART_ERR_NOT_ACTIVE if there was no transmit operation in progress.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 245 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, hal_uart_driver::state, hal_uart_driver::txstate, UART_ERR_NOT_ACTIVE, uart_lld_stop_send(), UART_READY, UART_TX_ACTIVE, and UART_TX_IDLE.

Referenced by uartSendFullTimeout(), and uartSendTimeout().

Here is the call graph for this function:

◆ uartStartReceive()

void uartStartReceive	(	UARTDriver *	uartp,
		size_t	n,
		void *	rxbuf )

Starts a receive operation on the UART peripheral.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	n	number of data frames to receive
[in]	rxbuf	the pointer to the receive buffer

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 270 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), hal_uart_driver::rxstate, hal_uart_driver::state, uart_lld_start_receive(), UART_READY, and UART_RX_ACTIVE.

Here is the call graph for this function:

◆ uartStartReceiveI()

void uartStartReceiveI	(	UARTDriver *	uartp,
		size_t	n,
		void *	rxbuf )

Starts a receive operation on the UART peripheral.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.; This function has to be invoked from a lock zone.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	n	number of data frames to receive
[out]	rxbuf	the pointer to the receive buffer

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 295 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, hal_uart_driver::rxstate, hal_uart_driver::state, uart_lld_start_receive(), UART_READY, and UART_RX_ACTIVE.

Here is the call graph for this function:

◆ uartStopReceive()

size_t uartStopReceive ( UARTDriver * uartp )

Stops any ongoing receive operation.

Note: Stopping a receive operation also suppresses the receive callbacks.

Parameters

[in] uartp pointer to the UARTDriver object

Returns: The number of data frames not received by the stopped receive operation.

Return values

UART_ERR_NOT_ACTIVE if there was no receive operation in progress.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 318 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), hal_uart_driver::rxstate, hal_uart_driver::state, UART_ERR_NOT_ACTIVE, uart_lld_stop_receive(), UART_READY, UART_RX_ACTIVE, and UART_RX_IDLE.

Here is the call graph for this function:

◆ uartStopReceiveI()

size_t uartStopReceiveI ( UARTDriver * uartp )

Stops any ongoing receive operation.

Note: Stopping a receive operation also suppresses the receive callbacks.; This function has to be invoked from a lock zone.

Parameters

[in] uartp pointer to the UARTDriver object

Returns: The number of data frames not received by the stopped receive operation.

Return values

UART_ERR_NOT_ACTIVE if there was no receive operation in progress.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 351 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, hal_uart_driver::rxstate, hal_uart_driver::state, UART_ERR_NOT_ACTIVE, uart_lld_stop_receive(), UART_READY, UART_RX_ACTIVE, and UART_RX_IDLE.

Referenced by uartReceiveTimeout().

Here is the call graph for this function:

◆ uartSendTimeout()

msg_t uartSendTimeout	(	UARTDriver *	uartp,
		size_t *	np,
		const void *	txbuf,
		sysinterval_t	timeout )

Performs a transmission on the UART peripheral.

Note: The function returns when the specified number of frames have been sent to the UART or on timeout.; The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.; This function implements a software timeout, it does not use any underlying HW timeout mechanism.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in,out]	np	number of data frames to transmit, on exit the number of frames actually transmitted
[in]	txbuf	the pointer to the transmit buffer
[in]	timeout	operation timeout

Returns: The operation status.

Return values

MSG_OK	if the operation completed successfully.
MSG_TIMEOUT	if the operation timed out.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 386 of file hal_uart.c.

References hal_uart_driver::early, MSG_OK, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendTimeoutS(), hal_uart_driver::state, hal_uart_driver::threadtx, hal_uart_driver::txstate, uart_lld_start_send(), UART_READY, UART_TX_ACTIVE, and uartStopSendI().

Here is the call graph for this function:

◆ uartSendFullTimeout()

msg_t uartSendFullTimeout	(	UARTDriver *	uartp,
		size_t *	np,
		const void *	txbuf,
		sysinterval_t	timeout )

Performs a transmission on the UART peripheral.

Note: The function returns when the specified number of frames have been physically transmitted or on timeout.; The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.; This function implements a software timeout, it does not use any underlying HW timeout mechanism.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in,out]	np	number of data frames to transmit, on exit the number of frames actually transmitted
[in]	txbuf	the pointer to the transmit buffer
[in]	timeout	operation timeout

Returns: The operation status.

Return values

MSG_OK	if the operation completed successfully.
MSG_TIMEOUT	if the operation timed out.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 431 of file hal_uart.c.

References hal_uart_driver::early, MSG_OK, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendTimeoutS(), hal_uart_driver::state, hal_uart_driver::threadtx, hal_uart_driver::txstate, uart_lld_start_send(), UART_READY, UART_TX_ACTIVE, and uartStopSendI().

Here is the call graph for this function:

◆ uartReceiveTimeout()

msg_t uartReceiveTimeout	(	UARTDriver *	uartp,
		size_t *	np,
		void *	rxbuf,
		sysinterval_t	timeout )

Performs a receive operation on the UART peripheral.

Note: The function returns when the specified number of frames have been received or on error/timeout.; The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.; This function implements a software timeout, it does not use any underlying HW timeout mechanism.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in,out]	np	number of data frames to receive, on exit the number of frames actually received
[in]	rxbuf	the pointer to the receive buffer
[in]	timeout	operation timeout

Returns: The operation status.

Return values

MSG_OK	if the operation completed successfully.
MSG_TIMEOUT	if the operation timed out.
MSG_RESET	in case of a receive error.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 478 of file hal_uart.c.

References MSG_OK, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendTimeoutS(), hal_uart_driver::rxstate, hal_uart_driver::state, hal_uart_driver::threadrx, uart_lld_start_receive(), UART_READY, UART_RX_ACTIVE, and uartStopReceiveI().

Here is the call graph for this function:

◆ uartAcquireBus()

void uartAcquireBus ( UARTDriver * uartp )

Gains exclusive access to the UART bus.

This function tries to gain ownership to the UART bus, if the bus is already being used then the invoking thread is queued.

Precondition: In order to use this function the option UART_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 515 of file hal_uart.c.

References hal_uart_driver::mutex, osalDbgCheck, and osalMutexLock().

Here is the call graph for this function:

◆ uartReleaseBus()

void uartReleaseBus ( UARTDriver * uartp )

Releases exclusive access to the UART bus.

Precondition: In order to use this function the option UART_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 531 of file hal_uart.c.

References hal_uart_driver::mutex, osalDbgCheck, and osalMutexUnlock().

Here is the call graph for this function:

◆ uart_lld_init()

void uart_lld_init ( void )

Low level UART driver initialization.

Function Class:: Not an API, this function is for internal use only.

Definition at line 65 of file hal_uart_lld.c.

References UARTD1, and uartObjectInit().

Referenced by uartInit().

Here is the call graph for this function:

◆ uart_lld_start()

void uart_lld_start ( UARTDriver * uartp )

Configures and activates the UART peripheral.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 80 of file hal_uart_lld.c.

References hal_uart_driver::state, UART_STOP, and UARTD1.

Referenced by uartStart().

◆ uart_lld_stop()

void uart_lld_stop ( UARTDriver * uartp )

Deactivates the UART peripheral.

Parameters

[in] uartp pointer to the UARTDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 101 of file hal_uart_lld.c.

References hal_uart_driver::state, UART_READY, and UARTD1.

Referenced by uartStop().

◆ uart_lld_start_send()

void uart_lld_start_send	(	UARTDriver *	uartp,
		size_t	n,
		const void *	txbuf )

Starts a transmission on the UART peripheral.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	n	number of data frames to send
[in]	txbuf	the pointer to the transmit buffer

Function Class:: Not an API, this function is for internal use only.

Definition at line 126 of file hal_uart_lld.c.

Referenced by uartSendFullTimeout(), uartSendTimeout(), uartStartSend(), and uartStartSendI().

◆ uart_lld_stop_send()

size_t uart_lld_stop_send ( UARTDriver * uartp )

Stops any ongoing transmission.

Note: Stopping a transmission also suppresses the transmission callbacks.

Parameters

[in] uartp pointer to the UARTDriver object

Returns: The number of data frames not transmitted by the stopped transmit operation.

Function Class:: Not an API, this function is for internal use only.

Definition at line 145 of file hal_uart_lld.c.

Referenced by uartStopSend(), and uartStopSendI().

◆ uart_lld_start_receive()

void uart_lld_start_receive	(	UARTDriver *	uartp,
		size_t	n,
		void *	rxbuf )

Starts a receive operation on the UART peripheral.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	uartp	pointer to the `UARTDriver` object
[in]	n	number of data frames to send
[out]	rxbuf	the pointer to the receive buffer

Function Class:: Not an API, this function is for internal use only.

Definition at line 163 of file hal_uart_lld.c.

Referenced by uartReceiveTimeout(), uartStartReceive(), and uartStartReceiveI().

◆ uart_lld_stop_receive()

size_t uart_lld_stop_receive ( UARTDriver * uartp )

Stops any ongoing receive operation.

Note: Stopping a receive operation also suppresses the receive callbacks.

Parameters

[in] uartp pointer to the UARTDriver object

Returns: The number of data frames not received by the stopped receive operation.

Function Class:: Not an API, this function is for internal use only.

Definition at line 182 of file hal_uart_lld.c.

Referenced by uartStopReceive(), and uartStopReceiveI().

Variable Documentation

◆ UARTD1

UARTDriver UARTD1

UART1 driver identifier.

Definition at line 41 of file hal_uart_lld.c.

Referenced by uart_lld_init(), uart_lld_start(), and uart_lld_stop().

Detailed Description

Driver State Machine

Transmitter sub State Machine

Receiver sub State Machine

UART status flags

UART error conditions

UART configuration options

Low level driver helper macros

PLATFORM configuration options

Data Structures

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ UART_NO_ERROR

◆ UART_PARITY_ERROR

◆ UART_FRAMING_ERROR

◆ UART_OVERRUN_ERROR

◆ UART_NOISE_ERROR

◆ UART_BREAK_DETECTED

◆ UART_ERR_NOT_ACTIVE

◆ UART_USE_WAIT

◆ UART_USE_MUTUAL_EXCLUSION

◆ _uart_wakeup_tx1_isr

◆ _uart_wakeup_tx2_isr

◆ _uart_wakeup_rx_complete_isr

◆ _uart_wakeup_rx_error_isr

◆ _uart_wakeup_rx_cm_isr

◆ _uart_wakeup_rx_timeout_isr

◆ _uart_tx1_isr_code

◆ _uart_tx2_isr_code

◆ _uart_rx_complete_isr_code

◆ _uart_rx_error_isr_code

◆ _uart_rx_idle_code

◆ _uart_timeout_isr_code

◆ _uart_rx_char_match_isr_code

◆ PLATFORM_UART_USE_UART1

Typedef Documentation

◆ uartflags_t

◆ UARTDriver

◆ uartcb_t

◆ uartccb_t

◆ uartecb_t

◆ UARTConfig

Enumeration Type Documentation

◆ uartstate_t

◆ uarttxstate_t

◆ uartrxstate_t

Function Documentation

◆ uartInit()

◆ uartObjectInit()

◆ uartStart()

◆ uartStop()

◆ uartStartSend()

◆ uartStartSendI()

◆ uartStopSend()

◆ uartStopSendI()

◆ uartStartReceive()

◆ uartStartReceiveI()

◆ uartStopReceive()

◆ uartStopReceiveI()

◆ uartSendTimeout()

◆ uartSendFullTimeout()

◆ uartReceiveTimeout()

◆ uartAcquireBus()

◆ uartReleaseBus()

◆ uart_lld_init()

◆ uart_lld_start()

◆ uart_lld_stop()

◆ uart_lld_start_send()

◆ uart_lld_stop_send()

◆ uart_lld_start_receive()

◆ uart_lld_stop_receive()

Variable Documentation

◆ UARTD1