X-Git-Url: http://git.linex4red.de/pub/lufa.git/blobdiff_plain/eee252603be67c539f9986cde76454f756e55d95..refs/heads/ProMicro:/LUFA/Drivers/Peripheral/XMEGA/Serial_XMEGA.h diff --git a/LUFA/Drivers/Peripheral/XMEGA/Serial_XMEGA.h b/LUFA/Drivers/Peripheral/XMEGA/Serial_XMEGA.h index 717b23d9a..215c7a470 100644 --- a/LUFA/Drivers/Peripheral/XMEGA/Serial_XMEGA.h +++ b/LUFA/Drivers/Peripheral/XMEGA/Serial_XMEGA.h @@ -1,13 +1,13 @@ /* LUFA Library - Copyright (C) Dean Camera, 2012. + Copyright (C) Dean Camera, 2021. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* - Copyright 2012 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2021 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 @@ -40,23 +40,23 @@ /** \ingroup Group_Serial * \defgroup Group_Serial_XMEGA Serial USART Peripheral Driver (XMEGA) * - * \section Sec_ModDescription Module Description + * \section Sec_Serial_XMEGA_ModDescription Module Description * On-chip serial USART driver for the XMEGA AVR microcontrollers. * * \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 + * \section Sec_Serial_XMEGA_ExampleUsage Example Usage * The following snippet is an example of how this module may be used within a typical * application. * * \code * // Initialize the serial USART driver before first use, with 9600 baud (and no double-speed mode) * Serial_Init(&USARTD0, 9600, false); - * + * * // Send a string through the USART * Serial_TxString(&USARTD0, "Test String\r\n"); - * + * * // Receive a byte through the USART * uint8_t DataByte = Serial_RxByte(&USARTD0); * \endcode @@ -139,7 +139,8 @@ * \param[in] Length Length of the data to send, in bytes. */ void Serial_SendData(USART_t* const USART, - const uint8_t* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + const void* 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 @@ -150,40 +151,46 @@ * 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] USART Pointer to the base of the USART peripheral within the device. * \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 + void Serial_CreateStream(USART_t* USART, FILE* Stream); + + /** Identical to \ref Serial_CreateStream(), except that reads are blocking until the calling stream function terminates * the transfer. * + * \param[in,out] USART Pointer to the base of the USART peripheral within the device. * \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); + void Serial_CreateBlockingStream(USART_t* USART, 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. * * \param[in,out] USART Pointer to the base of the USART peripheral within the device. - * \param[in] BaudRate Serial baud rate, in bits per second. + * \param[in] BaudRate Serial baud rate, in bits per second. This should be the target baud rate regardless of + * the \c DoubleSpeed parameter's value. * \param[in] DoubleSpeed Enables double speed mode when set, halving the sample time to double the baud rate. */ static inline void Serial_Init(USART_t* const USART, const uint32_t BaudRate, + const bool DoubleSpeed) ATTR_NON_NULL_PTR_ARG(1); + static inline void Serial_Init(USART_t* const USART, + const uint32_t BaudRate, const bool DoubleSpeed) { uint16_t BaudValue = (DoubleSpeed ? SERIAL_2X_UBBRVAL(BaudRate) : SERIAL_UBBRVAL(BaudRate)); USART->BAUDCTRLB = (BaudValue >> 8); USART->BAUDCTRLA = (BaudValue & 0xFF); - + USART->CTRLC = (USART_CMODE_ASYNCHRONOUS_gc | USART_PMODE_DISABLED_gc | USART_CHSIZE_8BIT_gc); USART->CTRLB = (USART_RXEN_bm | USART_TXEN_bm | (DoubleSpeed ? USART_CLK2X_bm : 0)); } @@ -192,36 +199,66 @@ * * \param[in,out] USART Pointer to the base of the USART peripheral within the device. */ + static inline void Serial_Disable(USART_t* const USART) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1); static inline void Serial_Disable(USART_t* const USART) { USART->CTRLA = 0; USART->CTRLB = 0; USART->CTRLC = 0; } - + /** Indicates whether a character has been received through the USART. * * \param[in,out] USART Pointer to the base of the USART peripheral within the device. * * \return Boolean \c true if a character has been received, \c false otherwise. */ - static inline bool Serial_IsCharReceived(USART_t* const USART) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; + static inline bool Serial_IsCharReceived(USART_t* const USART) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1); static inline bool Serial_IsCharReceived(USART_t* const USART) { return ((USART->STATUS & USART_RXCIF_bm) ? true : false); } + /** Indicates whether there is hardware buffer space for a new transmit on the USART. This + * function can be used to determine if a call to \ref Serial_SendByte() will block in advance. + * + * \param[in,out] USART Pointer to the base of the USART peripheral within the device. + * + * \return Boolean \c true if a character can be queued for transmission immediately, \c false otherwise. + */ + static inline bool Serial_IsSendReady(USART_t* const USART) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1); + static inline bool Serial_IsSendReady(USART_t* const USART) + { + return (USART->STATUS & USART_DREIF_bm) ? true : false; + } + + /** Indicates whether the hardware USART transmit buffer is completely empty, indicating all + * pending transmissions have completed. + * + * \param[in,out] USART Pointer to the base of the USART peripheral within the device. + * + * \return Boolean \c true if no characters are buffered for transmission, \c false otherwise. + */ + static inline bool Serial_IsSendComplete(USART_t* const USART) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1); + static inline bool Serial_IsSendComplete(USART_t* const USART) + { + return (USART->STATUS & USART_TXCIF_bm) ? true : false; + } + /** Transmits a given byte through the USART. * + * \note If no buffer space is available in the hardware USART, this function will block. To check if + * space is available before calling this function, see \ref Serial_IsSendReady(). + * * \param[in,out] USART Pointer to the base of the USART peripheral within the device. * \param[in] DataByte Byte to transmit through the USART. */ static inline void Serial_SendByte(USART_t* const USART, - const char DataByte) ATTR_ALWAYS_INLINE; + const char DataByte) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1); static inline void Serial_SendByte(USART_t* const USART, const char DataByte) { - while (!(USART->STATUS & USART_DREIF_bm)); + while (!(Serial_IsSendReady(USART))); USART->DATA = DataByte; } @@ -231,7 +268,7 @@ * * \return Next byte received from the USART, or a negative value if no byte has been received. */ - static inline int16_t Serial_ReceiveByte(USART_t* const USART) ATTR_ALWAYS_INLINE; + static inline int16_t Serial_ReceiveByte(USART_t* const USART) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1); static inline int16_t Serial_ReceiveByte(USART_t* const USART) { if (!(Serial_IsCharReceived(USART)))