Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / Peripheral / AVR8 / Serial_AVR8.h @ 978b99e5

History | View | Annotate | Download (9.23 KB)

1
/*
2
             LUFA Library
3
     Copyright (C) Dean Camera, 2011.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7
*/
8

    
9
/*
10
  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
11

12
  Permission to use, copy, modify, distribute, and sell this
13
  software and its documentation for any purpose is hereby granted
14
  without fee, provided that the above copyright notice appear in
15
  all copies and that both that the copyright notice and this
16
  permission notice and warranty disclaimer appear in supporting
17
  documentation, and that the name of the author not be used in
18
  advertising or publicity pertaining to distribution of the
19
  software without specific, written prior permission.
20

21
  The author disclaim all warranties with regard to this
22
  software, including all implied warranties of merchantability
23
  and fitness.  In no event shall the author be liable for any
24
  special, indirect or consequential damages or any damages
25
  whatsoever resulting from loss of use, data or profits, whether
26
  in an action of contract, negligence or other tortious action,
27
  arising out of or in connection with the use or performance of
28
  this software.
29
*/
30

    
31
/** \file
32
 *  \brief Serial USART Peripheral Driver (AVR8)
33
 *
34
 *  On-chip serial USART driver for the 8-bit AVR microcontrollers.
35
 *
36
 *  \note This file should not be included directly. It is automatically included as needed by the USART driver
37
 *        dispatch header located in LUFA/Drivers/Peripheral/Serial.h.
38
 */
39

    
40
/** \ingroup Group_Serial
41
 *  \defgroup Group_Serial_AVR8 Serial USART Peripheral Driver (AVR8)
42
 *
43
 *  \section Sec_ModDescription Module Description
44
 *  On-chip serial USART driver for the 8-bit AVR microcontrollers.
45
 *
46
 *  \note This file should not be included directly. It is automatically included as needed by the ADC driver
47
 *        dispatch header located in LUFA/Drivers/Peripheral/Serial.h.
48
 *
49
 *  \section Sec_ExampleUsage Example Usage
50
 *  The following snippet is an example of how this module may be used within a typical
51
 *  application.
52
 *
53
 *  \code
54
 *      // Initialize the serial USART driver before first use, with 9600 baud (and no double-speed mode)
55
 *      Serial_Init(9600, false);
56
 *
57
 *      // Send a string through the USART
58
 *      Serial_TxString("Test String\r\n");
59
 *
60
 *      // Receive a byte through the USART
61
 *      uint8_t DataByte = Serial_RxByte();
62
 *  \endcode
63
 *
64
 *  @{
65
 */
66

    
67
#ifndef __SERIAL_AVR8_H__
68
#define __SERIAL_AVR8_H__
69

    
70
        /* Includes: */
71
                #include "../../../Common/Common.h"
72
                #include "../../Misc/TerminalCodes.h"
73
                
74
                #include <stdio.h>
75

    
76
        /* Enable C linkage for C++ Compilers: */
77
                #if defined(__cplusplus)
78
                        extern "C" {
79
                #endif
80

    
81
        /* Preprocessor Checks: */
82
                #if !defined(__INCLUDE_FROM_SERIAL_H) && !defined(__INCLUDE_FROM_SERIAL_C)
83
                        #error Do not include this file directly. Include LUFA/Drivers/Peripheral/Serial.h instead.
84
                #endif
85

    
86
        /* Private Interface - For use in library only: */
87
        #if !defined(__DOXYGEN__)
88
                /* External Variables: */
89
                        extern FILE USARTSerialStream;
90
        
91
                /* Function Prototypes: */
92
                        int Serial_putchar(char DataByte,
93
                                           FILE *Stream);
94
                        int Serial_getchar(FILE *Stream);
95
                        int Serial_getchar_Blocking(FILE *Stream);
96
        #endif
97

    
98
        /* Public Interface - May be used in end-application: */
99
                /* Macros: */
100
                        /** Macro for calculating the baud value from a given baud rate when the \c U2X (double speed) bit is
101
                         *  not set.
102
                         *
103
                         *  \param[in] Baud  Target serial UART baud rate.
104
                         *
105
                         *  \return Closest UBRR register value for the given UART frequency.
106
                         */
107
                        #define SERIAL_UBBRVAL(Baud)    ((((F_CPU / 16) + (Baud / 2)) / (Baud)) - 1)
108

    
109
                        /** Macro for calculating the baud value from a given baud rate when the \c U2X (double speed) bit is
110
                         *  set.
111
                         *
112
                         *  \param[in] Baud  Target serial UART baud rate.
113
                         *
114
                         *  \return Closest UBRR register value for the given UART frequency.
115
                         */
116
                        #define SERIAL_2X_UBBRVAL(Baud) ((((F_CPU / 8) + (Baud / 2)) / (Baud)) - 1)
117

    
118
                /* Function Prototypes: */
119
                        /** Transmits a given string located in program space (FLASH) through the USART.
120
                         *
121
                         *  \param[in] FlashStringPtr  Pointer to a string located in program space.
122
                         */
123
                        void Serial_SendString_P(const char* FlashStringPtr) ATTR_NON_NULL_PTR_ARG(1);
124

    
125
                        /** Transmits a given string located in SRAM memory through the USART.
126
                         *
127
                         *  \param[in] StringPtr  Pointer to a string located in SRAM space.
128
                         */
129
                        void Serial_SendString(const char* StringPtr) ATTR_NON_NULL_PTR_ARG(1);
130
                        
131
                        /** Transmits a given buffer located in SRAM memory through the USART.
132
                         *
133
                         *  \param[in] Buffer  Pointer to a buffer containing the data to send.
134
                         *  \param[in] Length  Length of the data to send, in bytes.
135
                         */
136
                        void Serial_SendData(const uint8_t* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
137

    
138
                /* Inline Functions: */
139
                        /** Initializes the USART, ready for serial data transmission and reception. This initializes the interface to
140
                         *  standard 8-bit, no parity, 1 stop bit settings suitable for most applications.
141
                         *
142
                         *  \param[in] BaudRate     Serial baud rate, in bits per second.
143
                         *  \param[in] DoubleSpeed  Enables double speed mode when set, halving the sample time to double the baud rate.
144
                         */
145
                        static inline void Serial_Init(const uint32_t BaudRate,
146
                                                       const bool DoubleSpeed)
147
                        {
148
                                UBRR1  = (DoubleSpeed ? SERIAL_2X_UBBRVAL(BaudRate) : SERIAL_UBBRVAL(BaudRate));
149

    
150
                                UCSR1C = ((1 << UCSZ11) | (1 << UCSZ10));
151
                                UCSR1A = (DoubleSpeed ? (1 << U2X1) : 0);
152
                                UCSR1B = ((1 << TXEN1)  | (1 << RXEN1));
153

    
154
                                DDRD  |= (1 << 3);
155
                                PORTD |= (1 << 2);
156
                        }
157

    
158
                        /** Turns off the USART driver, disabling and returning used hardware to their default configuration. */
159
                        static inline void Serial_Disable(void)
160
                        {
161
                                UCSR1B = 0;
162
                                UCSR1A = 0;
163
                                UCSR1C = 0;
164

    
165
                                UBRR1  = 0;
166

    
167
                                DDRD  &= ~(1 << 3);
168
                                PORTD &= ~(1 << 2);
169
                        }
170

    
171
                        /** Creates a standard character stream from the USART so that it can be used with all the regular functions
172
                         *  in the avr-libc \c <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created
173
                         *  stream is bidirectional and can be used for both input and output functions.
174
                         *
175
                         *  Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single
176
                         *  fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may
177
                         *  be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
178
                         *  line buffering.
179
                         *
180
                         *  \param[in,out] Stream  Pointer to a FILE structure where the created stream should be placed, if \c NULL, \c stdout
181
                         *                         and \c stdin will be configured to use the USART.
182
                         *
183
                         *  \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used.
184
                         */
185
                        static inline void Serial_CreateStream(FILE* Stream)
186
                        {
187
                                if (!(Stream))
188
                                {
189
                                        Stream = &USARTSerialStream;
190
                                        stdin  = Stream;
191
                                        stdout = Stream;
192
                                }
193
                        
194
                                *Stream = (FILE)FDEV_SETUP_STREAM(Serial_putchar, Serial_getchar, _FDEV_SETUP_RW);
195
                        }
196

    
197
                        /** Identical to \ref Serial_CreateStream(), except that reads are blocking until the calling stream function terminates
198
                         *  the transfer.
199
                         *
200
                         *  \param[in,out] Stream  Pointer to a FILE structure where the created stream should be placed, if \c NULL, \c stdout
201
                         *                         and \c stdin will be configured to use the USART.
202
                         *
203
                         *  \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used.
204
                         */
205
                        static inline void Serial_CreateBlockingStream(FILE* Stream)
206
                        {
207
                                if (!(Stream))
208
                                {
209
                                        Stream = &USARTSerialStream;
210
                                        stdin  = Stream;
211
                                        stdout = Stream;
212
                                }
213

    
214
                                *Stream = (FILE)FDEV_SETUP_STREAM(Serial_putchar, Serial_getchar_Blocking, _FDEV_SETUP_RW);
215
                        }
216

    
217
                        /** Indicates whether a character has been received through the USART.
218
                         *
219
                         *  \return Boolean \c true if a character has been received, \c false otherwise.
220
                         */
221
                        static inline bool Serial_IsCharReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
222
                        static inline bool Serial_IsCharReceived(void)
223
                        {
224
                                return ((UCSR1A & (1 << RXC1)) ? true : false);
225
                        }
226

    
227
                        /** Transmits a given byte through the USART.
228
                         *
229
                         *  \param[in] DataByte  Byte to transmit through the USART.
230
                         */
231
                        static inline void Serial_SendByte(const char DataByte) ATTR_ALWAYS_INLINE;
232
                        static inline void Serial_SendByte(const char DataByte)
233
                        {
234
                                while (!(UCSR1A & (1 << UDRE1)));
235
                                UDR1 = DataByte;
236
                        }
237

    
238
                        /** Receives the next byte from the USART.
239
                         *
240
                         *  \return Next byte received from the USART, or a negative value if no byte has been received.
241
                         */
242
                        static inline int16_t Serial_ReceiveByte(void) ATTR_ALWAYS_INLINE;
243
                        static inline int16_t Serial_ReceiveByte(void)
244
                        {
245
                                if (!(Serial_IsCharReceived()))
246
                                  return -1;
247
                                
248
                                return UDR1;
249
                        }
250

    
251
        /* Disable C linkage for C++ Compilers: */
252
                #if defined(__cplusplus)
253
                        }
254
                #endif
255

    
256
#endif
257

    
258
/** @} */
259