uart.h

Go to the documentation of this file.

//   Copyright 2016-2023 Jean-Francois Poilpret
//
//   Licensed under the Apache License, Version 2.0 (the "License");
//   you may not use this file except in compliance with the License.
//   You may obtain a copy of the License at
//
//       http://www.apache.org/licenses/LICENSE-2.0
//
//   Unless required by applicable law or agreed to in writing, software
//   distributed under the License is distributed on an "AS IS" BASIS,
//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//   See the License for the specific language governing permissions and
//   limitations under the License.
 
 
#ifndef UART_HH
#define UART_HH
 
#include "boards/board_traits.h"
#include "interrupts.h"
#include "uart_commons.h"
#include "streams.h"
 
// Only MCU with physical USART are supported (not ATtiny then)
#if defined(UCSR0A) || defined(UCSR1A)
 
#define REGISTER_UATX_ISR(UART_NUM)                  \
    ISR(CAT3(USART, UART_NUM, _UDRE_vect))           \
    {                                                \
        serial::hard::isr_handler::uatx<UART_NUM>(); \
    }
 
#define REGISTER_UARX_ISR(UART_NUM)                  \
    ISR(CAT3(USART, UART_NUM, _RX_vect))             \
    {                                                \
        serial::hard::isr_handler::uarx<UART_NUM>(); \
    }
 
#define REGISTER_UART_ISR(UART_NUM)                     \
    ISR(CAT3(USART, UART_NUM, _UDRE_vect))              \
    {                                                   \
        serial::hard::isr_handler::uart_tx<UART_NUM>(); \
    }                                                   \
                                                        \
    ISR(CAT3(USART, UART_NUM, _RX_vect))                \
    {                                                   \
        serial::hard::isr_handler::uart_rx<UART_NUM>(); \
    }
 
namespace serial
{
    namespace hard
    {
    }
}
 
namespace serial::hard
{
    //TODO Handle generic errors coming from UART TX (which errors?) in addition to internal overflow
    class AbstractUART
    {
    protected:
        AbstractUART() = default;
        AbstractUART(const AbstractUART&) = delete;
        AbstractUART& operator=(const AbstractUART&) = delete;
        
        struct SpeedSetup
        {
            constexpr SpeedSetup(uint16_t ubrr_value, bool u2x) : ubrr_value_{ubrr_value}, u2x_{u2x} {}
            const uint16_t ubrr_value_;
            const bool u2x_;
        };
 
        static constexpr SpeedSetup compute_speed(uint32_t rate)
        {
            const uint16_t double_rate = UBRR_double(rate);
            if (double_rate < DOUBLE_SPEED_RATE_LIMIT)
                return SpeedSetup(double_rate, true);
            else
                return SpeedSetup(UBRR_single(rate), false);
        }
 
        template<board::USART USART>
        static void begin_(uint32_t rate, Parity parity, StopBits stop_bits,
                           streams::istreambuf* in, streams::ostreambuf* out)
        {
            using TRAIT = board_traits::USART_trait<USART>;
            constexpr uint8_t UCSRB_TX = TRAIT::TX_ENABLE_MASK | TRAIT::UDRIE_MASK;
            constexpr uint8_t UCSRB_RX = TRAIT::RX_ENABLE_MASK | TRAIT::RXCIE_MASK;
            const uint8_t UCSRB_MASK = ((out != nullptr) ? UCSRB_TX : 0U) | ((in != nullptr) ? UCSRB_RX : 0U);
            SpeedSetup setup = compute_speed(rate);
            const uint8_t UCSRA_MASK = (setup.u2x_ ? TRAIT::U2X_MASK : 0);
            synchronized
            {
                TRAIT::UBRR = setup.ubrr_value_;
                TRAIT::UCSRA = UCSRA_MASK;
                TRAIT::UCSRB |= UCSRB_MASK;
                TRAIT::UCSRC = TRAIT::UCSRC_value(parity, stop_bits);
            }
            if (out != nullptr) out->queue().unlock();
        }
 
        template<board::USART USART>
        static void end_(BufferHandling buffer_handling, streams::istreambuf* in , streams::ostreambuf* out)
        {
            using TRAIT = board_traits::USART_trait<USART>;
            if (out != nullptr)
            {
                out->queue().lock();
                if (buffer_handling == BufferHandling::CLEAR)
                    out->queue().clear();
                else if (buffer_handling == BufferHandling::FLUSH)
                    out->pubsync();
            }
            constexpr uint8_t UCSRB_TX = TRAIT::TX_ENABLE_MASK | TRAIT::UDRIE_MASK;
            constexpr uint8_t UCSRB_RX = TRAIT::RX_ENABLE_MASK | TRAIT::RXCIE_MASK;
            const uint8_t UCSRB_MASK = ((out != nullptr) ? UCSRB_TX : 0U) | ((in != nullptr) ? UCSRB_RX : 0U);
            synchronized TRAIT::UCSRB &= ~UCSRB_MASK;
            if ((in != nullptr) && (buffer_handling == BufferHandling::CLEAR))
                in->queue().clear();
        }
 
    private:
        static constexpr const uint16_t DOUBLE_SPEED_RATE_LIMIT = 4096;
 
        static constexpr uint16_t UBRR_double(uint32_t rate)
        {
            return ((F_CPU / 4 / rate) - 1) / 2;
        }
        static constexpr uint16_t UBRR_single(uint32_t rate)
        {
            return ((F_CPU / 8 / rate) - 1) / 2;
        }
    };
 
    class AbstractUATX : public AbstractUART
    {
    public:
        streams::ostream out()
        {
            return streams::ostream(obuf_);
        }
 
    protected:
        template<uint8_t SIZE_TX> 
        explicit AbstractUATX(char (&output)[SIZE_TX]) : obuf_{output} {}
 
        streams::ostreambuf& out_()
        {
            return obuf_;
        }
 
        template<board::USART USART>
        void data_register_empty(Errors& errors)
        {
            using TRAIT = board_traits::USART_trait<USART>;
            errors.has_errors = 0;
            char value;
            if (obuf_.queue().pull_(value))
                TRAIT::UDR = value;
            else
            {
                transmitting_ = false;
                // Clear UDRIE to prevent UDR interrupt to go on forever
                TRAIT::UCSRB &= bits::COMPL(TRAIT::UDRIE_MASK);
            }
        }
 
        template<board::USART USART>
        void on_put(Errors& errors)
        {
            using TRAIT = board_traits::USART_trait<USART>;
            errors.queue_overflow = obuf_.overflow();
            synchronized
            {
                // Check if TX is not currently active, if so, activate it
                if (!transmitting_)
                {
                    // Yes, trigger TX
                    char value;
                    if (obuf_.queue().pull_(value))
                    {
                        // Set UDR interrupt to be notified when we can send the next character
                        TRAIT::UCSRB |= TRAIT::UDRIE_MASK;
                        TRAIT::UDR = value;
                        transmitting_ = true;
                    }
                }
            }
        }
 
    private:
        streams::ostreambuf obuf_;
        bool transmitting_ = false;
    };
 
    template<board::USART USART_> class UATX : public AbstractUATX, public UARTErrors
    {
    public:
        static constexpr const board::USART USART = USART_;
 
        template<uint8_t SIZE_TX> explicit UATX(char (&output)[SIZE_TX]) : AbstractUATX{output}
        {
            interrupt::register_handler(*this);
        }
 
        void begin(uint32_t rate, Parity parity = Parity::NONE, StopBits stop_bits = StopBits::ONE)
        {
            AbstractUART::begin_<USART>(rate, parity, stop_bits, nullptr, &out_());
        }
 
        void end(BufferHandling buffer_handling = BufferHandling::KEEP)
        {
            AbstractUART::end_<USART>(buffer_handling, nullptr, &out_());
        }
 
    private:
        // Listeners of events on the buffer
        bool on_put(streams::ostreambuf& obuf)
        {
            if (&obuf != &out_()) return false;
            AbstractUATX::on_put<USART>(errors());
            return true;
        }
 
        void data_register_empty()
        {
            AbstractUATX::data_register_empty<USART>(errors());
        }
 
        friend struct isr_handler;
        DECL_OSTREAMBUF_LISTENERS_FRIEND
    };
 
    class AbstractUARX : public AbstractUART
    {
    public:
        streams::istream in()
        {
            return streams::istream(ibuf_);
        }
 
    protected:
        template<uint8_t SIZE_RX> explicit AbstractUARX(char (&input)[SIZE_RX]) : ibuf_{input} {}
 
        streams::istreambuf& in_()
        {
            return ibuf_;
        }
 
        template<board::USART USART>
        void data_receive_complete(Errors& errors)
        {
            using TRAIT = board_traits::USART_trait<USART>;
            uint8_t status = TRAIT::UCSRA;
            errors.data_overrun = status & TRAIT::DOR_MASK;
            errors.frame_error = status & TRAIT::FE_MASK;
            errors.parity_error = status & TRAIT::UPE_MASK;
            uint8_t value = TRAIT::UDR;
            errors.queue_overflow = !ibuf_.queue().push_(value);
        }
 
    private:
        streams::istreambuf ibuf_;
    };
 
    template<board::USART USART_> class UARX : public AbstractUARX, public UARTErrors
    {
    public:
        static constexpr const board::USART USART = USART_;
 
        template<uint8_t SIZE_RX> explicit UARX(char (&input)[SIZE_RX]) : AbstractUARX{input}
        {
            interrupt::register_handler(*this);
        }
 
        void begin(uint32_t rate, Parity parity = Parity::NONE, StopBits stop_bits = StopBits::ONE)
        {
            AbstractUART::begin_<USART>(rate, parity, stop_bits, &in_(), nullptr);
        }
 
        void end(BufferHandling buffer_handling = BufferHandling::KEEP)
        {
            AbstractUART::end_<USART>(buffer_handling, &in_(), nullptr);
        }
 
    private:
        void data_receive_complete()
        {
            AbstractUARX::data_receive_complete<USART>(errors());
        }
 
        friend struct isr_handler;
    };
 
    template<board::USART USART_> class UART : public AbstractUARX, public AbstractUATX, public UARTErrors
    {
    public:
        static constexpr const board::USART USART = USART_;
 
        template<uint8_t SIZE_RX, uint8_t SIZE_TX>
        UART(char (&input)[SIZE_RX], char (&output)[SIZE_TX]) 
        : AbstractUARX{input}, AbstractUATX{output}
        {
            interrupt::register_handler(*this);
        }
 
        void begin(uint32_t rate, Parity parity = Parity::NONE, StopBits stop_bits = StopBits::ONE)
        {
            AbstractUART::begin_<USART>(rate, parity, stop_bits, &in_(), &out_());
        }
 
        void end(BufferHandling buffer_handling = BufferHandling::KEEP)
        {
            AbstractUART::end_<USART>(buffer_handling, &in_(), &out_());
        }
 
    private:
        // Listeners of events on the buffer
        bool on_put(streams::ostreambuf& obuf)
        {
            if (&obuf != &out_()) return false;
            AbstractUATX::on_put<USART>(errors());
            return true;
        }
 
        void data_register_empty()
        {
            AbstractUATX::data_register_empty<USART>(errors());
        }
 
        void data_receive_complete()
        {
            AbstractUARX::data_receive_complete<USART>(errors());
        }
 
        friend struct isr_handler;
        DECL_OSTREAMBUF_LISTENERS_FRIEND
    };
 
    // All UART-related methods called by pre-defined ISR are defined here
    //=====================================================================
    struct isr_handler
    {
        template<uint8_t UART_NUM_> static constexpr board::USART check_uart()
        {
            constexpr board::USART USART = (board::USART) UART_NUM_;
            static_assert(board_traits::USART_trait<USART>::U2X_MASK != 0,
                          "UART_NUM must be an actual USART in target MCU");
            return USART;
        }
 
        template<uint8_t UART_NUM_> static void uatx()
        {
            static constexpr board::USART USART = check_uart<UART_NUM_>();
            interrupt::HandlerHolder<UATX<USART>>::handler()->data_register_empty();
        }
 
        template<uint8_t UART_NUM_> static void uarx()
        {
            static constexpr board::USART USART = check_uart<UART_NUM_>();
            interrupt::HandlerHolder<UARX<USART>>::handler()->data_receive_complete();
        }
 
        template<uint8_t UART_NUM_> static void uart_tx()
        {
            static constexpr board::USART USART = check_uart<UART_NUM_>();
            interrupt::HandlerHolder<UART<USART>>::handler()->data_register_empty();
        }
 
        template<uint8_t UART_NUM_> static void uart_rx()
        {
            static constexpr board::USART USART = check_uart<UART_NUM_>();
            interrupt::HandlerHolder<UART<USART>>::handler()->data_receive_complete();
        }
    };
}
 
namespace serial
{
    // Specific traits of HW UART classes
    template<board::USART USART> struct UART_trait<hard::UATX<USART>>
    {
        static constexpr bool IS_UART = true;
        static constexpr bool IS_HW_UART = true;
        static constexpr bool IS_SW_UART = false;
        static constexpr bool HAS_TX = true;
        static constexpr bool HAS_RX = false;
    };
    template<board::USART USART> struct UART_trait<hard::UARX<USART>>
    {
        static constexpr bool IS_UART = true;
        static constexpr bool IS_HW_UART = true;
        static constexpr bool IS_SW_UART = false;
        static constexpr bool HAS_TX = false;
        static constexpr bool HAS_RX = true;
    };
    template<board::USART USART> struct UART_trait<hard::UART<USART>>
    {
        static constexpr bool IS_UART = true;
        static constexpr bool IS_HW_UART = true;
        static constexpr bool IS_SW_UART = false;
        static constexpr bool HAS_TX = true;
        static constexpr bool HAS_RX = true;
    };
}
 
#endif /* UCSR0A */
#endif /* UART_HH */