UART Driver

Generic UART Driver. More...

Collaboration diagram for UART Driver:

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.

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

UART error conditions
#define	UART_ERR_NOT_ACTIVE   (size_t)-1

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

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

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

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

Data Structures
struct	UARTConfig
	Driver configuration structure. More...
struct	UARTDriver
	Structure representing an UART driver. More...

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

Enumerations

Variables
UARTDriver	UARTD1
	UART1 driver identifier. More...

Macro Definition Documentation

#define UART_NO_ERROR   0

No pending conditions.

Definition at line 38 of file hal_uart.h.

#define UART_PARITY_ERROR   4

Parity error happened.

Definition at line 39 of file hal_uart.h.

#define UART_FRAMING_ERROR   8

Framing error happened.

Definition at line 40 of file hal_uart.h.

#define UART_OVERRUN_ERROR   16

Overflow happened.

Definition at line 41 of file hal_uart.h.

#define UART_NOISE_ERROR   32

Noise on the line.

Definition at line 42 of file hal_uart.h.

#define UART_BREAK_DETECTED   64

Break detected.

Definition at line 43 of file hal_uart.h.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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

typedef uint32_t uartflags_t

UART driver condition flags type.

Definition at line 63 of file hal_uart_lld.h.

typedef struct UARTDriver UARTDriver

Type of structure representing an UART driver.

Definition at line 68 of file hal_uart_lld.h.

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.

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.

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.

Enumeration Type Documentation

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.

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.

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

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:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 56 of file hal_uart.c.

References uart_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void uartObjectInit

(

UARTDriver *

uartp

)

Initializes the standard part of a UARTDriver structure.

Parameters

[out]

uartp

pointer to the UARTDriver object

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 68 of file hal_uart.c.

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

Referenced by uart_lld_init().

Here is the call graph for this function:

void 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

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

Definition at line 97 of file hal_uart.c.

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

Here is the call graph for this function:

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 118 of file hal_uart.c.

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

Here is the call graph for this function:

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 147 of file hal_uart.c.

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

Here is the call graph for this function:

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 172 of file hal_uart.c.

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

Here is the call graph for this function:

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 195 of file hal_uart.c.

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

Here is the call graph for this function:

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 228 of file hal_uart.c.

References osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, UARTDriver::state, UARTDriver::txstate, 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:

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 253 of file hal_uart.c.

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

Here is the call graph for this function:

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 278 of file hal_uart.c.

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

Here is the call graph for this function:

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 301 of file hal_uart.c.

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

Here is the call graph for this function:

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 334 of file hal_uart.c.

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

Referenced by uartReceiveTimeout().

Here is the call graph for this function:

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 369 of file hal_uart.c.

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

Here is the call graph for this function:

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 414 of file hal_uart.c.

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

Here is the call graph for this function:

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 461 of file hal_uart.c.

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

Here is the call graph for this function:

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 498 of file hal_uart.c.

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

Here is the call graph for this function:

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 514 of file hal_uart.c.

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

Here is the call graph for this function:

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 uartObjectInit().

Referenced by uartInit().

Here is the call graph for this function:

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 UARTDriver::state, and UART_STOP.

Referenced by uartStart().

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 UARTDriver::state, and UART_READY.

Referenced by uartStop().

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().

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().

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().

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

UARTDriver UARTD1

UART1 driver identifier.

Definition at line 41 of file hal_uart_lld.c.