Driver for the USART (Universal Synchronous Asynchronous Receiver Transmitter).

The driver supports the following modes: RS232, RS485, SPI, LIN and ISO7816.

Data Structures
struct	usart_iso7816_options_t
	Input parameters when initializing ISO7816 mode. More...

struct	usart_options_t
	Input parameters when initializing RS232 and similar modes. More...

Macros
#define	USART_DEFAULT_TIMEOUT 10000
	Default time-out value (number of attempts). More...

Return Values
#define	USART_SUCCESS 0
	Successful completion. More...

#define	USART_FAILURE -1
	Failure because of some unspecified reason. More...

#define	USART_INVALID_INPUT 1
	Input value out of range. More...

#define	USART_INVALID_ARGUMENT -1
	Argument value out of range. More...

#define	USART_TX_BUSY 2
	Transmitter was busy. More...

#define	USART_RX_EMPTY 3
	Nothing was received. More...

#define	USART_RX_ERROR 4
	Transmission error occurred. More...

#define	USART_MODE_FAULT 5
	USART not in the appropriate mode. More...

Parity Settings
#define	USART_EVEN_PARITY AVR32_USART_MR_PAR_EVEN
	Use even parity on character transmission. More...

#define	USART_ODD_PARITY AVR32_USART_MR_PAR_ODD
	Use odd parity on character transmission. More...

#define	USART_SPACE_PARITY AVR32_USART_MR_PAR_SPACE
	Use a space as parity bit. More...

#define	USART_MARK_PARITY AVR32_USART_MR_PAR_MARK
	Use a mark as parity bit. More...

#define	USART_NO_PARITY AVR32_USART_MR_PAR_NONE
	Don't use a parity bit. More...

#define	USART_MULTIDROP_PARITY AVR32_USART_MR_PAR_MULTI
	Parity bit is used to flag address characters. More...

Stop Bits Settings
#define	USART_1_STOPBIT AVR32_USART_MR_NBSTOP_1
	Use 1 stop bit. More...

#define	USART_1_5_STOPBITS AVR32_USART_MR_NBSTOP_1_5
	Use 1.5 stop bits. More...

#define	USART_2_STOPBITS AVR32_USART_MR_NBSTOP_2
	Use 2 stop bits (for more, just give the number of bits). More...

Channel Modes
#define	USART_NORMAL_CHMODE AVR32_USART_MR_CHMODE_NORMAL
	Normal communication. More...

#define	USART_AUTO_ECHO AVR32_USART_MR_CHMODE_ECHO
	Echo data. More...

#define	USART_LOCAL_LOOPBACK AVR32_USART_MR_CHMODE_LOCAL_LOOP
	Local loopback. More...

#define	USART_REMOTE_LOOPBACK AVR32_USART_MR_CHMODE_REMOTE_LOOP
	Remote loopback. More...

Initialization Functions
void	usart_reset (volatile avr32_usart_t *usart)
	Resets the USART and disables TX and RX. More...

int	usart_init_rs232 (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use the standard RS232 protocol. More...

int	usart_init_rs232_tx_only (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use the standard RS232 protocol in TX-only mode. More...

int	usart_init_hw_handshaking (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use hardware handshaking. More...

int	usart_init_modem (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use the modem protocol, activating dedicated inputs/outputs. More...

int	usart_init_sync_master (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use a synchronous RS232-like protocol in master mode. More...

int	usart_init_sync_slave (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use a synchronous RS232-like protocol in slave mode. More...

int	usart_init_rs485 (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz)
	Sets up the USART to use the RS485 protocol. More...

int	usart_init_IrDA (volatile avr32_usart_t usart, const usart_options_t opt, long pba_hz, unsigned char irda_filter)
	Sets up the USART to use the IrDA protocol. More...

int	usart_init_iso7816 (volatile avr32_usart_t usart, const usart_iso7816_options_t opt, int t, long pba_hz)
	Sets up the USART to use the ISO7816 T=0 or T=1 smartcard protocols. More...

Read and Reset Error Status Bits
static __always_inline void	usart_reset_status (volatile avr32_usart_t *usart)
	Resets the error status. More...

static __always_inline int	usart_parity_error (volatile avr32_usart_t *usart)
	Checks if a parity error has occurred since last status reset. More...

static __always_inline int	usart_framing_error (volatile avr32_usart_t *usart)
	Checks if a framing error has occurred since last status reset. More...

static __always_inline int	usart_overrun_error (volatile avr32_usart_t *usart)
	Checks if an overrun error has occurred since last status reset. More...

ISO7816 Control Functions
static __always_inline void	usart_iso7816_enable_receiver (volatile avr32_usart_t *usart)
	Enables the ISO7816 receiver. More...

static __always_inline void	usart_iso7816_enable_transmitter (volatile avr32_usart_t *usart)
	Enables the ISO7816 transmitter. More...

Transmit/Receive Functions
int	usart_send_address (volatile avr32_usart_t *usart, int address)
	Addresses a receiver. More...

static __always_inline int	usart_tx_ready (volatile avr32_usart_t *usart)
	Tests if the USART is ready to transmit a character. More...

int	usart_write_char (volatile avr32_usart_t *usart, int c)
	Writes the given character to the TX buffer if the transmitter is ready. More...

static __always_inline void	usart_bw_write_char (volatile avr32_usart_t *usart, int c)
	An active wait writing a character to the USART. More...

int	usart_putchar (volatile avr32_usart_t *usart, int c)
	Sends a character with the USART. More...

static __always_inline int	usart_tx_empty (volatile avr32_usart_t *usart)
	Tests if all requested USART transmissions are over. More...

static __always_inline int	usart_test_hit (volatile avr32_usart_t *usart)
	Tests if the USART contains a received character. More...

int	usart_read_char (volatile avr32_usart_t usart, int c)
	Checks the RX buffer for a received character, and stores it at the given memory location. More...

int	usart_getchar (volatile avr32_usart_t *usart)
	Waits until a character is received, and returns it. More...

void	usart_write_line (volatile avr32_usart_t usart, const char string)
	Writes one character string to the USART. More...

int	usart_get_echo_line (volatile avr32_usart_t *usart)
	Gets and echoes characters until end of line (detected by a CR character). More...

#define USART_1_5_STOPBITS AVR32_USART_MR_NBSTOP_1_5

Use 1.5 stop bits.

#define USART_1_STOPBIT AVR32_USART_MR_NBSTOP_1

Use 1 stop bit.

Referenced by init_dbg_rs232_ex(), and init_stdio().

#define USART_2_STOPBITS AVR32_USART_MR_NBSTOP_2

Use 2 stop bits (for more, just give the number of bits).

Referenced by usart_init_rs232(), usart_init_rs232_tx_only(), usart_init_sync_master(), and usart_init_sync_slave().

#define USART_AUTO_ECHO AVR32_USART_MR_CHMODE_ECHO

Echo data.

#define USART_DEFAULT_TIMEOUT 10000

Default time-out value (number of attempts).

Referenced by usart_putchar().

#define USART_EVEN_PARITY AVR32_USART_MR_PAR_EVEN

Use even parity on character transmission.

#define USART_FAILURE -1

Failure because of some unspecified reason.

Referenced by usart_get_echo_line(), usart_getchar(), and usart_putchar().

#define USART_INVALID_ARGUMENT -1

Argument value out of range.

#define USART_INVALID_INPUT 1

Input value out of range.

Referenced by usart_init_hw_handshaking(), usart_init_IrDA(), usart_init_iso7816(), usart_init_modem(), usart_init_rs232(), usart_init_rs232_tx_only(), usart_init_rs485(), usart_init_sync_master(), usart_init_sync_slave(), usart_set_async_baudrate(), usart_set_iso7816_clock(), and usart_set_sync_master_baudrate().

#define USART_LOCAL_LOOPBACK AVR32_USART_MR_CHMODE_LOCAL_LOOP

Local loopback.

#define USART_MARK_PARITY AVR32_USART_MR_PAR_MARK

Use a mark as parity bit.

#define USART_MODE_FAULT 5

USART not in the appropriate mode.

Referenced by usart_send_address().

#define USART_MULTIDROP_PARITY AVR32_USART_MR_PAR_MULTI

Parity bit is used to flag address characters.

#define USART_NO_PARITY AVR32_USART_MR_PAR_NONE

Don't use a parity bit.

Referenced by init_dbg_rs232_ex(), and init_stdio().

#define USART_NORMAL_CHMODE AVR32_USART_MR_CHMODE_NORMAL

Normal communication.

Referenced by init_dbg_rs232_ex(), and init_stdio().

#define USART_ODD_PARITY AVR32_USART_MR_PAR_ODD

Use odd parity on character transmission.

#define USART_REMOTE_LOOPBACK AVR32_USART_MR_CHMODE_REMOTE_LOOP

Remote loopback.

#define USART_RX_EMPTY 3

Nothing was received.

Referenced by usart_getchar(), and usart_read_char().

#define USART_RX_ERROR 4

Transmission error occurred.

Referenced by usart_getchar(), and usart_read_char().

#define USART_SPACE_PARITY AVR32_USART_MR_PAR_SPACE

Use a space as parity bit.

#define USART_SUCCESS 0

Successful completion.

Referenced by usart_bw_write_char(), usart_get_echo_line(), usart_init_hw_handshaking(), usart_init_IrDA(), usart_init_iso7816(), usart_init_modem(), usart_init_rs232(), usart_init_rs232_tx_only(), usart_init_rs485(), usart_init_sync_master(), usart_init_sync_slave(), usart_putchar(), usart_read_char(), usart_send_address(), usart_set_async_baudrate(), usart_set_iso7816_clock(), usart_set_sync_master_baudrate(), usart_set_sync_slave_baudrate(), and usart_write_char().

#define USART_TX_BUSY 2

Transmitter was busy.

Referenced by usart_write_char().

static __always_inline void usart_bw_write_char	(	volatile avr32_usart_t *	usart,
		int	c
	)

static

An active wait writing a character to the USART.

Parameters

usart	Base address of the USART instance.
c	The character (up to 9 bits) to transmit.

References USART_SUCCESS, and usart_write_char().

Referenced by usart_send_address().

static __always_inline int usart_framing_error ( volatile avr32_usart_t * usart )

static

Checks if a framing error has occurred since last status reset.

Parameters

usart Base address of the USART instance.

Returns: 1 if a framing error has been detected, otherwise 0.

int usart_get_echo_line ( volatile avr32_usart_t * usart )

Gets and echoes characters until end of line (detected by a CR character).

Parameters

usart Base address of the USART instance.

Return values

USART_SUCCESS	Success.
USART_FAILURE	Low-level error detected or ETX character received.

References USART_FAILURE, usart_getchar(), usart_putchar(), USART_SUCCESS, and usart_write_line().

int usart_getchar ( volatile avr32_usart_t * usart )

Waits until a character is received, and returns it.

Parameters

usart Base address of the USART instance.

Returns: The received character, or USART_FAILURE upon error.

References USART_FAILURE, usart_read_char(), USART_RX_EMPTY, and USART_RX_ERROR.

Referenced by usart_get_echo_line().

int usart_init_hw_handshaking	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use hardware handshaking.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

Note: usart_init_rs232 does not need to be invoked before this function.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

int usart_init_IrDA	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz,
		unsigned char	irda_filter
	)

Sets up the USART to use the IrDA protocol.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).
irda_filter	Counter used to distinguish received ones from zeros.

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

int usart_init_iso7816	(	volatile avr32_usart_t *	usart,
		const usart_iso7816_options_t *	opt,
		int	t,
		long	pba_hz
	)

Sets up the USART to use the ISO7816 T=0 or T=1 smartcard protocols.

The receiver is enabled by default. usart_iso7816_enable_receiver and usart_iso7816_enable_transmitter can be called to change the half-duplex communication direction.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up ISO7816 communication (see usart_iso7816_options_t).
t	ISO7816 mode to use (T=0 or T=1).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_iso7816_options_t::bit_order, usart_iso7816_options_t::dis_suc_nack, usart_iso7816_options_t::fidi_ratio, usart_iso7816_options_t::inhibit_nack, usart_iso7816_options_t::iso7816_hz, usart_iso7816_options_t::max_iterations, usart_iso7816_options_t::paritytype, USART_INVALID_INPUT, usart_iso7816_enable_receiver(), usart_reset(), usart_set_iso7816_clock(), and USART_SUCCESS.

int usart_init_modem	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use the modem protocol, activating dedicated inputs/outputs.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

int usart_init_rs232	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use the standard RS232 protocol.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_options_t::baudrate, usart_options_t::channelmode, usart_options_t::charlength, usart_options_t::paritytype, usart_options_t::stopbits, USART_2_STOPBITS, USART_INVALID_INPUT, usart_reset(), usart_set_async_baudrate(), and USART_SUCCESS.

Referenced by init_dbg_rs232_ex(), init_stdio(), usart_init_hw_handshaking(), usart_init_IrDA(), usart_init_modem(), and usart_init_rs485().

int usart_init_rs232_tx_only	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use the standard RS232 protocol in TX-only mode.

Compared to usart_init_rs232, this function allows very high baud rates (up to pba_hz instead of pba_hz / 8) at the expense of full duplex.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

Note: The 1.5 stop bit is not supported in this mode.

References usart_options_t::baudrate, usart_options_t::channelmode, usart_options_t::charlength, usart_options_t::paritytype, usart_options_t::stopbits, USART_2_STOPBITS, USART_INVALID_INPUT, usart_reset(), usart_set_sync_master_baudrate(), and USART_SUCCESS.

int usart_init_rs485	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use the RS485 protocol.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

int usart_init_sync_master	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use a synchronous RS232-like protocol in master mode.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_options_t::baudrate, usart_options_t::channelmode, usart_options_t::charlength, usart_options_t::paritytype, usart_options_t::stopbits, USART_2_STOPBITS, USART_INVALID_INPUT, usart_reset(), usart_set_sync_master_baudrate(), and USART_SUCCESS.

int usart_init_sync_slave	(	volatile avr32_usart_t *	usart,
		const usart_options_t *	opt,
		long	pba_hz
	)

Sets up the USART to use a synchronous RS232-like protocol in slave mode.

Parameters

usart	Base address of the USART instance.
opt	Options needed to set up RS232 communication (see usart_options_t).
pba_hz	USART module input clock frequency (PBA clock, Hz).

Return values

USART_SUCCESS	Mode successfully initialized.
USART_INVALID_INPUT	One or more of the arguments is out of valid range.

References usart_options_t::channelmode, usart_options_t::charlength, usart_options_t::paritytype, usart_options_t::stopbits, USART_2_STOPBITS, USART_INVALID_INPUT, usart_reset(), usart_set_sync_slave_baudrate(), and USART_SUCCESS.

static __always_inline void usart_iso7816_enable_receiver ( volatile avr32_usart_t * usart )

static

Enables the ISO7816 receiver.

The ISO7816 transmitter is disabled.

Parameters

usart Base address of the USART instance.

Referenced by usart_init_iso7816().

static __always_inline void usart_iso7816_enable_transmitter ( volatile avr32_usart_t * usart )

static

Enables the ISO7816 transmitter.

The ISO7816 receiver is disabled.

Parameters

usart Base address of the USART instance.

static __always_inline int usart_overrun_error ( volatile avr32_usart_t * usart )

static

Checks if an overrun error has occurred since last status reset.

Parameters

usart Base address of the USART instance.

Returns: 1 if a overrun error has been detected, otherwise 0.

static __always_inline int usart_parity_error ( volatile avr32_usart_t * usart )

static

Checks if a parity error has occurred since last status reset.

Parameters

usart Base address of the USART instance.

Returns: 1 if a parity error has been detected, otherwise 0.

int usart_putchar	(	volatile avr32_usart_t *	usart,
		int	c
	)

Sends a character with the USART.

Parameters

usart	Base address of the USART instance.
c	Character to write.

Return values

USART_SUCCESS	The character was written.
USART_FAILURE	The function timed out before the USART transmitter became ready to send.

References USART_DEFAULT_TIMEOUT, USART_FAILURE, USART_SUCCESS, and usart_write_char().

Referenced by print_char(), usart_get_echo_line(), and usart_write_line().

int usart_read_char	(	volatile avr32_usart_t *	usart,
		int *	c
	)

Checks the RX buffer for a received character, and stores it at the given memory location.

Parameters

usart	Base address of the USART instance.
c	Pointer to the where the read character should be stored (must be at least short in order to accept 9-bit characters).

Return values

USART_SUCCESS	The character was read successfully.
USART_RX_EMPTY	The RX buffer was empty.
USART_RX_ERROR	An error was detected.

References USART_RX_EMPTY, USART_RX_ERROR, USART_SUCCESS, and usart_test_hit().

Referenced by usart_getchar().

void usart_reset ( volatile avr32_usart_t * usart )

Resets the USART and disables TX and RX.

Parameters

usart Base address of the USART instance.

References cpu_irq_disable, cpu_irq_enable, and cpu_irq_is_enabled.

Referenced by usart_init_iso7816(), usart_init_rs232(), usart_init_rs232_tx_only(), usart_init_sync_master(), and usart_init_sync_slave().

static __always_inline void usart_reset_status ( volatile avr32_usart_t * usart )

static

Resets the error status.

This function resets the status bits indicating that a parity error, framing error or overrun has occurred. The RXBRK bit, indicating a start/end of break condition on the RX line, is also reset.

Parameters

usart Base address of the USART instance.

int usart_send_address	(	volatile avr32_usart_t *	usart,
		int	address
	)

Addresses a receiver.

While in RS485 mode, receivers only accept data addressed to them. A packet/char with the address tag set has to precede any data. This function is used to address a receiver. This receiver should read all the following data, until an address packet addresses another receiver.

Parameters

usart	Base address of the USART instance.
address	Address of the target device.

Return values

USART_SUCCESS	Address successfully sent (if current mode is RS485).
USART_MODE_FAULT	Wrong operating mode.

References usart_bw_write_char(), USART_MODE_FAULT, usart_mode_is_multidrop(), and USART_SUCCESS.

static __always_inline int usart_test_hit ( volatile avr32_usart_t * usart )

static

Tests if the USART contains a received character.

Parameters

usart Base address of the USART instance.

Returns: 1 if the USART Receive Holding Register is full, otherwise 0.

Referenced by usart_read_char().

static __always_inline int usart_tx_empty ( volatile avr32_usart_t * usart )

static

Tests if all requested USART transmissions are over.

Parameters

usart Base address of the USART instance.

Returns: 1 if the USART Transmit Shift Register and the USART Transmit Holding Register are free, otherwise 0.

static __always_inline int usart_tx_ready ( volatile avr32_usart_t * usart )

static

Tests if the USART is ready to transmit a character.

Parameters

usart Base address of the USART instance.

Returns: 1 if the USART Transmit Holding Register is free, otherwise 0.

Referenced by usart_write_char().

int usart_write_char	(	volatile avr32_usart_t *	usart,
		int	c
	)

Writes the given character to the TX buffer if the transmitter is ready.

Parameters

usart	Base address of the USART instance.
c	The character (up to 9 bits) to transmit.

Return values

USART_SUCCESS	The transmitter was ready.
USART_TX_BUSY	The transmitter was busy.

References USART_SUCCESS, USART_TX_BUSY, and usart_tx_ready().

Referenced by usart_bw_write_char(), and usart_putchar().

void usart_write_line	(	volatile avr32_usart_t *	usart,
		const char *	string
	)

Writes one character string to the USART.

Parameters

usart	Base address of the USART instance.
string	String to be written.

References usart_putchar().

Referenced by print(), and usart_get_echo_line().

Microchip® Advanced Software Framework

Data Structures

Macros

Return Values

Parity Settings

Stop Bits Settings

Channel Modes

Initialization Functions

Read and Reset Error Status Bits

ISO7816 Control Functions

Transmit/Receive Functions