projects / pub / USBasp.git / blob
? search:


8dd7844b51c6bcaf34a1d9919730a5ad2638f497
[pub/USBasp.git] / LUFA / Drivers / Peripheral / XMEGA / Serial_XMEGA.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2012.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.lufa-lib.org
7 */
8
9 /*
10 Copyright 2012 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 (XMEGA)
33 *
34 * On-chip serial USART driver for the XMEGA 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_XMEGA Serial USART Peripheral Driver (XMEGA)
42 *
43 * \section Sec_ModDescription Module Description
44 * On-chip serial USART driver for the XMEGA AVR microcontrollers.
45 *
46 * \note This file should not be included directly. It is automatically included as needed by the USART 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(&USARTD, 9600, false);
56 *
57 * // Send a string through the USART
58 * Serial_TxString(&USARTD, "Test String\r\n");
59 *
60 * // Receive a byte through the USART
61 * uint8_t DataByte = Serial_RxByte(&USARTD);
62 * \endcode
63 *
64 * @{
65 */
66
67 #ifndef __SERIAL_XMEGA_H__
68 #define __SERIAL_XMEGA_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,out] USART Pointer to the base of the USART peripheral within the device.
122 * \param[in] FlashStringPtr Pointer to a string located in program space.
123 */
124 void Serial_SendString_P(USART_t* const USART,
125 const char* FlashStringPtr) ATTR_NON_NULL_PTR_ARG(1);
126
127 /** Transmits a given string located in SRAM memory through the USART.
128 *
129 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
130 * \param[in] StringPtr Pointer to a string located in SRAM space.
131 */
132 void Serial_SendString(USART_t* const USART,
133 const char* StringPtr) ATTR_NON_NULL_PTR_ARG(1);
134
135 /** Transmits a given buffer located in SRAM memory through the USART.
136 *
137 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
138 * \param[in] Buffer Pointer to a buffer containing the data to send.
139 * \param[in] Length Length of the data to send, in bytes.
140 */
141 void Serial_SendData(USART_t* const USART,
142 const uint8_t* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
143
144 /* Inline Functions: */
145 /** Initializes the USART, ready for serial data transmission and reception. This initializes the interface to
146 * standard 8-bit, no parity, 1 stop bit settings suitable for most applications.
147 *
148 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
149 * \param[in] BaudRate Serial baud rate, in bits per second.
150 * \param[in] DoubleSpeed Enables double speed mode when set, halving the sample time to double the baud rate.
151 */
152 static inline void Serial_Init(USART_t* const USART,
153 const uint32_t BaudRate,
154 const bool DoubleSpeed)
155 {
156 uint16_t BaudValue = (DoubleSpeed ? SERIAL_2X_UBBRVAL(BaudRate) : SERIAL_UBBRVAL(BaudRate));
157
158 USART->BAUDCTRLB = (BaudValue >> 8);
159 USART->BAUDCTRLA = (BaudValue & 0xFF);
160
161 USART->CTRLC = (USART_CMODE_ASYNCHRONOUS_gc | USART_PMODE_DISABLED_gc | USART_CHSIZE_8BIT_gc);
162 USART->CTRLB = (USART_RXEN_bm | USART_TXEN_bm | (DoubleSpeed ? USART_CLK2X_bm : 0));
163 }
164
165 /** Turns off the USART driver, disabling and returning used hardware to their default configuration.
166 *
167 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
168 */
169 static inline void Serial_Disable(USART_t* const USART)
170 {
171 USART->CTRLA = 0;
172 USART->CTRLB = 0;
173 USART->CTRLC = 0;
174 }
175
176 /** Creates a standard character stream from the USART so that it can be used with all the regular functions
177 * in the avr-libc \c <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created
178 * stream is bidirectional and can be used for both input and output functions.
179 *
180 * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single
181 * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may
182 * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
183 * line buffering.
184 *
185 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
186 * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed, if \c NULL, \c stdout
187 * and \c stdin will be configured to use the USART.
188 *
189 * \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used.
190 */
191 static inline void Serial_CreateStream(USART_t* const USART,
192 FILE* Stream)
193 {
194 if (!(Stream))
195 {
196 Stream = &USARTSerialStream;
197 stdin = Stream;
198 stdout = Stream;
199 }
200
201 *Stream = (FILE)FDEV_SETUP_STREAM(Serial_putchar, Serial_getchar, _FDEV_SETUP_RW);
202 fdev_set_udata(Stream, USART);
203 }
204
205 /** Identical to \ref Serial_CreateStream(), except that reads are blocking until the calling stream function terminates
206 * the transfer.
207 *
208 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
209 * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed, if \c NULL, \c stdout
210 * and \c stdin will be configured to use the USART.
211 *
212 * \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used.
213 */
214 static inline void Serial_CreateBlockingStream(USART_t* const USART,
215 FILE* Stream)
216 {
217 if (!(Stream))
218 {
219 Stream = &USARTSerialStream;
220 stdin = Stream;
221 stdout = Stream;
222 }
223
224 *Stream = (FILE)FDEV_SETUP_STREAM(Serial_putchar, Serial_getchar_Blocking, _FDEV_SETUP_RW);
225 fdev_set_udata(Stream, USART);
226 }
227
228 /** Indicates whether a character has been received through the USART.
229 *
230 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
231 *
232 * \return Boolean \c true if a character has been received, \c false otherwise.
233 */
234 static inline bool Serial_IsCharReceived(USART_t* const USART) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
235 static inline bool Serial_IsCharReceived(USART_t* const USART)
236 {
237 return ((USART->STATUS & USART_RXCIF_bm) ? true : false);
238 }
239
240 /** Transmits a given byte through the USART.
241 *
242 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
243 * \param[in] DataByte Byte to transmit through the USART.
244 */
245 static inline void Serial_SendByte(USART_t* const USART,
246 const char DataByte) ATTR_ALWAYS_INLINE;
247 static inline void Serial_SendByte(USART_t* const USART,
248 const char DataByte)
249 {
250 while (!(USART->STATUS & USART_DREIF_bm));
251 USART->DATA = DataByte;
252 }
253
254 /** Receives the next byte from the USART.
255 *
256 * \param[in,out] USART Pointer to the base of the USART peripheral within the device.
257 *
258 * \return Next byte received from the USART, or a negative value if no byte has been received.
259 */
260 static inline int16_t Serial_ReceiveByte(USART_t* const USART) ATTR_ALWAYS_INLINE;
261 static inline int16_t Serial_ReceiveByte(USART_t* const USART)
262 {
263 if (!(Serial_IsCharReceived(USART)))
264 return -1;
265
266 USART->STATUS = USART_RXCIF_bm;
267 return USART->DATA;
268 }
269
270 /* Disable C linkage for C++ Compilers: */
271 #if defined(__cplusplus)
272 }
273 #endif
274
275 #endif
276
277 /** @} */
278
USB isp AVR programmer