X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/612df774d9fbddc2e9cb36e6bca849746aa925f5..30f6d2bfd82995e0fa346b3b4eb33861f6a0fde3:/LUFA/Drivers/Peripheral/Serial.h

diff --git a/LUFA/Drivers/Peripheral/Serial.h b/LUFA/Drivers/Peripheral/Serial.h
index 4eb74b9d2..7b3659ca0 100644
--- a/LUFA/Drivers/Peripheral/Serial.h
+++ b/LUFA/Drivers/Peripheral/Serial.h
@@ -1,21 +1,21 @@
 /*
              LUFA Library
-     Copyright (C) Dean Camera, 2010.
-              
+     Copyright (C) Dean Camera, 2011.
+
   dean [at] fourwalledcubicle [dot] com
-      www.fourwalledcubicle.com
+           www.lufa-lib.org
 */
 
 /*
-  Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
 
-  Permission to use, copy, modify, distribute, and sell this 
+  Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
-  without fee, provided that the above copyright notice appear in 
+  without fee, provided that the above copyright notice appear in
   all copies and that both that the copyright notice and this
-  permission notice and warranty disclaimer appear in supporting 
-  documentation, and that the name of the author not be used in 
-  advertising or publicity pertaining to distribution of the 
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
   software without specific, written prior permission.
 
   The author disclaim all warranties with regard to this
@@ -33,7 +33,7 @@
  *
  *  Driver for the USART subsystem on supported USB AVRs.
  */
- 
+
 /** \ingroup Group_PeripheralDrivers
  *  @defgroup Group_Serial Serial USART Driver - LUFA/Drivers/Peripheral/Serial.h
  *
@@ -41,13 +41,28 @@
  *  The following files must be built with any user project that uses this module:
  *    - LUFA/Drivers/Peripheral/Serial.c <i>(Makefile source module name: LUFA_SRC_SERIAL)</i>
  *
- *  \section Module Description
+ *  \section Sec_ModDescription Module Description
  *  Hardware serial USART driver. This module provides an easy to use driver for
  *  the setup of and transfer of data over the AVR's USART port.
  *
+ *  \section Sec_ExampleUsage Example Usage
+ *  The following snippet is an example of how this module may be used within a typical
+ *  application.
+ *
+ *  \code
+ *      // Initialise the serial USART driver before first use, with 9600 baud (and no double-speed mode)
+ *      Serial_Init(9600, false);
+ *
+ *      // Send a string through the USART
+ *      Serial_TxString("Test String\r\n");
+ *
+ *      // Receive a byte through the USART
+ *      uint8_t DataByte = Serial_RxByte();
+ *  \endcode
+ *
  *  @{
  */
- 
+
 #ifndef __SERIAL_H__
 #define __SERIAL_H__
 
@@ -55,7 +70,7 @@
 		#include <avr/io.h>
 		#include <avr/pgmspace.h>
 		#include <stdbool.h>
-		
+
 		#include "../../Common/Common.h"
 		#include "../Misc/TerminalCodes.h"
 
@@ -99,39 +114,39 @@
 			static inline void Serial_Init(const uint32_t BaudRate,
 			                               const bool DoubleSpeed)
 			{
+				UBRR1  = (DoubleSpeed ? SERIAL_2X_UBBRVAL(BaudRate) : SERIAL_UBBRVAL(BaudRate));
+
+				UCSR1C = ((1 << UCSZ11) | (1 << UCSZ10));
 				UCSR1A = (DoubleSpeed ? (1 << U2X1) : 0);
 				UCSR1B = ((1 << TXEN1)  | (1 << RXEN1));
-				UCSR1C = ((1 << UCSZ11) | (1 << UCSZ10));
-				
-				DDRD  |= (1 << 3);	
+
+				DDRD  |= (1 << 3);
 				PORTD |= (1 << 2);
-				
-				UBRR1  = (DoubleSpeed ? SERIAL_2X_UBBRVAL(BaudRate) : SERIAL_UBBRVAL(BaudRate));
 			}
 
 			/** Turns off the USART driver, disabling and returning used hardware to their default configuration. */
 			static inline void Serial_ShutDown(void)
 			{
-				UCSR1A = 0;
 				UCSR1B = 0;
+				UCSR1A = 0;
 				UCSR1C = 0;
-				
-				DDRD  &= ~(1 << 3);	
-				PORTD &= ~(1 << 2);
-				
+
 				UBRR1  = 0;
+
+				DDRD  &= ~(1 << 3);
+				PORTD &= ~(1 << 2);
 			}
 
 			/** Indicates whether a character has been received through the USART.
 			 *
-			 *  \return Boolean true if a character has been received, false otherwise.
+			 *  \return Boolean \c true if a character has been received, \c false otherwise.
 			 */
 			static inline bool Serial_IsCharReceived(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
 			static inline bool Serial_IsCharReceived(void)
 			{
 				return ((UCSR1A & (1 << RXC1)) ? true : false);
 			}
-			
+
 			/** Transmits a given byte through the USART.
 			 *
 			 *  \param[in] DataByte  Byte to transmit through the USART.
@@ -143,7 +158,9 @@
 				UDR1 = DataByte;
 			}
 
-			/** Receives a byte from the USART.
+			/** Receives a byte from the USART. This function blocks until a byte has been
+			 *  received; if non-blocking behaviour is required, test for a received character
+			 *  beforehand with \ref Serial_IsCharReceived().
 			 *
 			 *  \return Byte received from the USART.
 			 */
@@ -151,14 +168,15 @@
 			static inline char Serial_RxByte(void)
 			{
 				while (!(UCSR1A & (1 << RXC1)));
-				return UDR1; 
+				return UDR1;
 			}
 
 	/* Disable C linkage for C++ Compilers: */
 		#if defined(__cplusplus)
 			}
 		#endif
-		
+
 #endif
 
 /** @} */
+