X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/f01a05415c03b0dd61297849ece2cfcce7f8d3e8..0da99447d3e88e83f9977501bee56af5c7aa56c0:/LUFA/Drivers/Peripheral/AVR8/Serial_AVR8.h diff --git a/LUFA/Drivers/Peripheral/AVR8/Serial_AVR8.h b/LUFA/Drivers/Peripheral/AVR8/Serial_AVR8.h index 7f519d3ba..b7b50f434 100644 --- a/LUFA/Drivers/Peripheral/AVR8/Serial_AVR8.h +++ b/LUFA/Drivers/Peripheral/AVR8/Serial_AVR8.h @@ -1,13 +1,13 @@ /* LUFA Library - Copyright (C) Dean Camera, 2011. + Copyright (C) Dean Camera, 2012. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* - Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2012 Dean Camera (dean [at] fourwalledcubicle [dot] com) Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted @@ -43,7 +43,7 @@ * \section Sec_ModDescription Module Description * On-chip serial USART driver for the 8-bit AVR microcontrollers. * - * \note This file should not be included directly. It is automatically included as needed by the ADC driver + * \note This file should not be included directly. It is automatically included as needed by the USART driver * dispatch header located in LUFA/Drivers/Peripheral/Serial.h. * * \section Sec_ExampleUsage Example Usage @@ -53,10 +53,10 @@ * \code * // Initialize 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 @@ -70,7 +70,7 @@ /* Includes: */ #include "../../../Common/Common.h" #include "../../Misc/TerminalCodes.h" - + #include /* Enable C linkage for C++ Compilers: */ @@ -87,7 +87,7 @@ #if !defined(__DOXYGEN__) /* External Variables: */ extern FILE USARTSerialStream; - + /* Function Prototypes: */ int Serial_putchar(char DataByte, FILE *Stream); @@ -97,15 +97,23 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Macro for calculating the baud value from a given baud rate when the U2X (double speed) bit is + /** Macro for calculating the baud value from a given baud rate when the \c U2X (double speed) bit is * not set. + * + * \param[in] Baud Target serial UART baud rate. + * + * \return Closest UBRR register value for the given UART frequency. */ - #define SERIAL_UBBRVAL(baud) ((((F_CPU / 16) + (baud / 2)) / (baud)) - 1) + #define SERIAL_UBBRVAL(Baud) ((((F_CPU / 16) + (Baud / 2)) / (Baud)) - 1) - /** Macro for calculating the baud value from a given baud rate when the U2X (double speed) bit is + /** Macro for calculating the baud value from a given baud rate when the \c U2X (double speed) bit is * set. + * + * \param[in] Baud Target serial UART baud rate. + * + * \return Closest UBRR register value for the given UART frequency. */ - #define SERIAL_2X_UBBRVAL(baud) ((((F_CPU / 8) + (baud / 2)) / (baud)) - 1) + #define SERIAL_2X_UBBRVAL(Baud) ((((F_CPU / 8) + (Baud / 2)) / (Baud)) - 1) /* Function Prototypes: */ /** Transmits a given string located in program space (FLASH) through the USART. @@ -119,7 +127,7 @@ * \param[in] StringPtr Pointer to a string located in SRAM space. */ void Serial_SendString(const char* StringPtr) ATTR_NON_NULL_PTR_ARG(1); - + /** Transmits a given buffer located in SRAM memory through the USART. * * \param[in] Buffer Pointer to a buffer containing the data to send. @@ -127,6 +135,32 @@ */ void Serial_SendData(const uint8_t* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + /** Creates a standard character stream from the USART so that it can be used with all the regular functions + * in the avr-libc \c library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created + * stream is bidirectional and can be used for both input and output functions. + * + * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single + * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may + * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own + * line buffering. + * + * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed, if \c NULL, \c stdout + * and \c stdin will be configured to use the USART. + * + * \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used. + */ + void Serial_CreateStream(FILE* Stream); + + /** Identical to \ref Serial_CreateStream(), except that reads are blocking until the calling stream function terminates + * the transfer. + * + * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed, if \c NULL, \c stdout + * and \c stdin will be configured to use the USART. + * + * \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used. + */ + void Serial_CreateBlockingStream(FILE* Stream); + /* Inline Functions: */ /** Initializes the USART, ready for serial data transmission and reception. This initializes the interface to * standard 8-bit, no parity, 1 stop bit settings suitable for most applications. @@ -160,52 +194,6 @@ PORTD &= ~(1 << 2); } - /** Creates a standard character stream from the USART so that it can be used with all the regular functions - * in the avr-libc \c library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created - * stream is bidirectional and can be used for both input and output functions. - * - * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single - * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may - * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own - * line buffering. - * - * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed, if \c NULL stdio - * and stdin will be configured to use the USART. - * - * \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used. - */ - static inline void Serial_CreateStream(FILE* Stream) - { - if (!(Stream)) - { - Stream = &USARTSerialStream; - stdin = Stream; - stdout = Stream; - } - - *Stream = (FILE)FDEV_SETUP_STREAM(Serial_putchar, Serial_getchar, _FDEV_SETUP_RW); - } - - /** Identical to \ref Serial_CreateStream(), except that reads are blocking until the calling stream function terminates - * the transfer. - * - * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed, if \c NULL stdio - * and stdin will be configured to use the USART. - * - * \pre The USART must first be configured via a call to \ref Serial_Init() before the stream is used. - */ - static inline void Serial_CreateBlockingStream(FILE* Stream) - { - if (!(Stream)) - { - Stream = &USARTSerialStream; - stdin = Stream; - stdout = Stream; - } - - *Stream = (FILE)FDEV_SETUP_STREAM(Serial_putchar, Serial_getchar_Blocking, _FDEV_SETUP_RW); - } - /** Indicates whether a character has been received through the USART. * * \return Boolean \c true if a character has been received, \c false otherwise. @@ -236,7 +224,7 @@ { if (!(Serial_IsCharReceived())) return -1; - + return UDR1; }