Rename PDIProtocol.c/.h to XPROGProtocol.c/.h as it will now handle both TPI and...

[pub/USBasp.git] / LUFA / Drivers / Peripheral / Serial.h

diff --git a/LUFA/Drivers/Peripheral/Serial.h b/LUFA/Drivers/Peripheral/Serial.h
index d83761f..326d0fd 100644 (file)
--- a/LUFA/Drivers/Peripheral/Serial.h
+++ b/LUFA/Drivers/Peripheral/Serial.h
@@ -33,10 +33,16 @@
  *  Driver for the USART subsystem on supported USB AVRs.\r
  */\r
  \r
-/** \ingroup Group_SubsystemDrivers\r
+/** \ingroup Group_PeripheralDrivers\r
  *  @defgroup Group_Serial Serial USART Driver - LUFA/Drivers/Peripheral/Serial.h\r
  *\r
- *  Functions, macros, variables, enums and types related to the setup of the USART for serial communications.\r
+ *  \section Sec_Dependencies Module Source Dependencies\r
+ *  The following files must be built with any user project that uses this module:\r
+ *    - LUFA/Drivers/Peripheral/Serial.c\r
+ *\r
+ *  \section Module Description\r
+ *  Hardware serial USART driver. This module provides an easy to use driver for\r
+ *  the setup of and transfer of data over the AVR's USART port.\r
  *\r
  *  @{\r
  */\r
@@ -58,46 +64,76 @@
                #endif\r
 \r
        /* Public Interface - May be used in end-application: */\r
-               /* Macros: */   \r
-                       /** Indicates whether a character has been received through the USART - boolean false if no character\r
-                        *  has been received, or non-zero if a character is waiting to be read from the reception buffer.\r
-                        */\r
-                       #define Serial_IsCharReceived() ((UCSR1A & (1 << RXC1)) ? true : false)\r
-\r
+               /* Macros: */\r
                        /** Macro for calculating the baud value from a given baud rate when the U2X (double speed) bit is\r
                         *  not set.\r
                         */\r
-                       #define SERIAL_UBBRVAL(baud)    (((F_CPU / 16) / baud) - 1)\r
+                       #define SERIAL_UBBRVAL(baud)    (((F_CPU / 16) / (baud)) - 1)\r
 \r
                        /** Macro for calculating the baud value from a given baud rate when the U2X (double speed) bit is\r
                         *  set.\r
                         */\r
-                       #define SERIAL_2X_UBBRVAL(baud) (((F_CPU / 8) / baud) - 1)\r
+                       #define SERIAL_2X_UBBRVAL(baud) (((F_CPU / 8) / (baud)) - 1)\r
+\r
+               /* Pseudo-Function Macros: */\r
+                       #if defined(__DOXYGEN__)\r
+                               /** Indicates whether a character has been received through the USART.\r
+                                *\r
+                                *  \return Boolean true if a character has been received, false otherwise\r
+                                */\r
+                               static inline bool Serial_IsCharReceived(void);\r
+                       #else\r
+                               #define Serial_IsCharReceived() ((UCSR1A & (1 << RXC1)) ? true : false)\r
+                       #endif\r
 \r
                /* Function Prototypes: */\r
-                       /** Initializes the USART, ready for serial data transmission and reception.\r
-                        *\r
-                        *  \param BaudRate     Baud rate to configure the USART to\r
-                        *  \param DoubleSpeed  Enables double speed mode when set, halving the sample time to double the baud rate\r
-                        */\r
-                       void Serial_Init(const uint32_t BaudRate, const bool DoubleSpeed);\r
-\r
                        /** Transmits a given string located in program space (FLASH) through the USART.\r
                         *\r
-                        *  \param FlashStringPtr  Pointer to a string located in program space\r
+                        *  \param[in] FlashStringPtr  Pointer to a string located in program space\r
                         */\r
                        void Serial_TxString_P(const char *FlashStringPtr) ATTR_NON_NULL_PTR_ARG(1);\r
 \r
                        /** Transmits a given string located in SRAM memory through the USART.\r
                         *\r
-                        *  \param StringPtr  Pointer to a string located in SRAM space\r
+                        *  \param[in] StringPtr  Pointer to a string located in SRAM space\r
                         */\r
                        void Serial_TxString(const char *StringPtr) ATTR_NON_NULL_PTR_ARG(1);\r
 \r
                /* Inline Functions: */\r
+                       /** Initializes the USART, ready for serial data transmission and reception. This initializes the interface to\r
+                        *  standard 8-bit, no parity, 1 stop bit settings suitable for most applications.\r
+                        *\r
+                        *  \param[in] BaudRate     Serial baud rate, in bits per second\r
+                        *  \param[in] DoubleSpeed  Enables double speed mode when set, halving the sample time to double the baud rate\r
+                        */\r
+                       static inline void Serial_Init(const uint32_t BaudRate, const bool DoubleSpeed)\r
+                       {\r
+                               UCSR1A = (DoubleSpeed ? (1 << U2X1) : 0);\r
+                               UCSR1B = ((1 << TXEN1)  | (1 << RXEN1));\r
+                               UCSR1C = ((1 << UCSZ11) | (1 << UCSZ10));\r
+                               \r
+                               DDRD  |= (1 << 3);      \r
+                               PORTD |= (1 << 2);\r
+                               \r
+                               UBRR1  = (DoubleSpeed ? SERIAL_2X_UBBRVAL(BaudRate) : SERIAL_UBBRVAL(BaudRate));\r
+                       }\r
+\r
+                       /** Turns off the USART driver, disabling and returning used hardware to their default configuration. */\r
+                       static inline void Serial_ShutDown(void)\r
+                       {\r
+                               UCSR1A = 0;\r
+                               UCSR1B = 0;\r
+                               UCSR1C = 0;\r
+                               \r
+                               DDRD  &= ~(1 << 3);     \r
+                               PORTD &= ~(1 << 2);\r
+                               \r
+                               UBRR1  = 0;\r
+                       }\r
+                       \r
                        /** Transmits a given byte through the USART.\r
                         *\r
-                        *  \param DataByte  Byte to transmit through the USART\r
+                        *  \param[in] DataByte  Byte to transmit through the USART\r
                         */\r
                        static inline void Serial_TxByte(const char DataByte)\r
                        {\r