# usart.h File Reference

## Detailed Description

USART driver for AVR32 UC3.

This file contains basic functions for the AVR32 USART, with support for all modes, settings and clock speeds.

- Compiler: IAR EWAVR32 and GNU GCC for AVR32
- Supported devices: All AVR32 devices with a USART module can be used.
- AppNote:

Author:
  Atmel Corporation: http://www.atmel.com
  Support and FAQ: http://support.atmel.no/

Definition in file usart.h.

`#include <avr32/io.h>`
`#include "compiler.h"`

Go to the source code of this file.

## 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...
## Defines
#define | USART_DEFAULT_TIMEOUT 10000
| Default time-out value (number of attempts).
Stop Bits Settings
#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.
#define | USART_2_STOPBITS AVR32_USART_MR_NBSTOP_2
| Use 2 stop bits (for more, just give the number of bits).
Channel Modes
#define | USART_AUTO_ECHO AVR32_USART_MR_CHMODE_ECHO
| Echo data.
#define | USART_LOCAL_LOOPBACK AVR32_USART_MR_CHMODE_LOCAL_LOOP
| Local loopback.
#define | USART_NORMAL_CHMODE AVR32_USART_MR_CHMODE_NORMAL
| Normal communication.
#define | USART_REMOTE_LOOPBACK AVR32_USART_MR_CHMODE_REMOTE_LOOP
| Remote loopback.
Parity Settings
#define | USART_EVEN_PARITY AVR32_USART_MR_PAR_EVEN
| Use even parity on character transmission.
#define | USART_MARK_PARITY AVR32_USART_MR_PAR_MARK
| Use a mark as parity bit.
#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.
#define | USART_ODD_PARITY AVR32_USART_MR_PAR_ODD
| Use odd parity on character transmission.
#define | USART_SPACE_PARITY AVR32_USART_MR_PAR_SPACE
| Use a space as parity bit.
Return Values
#define | USART_FAILURE -1
| Failure because of some unspecified reason.
#define | USART_INVALID_ARGUMENT -1
| Argument value out of range.
#define | USART_INVALID_INPUT 1
| Input value out of range.
#define | USART_MODE_FAULT 5
| USART not in the appropriate mode.
#define | USART_RX_EMPTY 3
| Nothing was received.
#define | USART_RX_ERROR 4
| Transmission error occurred.
#define | USART_SUCCESS 0
| Successful completion.
#define | USART_TX_BUSY 2
| Transmitter was busy.
## Functions
Transmit/Receive Functions
__inline__ void | usart_bw_write_char (volatile avr32_usart_t *usart, int c)
| An active wait writing a character to the USART.
int | usart_get_echo_line (volatile avr32_usart_t *usart)
| Gets and echoes characters until end of line.
int | usart_getchar (volatile avr32_usart_t *usart)
| Waits until a character is received, and returns it.
int | usart_putchar (volatile avr32_usart_t *usart, int c)
| Sends a character with the USART.
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.
int | usart_send_address (volatile avr32_usart_t *usart, int address)
| Addresses a receiver.
__inline__ int | usart_test_hit (volatile avr32_usart_t *usart)
| Tests if the USART contains a received character.
__inline__ int | usart_tx_empty (volatile avr32_usart_t *usart)
| Tests if all requested USART transmissions are over.
__inline__ int | usart_tx_ready (volatile avr32_usart_t *usart)
| Tests if the USART is ready to transmit a character.
int | usart_write_char (volatile avr32_usart_t *usart, int c)
| Writes the given character to the TX buffer if the transmitter is ready.
void | usart_write_line (volatile avr32_usart_t *usart, const char *string)
| Writes one character string to the USART.
Read and Reset Error Status Bits
__inline__ int | usart_framing_error (volatile avr32_usart_t *usart)
| Checks if a framing error has occurred since last status reset.
__inline__ int | usart_overrun_error (volatile avr32_usart_t *usart)
| Checks if an overrun error has occurred since last status reset.
__inline__ int | usart_parity_error (volatile avr32_usart_t *usart)
| Checks if a parity error has occurred since last status reset.
__inline__ void | usart_reset_status (volatile avr32_usart_t *usart)
| Resets the error status.
Initialization Functions
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.
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.
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.
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.
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.
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.
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.
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.
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.
void | usart_reset (volatile avr32_usart_t *usart)
| Resets the USART and disables TX and RX.
ISO7816 Control Functions
__inline__ void | usart_iso7816_enable_receiver (volatile avr32_usart_t *usart)
| Enables the ISO7816 receiver.
__inline__ void | usart_iso7816_enable_transmitter (volatile avr32_usart_t *usart)
| Enables the ISO7816 transmitter.

## Define Documentation

#define USART_1_5_STOPBITS AVR32_USART_MR_NBSTOP_1_5

Use 1.5 stop bits.

Definition at line 84 of file usart.h.

#define USART_1_STOPBIT AVR32_USART_MR_NBSTOP_1

Use 1 stop bit.

Definition at line 83 of file usart.h.

Referenced by main().

#define USART_2_STOPBITS AVR32_USART_MR_NBSTOP_2

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

Definition at line 85 of file usart.h.

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.

Definition at line 92 of file usart.h.

#define USART_DEFAULT_TIMEOUT 10000

Default time-out value (number of attempts).

Definition at line 67 of file usart.h.

Referenced by usart_putchar().

#define USART_EVEN_PARITY AVR32_USART_MR_PAR_EVEN

Use even parity on character transmission.

Definition at line 72 of file usart.h.

#define USART_FAILURE -1

Failure because of some unspecified reason.

Definition at line 57 of file usart.h.

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

#define USART_INVALID_ARGUMENT -1

Argument value out of range.

Definition at line 59 of file usart.h.

#define USART_INVALID_INPUT 1

Input value out of range.

Definition at line 58 of file usart.h.

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.

Definition at line 93 of file usart.h.

#define USART_MARK_PARITY AVR32_USART_MR_PAR_MARK

Use a mark as parity bit.

Definition at line 75 of file usart.h.

#define USART_MODE_FAULT 5

USART not in the appropriate mode.

Definition at line 63 of file usart.h.

Referenced by usart_send_address().

#define USART_MULTIDROP_PARITY AVR32_USART_MR_PAR_MULTI

Parity bit is used to flag address characters.

Definition at line 77 of file usart.h.

#define USART_NO_PARITY AVR32_USART_MR_PAR_NONE

Don't use a parity bit.

Definition at line 76 of file usart.h.

Referenced by main().

#define USART_NORMAL_CHMODE AVR32_USART_MR_CHMODE_NORMAL

Normal communication.

Definition at line 91 of file usart.h.

Referenced by main().

#define USART_ODD_PARITY AVR32_USART_MR_PAR_ODD

Use odd parity on character transmission.

Definition at line 73 of file usart.h.

#define USART_REMOTE_LOOPBACK AVR32_USART_MR_CHMODE_REMOTE_LOOP

Remote loopback.

Definition at line 94 of file usart.h.

#define USART_RX_EMPTY 3

Nothing was received.

Definition at line 61 of file usart.h.

Referenced by usart_getchar(), and usart_read_char().

#define USART_RX_ERROR 4

Transmission error occurred.

Definition at line 62 of file usart.h.

Referenced by usart_getchar(), and usart_read_char().

#define USART_SPACE_PARITY AVR32_USART_MR_PAR_SPACE

Use a space as parity bit.

Definition at line 74 of file usart.h.

#define USART_SUCCESS 0

Successful completion.

Definition at line 56 of file usart.h.

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.

Definition at line 60 of file usart.h.

Referenced by usart_write_char().

## Function Documentation

__inline__ void usart_bw_write_char | ( | volatile avr32_usart_t * | usart,
|  | int | c |
| ) |  |  |

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.

Definition at line 754 of file usart.h.

References USART_SUCCESS, and usart_write_char().

Referenced by usart_send_address().

    00755 {
    00756   while (usart_write_char(usart, c) != USART_SUCCESS);
    00757 }

__inline__ int usart_framing_error | ( | volatile avr32_usart_t * | usart | ) |

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

Definition at line 424 of file usart.h.

    00425 {
    00426   return (usart->csr & AVR32_USART_CSR_FRAME_MASK) != 0;
    00427 }

int usart_get_echo_line | ( | volatile avr32_usart_t * | usart | ) |

Gets and echoes characters until end of line.

Parameters:

  | usart | Base address of the USART instance.

Return values:

  | USART_SUCCESS | Success.
  | USART_FAILURE | ETX character received.

Definition at line 869 of file usart.c.

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

Referenced by main().

    00870 {
    00871   int rx_char;
    00872   int retval = USART_SUCCESS;
    00873
    00874   while (1)
    00875   {
    00876     rx_char = usart_getchar(usart);
    00877     if (rx_char == USART_FAILURE)
    00878     {
    00879       usart_write_line(usart, "Error!!!\n");
    00880       break;
    00881     }
    00882     if (rx_char == '\x03')
    00883     {
    00884       retval = USART_FAILURE;
    00885       break;
    00886     }
    00887     usart_putchar(usart, rx_char);
    00888     if (rx_char == '\r')
    00889     {
    00890       usart_putchar(usart, '\n');
    00891       break;
    00892     }
    00893   }
    00894
    00895   return retval;
    00896 }

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.

Definition at line 849 of file usart.c.

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

Referenced by usart_get_echo_line().

    00850 {
    00851   int c, ret;
    00852
    00853   while ((ret = usart_read_char(usart, &c)) == USART_RX_EMPTY);
    00854
    00855   if (ret == USART_RX_ERROR)
    00856     return USART_FAILURE;
    00857
    00858   return c;
    00859 }

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.

Definition at line 383 of file usart.c.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

    00384 {
    00385   // First: Setup standard RS232.
    00386   if (usart_init_rs232(usart, opt, pba_hz) == USART_INVALID_INPUT)
    00387     return USART_INVALID_INPUT;
    00388
    00389   // Set hardware handshaking mode.
    00390   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00391               AVR32_USART_MR_MODE_HARDWARE << AVR32_USART_MR_MODE_OFFSET;
    00392
    00393   return USART_SUCCESS;
    00394 }

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.

Definition at line 530 of file usart.c.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

    00532 {
    00533   // First: Setup standard RS232.
    00534   if (usart_init_rs232(usart, opt, pba_hz) == USART_INVALID_INPUT)
    00535     return USART_INVALID_INPUT;
    00536
    00537   // Set IrDA filter.
    00538   usart->ifr = irda_filter;
    00539
    00540   // Set IrDA mode and activate filtering of input.
    00541   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00542               AVR32_USART_MODE_IRDA << AVR32_USART_MR_MODE_OFFSET |
    00543               AVR32_USART_MR_FILTER_MASK;
    00544
    00545   return USART_SUCCESS;
    00546 }

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.

Definition at line 549 of file usart.c.

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.

    00550 {
    00551   // Reset the USART and shutdown TX and RX.
    00552   usart_reset(usart);
    00553
    00554   // Check input values.
    00555   if (!opt || // Null pointer.
    00556       opt->paritytype > 1)
    00557     return USART_INVALID_INPUT;
    00558
    00559   if (t == 0)
    00560   {
    00561     // Set USART mode to ISO7816, T=0.
    00562     // The T=0 protocol always uses 2 stop bits.
    00563     usart->mr = AVR32_USART_MR_MODE_ISO7816_T0 << AVR32_USART_MR_MODE_OFFSET |
    00564                 AVR32_USART_MR_NBSTOP_2 << AVR32_USART_MR_NBSTOP_OFFSET |
    00565                 opt->bit_order << AVR32_USART_MR_MSBF_OFFSET; // Allow MSBF in T=0.
    00566   }
    00567   else if (t == 1)
    00568   {
    00569     // Only LSB first in the T=1 protocol.
    00570     // max_iterations field is only used in T=0 mode.
    00571     if (opt->bit_order != 0 ||
    00572         opt->max_iterations != 0)
    00573       return USART_INVALID_INPUT;
    00574
    00575     // Set USART mode to ISO7816, T=1.
    00576     // The T=1 protocol always uses 1 stop bit.
    00577     usart->mr = AVR32_USART_MR_MODE_ISO7816_T1 << AVR32_USART_MR_MODE_OFFSET |
    00578                 AVR32_USART_MR_NBSTOP_1 << AVR32_USART_MR_NBSTOP_OFFSET;
    00579   }
    00580   else
    00581     return USART_INVALID_INPUT;
    00582
    00583   if (usart_set_iso7816_clock(usart, opt->iso7816_hz, pba_hz) == USART_INVALID_INPUT)
    00584     return USART_INVALID_INPUT;
    00585
    00586   // Set FIDI register: bit rate = selected clock/FI_DI_ratio/16.
    00587   usart->fidi = opt->fidi_ratio;
    00588
    00589   // Set ISO7816 spesific options in the MODE register.
    00590   usart->mr |= opt->paritytype << AVR32_USART_MR_PAR_OFFSET |
    00591                AVR32_USART_MR_CLKO_MASK | // Enable clock output.
    00592                opt->inhibit_nack << AVR32_USART_MR_INACK_OFFSET |
    00593                opt->dis_suc_nack << AVR32_USART_MR_DSNACK_OFFSET |
    00594                opt->max_iterations << AVR32_USART_MR_MAX_ITERATION_OFFSET;
    00595
    00596   // Setup complete; enable the receiver by default.
    00597   usart_iso7816_enable_receiver(usart);
    00598
    00599   return USART_SUCCESS;
    00600 }

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.

Definition at line 397 of file usart.c.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

    00398 {
    00399   // First: Setup standard RS232.
    00400   if (usart_init_rs232(usart, opt, pba_hz) == USART_INVALID_INPUT)
    00401     return USART_INVALID_INPUT;
    00402
    00403   // Set modem mode.
    00404   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00405               AVR32_USART_MR_MODE_MODEM << AVR32_USART_MR_MODE_OFFSET;
    00406
    00407   return USART_SUCCESS;
    00408 }

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.

Definition at line 279 of file usart.c.

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 main(), usart_init_hw_handshaking(), usart_init_IrDA(), usart_init_modem(), and usart_init_rs485().

    00280 {
    00281   // Reset the USART and shutdown TX and RX.
    00282   usart_reset(usart);
    00283
    00284   // Check input values.
    00285   if (!opt || // Null pointer.
    00286       opt->charlength < 5 || opt->charlength > 9 ||
    00287       opt->paritytype > 7 ||
    00288       opt->stopbits > 2 + 255 ||
    00289       opt->channelmode > 3 ||
    00290       usart_set_async_baudrate(usart, opt->baudrate, pba_hz) == USART_INVALID_INPUT)
    00291     return USART_INVALID_INPUT;
    00292
    00293   if (opt->charlength == 9)
    00294   {
    00295     // Character length set to 9 bits. MODE9 dominates CHRL.
    00296     usart->mr |= AVR32_USART_MR_MODE9_MASK;
    00297   }
    00298   else
    00299   {
    00300     // CHRL gives the character length (- 5) when MODE9 = 0.
    00301     usart->mr |= (opt->charlength - 5) << AVR32_USART_MR_CHRL_OFFSET;
    00302   }
    00303
    00304   usart->mr |= opt->paritytype << AVR32_USART_MR_PAR_OFFSET |
    00305                opt->channelmode << AVR32_USART_MR_CHMODE_OFFSET;
    00306
    00307   if (opt->stopbits > USART_2_STOPBITS)
    00308   {
    00309     // Set two stop bits
    00310     usart->mr |= AVR32_USART_MR_NBSTOP_2 << AVR32_USART_MR_NBSTOP_OFFSET;
    00311     // and a timeguard period gives the rest.
    00312     usart->ttgr = opt->stopbits - USART_2_STOPBITS;
    00313   }
    00314   else
    00315     // Insert 1, 1.5 or 2 stop bits.
    00316     usart->mr |= opt->stopbits << AVR32_USART_MR_NBSTOP_OFFSET;
    00317
    00318   // Set normal mode.
    00319   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00320               AVR32_USART_MR_MODE_NORMAL << AVR32_USART_MR_MODE_OFFSET;
    00321
    00322   // Setup complete; enable communication.
    00323   // Enable input and output.
    00324   usart->cr = AVR32_USART_CR_RXEN_MASK |
    00325               AVR32_USART_CR_TXEN_MASK;
    00326
    00327   return USART_SUCCESS;
    00328 }

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.

Definition at line 331 of file usart.c.

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.

    00332 {
    00333   // Reset the USART and shutdown TX and RX.
    00334   usart_reset(usart);
    00335
    00336   // Check input values.
    00337   if (!opt || // Null pointer.
    00338       opt->charlength < 5 || opt->charlength > 9 ||
    00339       opt->paritytype > 7 ||
    00340       opt->stopbits == 1 || opt->stopbits > 2 + 255 ||
    00341       opt->channelmode > 3 ||
    00342       usart_set_sync_master_baudrate(usart, opt->baudrate, pba_hz) == USART_INVALID_INPUT)
    00343     return USART_INVALID_INPUT;
    00344
    00345   if (opt->charlength == 9)
    00346   {
    00347     // Character length set to 9 bits. MODE9 dominates CHRL.
    00348     usart->mr |= AVR32_USART_MR_MODE9_MASK;
    00349   }
    00350   else
    00351   {
    00352     // CHRL gives the character length (- 5) when MODE9 = 0.
    00353     usart->mr |= (opt->charlength - 5) << AVR32_USART_MR_CHRL_OFFSET;
    00354   }
    00355
    00356   usart->mr |= opt->paritytype << AVR32_USART_MR_PAR_OFFSET |
    00357                opt->channelmode << AVR32_USART_MR_CHMODE_OFFSET;
    00358
    00359   if (opt->stopbits > USART_2_STOPBITS)
    00360   {
    00361     // Set two stop bits
    00362     usart->mr |= AVR32_USART_MR_NBSTOP_2 << AVR32_USART_MR_NBSTOP_OFFSET;
    00363     // and a timeguard period gives the rest.
    00364     usart->ttgr = opt->stopbits - USART_2_STOPBITS;
    00365   }
    00366   else
    00367     // Insert 1 or 2 stop bits.
    00368     usart->mr |= opt->stopbits << AVR32_USART_MR_NBSTOP_OFFSET;
    00369
    00370   // Set normal mode.
    00371   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00372               AVR32_USART_MR_MODE_NORMAL << AVR32_USART_MR_MODE_OFFSET;
    00373
    00374   // Setup complete; enable communication.
    00375   // Enable only output as input is not possible in synchronous mode without
    00376   // transferring clock.
    00377   usart->cr = AVR32_USART_CR_TXEN_MASK;
    00378
    00379   return USART_SUCCESS;
    00380 }

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.

Definition at line 516 of file usart.c.

References usart_init_rs232(), USART_INVALID_INPUT, and USART_SUCCESS.

    00517 {
    00518   // First: Setup standard RS232.
    00519   if (usart_init_rs232(usart, opt, pba_hz) == USART_INVALID_INPUT)
    00520     return USART_INVALID_INPUT;
    00521
    00522   // Set RS485 mode.
    00523   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00524               AVR32_USART_MR_MODE_RS485 << AVR32_USART_MR_MODE_OFFSET;
    00525
    00526   return USART_SUCCESS;
    00527 }

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.

Definition at line 411 of file usart.c.

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.

    00412 {
    00413   // Reset the USART and shutdown TX and RX.
    00414   usart_reset(usart);
    00415
    00416   // Check input values.
    00417   if (!opt || // Null pointer.
    00418       opt->charlength < 5 || opt->charlength > 9 ||
    00419       opt->paritytype > 7 ||
    00420       opt->stopbits == 1 || opt->stopbits > 2 + 255 ||
    00421       opt->channelmode > 3 ||
    00422       usart_set_sync_master_baudrate(usart, opt->baudrate, pba_hz) == USART_INVALID_INPUT)
    00423     return USART_INVALID_INPUT;
    00424
    00425   if (opt->charlength == 9)
    00426   {
    00427     // Character length set to 9 bits. MODE9 dominates CHRL.
    00428     usart->mr |= AVR32_USART_MR_MODE9_MASK;
    00429   }
    00430   else
    00431   {
    00432     // CHRL gives the character length (- 5) when MODE9 = 0.
    00433     usart->mr |= (opt->charlength - 5) << AVR32_USART_MR_CHRL_OFFSET;
    00434   }
    00435
    00436   usart->mr |= opt->paritytype << AVR32_USART_MR_PAR_OFFSET |
    00437                opt->channelmode << AVR32_USART_MR_CHMODE_OFFSET;
    00438
    00439   if (opt->stopbits > USART_2_STOPBITS)
    00440   {
    00441     // Set two stop bits
    00442     usart->mr |= AVR32_USART_MR_NBSTOP_2 << AVR32_USART_MR_NBSTOP_OFFSET;
    00443     // and a timeguard period gives the rest.
    00444     usart->ttgr = opt->stopbits - USART_2_STOPBITS;
    00445   }
    00446   else
    00447     // Insert 1 or 2 stop bits.
    00448     usart->mr |= opt->stopbits << AVR32_USART_MR_NBSTOP_OFFSET;
    00449
    00450   // Set normal mode.
    00451   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00452               AVR32_USART_MR_MODE_NORMAL << AVR32_USART_MR_MODE_OFFSET |
    00453               AVR32_USART_MR_CLKO_MASK;
    00454
    00455   // Setup complete; enable communication.
    00456   // Enable input and output.
    00457   usart->cr = AVR32_USART_CR_RXEN_MASK |
    00458               AVR32_USART_CR_TXEN_MASK;
    00459
    00460   return USART_SUCCESS;
    00461 }

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.

Definition at line 464 of file usart.c.

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.

    00465 {
    00466   // Reset the USART and shutdown TX and RX.
    00467   usart_reset(usart);
    00468
    00469   // Check input values.
    00470   if (!opt || // Null pointer.
    00471       opt->charlength < 5 || opt->charlength > 9 ||
    00472       opt->paritytype > 7 ||
    00473       opt->stopbits == 1 || opt->stopbits > 2 + 255 ||
    00474       opt->channelmode > 3 ||
    00475       usart_set_sync_slave_baudrate(usart) == USART_INVALID_INPUT)
    00476     return USART_INVALID_INPUT;
    00477
    00478   if (opt->charlength == 9)
    00479   {
    00480     // Character length set to 9 bits. MODE9 dominates CHRL.
    00481     usart->mr |= AVR32_USART_MR_MODE9_MASK;
    00482   }
    00483   else
    00484   {
    00485     // CHRL gives the character length (- 5) when MODE9 = 0.
    00486     usart->mr |= (opt->charlength - 5) << AVR32_USART_MR_CHRL_OFFSET;
    00487   }
    00488
    00489   usart->mr |= opt->paritytype << AVR32_USART_MR_PAR_OFFSET |
    00490                opt->channelmode << AVR32_USART_MR_CHMODE_OFFSET;
    00491
    00492   if (opt->stopbits > USART_2_STOPBITS)
    00493   {
    00494     // Set two stop bits
    00495     usart->mr |= AVR32_USART_MR_NBSTOP_2 << AVR32_USART_MR_NBSTOP_OFFSET;
    00496     // and a timeguard period gives the rest.
    00497     usart->ttgr = opt->stopbits - USART_2_STOPBITS;
    00498   }
    00499   else
    00500     // Insert 1 or 2 stop bits.
    00501     usart->mr |= opt->stopbits << AVR32_USART_MR_NBSTOP_OFFSET;
    00502
    00503   // Set normal mode.
    00504   usart->mr = (usart->mr & ~AVR32_USART_MR_MODE_MASK) |
    00505               AVR32_USART_MR_MODE_NORMAL << AVR32_USART_MR_MODE_OFFSET;
    00506
    00507   // Setup complete; enable communication.
    00508   // Enable input and output.
    00509   usart->cr = AVR32_USART_CR_RXEN_MASK |
    00510               AVR32_USART_CR_TXEN_MASK;
    00511
    00512   return USART_SUCCESS;
    00513 }

__inline__ void usart_iso7816_enable_receiver | ( | volatile avr32_usart_t * | usart | ) |

Enables the ISO7816 receiver.

The ISO7816 transmitter is disabled.

Parameters:

  | usart | Base address of the USART instance.

Definition at line 484 of file usart.h.

Referenced by usart_init_iso7816().

    00485 {
    00486   usart->cr = AVR32_USART_CR_TXDIS_MASK | AVR32_USART_CR_RXEN_MASK;
    00487 }

__inline__ void usart_iso7816_enable_transmitter | ( | volatile avr32_usart_t * | usart | ) |

Enables the ISO7816 transmitter.

The ISO7816 receiver is disabled.

Parameters:

  | usart | Base address of the USART instance.

Definition at line 498 of file usart.h.

    00499 {
    00500   usart->cr = AVR32_USART_CR_RXDIS_MASK | AVR32_USART_CR_TXEN_MASK;
    00501 }

__inline__ int usart_overrun_error | ( | volatile avr32_usart_t * | usart | ) |

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

Definition at line 438 of file usart.h.

    00439 {
    00440   return (usart->csr & AVR32_USART_CSR_OVRE_MASK) != 0;
    00441 }

__inline__ int usart_parity_error | ( | volatile avr32_usart_t * | usart | ) |

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

Definition at line 410 of file usart.h.

    00411 {
    00412   return (usart->csr & AVR32_USART_CSR_PARE_MASK) != 0;
    00413 }

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.

Definition at line 806 of file usart.c.

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

Referenced by usart_get_echo_line(), and usart_write_line().

    00807 {
    00808   int timeout = USART_DEFAULT_TIMEOUT;
    00809
    00810   if (c == '\n')
    00811   {
    00812     do
    00813     {
    00814       if (!timeout--) return USART_FAILURE;
    00815     } while (usart_write_char(usart, '\r') != USART_SUCCESS);
    00816
    00817     timeout = USART_DEFAULT_TIMEOUT;
    00818   }
    00819
    00820   do
    00821   {
    00822     if (!timeout--) return USART_FAILURE;
    00823   } while (usart_write_char(usart, c) != USART_SUCCESS);
    00824
    00825   return USART_SUCCESS;
    00826 }

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

Definition at line 829 of file usart.c.

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

Referenced by usart_getchar().

    00830 {
    00831   // Check for errors: frame, parity and overrun. In RS485 mode, a parity error
    00832   // would mean that an address char has been received.
    00833   if (usart->csr & (AVR32_USART_CSR_OVRE_MASK |
    00834                     AVR32_USART_CSR_FRAME_MASK |
    00835                     AVR32_USART_CSR_PARE_MASK))
    00836     return USART_RX_ERROR;
    00837
    00838   // No error; if we really did receive a char, read it and return SUCCESS.
    00839   if (usart_test_hit(usart))
    00840   {
    00841     *c = (usart->rhr & AVR32_USART_RHR_RXCHR_MASK) >> AVR32_USART_RHR_RXCHR_OFFSET;
    00842     return USART_SUCCESS;
    00843   }
    00844   else
    00845     return USART_RX_EMPTY;
    00846 }

void usart_reset | ( | volatile avr32_usart_t * | usart | ) |

Resets the USART and disables TX and RX.

Parameters:

  | usart | Base address of the USART instance.

Definition at line 251 of file usart.c.

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

    00252 {
    00253   Bool global_interrupt_enabled = Is_global_interrupt_enabled();
    00254
    00255   // Disable all USART interrupts.
    00256   // Interrupts needed should be set explicitly on every reset.
    00257   if (global_interrupt_enabled) Disable_global_interrupt();
    00258   usart->idr = 0xFFFFFFFF;
    00259   usart->csr;
    00260   if (global_interrupt_enabled) Enable_global_interrupt();
    00261
    00262   // Reset mode and other registers that could cause unpredictable behavior after reset.
    00263   usart->mr = 0;
    00264   usart->rtor = 0;
    00265   usart->ttgr = 0;
    00266
    00267   // Shutdown TX and RX (will be re-enabled when setup has successfully completed),
    00268   // reset status bits and turn off DTR and RTS.
    00269   usart->cr = AVR32_USART_CR_RSTRX_MASK   |
    00270               AVR32_USART_CR_RSTTX_MASK   |
    00271               AVR32_USART_CR_RSTSTA_MASK  |
    00272               AVR32_USART_CR_RSTIT_MASK   |
    00273               AVR32_USART_CR_RSTNACK_MASK |
    00274               AVR32_USART_CR_DTRDIS_MASK  |
    00275               AVR32_USART_CR_RTSDIS_MASK;
    00276 }

__inline__ void usart_reset_status | ( | volatile avr32_usart_t * | usart | ) |

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.

Definition at line 396 of file usart.h.

    00397 {
    00398   usart->cr = AVR32_USART_CR_RSTSTA_MASK;
    00399 }

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.

Definition at line 779 of file usart.c.

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

    00780 {
    00781   // Check if USART is in multidrop / RS485 mode.
    00782   if (!usart_mode_is_multidrop(usart)) return USART_MODE_FAULT;
    00783
    00784   // Prepare to send an address.
    00785   usart->cr = AVR32_USART_CR_SENDA_MASK;
    00786
    00787   // Write the address to TX.
    00788   usart_bw_write_char(usart, address);
    00789
    00790   return USART_SUCCESS;
    00791 }

__inline__ int usart_test_hit | ( | volatile avr32_usart_t * | usart | ) |

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

Definition at line 793 of file usart.h.

Referenced by usart_read_char().

    00794 {
    00795   return (usart->csr & AVR32_USART_CSR_RXRDY_MASK) != 0;
    00796 }

__inline__ int usart_tx_empty | ( | volatile avr32_usart_t * | usart | ) |

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

Definition at line 779 of file usart.h.

    00780 {
    00781   return (usart->csr & AVR32_USART_CSR_TXEMPTY_MASK) != 0;
    00782 }

__inline__ int usart_tx_ready | ( | volatile avr32_usart_t * | usart | ) |

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

Definition at line 731 of file usart.h.

Referenced by usart_write_char().

    00732 {
    00733   return (usart->csr & AVR32_USART_CSR_TXRDY_MASK) != 0;
    00734 }

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.

Definition at line 794 of file usart.c.

References USART_SUCCESS, USART_TX_BUSY, and usart_tx_ready().

Referenced by usart_bw_write_char(), and usart_putchar().

    00795 {
    00796   if (usart_tx_ready(usart))
    00797   {
    00798     usart->thr = (c << AVR32_USART_THR_TXCHR_OFFSET) & AVR32_USART_THR_TXCHR_MASK;
    00799     return USART_SUCCESS;
    00800   }
    00801   else
    00802     return USART_TX_BUSY;
    00803 }

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.

Definition at line 862 of file usart.c.

References usart_putchar().

Referenced by main(), and usart_get_echo_line().

    00863 {
    00864   while (*string != '\0')
    00865     usart_putchar(usart, *string++);
    00866 }