Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
USART - Univ. Sync/Async Serial Rec/Trans

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

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

Modules

 

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.

Referenced by cdc_set_line_coding(), and uart_config().

#define USART_2_STOPBITS   AVR32_USART_MR_NBSTOP_2

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

Referenced by cdc_set_line_coding(), uart_config(), 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.

Referenced by cdc_set_line_coding(), and uart_config().

#define USART_FAILURE   -1

Failure because of some unspecified reason.

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

#define USART_INVALID_ARGUMENT   -1

Argument value out of range.

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

Referenced by cdc_set_line_coding(), and uart_config().

#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
#define USART_ODD_PARITY   AVR32_USART_MR_PAR_ODD

Use odd parity on character transmission.

Referenced by cdc_set_line_coding(), and uart_config().

#define USART_REMOTE_LOOPBACK   AVR32_USART_MR_CHMODE_REMOTE_LOOP

Remote loopback.

#define USART_RX_EMPTY   3

Nothing was received.

Referenced by io_getc(), usart_getchar(), and usart_read_char().

#define USART_RX_ERROR   4

Transmission error occurred.

Referenced by io_getc(), usart_getchar(), and usart_read_char().

#define USART_SPACE_PARITY   AVR32_USART_MR_PAR_SPACE

Use a space as parity bit.

Referenced by cdc_set_line_coding(), and uart_config().

#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
usartBase address of the USART instance.
cThe 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
usartBase 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
usartBase address of the USART instance.
Return values
USART_SUCCESSSuccess.
USART_FAILURELow-level error detected or ETX character received.

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

Referenced by main().

int usart_getchar ( volatile avr32_usart_t *  usart)

Waits until a character is received, and returns it.

Parameters
usartBase address of the USART instance.
Returns
The received character, or USART_FAILURE upon error.

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

Referenced by dsp_debug_read_fct(), main(), usart_get_echo_line(), usart_serial_getchar(), usart_spi_read_packet(), usart_spi_read_single(), and usart_spi_write_packet().

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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
irda_filterCounter used to distinguish received ones from zeros.
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up ISO7816 communication (see usart_iso7816_options_t).
tISO7816 mode to use (T=0 or T=1).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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 cdc_set_line_coding(), dsp_debug_init(), init_dbg_rs232_ex(), init_printk(), init_shl_rs232(), init_stdio(), init_usart(), main(), uart_config(), uart_open(), usart_init_hw_handshaking(), usart_init_IrDA(), usart_init_modem(), usart_init_rs485(), usart_serial_init(), ushell_task_init(), xSerialPortInitMinimal(), and xUsartInit().

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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase address of the USART instance.
optOptions needed to set up RS232 communication (see usart_options_t).
pba_hzUSART module input clock frequency (PBA clock, Hz).
Return values
USART_SUCCESSMode successfully initialized.
USART_INVALID_INPUTOne 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
usartBase 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
usartBase 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
usartBase 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
usartBase 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
usartBase address of the USART instance.
cCharacter to write.
Return values
USART_SUCCESSThe character was written.
USART_FAILUREThe 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 board_putchar(), dsp_debug_write_fct(), host_cdc_task(), io_getc(), main(), print_char(), usart_get_echo_line(), usart_spi_read_packet(), usart_spi_read_single(), usart_spi_write_packet(), usart_spi_write_single(), 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
usartBase address of the USART instance.
cPointer to the where the read character should be stored (must be at least short in order to accept 9-bit characters).
Return values
USART_SUCCESSThe character was read successfully.
USART_RX_EMPTYThe RX buffer was empty.
USART_RX_ERRORAn error was detected.

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

Referenced by fat_example_append_file(), fat_example_build_cmd(), fsaccess_example_get_filename(), fsaccess_example_get_mode(), host_cdc_task(), io_getc(), ISR(), usart_getchar(), usart_int_handler(), ushell_cmd_append_file(), ushell_cmd_scan(), and ushell_more_wait().

void usart_reset ( volatile avr32_usart_t *  usart)

Resets the USART and disables TX and RX.

Parameters
usartBase 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
usartBase address of the USART instance.

Referenced by fat_example_append_file(), fat_example_build_cmd(), fsaccess_example_get_filename(), fsaccess_example_get_mode(), host_cdc_task(), ISR(), ushell_cmd_append_file(), ushell_cmd_scan(), and ushell_more_wait().

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
usartBase address of the USART instance.
addressAddress of the target device.
Return values
USART_SUCCESSAddress successfully sent (if current mode is RS485).
USART_MODE_FAULTWrong 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
usartBase address of the USART instance.
Returns
1 if the USART Receive Holding Register is full, otherwise 0.

Referenced by host_cdc_task(), and 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
usartBase address of the USART instance.
Returns
1 if the USART Transmit Shift Register and the USART Transmit Holding Register are free, otherwise 0.

Referenced by main(), and usart_spi_is_tx_empty().

static __always_inline int usart_tx_ready ( volatile avr32_usart_t *  usart)
static

Tests if the USART is ready to transmit a character.

Parameters
usartBase address of the USART instance.
Returns
1 if the USART Transmit Holding Register is free, otherwise 0.

Referenced by device_cdc_task(), usart_spi_is_tx_ready(), and 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
usartBase address of the USART instance.
cThe character (up to 9 bits) to transmit.
Return values
USART_SUCCESSThe transmitter was ready.
USART_TX_BUSYThe transmitter was busy.

References USART_SUCCESS, USART_TX_BUSY, and usart_tx_ready().

Referenced by device_cdc_task(), ISR(), usart_bw_write_char(), usart_int_handler(), usart_putchar(), and usart_serial_putchar().

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

Writes one character string to the USART.

Parameters
usartBase address of the USART instance.
stringString to be written.

References usart_putchar().

Referenced by main(), print(), print_fct(), and usart_get_echo_line().