Rev Author Line No. Line
1269 kakl 1 /*! \file uart.h \brief UART driver with buffer support. */
2 //*****************************************************************************
3 //
4 // File Name : 'uart.h'
5 // Title : UART driver with buffer support
6 // Author : Pascal Stang - Copyright (C) 2000-2002
7 // Created : 11/22/2000
8 // Revised : 02/01/2004
9 // Version : 1.3
10 // Target MCU : ATMEL AVR Series
11 // Editor Tabs : 4
12 //
13 // This code is distributed under the GNU Public License
14 // which can be found at http://www.gnu.org/licenses/gpl.txt
15 //
16 /// \ingroup driver_avr
17 /// \defgroup uart UART Driver/Function Library (uart.c)
18 /// \code #include "uart.h" \endcode
19 /// \par Overview
20 /// This library provides both buffered and unbuffered transmit and receive
21 /// functions for the AVR processor UART.  Buffered access means that the
22 /// UART can transmit and receive data in the "background", while your code
23 /// continues executing.  Also included are functions to initialize the
24 /// UART, set the baud rate, flush the buffers, and check buffer status.
25 ///
26 /// \note For full text output functionality, you may wish to use the rprintf
27 /// functions along with this driver.
28 ///
29 /// \par About UART operations
30 /// Most Atmel AVR-series processors contain one or more hardware UARTs
31 /// (aka, serial ports). UART serial ports can communicate with other
32 /// serial ports of the same type, like those used on PCs. In general,
33 /// UARTs are used to communicate with devices that are RS-232 compatible
34 /// (RS-232 is a certain kind of serial port).
35 /// \par
36 /// By far, the most common use for serial communications on AVR processors
37 /// is for sending information and data to a PC running a terminal program.
38 /// Here is an exmaple:
39 /// \code
40 /// uartInit(); // initialize UART (serial port)
41 /// uartSetBaudRate(9600); // set UART speed to 9600 baud
42 /// rprintfInit(uartSendByte); // configure rprintf to use UART for output
43 /// rprintf("Hello World\r\n"); // send "hello world" message via serial port
44 /// \endcode
45 ///
46 /// \warning The CPU frequency (F_CPU) must be set correctly in \c global.h
47 /// for the UART library to calculate correct baud rates. Furthermore,
48 /// certain CPU frequencies will not produce exact baud rates due to
49 /// integer frequency division round-off. See your AVR processor's
50 /// datasheet for full details.
51 //
52 //*****************************************************************************
53 //@{
54  
55 #ifndef UART_H
56 #define UART_H
57  
58 #include "global.h"
59 #include "buffer.h"
60  
61 //! Default uart baud rate.
62 /// This is the default speed after a uartInit() command,
63 /// and can be changed by using uartSetBaudRate().
64 #define UART_DEFAULT_BAUD_RATE 9600
65  
66 // buffer memory allocation defines
67 // buffer sizes
68 #ifndef UART_TX_BUFFER_SIZE
69 //! Number of bytes for uart transmit buffer.
70 /// Do not change this value in uart.h, but rather override
71 /// it with the desired value defined in your project's global.h
72 #define UART_TX_BUFFER_SIZE 0x0040
73 #endif
74 #ifndef UART_RX_BUFFER_SIZE
75 //! Number of bytes for uart receive buffer.
76 /// Do not change this value in uart.h, but rather override
77 /// it with the desired value defined in your project's global.h
78 #define UART_RX_BUFFER_SIZE 0x0040
79 #endif
80  
81 // define this key if you wish to use
82 // external RAM for the UART buffers
83 //#define UART_BUFFER_EXTERNAL_RAM
84 #ifdef UART_BUFFER_EXTERNAL_RAM
85 // absolute address of uart buffers
86 #define UART_TX_BUFFER_ADDR 0x1000
87 #define UART_RX_BUFFER_ADDR 0x1100
88 #endif
89  
90 //! Type of interrupt handler to use for uart interrupts.
91 /// Value may be SIGNAL or INTERRUPT.
92 /// \warning Do not change unless you know what you're doing.
93 #ifndef UART_INTERRUPT_HANDLER
94 #define UART_INTERRUPT_HANDLER SIGNAL
95 #endif
96  
97 // compatibility with most newer processors
98 #ifdef UCSRB
99 #define UCR UCSRB
100 #endif
101 // compatibility with old Mega processors
102 #if defined(UBRR) && !defined(UBRRL)
103 #define UBRRL UBRR
104 #endif
105 // compatibility with megaXX8 processors
106 #if defined(__AVR_ATmega88__) || \
107 defined(__AVR_ATmega168__) || \
108 defined(__AVR_ATmega644__)
109 #define UDR UDR0
110 #define UCR UCSR0B
111 #define RXCIE RXCIE0
112 #define TXCIE TXCIE0
113 #define RXC RXC0
114 #define TXC TXC0
115 #define RXEN RXEN0
116 #define TXEN TXEN0
117 #define UBRRL UBRR0L
118 #define UBRRH UBRR0H
119 #define SIG_UART_TRANS SIG_USART_TRANS
120 #define SIG_UART_RECV SIG_USART_RECV
121 #define SIG_UART_DATA SIG_USART_DATA
122 #endif
123 // compatibility with mega169 processors
124 #if defined(__AVR_ATmega169__)
125 #define SIG_UART_TRANS SIG_USART_TRANS
126 #define SIG_UART_RECV SIG_USART_RECV
127 #define SIG_UART_DATA SIG_USART_DATA
128 #endif
129 // compatibility with dual-uart processors
130 // (if you need to use both uarts, please use the uart2 library)
131 #if defined(__AVR_ATmega161__)
132 #define UDR UDR0
133 #define UCR UCSR0B
134 #define UBRRL UBRR0
135 #define SIG_UART_TRANS SIG_UART0_TRANS
136 #define SIG_UART_RECV SIG_UART0_RECV
137 #define SIG_UART_DATA SIG_UART0_DATA
138 #endif
139 #if defined(__AVR_ATmega128__)
140 #ifdef UART_USE_UART1
141 #define UDR UDR1
142 #define UCR UCSR1B
143 #define UBRRL UBRR1L
144 #define UBRRH UBRR1H
145 #define SIG_UART_TRANS SIG_UART1_TRANS
146 #define SIG_UART_RECV SIG_UART1_RECV
147 #define SIG_UART_DATA SIG_UART1_DATA
148 #else
149 #define UDR UDR0
150 #define UCR UCSR0B
151 #define UBRRL UBRR0L
152 #define UBRRH UBRR0H
153 #define SIG_UART_TRANS SIG_UART0_TRANS
154 #define SIG_UART_RECV SIG_UART0_RECV
155 #define SIG_UART_DATA SIG_UART0_DATA
156 #endif
157 #endif
158  
159 // functions
160  
161 //! Initializes uart.
162 /// \note After running this init function, the processor
163 /// I/O pins that used for uart communications (RXD, TXD)
164 /// are no long available for general purpose I/O.
165 void uartInit(void);
166  
167 //! Initializes transmit and receive buffers.
168 /// Automatically called from uartInit()
169 void uartInitBuffers(void);
170  
171 //! Redirects received data to a user function.
172 ///
173 void uartSetRxHandler(void (*rx_func)(unsigned char c));
174  
175 //! Sets the uart baud rate.
176 /// Argument should be in bits-per-second, like \c uartSetBaudRate(9600);
177 void uartSetBaudRate(u32 baudrate);
178  
179 //! Returns pointer to the receive buffer structure.
180 ///
181 cBuffer* uartGetRxBuffer(void);
182  
183 //! Returns pointer to the transmit buffer structure.
184 ///
185 cBuffer* uartGetTxBuffer(void);
186  
187 //! Sends a single byte over the uart.
188 /// \note This function waits for the uart to be ready,
189 /// therefore, consecutive calls to uartSendByte() will
190 /// go only as fast as the data can be sent over the
191 /// serial port.
192 void uartSendByte(u08 data);
193  
194 //! Gets a single byte from the uart receive buffer.
195 /// Returns the byte, or -1 if no byte is available (getchar-style).
196 int uartGetByte(void);
197  
198 //! Gets a single byte from the uart receive buffer.
199 /// Function returns TRUE if data was available, FALSE if not.
200 /// Actual data is returned in variable pointed to by "data".
201 /// Example usage:
202 /// \code
203 /// char myReceivedByte;
204 /// uartReceiveByte( &myReceivedByte );
205 /// \endcode
206 u08 uartReceiveByte(u08* data);
207  
208 //! Returns TRUE/FALSE if receive buffer is empty/not-empty.
209 ///
210 u08 uartReceiveBufferIsEmpty(void);
211  
212 //! Flushes (deletes) all data from receive buffer.
213 ///
214 void uartFlushReceiveBuffer(void);
215  
216 //! Add byte to end of uart Tx buffer.
217 /// Returns TRUE if successful, FALSE if failed (no room left in buffer).
218 u08 uartAddToTxBuffer(u08 data);
219  
220 //! Begins transmission of the transmit buffer under interrupt control.
221 ///
222 void uartSendTxBuffer(void);
223  
224 //! Sends a block of data via the uart using interrupt control.
225 /// \param buffer pointer to data to be sent
226 /// \param nBytes length of data (number of bytes to sent)
227 u08 uartSendBuffer(char *buffer, u16 nBytes);
228  
229 #endif
230 //@}
231  
232