Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

uart.h

Go to the documentation of this file.
00001 /*! \file uart.h \brief UART driver with buffer support. */
00002 //*****************************************************************************
00003 //
00004 // File Name    : 'uart.h'
00005 // Title        : UART driver with buffer support
00006 // Author       : Pascal Stang - Copyright (C) 2000-2002
00007 // Created      : 11/22/2000
00008 // Revised      : 02/01/2004
00009 // Version      : 1.3
00010 // Target MCU   : ATMEL AVR Series
00011 // Editor Tabs  : 4
00012 //
00013 // This code is distributed under the GNU Public License
00014 //      which can be found at http://www.gnu.org/licenses/gpl.txt
00015 //
00016 /// \ingroup driver_avr
00017 /// \defgroup uart UART Driver/Function Library (uart.c)
00018 /// \code #include "uart.h" \endcode
00019 /// \par Overview
00020 ///     This library provides both buffered and unbuffered transmit and receive
00021 ///     functions for the AVR processor UART.  Buffered access means that the
00022 ///     UART can transmit and receive data in the "background", while your code
00023 ///     continues executing.  Also included are functions to initialize the
00024 ///     UART, set the baud rate, flush the buffers, and check buffer status.
00025 ///
00026 /// \note   For full text output functionality, you may wish to use the rprintf
00027 ///     functions along with this driver.
00028 ///
00029 /// \par About UART operations
00030 ///     Most Atmel AVR-series processors contain one or more hardware UARTs
00031 ///     (aka, serial ports).  UART serial ports can communicate with other 
00032 ///     serial ports of the same type, like those used on PCs.  In general,
00033 ///     UARTs are used to communicate with devices that are RS-232 compatible
00034 ///     (RS-232 is a certain kind of serial port).
00035 /// \par
00036 ///     By far, the most common use for serial communications on AVR processors
00037 ///     is for sending information and data to a PC running a terminal program.
00038 ///     Here is an exmaple:
00039 /// \code
00040 /// uartInit();                 // initialize UART (serial port)
00041 /// uartSetBaudRate(9600);      // set UART speed to 9600 baud
00042 /// rprintfInit(uartSendByte);  // configure rprintf to use UART for output
00043 /// rprintf("Hello World\r\n"); // send "hello world" message via serial port
00044 /// \endcode
00045 ///
00046 /// \warning The CPU frequency (F_CPU) must be set correctly in \c global.h
00047 ///     for the UART library to calculate correct baud rates.  Furthermore,
00048 ///     certain CPU frequencies will not produce exact baud rates due to
00049 ///     integer frequency division round-off.  See your AVR processor's
00050 ///      datasheet for full details.
00051 //
00052 //*****************************************************************************
00053 //@{
00054 
00055 #ifndef UART_H
00056 #define UART_H
00057 
00058 #include "global.h"
00059 #include "buffer.h"
00060 
00061 //! Default uart baud rate.
00062 /// This is the default speed after a uartInit() command,
00063 /// and can be changed by using uartSetBaudRate().
00064 #define UART_DEFAULT_BAUD_RATE  9600
00065 
00066 // buffer memory allocation defines
00067 // buffer sizes
00068 #ifndef UART_TX_BUFFER_SIZE
00069 //! Number of bytes for uart transmit buffer.
00070 /// Do not change this value in uart.h, but rather override
00071 /// it with the desired value defined in your project's global.h
00072 #define UART_TX_BUFFER_SIZE     0x0040
00073 #endif
00074 #ifndef UART_RX_BUFFER_SIZE
00075 //! Number of bytes for uart receive buffer.
00076 /// Do not change this value in uart.h, but rather override
00077 /// it with the desired value defined in your project's global.h
00078 #define UART_RX_BUFFER_SIZE     0x0040
00079 #endif
00080 
00081 // define this key if you wish to use
00082 // external RAM for the UART buffers
00083 //#define UART_BUFFER_EXTERNAL_RAM
00084 #ifdef UART_BUFFER_EXTERNAL_RAM
00085     // absolute address of uart buffers
00086     #define UART_TX_BUFFER_ADDR 0x1000
00087     #define UART_RX_BUFFER_ADDR 0x1100
00088 #endif
00089 
00090 //! Type of interrupt handler to use for uart interrupts.
00091 /// Value may be SIGNAL or INTERRUPT.
00092 /// \warning Do not change unless you know what you're doing.
00093 #ifndef UART_INTERRUPT_HANDLER
00094 #define UART_INTERRUPT_HANDLER  SIGNAL
00095 #endif
00096 
00097 // compatibility with most newer processors
00098 #ifdef UCSRB
00099     #define UCR                 UCSRB
00100 #endif
00101 // compatibility with old Mega processors
00102 #if defined(UBRR) && !defined(UBRRL)
00103     #define UBRRL               UBRR
00104 #endif
00105 // compatibility with megaXX8 processors
00106 #if defined(__AVR_ATmega88__)   || \
00107     defined(__AVR_ATmega168__)
00108     #define UDR                 UDR0
00109     #define UCR                 UCSR0B
00110     #define RXCIE               RXCIE0
00111     #define TXCIE               TXCIE0
00112     #define RXC                 RXC0
00113     #define TXC                 TXC0
00114     #define RXEN                RXEN0
00115     #define TXEN                TXEN0
00116     #define UBRRL               UBRR0L
00117     #define UBRRH               UBRR0H
00118     #define SIG_UART_TRANS      SIG_USART_TRANS
00119     #define SIG_UART_RECV       SIG_USART_RECV
00120     #define SIG_UART_DATA       SIG_USART_DATA
00121 #endif
00122 // compatibility with mega169 processors
00123 #if defined(__AVR_ATmega169__)
00124     #define SIG_UART_TRANS      SIG_USART_TRANS
00125     #define SIG_UART_RECV       SIG_USART_RECV
00126     #define SIG_UART_DATA       SIG_USART_DATA
00127 #endif
00128 // compatibility with dual-uart processors
00129 // (if you need to use both uarts, please use the uart2 library)
00130 #if defined(__AVR_ATmega161__)
00131     #define UDR                 UDR0
00132     #define UCR                 UCSR0B
00133     #define UBRRL               UBRR0
00134     #define SIG_UART_TRANS      SIG_UART0_TRANS
00135     #define SIG_UART_RECV       SIG_UART0_RECV
00136     #define SIG_UART_DATA       SIG_UART0_DATA
00137 #endif
00138 #if defined(__AVR_ATmega128__)
00139 #ifdef UART_USE_UART1
00140     #define UDR                 UDR1
00141     #define UCR                 UCSR1B
00142     #define UBRRL               UBRR1L
00143     #define UBRRH               UBRR1H
00144     #define SIG_UART_TRANS      SIG_UART1_TRANS
00145     #define SIG_UART_RECV       SIG_UART1_RECV
00146     #define SIG_UART_DATA       SIG_UART1_DATA
00147 #else
00148     #define UDR                 UDR0
00149     #define UCR                 UCSR0B
00150     #define UBRRL               UBRR0L
00151     #define UBRRH               UBRR0H
00152     #define SIG_UART_TRANS      SIG_UART0_TRANS
00153     #define SIG_UART_RECV       SIG_UART0_RECV
00154     #define SIG_UART_DATA       SIG_UART0_DATA
00155 #endif
00156 #endif
00157 
00158 // functions
00159 
00160 //! Initializes uart.
00161 /// \note   After running this init function, the processor
00162 /// I/O pins that used for uart communications (RXD, TXD)
00163 /// are no long available for general purpose I/O.
00164 void uartInit(void);
00165 
00166 //! Initializes transmit and receive buffers.
00167 /// Automatically called from uartInit()
00168 void uartInitBuffers(void);
00169 
00170 //! Redirects received data to a user function.
00171 ///
00172 void uartSetRxHandler(void (*rx_func)(unsigned char c));
00173 
00174 //! Sets the uart baud rate.
00175 /// Argument should be in bits-per-second, like \c uartSetBaudRate(9600);
00176 void uartSetBaudRate(u32 baudrate);
00177 
00178 //! Returns pointer to the receive buffer structure.
00179 ///
00180 cBuffer* uartGetRxBuffer(void);
00181 
00182 //! Returns pointer to the transmit buffer structure.
00183 ///
00184 cBuffer* uartGetTxBuffer(void);
00185 
00186 //! Sends a single byte over the uart.
00187 /// \note This function waits for the uart to be ready,
00188 /// therefore, consecutive calls to uartSendByte() will
00189 /// go only as fast as the data can be sent over the
00190 /// serial port.
00191 void uartSendByte(u08 data);
00192 
00193 //! Gets a single byte from the uart receive buffer.
00194 /// Returns the byte, or -1 if no byte is available (getchar-style).
00195 int uartGetByte(void);
00196 
00197 //! Gets a single byte from the uart receive buffer.
00198 /// Function returns TRUE if data was available, FALSE if not.
00199 /// Actual data is returned in variable pointed to by "data".
00200 /// Example usage:
00201 /// \code
00202 /// char myReceivedByte;
00203 /// uartReceiveByte( &myReceivedByte );
00204 /// \endcode
00205 u08 uartReceiveByte(u08* data);
00206 
00207 //! Returns TRUE/FALSE if receive buffer is empty/not-empty.
00208 ///
00209 u08 uartReceiveBufferIsEmpty(void);
00210 
00211 //! Flushes (deletes) all data from receive buffer.
00212 ///
00213 void uartFlushReceiveBuffer(void);
00214 
00215 //! Add byte to end of uart Tx buffer.
00216 /// Returns TRUE if successful, FALSE if failed (no room left in buffer).
00217 u08 uartAddToTxBuffer(u08 data);
00218 
00219 //! Begins transmission of the transmit buffer under interrupt control.
00220 ///
00221 void uartSendTxBuffer(void);
00222 
00223 //! Sends a block of data via the uart using interrupt control.
00224 /// \param buffer   pointer to data to be sent
00225 /// \param nBytes   length of data (number of bytes to sent)
00226 u08  uartSendBuffer(char *buffer, u16 nBytes);
00227 
00228 #endif
00229 //@}
00230 
00231 

Generated on Tue Sep 20 03:11:43 2005 for Procyon AVRlib by  doxygen 1.4.2