Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Serial USART (SERCOM USART) Driver

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:

The following peripheral is used by this module:

The following devices can use this module:

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.svg
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:

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:

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 usart_get_config_defaults(), and usart_init().

#define PINMUX_UNUSED   0xFFFFFFFF

Unused pinmux.

Referenced by 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.

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.

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.

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.

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.

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.

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.

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.

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]modulePointer to USART software instance struct
[in]transceiver_typeTransfer 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]modulePointer to USART software instance struct

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

Referenced by uart_close(), uart_config(), and 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]modulePointer to USART software instance struct
[in]callback_typeCallback type given by an enum

References Assert.

Referenced by usart_tx_callback().

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]modulePointer to USART software instance struct
[in]transceiver_typeTransceiver 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]modulePointer to USART software instance struct

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

Referenced by uart_config(), and uart_open().

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]modulePointer to USART software instance struct
[in]callback_typeCallback type given by an enum

References Assert.

Referenced by uart_config(), and uart_rx_notify().

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]modulePointer to USART software instance struct
[in]transceiver_typeTransceiver 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]configPointer 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 uart_config().

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]modulePointer to USART software instance struct
[in]transceiver_typeTransfer type to check
Returns
Status of the given job.
Return values
STATUS_OKNo error occurred during the last transfer
STATUS_BUSYA transfer is ongoing
STATUS_ERR_BAD_DATAThe last operation was aborted due to a parity error. The transfer could be affected by external noise
STATUS_ERR_BAD_FORMATThe last operation was aborted due to a frame error
STATUS_ERR_OVERFLOWThe last operation was aborted due to a buffer overflow
STATUS_ERR_INVALID_ARGAn 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]modulePointer to USART device
[in]hwPointer to USART hardware instance
[in]configPointer to configuration struct
Returns
Status of the initialization.
Return values
STATUS_OKThe initialization was successful
STATUS_BUSYThe USART module is busy resetting
STATUS_ERR_DENIEDThe USART has not been disabled in advance of initialization
STATUS_ERR_INVALID_ARGThe configuration struct contains invalid configuration
STATUS_ERR_ALREADY_INITIALIZEDThe SERCOM instance has already been initialized with different clock configuration
STATUS_ERR_BAUD_UNAVAILABLEThe 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 uart_config().

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]modulePointer to peripheral module
Returns
Peripheral sync status.
Return values
truePeripheral is busy syncing
falsePeripheral 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]modulePointer to the driver instance to lock
Return values
STATUS_OKIf the module was locked
STATUS_BUSYIf 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]modulePointer to USART software instance struct
[out]rx_dataPointer to data buffer to receive
[in]lengthData 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_OKIf operation was completed
STATUS_BUSYIf operation was not completed, due to the USART module being busy
STATUS_ERR_INVALID_ARGIf operation was not completed, due to invalid arguments
STATUS_ERR_DENIEDIf the transmitter is not enabled

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

Referenced by uart_config(), and usart_rx_callback().

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]modulePointer to USART software instance struct
[out]rx_dataPointer to receive buffer
[in]lengthNumber 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_OKIf operation was completed
STATUS_ERR_INVALID_ARGIf operation was not completed, due to an invalid argument being supplied
STATUS_ERR_TIMEOUTIf operation was not completed, due to USART module timing out
STATUS_ERR_BAD_FORMATIf the operation was not completed, due to a configuration mismatch between USART and the sender
STATUS_ERR_BAD_OVERFLOWIf the operation was not completed, due to the baudrate being too low or the system frequency being too high
STATUS_ERR_BAD_DATAIf the operation was not completed, due to data being corrupted
STATUS_ERR_DENIEDIf 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.

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]modulePointer to USART software instance struct
[out]rx_dataPointer to where received data should be put
Returns
Status of the operation.
Return values
STATUS_OKIf operation was completed
STATUS_BUSYIf 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]modulePointer to the software instance struct
[out]rx_dataPointer to received data
Returns
Status of the operation.
Return values
STATUS_OKIf the operation was completed
STATUS_BUSYIf the operation was not completed, due to the USART module being busy
STATUS_ERR_BAD_FORMATIf the operation was not completed, due to configuration mismatch between USART and the sender
STATUS_ERR_BAD_OVERFLOWIf the operation was not completed, due to the baudrate being too low or the system frequency being too high
STATUS_ERR_BAD_DATAIf the operation was not completed, due to data being corrupted
STATUS_ERR_DENIEDIf 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().

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]modulePointer to USART software instance struct
[in]callback_funcPointer to callback function
[in]callback_typeCallback type given by an enum

References Assert.

Referenced by uart_config().

static void usart_reset ( const struct usart_module *const  module)
inlinestatic

Resets the USART module.

Disables and resets the USART module.

Parameters
[in]modulePointer 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]modulePointer 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]modulePointer to USART software instance struct
[in]callback_typeCallback 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]modulePointer to USART software instance struct
[in]tx_dataPointer do data buffer to transmit
[in]lengthLength 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_OKIf operation was completed successfully.
STATUS_BUSYIf operation was not completed, due to the USART module being busy
STATUS_ERR_INVALID_ARGIf operation was not completed, due to invalid arguments
STATUS_ERR_DENIEDIf the transmitter is not enabled

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

Referenced by uart_rx_notify(), and usart_tx_callback().

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]modulePointer to USART software instance struct
[in]tx_dataPointer to data to transmit
[in]lengthNumber 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_OKIf operation was completed
STATUS_ERR_INVALID_ARGIf operation was not completed, due to invalid arguments
STATUS_ERR_TIMEOUTIf operation was not completed, due to USART module timing out
STATUS_ERR_DENIEDIf 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().

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]modulePointer to USART software instance struct
[in]tx_dataData to transfer
Returns
Status of the operation.
Return values
STATUS_OKIf operation was completed
STATUS_BUSYIf operation was not completed, due to the USART module being busy
STATUS_ERR_DENIEDIf 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]modulePointer to the software instance struct
[in]tx_dataData to transfer
Returns
Status of the operation.
Return values
STATUS_OKIf the operation was completed
STATUS_BUSYIf the operation was not completed, due to the USART module being busy
STATUS_ERR_DENIEDIf the transmitter is not enabled

References Assert, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_OK, and tx_data.

Referenced by usart_write_buffer_wait().