Xmega Application Note


usart_driver.h File Reference


Detailed Description

XMEGA USART driver header file.

This file contains the function prototypes and enumerator definitions for various configuration parameters for the XMEGA USART driver.

The driver is not intended for size and/or speed critical code, since most functions are just a few lines of code, and the function call overhead would decrease code performance. The driver is intended for rapid prototyping and documentation purposes for getting started with the XMEGA ADC module.

For size and/or speed critical code, it is recommended to copy the function contents directly into your application instead of making a function call.

Application note:
AVR1307: Using the XMEGA USART
Documentation
For comprehensive code documentation, supported compilers, compiler settings and supported devices see readme.html
Author:
Atmel Corporation: http://www.atmel.com
Support email: avr@atmel.com
Revision
1694
Date
2008-07-29 14:21:58 +0200 (ti, 29 jul 2008)

Copyright (c) 2008, Atmel Corporation All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name of ATMEL may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file usart_driver.h.

#include "avr_compiler.h"

Include dependency graph for usart_driver.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  Usart_and_buffer
 Struct used when interrupt driven driver is used. More...
struct  USART_Buffer

Defines

#define USART_Baudrate_Set(_usart, _bselValue, _bScaleFactor)
 Set USART baud rate.
#define USART_DreInterruptLevel_Set(_usart, _dreIntLevel)   (_usart)->CTRLA = ((_usart)->CTRLA & ~USART_DREINTLVL_gm) | _dreIntLevel
 Set USART DRE interrupt level.
#define USART_Format_Set(_usart, _charSize, _parityMode, _twoStopBits)
 Macro that sets the USART frame format.
#define USART_GetChar(_usart)   ((_usart)->DATA)
 Get received data (5-8 bit character).
#define USART_IsRXComplete(_usart)   (((_usart)->STATUS & USART_RXCIF_bm) != 0)
 Checks if the RX complete interrupt flag is set.
#define USART_IsTXDataRegisterEmpty(_usart)   (((_usart)->STATUS & USART_DREIF_bm) != 0)
 Check if data register empty flag is set.
#define USART_PutChar(_usart, _data)   ((_usart)->DATA = _data)
 Put data (5-8 bit character).
#define USART_RX_BUFFER_MASK   ( USART_RX_BUFFER_SIZE - 1 )
#define USART_RX_BUFFER_SIZE   4
#define USART_Rx_Disable(_usart)   ((_usart)->CTRLB &= ~USART_RXEN_bm)
 Disable USART receiver.
#define USART_Rx_Enable(_usart)   ((_usart)->CTRLB |= USART_RXEN_bm)
 Enable USART receiver.
#define USART_RxdInterruptLevel_Set(_usart, _rxdIntLevel)   ((_usart)->CTRLA = ((_usart)->CTRLA & ~USART_RXCINTLVL_gm) | _rxdIntLevel)
 Set USART RXD interrupt level.
#define USART_SetMode(_usart, _usartMode)   ((_usart)->CTRLC = ((_usart)->CTRLC & (~USART_CMODE_gm)) | _usartMode)
 Set the mode the USART run in.
#define USART_TX_BUFFER_MASK   ( USART_TX_BUFFER_SIZE - 1 )
#define USART_TX_BUFFER_SIZE   4
#define USART_Tx_Disable(_usart)   ((_usart)->CTRLB &= ~USART_TXEN_bm)
 Disable USART transmitter.
#define USART_Tx_Enable(_usart)   ((_usart)->CTRLB |= USART_TXEN_bm)
 Enable USART transmitter.
#define USART_TxdInterruptLevel_Set(_usart, _txdIntLevel)   (_usart)->CTRLA = ((_usart)->CTRLA & ~USART_TXCINTLVL_gm) | _txdIntLevel
 Set USART TXD interrupt level.

Typedefs

typedef struct USART_Buffer USART_Buffer_t
typedef struct Usart_and_buffer USART_data_t

Functions

void USART_DataRegEmpty (USART_data_t *usart_data)
 Data Register Empty Interrupt Service Routine.
void USART_InterruptDriver_DreInterruptLevel_Set (USART_data_t *usart_data, USART_DREINTLVL_t dreIntLevel)
 Set USART DRE interrupt level.
void USART_InterruptDriver_Initialize (USART_data_t *usart_data, USART_t *usart, USART_DREINTLVL_t dreIntLevel)
 Initializes buffer and selects what USART module to use.
uint16_t USART_NineBits_GetChar (USART_t *usart)
 Get received data (9 bit character).
void USART_NineBits_PutChar (USART_t *usart, uint16_t data)
 Put data (9 bit character).
uint8_t USART_RXBuffer_GetByte (USART_data_t *usart_data)
 Get received data (5-8 bit character).
bool USART_RXBufferData_Available (USART_data_t *usart_data)
 Test if there is data in the receive software buffer.
bool USART_RXComplete (USART_data_t *usart_data)
 RX Complete Interrupt Service Routine.
bool USART_TXBuffer_FreeSpace (USART_data_t *usart_data)
 Test if there is data in the transmitter software buffer.
bool USART_TXBuffer_PutByte (USART_data_t *usart_data, uint8_t data)
 Put data (5-8 bit character).


Define Documentation

#define USART_Baudrate_Set ( _usart,
_bselValue,
_bScaleFactor   ) 

Value:

(_usart)->BAUDCTRLA =(uint8_t)_bselValue;                                           \
        (_usart)->BAUDCTRLB =(_bScaleFactor << USART_BSCALE0_bp)|(_bselValue >> 8)
Set USART baud rate.

Sets the USART's baud rate register.

UBRR_Value : Value written to UBRR ScaleFactor : Time Base Generator Scale Factor

Equation for calculation of BSEL value in asynchronous normal speed mode: If ScaleFactor >= 0 BSEL = ((I/O clock frequency)/(2^(ScaleFactor)*16*Baudrate))-1 If ScaleFactor < 0 BSEL = (1/(2^(ScaleFactor)*16))*(((I/O clock frequency)/Baudrate)-1)

Note:
See XMEGA manual for equations for calculation of BSEL value in other modes.
Parameters:
_usart Pointer to the USART module.
_bselValue Value to write to BSEL part of Baud control register. Use uint16_t type.
_bScaleFactor USART baud rate scale factor. Use uint8_t type

Definition at line 156 of file usart_driver.h.

Referenced by main().

#define USART_DreInterruptLevel_Set ( _usart,
_dreIntLevel   )     (_usart)->CTRLA = ((_usart)->CTRLA & ~USART_DREINTLVL_gm) | _dreIntLevel

Set USART DRE interrupt level.

Sets the interrupt level on Data Register interrupt.

Parameters:
_usart Pointer to the USART module.
_dreIntLevel Interrupt level of the DRE interrupt. Use USART_DREINTLVL_t type.

Definition at line 222 of file usart_driver.h.

#define USART_Format_Set ( _usart,
_charSize,
_parityMode,
_twoStopBits   ) 

Value:

(_usart)->CTRLC = (uint8_t) _charSize | _parityMode |                      \
                          (_twoStopBits ? USART_SBMODE_bm : 0)
Macro that sets the USART frame format.

Sets the frame format, Frame Size, parity mode and number of stop bits.

Parameters:
_usart Pointer to the USART module
_charSize The character size. Use USART_CHSIZE_t type.
_parityMode The parity Mode. Use USART_PMODE_t type.
_twoStopBits Enable two stop bit mode. Use bool type.

Definition at line 129 of file usart_driver.h.

Referenced by main().

#define USART_GetChar ( _usart   )     ((_usart)->DATA)

Get received data (5-8 bit character).

This macro reads out the RX register. Use the macro USART_RX_Complete to check if anything is received.

Parameters:
_usart The USART module.
Return values:
Received data.

Definition at line 284 of file usart_driver.h.

Referenced by main().

#define USART_IsRXComplete ( _usart   )     (((_usart)->STATUS & USART_RXCIF_bm) != 0)

Checks if the RX complete interrupt flag is set.

Checks if the RX complete interrupt flag is set.

Parameters:
_usart The USART module.

Definition at line 270 of file usart_driver.h.

Referenced by main().

#define USART_IsTXDataRegisterEmpty ( _usart   )     (((_usart)->STATUS & USART_DREIF_bm) != 0)

Check if data register empty flag is set.

Parameters:
_usart The USART module.

Definition at line 248 of file usart_driver.h.

Referenced by main().

#define USART_PutChar ( _usart,
_data   )     ((_usart)->DATA = _data)

Put data (5-8 bit character).

Use the macro USART_IsTXDataRegisterEmpty before using this function to put data to the TX register.

Parameters:
_usart The USART module.
_data The data to send.

Definition at line 260 of file usart_driver.h.

Referenced by main().

#define USART_RX_BUFFER_MASK   ( USART_RX_BUFFER_SIZE - 1 )

Definition at line 71 of file usart_driver.h.

Referenced by USART_RXBuffer_GetByte(), and USART_RXComplete().

#define USART_RX_BUFFER_SIZE   4

Definition at line 67 of file usart_driver.h.

#define USART_Rx_Disable ( _usart   )     ((_usart)->CTRLB &= ~USART_RXEN_bm)

Disable USART receiver.

Parameters:
_usart Pointer to the USART module.

Definition at line 172 of file usart_driver.h.

Referenced by main().

#define USART_Rx_Enable ( _usart   )     ((_usart)->CTRLB |= USART_RXEN_bm)

Enable USART receiver.

Parameters:
_usart Pointer to the USART module

Definition at line 165 of file usart_driver.h.

Referenced by main().

#define USART_RxdInterruptLevel_Set ( _usart,
_rxdIntLevel   )     ((_usart)->CTRLA = ((_usart)->CTRLA & ~USART_RXCINTLVL_gm) | _rxdIntLevel)

Set USART RXD interrupt level.

Sets the interrupt level on RX Complete interrupt.

Parameters:
_usart Pointer to the USART module.
_rxdIntLevel Interrupt level of the RXD interrupt. Use USART_RXCINTLVL_t type.

Definition at line 197 of file usart_driver.h.

Referenced by main().

#define USART_SetMode ( _usart,
_usartMode   )     ((_usart)->CTRLC = ((_usart)->CTRLC & (~USART_CMODE_gm)) | _usartMode)

Set the mode the USART run in.

Set the mode the USART run in. The default mode is asynchronous mode.

Parameters:
_usart Pointer to the USART module register section.
_usartMode Selects the USART mode. Use USART_CMODE_t type.
USART modes:
  • 0x0 : Asynchronous mode.
  • 0x1 : Synchronous mode.
  • 0x2 : IrDA mode.
  • 0x3 : Master SPI mode.

Definition at line 239 of file usart_driver.h.

#define USART_TX_BUFFER_MASK   ( USART_TX_BUFFER_SIZE - 1 )

#define USART_TX_BUFFER_SIZE   4

Definition at line 69 of file usart_driver.h.

#define USART_Tx_Disable ( _usart   )     ((_usart)->CTRLB &= ~USART_TXEN_bm)

Disable USART transmitter.

Parameters:
_usart Pointer to the USART module.

Definition at line 186 of file usart_driver.h.

Referenced by main().

#define USART_Tx_Enable ( _usart   )     ((_usart)->CTRLB |= USART_TXEN_bm)

Enable USART transmitter.

Parameters:
_usart Pointer to the USART module.

Definition at line 179 of file usart_driver.h.

Referenced by main().

#define USART_TxdInterruptLevel_Set ( _usart,
_txdIntLevel   )     (_usart)->CTRLA = ((_usart)->CTRLA & ~USART_TXCINTLVL_gm) | _txdIntLevel

Set USART TXD interrupt level.

Sets the interrupt level on TX Complete interrupt.

Parameters:
_usart Pointer to the USART module.
_txdIntLevel Interrupt level of the TXD interrupt. Use USART_TXCINTLVL_t type.

Definition at line 209 of file usart_driver.h.


Typedef Documentation

typedef struct USART_Buffer USART_Buffer_t


Function Documentation

void USART_DataRegEmpty ( USART_data_t usart_data  ) 

Data Register Empty Interrupt Service Routine.

Data Register Empty Interrupt Service Routine. Transmits one byte from TX software buffer. Disables DRE interrupt if buffer is empty. Argument is pointer to USART (USART_data_t).

Parameters:
usart_data The USART_data_t struct instance.

Definition at line 260 of file usart_driver.c.

References Usart_and_buffer::buffer, USART_Buffer::TX, USART_Buffer::TX_Head, USART_Buffer::TX_Tail, Usart_and_buffer::usart, and USART_TX_BUFFER_MASK.

Referenced by ISR().

00261 {
00262         USART_Buffer_t * bufPtr;
00263         bufPtr = &usart_data->buffer;
00264 
00265         /* Check if all data is transmitted. */
00266         uint8_t tempTX_Tail = usart_data->buffer.TX_Tail;
00267         if (bufPtr->TX_Head == tempTX_Tail){
00268             /* Disable DRE interrupts. */
00269                 uint8_t tempCTRLA = usart_data->usart->CTRLA;
00270                 tempCTRLA = (tempCTRLA & ~USART_DREINTLVL_gm) | USART_DREINTLVL_OFF_gc;
00271                 usart_data->usart->CTRLA = tempCTRLA;
00272 
00273         }else{
00274                 /* Start transmitting. */
00275                 uint8_t data = bufPtr->TX[usart_data->buffer.TX_Tail];
00276                 usart_data->usart->DATA = data;
00277 
00278                 /* Advance buffer tail. */
00279                 bufPtr->TX_Tail = (bufPtr->TX_Tail + 1) & USART_TX_BUFFER_MASK;
00280         }
00281 }

void USART_InterruptDriver_DreInterruptLevel_Set ( USART_data_t usart_data,
USART_DREINTLVL_t  dreIntLevel 
)

Set USART DRE interrupt level.

Set the interrupt level on Data Register interrupt.

Note:
Changing the DRE interrupt level in the interrupt driver while it is running will not change the DRE interrupt level in the USART before the DRE interrupt have been disabled and enabled again.
Parameters:
usart_data The USART_data_t struct instance
dreIntLevel Interrupt level of the DRE interrupt.

Definition at line 106 of file usart_driver.c.

References Usart_and_buffer::dreIntLevel.

00108 {
00109         usart_data->dreIntLevel = dreIntLevel;
00110 }

void USART_InterruptDriver_Initialize ( USART_data_t usart_data,
USART_t *  usart,
USART_DREINTLVL_t  dreIntLevel 
)

Initializes buffer and selects what USART module to use.

Initializes receive and transmit buffer and selects what USART module to use, and stores the data register empty interrupt level.

Parameters:
usart_data The USART_data_t struct instance.
usart The USART module.
dreIntLevel Data register empty interrupt level.

Definition at line 81 of file usart_driver.c.

References Usart_and_buffer::buffer, Usart_and_buffer::dreIntLevel, USART_Buffer::RX_Head, USART_Buffer::RX_Tail, USART_Buffer::TX_Head, USART_Buffer::TX_Tail, and Usart_and_buffer::usart.

Referenced by main().

00084 {
00085         usart_data->usart = usart;
00086         usart_data->dreIntLevel = dreIntLevel;
00087 
00088         usart_data->buffer.RX_Tail = 0;
00089         usart_data->buffer.RX_Head = 0;
00090         usart_data->buffer.TX_Tail = 0;
00091         usart_data->buffer.TX_Head = 0;
00092 }

uint16_t USART_NineBits_GetChar ( USART_t *  usart  ) 

Get received data (9 bit character).

This function reads out the received 9 bit character (uint16_t). Use the function USART_IsRXComplete to check if anything is received.

Parameters:
usart The USART module.
Return values:
Received data.

Definition at line 313 of file usart_driver.c.

00314 {
00315         if(usart->CTRLB & USART_RXB8_bm) {
00316                 return(0x0100 | usart->DATA);
00317         }else {
00318                 return(usart->DATA);
00319         }
00320 }

void USART_NineBits_PutChar ( USART_t *  usart,
uint16_t  data 
)

Put data (9 bit character).

Use the function USART_IsTXDataRegisterEmpty before using this function to put 9 bit character to the TX register.

Parameters:
usart The USART module.
data The data to send.

Definition at line 292 of file usart_driver.c.

00293 {
00294         if(data & 0x0100) {
00295                 usart->CTRLB |= USART_TXB8_bm;
00296         }else {
00297                 usart->CTRLB &= ~USART_TXB8_bm;
00298         }
00299 
00300         usart->DATA = (data & 0x00FF);
00301 }

uint8_t USART_RXBuffer_GetByte ( USART_data_t usart_data  ) 

Get received data (5-8 bit character).

The function USART_RXBufferData_Available should be used before this function is used to ensure that data is available.

Returns data from RX software buffer.

Parameters:
usart_data The USART_data_t struct instance.
Returns:
Received data.

Definition at line 204 of file usart_driver.c.

References Usart_and_buffer::buffer, USART_Buffer::RX, USART_Buffer::RX_Tail, and USART_RX_BUFFER_MASK.

Referenced by main().

00205 {
00206         USART_Buffer_t * bufPtr;
00207         uint8_t ans;
00208 
00209         bufPtr = &usart_data->buffer;
00210         ans = (bufPtr->RX[bufPtr->RX_Tail]);
00211 
00212         /* Advance buffer tail. */
00213         bufPtr->RX_Tail = (bufPtr->RX_Tail + 1) & USART_RX_BUFFER_MASK;
00214 
00215         return ans;
00216 }

bool USART_RXBufferData_Available ( USART_data_t usart_data  ) 

Test if there is data in the receive software buffer.

This function can be used to test if there is data in the receive software buffer.

Parameters:
usart_data The USART_data_t struct instance
Return values:
true There is data in the receive buffer.
false The receive buffer is empty.

Definition at line 181 of file usart_driver.c.

References Usart_and_buffer::buffer, USART_Buffer::RX_Head, and USART_Buffer::RX_Tail.

Referenced by main().

00182 {
00183         /* Make copies to make sure that volatile access is specified. */
00184         uint8_t tempHead = usart_data->buffer.RX_Head;
00185         uint8_t tempTail = usart_data->buffer.RX_Tail;
00186 
00187         /* There are data left in the buffer unless Head and Tail are equal. */
00188         return (tempHead != tempTail);
00189 }

bool USART_RXComplete ( USART_data_t usart_data  ) 

RX Complete Interrupt Service Routine.

RX Complete Interrupt Service Routine. Stores received data in RX software buffer.

Parameters:
usart_data The USART_data_t struct instance.

Definition at line 227 of file usart_driver.c.

References Usart_and_buffer::buffer, USART_Buffer::RX, USART_Buffer::RX_Head, USART_Buffer::RX_Tail, Usart_and_buffer::usart, and USART_RX_BUFFER_MASK.

Referenced by ISR().

00228 {
00229         USART_Buffer_t * bufPtr;
00230         bool ans;
00231 
00232         bufPtr = &usart_data->buffer;
00233         /* Advance buffer head. */
00234         uint8_t tempRX_Head = (bufPtr->RX_Head + 1) & USART_RX_BUFFER_MASK;
00235 
00236         /* Check for overflow. */
00237         uint8_t tempRX_Tail = bufPtr->RX_Tail;
00238         uint8_t data = usart_data->usart->DATA;
00239 
00240         if (tempRX_Head == tempRX_Tail) {
00241                 ans = false;
00242         }else{
00243                 ans = true;
00244                 usart_data->buffer.RX[usart_data->buffer.RX_Head] = data;
00245                 usart_data->buffer.RX_Head = tempRX_Head;
00246         }
00247         return ans;
00248 }

bool USART_TXBuffer_FreeSpace ( USART_data_t usart_data  ) 

Test if there is data in the transmitter software buffer.

This function can be used to test if there is free space in the transmitter software buffer.

Parameters:
usart_data The USART_data_t struct instance.
Return values:
true There is data in the receive buffer.
false The receive buffer is empty.

Definition at line 123 of file usart_driver.c.

References Usart_and_buffer::buffer, USART_Buffer::TX_Head, USART_Buffer::TX_Tail, and USART_TX_BUFFER_MASK.

Referenced by USART_TXBuffer_PutByte().

00124 {
00125         /* Make copies to make sure that volatile access is specified. */
00126         uint8_t tempHead = (usart_data->buffer.TX_Head + 1) & USART_TX_BUFFER_MASK;
00127         uint8_t tempTail = usart_data->buffer.TX_Tail;
00128 
00129         /* There are data left in the buffer unless Head and Tail are equal. */
00130         return (tempHead != tempTail);
00131 }

bool USART_TXBuffer_PutByte ( USART_data_t usart_data,
uint8_t  data 
)

Put data (5-8 bit character).

Stores data byte in TX software buffer and enables DRE interrupt if there is free space in the TX software buffer.

Parameters:
usart_data The USART_data_t struct instance.
data The data to send.

Definition at line 143 of file usart_driver.c.

References Usart_and_buffer::buffer, Usart_and_buffer::dreIntLevel, USART_Buffer::TX, USART_Buffer::TX_Head, Usart_and_buffer::usart, USART_TX_BUFFER_MASK, and USART_TXBuffer_FreeSpace().

Referenced by main().

00144 {
00145         uint8_t tempCTRLA;
00146         uint8_t tempTX_Head;
00147         bool TXBuffer_FreeSpace;
00148         USART_Buffer_t * TXbufPtr;
00149 
00150         TXbufPtr = &usart_data->buffer;
00151         TXBuffer_FreeSpace = USART_TXBuffer_FreeSpace(usart_data);
00152 
00153 
00154         if(TXBuffer_FreeSpace)
00155         {
00156                 tempTX_Head = TXbufPtr->TX_Head;
00157                 TXbufPtr->TX[tempTX_Head]= data;
00158                 /* Advance buffer head. */
00159                 TXbufPtr->TX_Head = (tempTX_Head + 1) & USART_TX_BUFFER_MASK;
00160 
00161                 /* Enable DRE interrupt. */
00162                 tempCTRLA = usart_data->usart->CTRLA;
00163                 tempCTRLA = (tempCTRLA & ~USART_DREINTLVL_gm) | usart_data->dreIntLevel;
00164                 usart_data->usart->CTRLA = tempCTRLA;
00165         }
00166         return TXBuffer_FreeSpace;
00167 }

Here is the call graph for this function:

@DOC_TITLE@
Generated on Wed Nov 5 10:23:27 2008 for AVRxxxx Application note title by doxygen 1.5.5