This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the SERCOM module in its USART mode to transfer or receive USART data frames.

The following driver API modes are covered by this manual:

Polled APIs
Callback APIs

The following peripheral is used by this module:

SERCOM (Serial Communication Interface)

The following devices can use this module:

Atmel | SMART SAM D20/D21
Atmel | SMART SAM R21
Atmel | SMART SAM D09/D10/D11
Atmel | SMART SAM D10/D11
Atmel | SMART SAM L21/L22
Atmel | SMART SAM DA1
Atmel | SMART SAM C20/C21
Atmel | SMART SAM HA1
Atmel | SMART SAM R30
Atmel | SMART SAM R34
Atmel | SMART SAM R35

The outline of this documentation is as follows:

Prerequisites

To use the USART you need to have a GCLK generator enabled and running that can be used as the SERCOM clock source. This can either be configured in conf_clocks.h or by using the system clock driver.

Module Overview

This driver will use one (or more) SERCOM interface(s) in the system and configure it to run as a USART interface in either synchronous or asynchronous mode.

Driver Feature Macro Definition

Driver Feature Macro	Supported devices
FEATURE_USART_SYNC_SCHEME_V2	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_OVER_SAMPLE	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_HARDWARE_FLOW_CONTROL	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_IRDA	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_LIN_SLAVE	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_COLLISION_DECTION	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_START_FRAME_DECTION	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_IMMEDIATE_BUFFER_OVERFLOW_NOTIFICATION	SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_RS485	SAM C20/C21
FEATURE_USART_LIN_MASTER	SAM L22/C20/C21

Note: The specific features are only available in the driver when the selected device supports those features.

Frame Format

Communication is based on frames, where the frame format can be customized to accommodate a wide range of standards. A frame consists of a start bit, a number of data bits, an optional parity bit for error detection as well as a configurable length stop bit(s) - see the figure below. The table below shows the available parameters you can change in a frame.

USART Frame Parameters
Parameter	Options
Start bit	1
Data bits	5, 6, 7, 8, 9
Parity bit	None, Even, Odd
Stop bits	1, 2

USART Frame Overview

Synchronous Mode

In synchronous mode a dedicated clock line is provided; either by the USART itself if in master mode, or by an external master if in slave mode. Maximum transmission speed is the same as the GCLK clocking the USART peripheral when in slave mode, and the GCLK divided by two if in master mode. In synchronous mode the interface needs three lines to communicate:

TX (Transmit pin)
RX (Receive pin)
XCK (Clock pin)

Data Sampling

In synchronous mode the data is sampled on either the rising or falling edge of the clock signal. This is configured by setting the clock polarity in the configuration struct.

Asynchronous Mode

In asynchronous mode no dedicated clock line is used, and the communication is based on matching the clock speed on the transmitter and receiver. The clock is generated from the internal SERCOM baudrate generator, and the frames are synchronized by using the frame start bits. Maximum transmission speed is limited to the SERCOM GCLK divided by 16. In asynchronous mode the interface only needs two lines to communicate:

TX (Transmit pin)
RX (Receive pin)

Transmitter/receiver Clock Matching

For successful transmit and receive using the asynchronous mode the receiver and transmitter clocks needs to be closely matched. When receiving a frame that does not match the selected baudrate closely enough the receiver will be unable to synchronize the frame(s), and garbage transmissions will result.

Parity

Parity can be enabled to detect if a transmission was in error. This is done by counting the number of "1" bits in the frame. When using even parity the parity bit will be set if the total number of "1"s in the frame are an even number. If using odd parity the parity bit will be set if the total number of "1"s are odd.

When receiving a character the receiver will count the number of "1"s in the frame and give an error if the received frame and parity bit disagree.

GPIO Configuration

The SERCOM module has four internal pads; the RX pin can be placed freely on any one of the four pads, and the TX and XCK pins have two predefined positions that can be selected as a pair. The pads can then be routed to an external GPIO pin using the normal pin multiplexing scheme on the SAM.

Special Considerations

Never execute large portions of code in the callbacks. These are run from the interrupt routine, and thus having long callbacks will keep the processor in the interrupt handler for an equally long time. A common way to handle this is to use global flags signaling the main application that an interrupt event has happened, and only do the minimal needed processing in the callback.

Extra Information

For extra information, see Extra Information for SERCOM USART Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for SERCOM USART Driver.

API Overview

Data Structures
struct	usart_config
	USART configuration struct. More...

struct	usart_module
	SERCOM USART driver software device instance structure. More...

Macros
#define	PINMUX_DEFAULT 0
	Default pinmux. More...

#define	PINMUX_UNUSED 0xFFFFFFFF
	Unused pinmux. More...

#define	USART_TIMEOUT 0xFFFF
	USART timeout value. More...

Typedefs
typedef void(*	usart_callback_t )(struct usart_module *const module)
	USART callback type. More...

Enumerations
enum	usart_callback { USART_CALLBACK_BUFFER_TRANSMITTED, USART_CALLBACK_BUFFER_RECEIVED, USART_CALLBACK_ERROR }
	USART callback enum. More...

enum	usart_character_size { USART_CHARACTER_SIZE_5BIT = SERCOM_USART_CTRLB_CHSIZE(5), USART_CHARACTER_SIZE_6BIT = SERCOM_USART_CTRLB_CHSIZE(6), USART_CHARACTER_SIZE_7BIT = SERCOM_USART_CTRLB_CHSIZE(7), USART_CHARACTER_SIZE_8BIT = SERCOM_USART_CTRLB_CHSIZE(0), USART_CHARACTER_SIZE_9BIT = SERCOM_USART_CTRLB_CHSIZE(1) }
	USART Character Size. More...

enum	usart_dataorder { USART_DATAORDER_MSB = 0, USART_DATAORDER_LSB = SERCOM_USART_CTRLA_DORD }
	USART Data Order enum. More...

enum	usart_parity { USART_PARITY_ODD = SERCOM_USART_CTRLB_PMODE, USART_PARITY_EVEN = 0, USART_PARITY_NONE = 0xFF }
	USART Parity enum. More...

enum	usart_signal_mux_settings { USART_RX_0_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(0)), USART_RX_0_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(0) \| SERCOM_USART_CTRLA_TXPO), USART_RX_1_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(1)), USART_RX_1_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(1) \| SERCOM_USART_CTRLA_TXPO), USART_RX_2_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(2)), USART_RX_2_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(2) \| SERCOM_USART_CTRLA_TXPO), USART_RX_3_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(3)), USART_RX_3_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(3) \| SERCOM_USART_CTRLA_TXPO) }
	USART signal MUX settings. More...

enum	usart_stopbits { USART_STOPBITS_1 = 0, USART_STOPBITS_2 = SERCOM_USART_CTRLB_SBMODE }
	USART Stop Bits enum. More...

enum	usart_transceiver_type { USART_TRANSCEIVER_RX, USART_TRANSCEIVER_TX }
	USART Transceiver. More...

enum	usart_transfer_mode { USART_TRANSFER_SYNCHRONOUSLY = (SERCOM_USART_CTRLA_CMODE), USART_TRANSFER_ASYNCHRONOUSLY = (0x0ul << SERCOM_USART_CTRLA_CMODE_Pos) }
	USART Transfer mode enum. More...

Functions
static void	usart_disable (const struct usart_module *const module)
	Disable module. More...

static void	usart_enable (const struct usart_module *const module)
	Enable the module. More...

static void	usart_get_config_defaults (struct usart_config *const config)
	Initializes the device to predefined defaults. More...

enum status_code	usart_init (struct usart_module const module, Sercom const hw, const struct usart_config *const config)
	Initializes the device. More...

static bool	usart_is_syncing (const struct usart_module *const module)
	Check if peripheral is busy syncing registers across clock domains. More...

static void	usart_reset (const struct usart_module *const module)
	Resets the USART module. More...

Lock/Unlock
static enum status_code	usart_lock (struct usart_module *const module)
	Attempt to get lock on driver instance. More...

static void	usart_unlock (struct usart_module *const module)
	Unlock driver instance. More...

Writing and Reading
enum status_code	usart_write_wait (struct usart_module *const module, const uint16_t tx_data)
	Transmit a character via the USART. More...

enum status_code	usart_read_wait (struct usart_module const module, uint16_t const rx_data)
	Receive a character via the USART. More...

enum status_code	usart_write_buffer_wait (struct usart_module const module, const uint8_t tx_data, uint16_t length)
	Transmit a buffer of characters via the USART. More...

enum status_code	usart_read_buffer_wait (struct usart_module const module, uint8_t rx_data, uint16_t length)
	Receive a buffer of `length` characters via the USART. More...

Enabling/Disabling Receiver and Transmitter
static void	usart_enable_transceiver (struct usart_module *const module, enum usart_transceiver_type transceiver_type)
	Enable Transceiver. More...

static void	usart_disable_transceiver (struct usart_module *const module, enum usart_transceiver_type transceiver_type)
	Disable Transceiver. More...

Callback Management
void	usart_register_callback (struct usart_module *const module, usart_callback_t callback_func, enum usart_callback callback_type)
	Registers a callback. More...

void	usart_unregister_callback (struct usart_module *module, enum usart_callback callback_type)
	Unregisters a callback. More...

static void	usart_enable_callback (struct usart_module *const module, enum usart_callback callback_type)
	Enables callback. More...

static void	usart_disable_callback (struct usart_module *const module, enum usart_callback callback_type)
	Disable callback. More...

Writing and Reading
enum status_code	usart_write_job (struct usart_module const module, const uint16_t tx_data)
	Asynchronous write a single char. More...

enum status_code	usart_read_job (struct usart_module const module, uint16_t const rx_data)
	Asynchronous read a single char. More...

enum status_code	usart_write_buffer_job (struct usart_module const module, uint8_t tx_data, uint16_t length)
	Asynchronous buffer write. More...

enum status_code	usart_read_buffer_job (struct usart_module const module, uint8_t rx_data, uint16_t length)
	Asynchronous buffer read. More...

void	usart_abort_job (struct usart_module *const module, enum usart_transceiver_type transceiver_type)
	Cancels ongoing read/write operation. More...

enum status_code	usart_get_job_status (struct usart_module *const module, enum usart_transceiver_type transceiver_type)
	Get status from the ongoing or last asynchronous transfer operation. More...

#define PINMUX_DEFAULT 0

Default pinmux.

Referenced by _spi_set_config(), usart_get_config_defaults(), and usart_init().

#define PINMUX_UNUSED 0xFFFFFFFF

Unused pinmux.

Referenced by _spi_set_config(), and usart_init().

#define USART_TIMEOUT 0xFFFF

USART timeout value.

Referenced by usart_read_buffer_wait(), and usart_write_buffer_wait().

typedef void(* usart_callback_t)(struct usart_module *const module)

USART callback type.

Type of the callback functions.

enum usart_callback

USART callback enum.

Callbacks for the Asynchronous USART driver.

Enumerator
USART_CALLBACK_BUFFER_TRANSMITTED	Callback for buffer transmitted.
USART_CALLBACK_BUFFER_RECEIVED	Callback for buffer received.
USART_CALLBACK_ERROR	Callback for error.

enum usart_character_size

USART Character Size.

Number of bits for the character sent in a frame.

Enumerator
USART_CHARACTER_SIZE_5BIT	The char being sent in a frame is five bits long.
USART_CHARACTER_SIZE_6BIT	The char being sent in a frame is six bits long.
USART_CHARACTER_SIZE_7BIT	The char being sent in a frame is seven bits long.
USART_CHARACTER_SIZE_8BIT	The char being sent in a frame is eight bits long.
USART_CHARACTER_SIZE_9BIT	The char being sent in a frame is nine bits long.

enum usart_dataorder

USART Data Order enum.

The data order decides which MSB or LSB is shifted out first when data is transferred.

Enumerator
USART_DATAORDER_MSB	The MSB will be shifted out first during transmission, and shifted in first during reception.
USART_DATAORDER_LSB	The LSB will be shifted out first during transmission, and shifted in first during reception.

enum usart_parity

USART Parity enum.

Select parity USART parity mode.

Enumerator
USART_PARITY_ODD	For odd parity checking, the parity bit will be set if number of ones being transferred is even.
USART_PARITY_EVEN	For even parity checking, the parity bit will be set if number of ones being received is odd.
USART_PARITY_NONE	No parity checking will be executed, and there will be no parity bit in the received frame.

enum usart_signal_mux_settings

USART signal MUX settings.

Set the functionality of the SERCOM pins.

See SERCOM USART MUX Settings for a description of the various MUX setting options.

Enumerator
USART_RX_0_TX_0_XCK_1	MUX setting RX_0_TX_0_XCK_1.
USART_RX_0_TX_2_XCK_3	MUX setting RX_0_TX_2_XCK_3.
USART_RX_1_TX_0_XCK_1	MUX setting RX_1_TX_0_XCK_1.
USART_RX_1_TX_2_XCK_3	MUX setting RX_1_TX_2_XCK_3.
USART_RX_2_TX_0_XCK_1	MUX setting RX_2_TX_0_XCK_1.
USART_RX_2_TX_2_XCK_3	MUX setting RX_2_TX_2_XCK_3.
USART_RX_3_TX_0_XCK_1	MUX setting RX_3_TX_0_XCK_1.
USART_RX_3_TX_2_XCK_3	MUX setting RX_3_TX_2_XCK_3.

enum usart_stopbits

USART Stop Bits enum.

Number of stop bits for a frame.

Enumerator
USART_STOPBITS_1	Each transferred frame contains one stop bit.
USART_STOPBITS_2	Each transferred frame contains two stop bits.

enum usart_transceiver_type

USART Transceiver.

Select Receiver or Transmitter.

Enumerator
USART_TRANSCEIVER_RX	The parameter is for the Receiver.
USART_TRANSCEIVER_TX	The parameter is for the Transmitter.

enum usart_transfer_mode

USART Transfer mode enum.

Select USART transfer mode.

Enumerator
USART_TRANSFER_SYNCHRONOUSLY	Transfer of data is done synchronously.
USART_TRANSFER_ASYNCHRONOUSLY	Transfer of data is done asynchronously.

void usart_abort_job	(	struct usart_module *const	module,
		enum usart_transceiver_type	transceiver_type
	)

Cancels ongoing read/write operation.

Cancels the ongoing read/write operation modifying parameters in the USART software struct.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	transceiver_type	Transfer type to cancel

References Assert, USART_TRANSCEIVER_RX, and USART_TRANSCEIVER_TX.

static void usart_disable ( const struct usart_module *const module )

inlinestatic

Disable module.

Disables the USART module.

Parameters

[in] module Pointer to USART software instance struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_disable().

Referenced by usart_reset().

static void usart_disable_callback	(	struct usart_module *const	module,
		enum usart_callback	callback_type
	)

inlinestatic

Disable callback.

Disables the callback function registered by the usart_register_callback, and the callback will not be called from the interrupt routine.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	callback_type	Callback type given by an enum

References Assert.

static void usart_disable_transceiver	(	struct usart_module *const	module,
		enum usart_transceiver_type	transceiver_type
	)

inlinestatic

Disable Transceiver.

Disable the given transceiver (RX or TX).

Parameters

[in]	module	Pointer to USART software instance struct
[in]	transceiver_type	Transceiver type

References Assert, USART_TRANSCEIVER_RX, and USART_TRANSCEIVER_TX.

static void usart_enable ( const struct usart_module *const module )

inlinestatic

Enable the module.

Enables the USART module.

Parameters

[in] module Pointer to USART software instance struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_enable().

Referenced by cdc_uart_init().

static void usart_enable_callback	(	struct usart_module *const	module,
		enum usart_callback	callback_type
	)

inlinestatic

Enables callback.

Enables the callback function registered by the usart_register_callback. The callback function will be called from the interrupt handler when the conditions for the callback type are met.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	callback_type	Callback type given by an enum

References Assert.

static void usart_enable_transceiver	(	struct usart_module *const	module,
		enum usart_transceiver_type	transceiver_type
	)

inlinestatic

Enable Transceiver.

Enable the given transceiver. Either RX or TX.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	transceiver_type	Transceiver type

References Assert, USART_TRANSCEIVER_RX, and USART_TRANSCEIVER_TX.

static void usart_get_config_defaults ( struct usart_config *const config )

inlinestatic

Initializes the device to predefined defaults.

Initialize the USART device to predefined defaults:

8-bit asynchronous USART
No parity
One stop bit
9600 baud
Transmitter enabled
Receiver enabled
GCLK generator 0 as clock source
Default pin configuration

The configuration struct will be updated with the default configuration.

Parameters

[in,out] config Pointer to configuration struct

References Assert, usart_config::baudrate, usart_config::character_size, usart_config::clock_polarity_inverted, usart_config::data_order, usart_config::ext_clock_freq, GCLK_GENERATOR_0, usart_config::generator_source, usart_config::mux_setting, usart_config::parity, PINMUX_DEFAULT, usart_config::pinmux_pad0, usart_config::pinmux_pad1, usart_config::pinmux_pad2, usart_config::pinmux_pad3, usart_config::receiver_enable, usart_config::run_in_standby, usart_config::stopbits, usart_config::transfer_mode, usart_config::transmitter_enable, USART_CHARACTER_SIZE_8BIT, USART_DATAORDER_LSB, USART_PARITY_NONE, USART_RX_1_TX_2_XCK_3, USART_STOPBITS_1, USART_TRANSFER_ASYNCHRONOUSLY, and usart_config::use_external_clock.

Referenced by cdc_uart_init().

enum status_code usart_get_job_status	(	struct usart_module *const	module,
		enum usart_transceiver_type	transceiver_type
	)

Get status from the ongoing or last asynchronous transfer operation.

Returns the error from a given ongoing or last asynchronous transfer operation. Either from a read or write transfer.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	transceiver_type	Transfer type to check

Returns: Status of the given job.

Return values

STATUS_OK	No error occurred during the last transfer
STATUS_BUSY	A transfer is ongoing
STATUS_ERR_BAD_DATA	The last operation was aborted due to a parity error. The transfer could be affected by external noise
STATUS_ERR_BAD_FORMAT	The last operation was aborted due to a frame error
STATUS_ERR_OVERFLOW	The last operation was aborted due to a buffer overflow
STATUS_ERR_INVALID_ARG	An invalid transceiver enum given

References Assert, STATUS_ERR_INVALID_ARG, USART_TRANSCEIVER_RX, and USART_TRANSCEIVER_TX.

enum status_code usart_init	(	struct usart_module *const	module,
		Sercom *const	hw,
		const struct usart_config *const	config
	)

Initializes the device.

Initializes the USART device based on the setting specified in the configuration struct.

Parameters

[out]	module	Pointer to USART device
[in]	hw	Pointer to USART hardware instance
[in]	config	Pointer to configuration struct

Returns: Status of the initialization.

Return values

STATUS_OK	The initialization was successful
STATUS_BUSY	The USART module is busy resetting
STATUS_ERR_DENIED	The USART has not been disabled in advance of initialization
STATUS_ERR_INVALID_ARG	The configuration struct contains invalid configuration
STATUS_ERR_ALREADY_INITIALIZED	The SERCOM instance has already been initialized with different clock configuration
STATUS_ERR_BAUD_UNAVAILABLE	The BAUD rate given by the configuration struct cannot be reached with the current clock configuration

References _sercom_get_default_pad(), _sercom_get_sercom_inst_index(), _sercom_instances, _sercom_set_handler(), _usart_interrupt_handler(), _usart_set_config(), Assert, usart_config::character_size, system_pinmux_config::direction, usart_config::generator_source, system_pinmux_config::input_pull, system_pinmux_config::mux_position, PINMUX_DEFAULT, usart_config::pinmux_pad0, usart_config::pinmux_pad1, usart_config::pinmux_pad2, usart_config::pinmux_pad3, PINMUX_UNUSED, usart_config::receiver_enable, sercom_set_gclk_generator(), system_gclk_chan_config::source_generator, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), system_gclk_chan_set_config(), system_pinmux_get_config_defaults(), SYSTEM_PINMUX_PIN_DIR_INPUT, SYSTEM_PINMUX_PIN_PULL_NONE, system_pinmux_pin_set_config(), and usart_config::transmitter_enable.

Referenced by usart_serial_init().

static bool usart_is_syncing ( const struct usart_module *const module )

inlinestatic

Check if peripheral is busy syncing registers across clock domains.

Return peripheral synchronization status. If doing a non-blocking implementation this function can be used to check the sync state and hold of any new actions until sync is complete. If this function is not run; the functions will block until the sync has completed.

Parameters

[in] module Pointer to peripheral module

Returns: Peripheral sync status.

Return values

true	Peripheral is busy syncing
false	Peripheral is not busy syncing and can be read/written without stalling the bus

References Assert.

static enum status_code usart_lock ( struct usart_module *const module )

inlinestatic

Attempt to get lock on driver instance.

This function checks the instance's lock, which indicates whether or not it is currently in use, and sets the lock if it was not already set.

The purpose of this is to enable exclusive access to driver instances, so that, e.g., transactions by different services will not interfere with each other.

Parameters

[in,out] module Pointer to the driver instance to lock

Return values

STATUS_OK	If the module was locked
STATUS_BUSY	If the module was already locked

References STATUS_BUSY, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

enum status_code usart_read_buffer_job	(	struct usart_module *const	module,
		uint8_t *	rx_data,
		uint16_t	length
	)

Asynchronous buffer read.

Sets up the driver to read from the USART to a given buffer. If registered and enabled, a callback function will be called.

Parameters

[in]	module	Pointer to USART software instance struct
[out]	rx_data	Pointer to data buffer to receive
[in]	length	Data buffer length

Note: If using 9-bit data, the array that rx_data point to should be defined as uint16_t array and should be casted to uint8_t pointer. Because it is an address pointer, the highest byte is not discarded. For example:
#define RX_LEN 3

uint16_t rx_buf[RX_LEN] = {0x0,};

usart_read_buffer_job(&module, (uint8_t*)rx_buf, RX_LEN);

Returns: Status of the operation.

Return values

STATUS_OK	If operation was completed
STATUS_BUSY	If operation was not completed, due to the USART module being busy
STATUS_ERR_INVALID_ARG	If operation was not completed, due to invalid arguments
STATUS_ERR_DENIED	If the transmitter is not enabled

References _usart_read_buffer(), Assert, STATUS_ERR_DENIED, and STATUS_ERR_INVALID_ARG.

enum status_code usart_read_buffer_wait	(	struct usart_module *const	module,
		uint8_t *	rx_data,
		uint16_t	length
	)

Receive a buffer of length characters via the USART.

This blocking function will receive a block of length characters via the USART.

Note: Using this function in combination with the interrupt (*_job) functions is not recommended as it has no functionality to check if there is an ongoing interrupt driven operation running or not.

Parameters

[in]	module	Pointer to USART software instance struct
[out]	rx_data	Pointer to receive buffer
[in]	length	Number of characters to receive

Note: If using 9-bit data, the array that rx_data point to should be defined as uint16_t array and should be casted to uint8_t pointer. Because it is an address pointer, the highest byte is not discarded. For example:
#define RX_LEN 3

uint16_t rx_buf[RX_LEN] = {0x0,};

usart_read_buffer_wait(&module, (uint8_t*)rx_buf, RX_LEN);

Returns: Status of the operation.

Return values

STATUS_OK	If operation was completed
STATUS_ERR_INVALID_ARG	If operation was not completed, due to an invalid argument being supplied
STATUS_ERR_TIMEOUT	If operation was not completed, due to USART module timing out
STATUS_ERR_BAD_FORMAT	If the operation was not completed, due to a configuration mismatch between USART and the sender
STATUS_ERR_BAD_OVERFLOW	If the operation was not completed, due to the baudrate being too low or the system frequency being too high
STATUS_ERR_BAD_DATA	If the operation was not completed, due to data being corrupted
STATUS_ERR_DENIED	If the receiver is not enabled

References Assert, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, STATUS_OK, USART_CHARACTER_SIZE_9BIT, usart_read_wait(), and USART_TIMEOUT.

Referenced by usart_serial_read_packet().

enum status_code usart_read_job	(	struct usart_module *const	module,
		uint16_t *const	rx_data
	)

Asynchronous read a single char.

Sets up the driver to read data from the USART module to the data pointer given. If registered and enabled, a callback will be called when the receiving is completed.

Parameters

[in]	module	Pointer to USART software instance struct
[out]	rx_data	Pointer to where received data should be put

Returns: Status of the operation.

Return values

STATUS_OK	If operation was completed
STATUS_BUSY	If operation was not completed

References _usart_read_buffer(), and Assert.

enum status_code usart_read_wait	(	struct usart_module *const	module,
		uint16_t *const	rx_data
	)

Receive a character via the USART.

This blocking function will receive a character via the USART.

Parameters

[in]	module	Pointer to the software instance struct
[out]	rx_data	Pointer to received data

Returns: Status of the operation.

Return values

STATUS_OK	If the operation was completed
STATUS_BUSY	If the operation was not completed, due to the USART module being busy
STATUS_ERR_BAD_FORMAT	If the operation was not completed, due to configuration mismatch between USART and the sender
STATUS_ERR_BAD_OVERFLOW	If the operation was not completed, due to the baudrate being too low or the system frequency being too high
STATUS_ERR_BAD_DATA	If the operation was not completed, due to data being corrupted
STATUS_ERR_DENIED	If the receiver is not enabled

References Assert, STATUS_BUSY, STATUS_ERR_BAD_DATA, STATUS_ERR_BAD_FORMAT, STATUS_ERR_DENIED, STATUS_ERR_OVERFLOW, STATUS_ERR_PACKET_COLLISION, STATUS_ERR_PROTOCOL, and STATUS_OK.

Referenced by usart_read_buffer_wait(), and usart_serial_getchar().

void usart_register_callback	(	struct usart_module *const	module,
		usart_callback_t	callback_func,
		enum usart_callback	callback_type
	)

Registers a callback.

Registers a callback function, which is implemented by the user.

Note: The callback must be enabled by usart_enable_callback in order for the interrupt handler to call it when the conditions for the callback type are met.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	callback_func	Pointer to callback function
[in]	callback_type	Callback type given by an enum

References Assert.

static void usart_reset ( const struct usart_module *const module )

inlinestatic

Resets the USART module.

Disables and resets the USART module.

Parameters

[in] module Pointer to the USART software instance struct

References Assert, and usart_disable().

static void usart_unlock ( struct usart_module *const module )

inlinestatic

Unlock driver instance.

This function clears the instance lock, indicating that it is available for use.

Parameters

[in,out] module Pointer to the driver instance to lock

void usart_unregister_callback	(	struct usart_module *const	module,
		enum usart_callback	callback_type
	)

Unregisters a callback.

Unregisters a callback function, which is implemented by the user.

Parameters

[in,out]	module	Pointer to USART software instance struct
[in]	callback_type	Callback type given by an enum

References Assert.

enum status_code usart_write_buffer_job	(	struct usart_module *const	module,
		uint8_t *	tx_data,
		uint16_t	length
	)

Asynchronous buffer write.

Sets up the driver to write a given buffer over the USART. If registered and enabled, a callback function will be called.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	tx_data	Pointer do data buffer to transmit
[in]	length	Length of the data to transmit

Note: If using 9-bit data, the array that tx_data point to should be defined as uint16_t array and should be casted to uint8_t pointer. Because it is an address pointer, the highest byte is not discarded. For example:
#define TX_LEN 3

uint16_t tx_buf[TX_LEN] = {0x0111, 0x0022, 0x0133};

usart_write_buffer_job(&module, (uint8_t*)tx_buf, TX_LEN);

Returns: Status of the operation.

Return values

STATUS_OK	If operation was completed successfully.
STATUS_BUSY	If operation was not completed, due to the USART module being busy
STATUS_ERR_INVALID_ARG	If operation was not completed, due to invalid arguments
STATUS_ERR_DENIED	If the transmitter is not enabled

References _usart_write_buffer(), Assert, STATUS_ERR_DENIED, and STATUS_ERR_INVALID_ARG.

enum status_code usart_write_buffer_wait	(	struct usart_module *const	module,
		const uint8_t *	tx_data,
		uint16_t	length
	)

Transmit a buffer of characters via the USART.

This blocking function will transmit a block of length characters via the USART.

Note: Using this function in combination with the interrupt (_job) functions is not recommended as it has no functionality to check if there is an ongoing interrupt driven operation running or not.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	tx_data	Pointer to data to transmit
[in]	length	Number of characters to transmit

Note: If using 9-bit data, the array that tx_data point to should be defined as uint16_t array and should be casted to uint8_t pointer. Because it is an address pointer, the highest byte is not discarded. For example:
#define TX_LEN 3

uint16_t tx_buf[TX_LEN] = {0x0111, 0x0022, 0x0133};

usart_write_buffer_wait(&module, (uint8_t*)tx_buf, TX_LEN);

Returns: Status of the operation.

Return values

STATUS_OK	If operation was completed
STATUS_ERR_INVALID_ARG	If operation was not completed, due to invalid arguments
STATUS_ERR_TIMEOUT	If operation was not completed, due to USART module timing out
STATUS_ERR_DENIED	If the transmitter is not enabled

References Assert, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, STATUS_OK, USART_CHARACTER_SIZE_9BIT, USART_TIMEOUT, and usart_write_wait().

Referenced by usart_serial_write_packet().

enum status_code usart_write_job	(	struct usart_module *const	module,
		const uint16_t *	tx_data
	)

Asynchronous write a single char.

Sets up the driver to write the data given. If registered and enabled, a callback function will be called when the transmit is completed.

Parameters

[in]	module	Pointer to USART software instance struct
[in]	tx_data	Data to transfer

Returns: Status of the operation.

Return values

STATUS_OK	If operation was completed
STATUS_BUSY	If operation was not completed, due to the USART module being busy
STATUS_ERR_DENIED	If the transmitter is not enabled

References _usart_write_buffer(), Assert, and STATUS_ERR_DENIED.

enum status_code usart_write_wait	(	struct usart_module *const	module,
		const uint16_t	tx_data
	)

Transmit a character via the USART.

This blocking function will transmit a single character via the USART.

Parameters

[in]	module	Pointer to the software instance struct
[in]	tx_data	Data to transfer

Returns: Status of the operation.

Return values

STATUS_OK	If the operation was completed
STATUS_BUSY	If the operation was not completed, due to the USART module being busy
STATUS_ERR_DENIED	If the transmitter is not enabled

References Assert, STATUS_BUSY, STATUS_ERR_DENIED, and STATUS_OK.

Referenced by usart_serial_putchar(), and usart_write_buffer_wait().

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Driver Feature Macro Definition

Frame Format

Synchronous Mode

Data Sampling

Asynchronous Mode

Transmitter/receiver Clock Matching

Parity

GPIO Configuration

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Macros

Typedefs

Enumerations

Functions

Lock/Unlock

Writing and Reading

Enabling/Disabling Receiver and Transmitter

Callback Management

Writing and Reading