i2c_handler_common.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 I2C_HANDLER_COMMON_HH
#define I2C_HANDLER_COMMON_HH
 
#include <stdint.h>
#include "boards/board_traits.h"
#include "bits.h"
#include "i2c.h"
#include "ios.h"
#include "future.h"
#include "queue.h"
#include "utilities.h"
 
namespace i2c
{
    enum class DebugStatus : uint8_t
    {
        START = 0,
        REPEAT_START,
        SLAW,
        SLAR,
        SEND,
        RECV,
        RECV_LAST,
        STOP,
 
        SEND_OK,
        SEND_ERROR,
        RECV_OK,
        RECV_ERROR
    };
 
    using I2C_DEBUG_HOOK = void (*)(DebugStatus status, uint8_t data);
 
    // Generic support for I2C debugging
    template<bool IS_DEBUG_ = false, typename DEBUG_HOOK_ = I2C_DEBUG_HOOK>  struct I2CDebugSupport
    {
        explicit I2CDebugSupport(UNUSED DEBUG_HOOK_ hook = nullptr) {}
        void call_hook(UNUSED DebugStatus status, UNUSED uint8_t data = 0)
        {
            // Intentionally left empty
        }
    };
    template<typename DEBUG_HOOK_> struct I2CDebugSupport<true, DEBUG_HOOK_>
    {
        explicit I2CDebugSupport(DEBUG_HOOK_ hook) : hook_{hook} {}
        void call_hook(DebugStatus status, uint8_t data = 0)
        {
            hook_(status, data);
        }
    private:
        DEBUG_HOOK_ hook_;
    };
 
    using I2C_STATUS_HOOK = void (*)(Status expected, Status actual);
 
    // Generic support for I2C status hook
    template<bool IS_STATUS_ = false, typename STATUS_HOOK_ = I2C_STATUS_HOOK>  struct I2CStatusSupport
    {
        explicit I2CStatusSupport(UNUSED STATUS_HOOK_ hook = nullptr) {}
        void call_hook(UNUSED Status expected, UNUSED Status actual)
        {
            // Intentionally left empty
        }
    };
    template<typename STATUS_HOOK_> struct I2CStatusSupport<true, STATUS_HOOK_>
    {
        explicit I2CStatusSupport(STATUS_HOOK_ hook) : hook_{hook} {}
        void call_hook(Status expected, Status actual)
        {
            hook_(expected, actual);
        }
    private:
        STATUS_HOOK_ hook_;
    };
 
    enum class I2CErrorPolicy : uint8_t
    {
        DO_NOTHING,
 
        CLEAR_ALL_COMMANDS,
 
        CLEAR_TRANSACTION_COMMANDS
    };
 
    // Type of commands in queue
    class I2CCommandType
    {
    public:
        constexpr I2CCommandType() = default;
        constexpr I2CCommandType(const I2CCommandType&) = default;
        I2CCommandType& operator=(const I2CCommandType&) = default;
 
        bool is_none() const
        {
            return value_ == NONE;
        }
        bool is_write() const
        {
            return value_ & WRITE;
        }
        bool is_stop() const
        {
            return value_ & STOP;
        }
        bool is_finish() const
        {
            return value_ & FINISH;
        }
        bool is_end() const
        {
            return value_ & END;
        }
 
    private:
        explicit constexpr I2CCommandType(uint8_t value) : value_{value} {}
        constexpr I2CCommandType(bool write, bool stop, bool finish, bool end)
            :   value_{value(write, stop, finish, end)} {}
 
        void add_flags(uint8_t value)
        {
            value_ |= value;
        }
 
        static constexpr uint8_t flags(bool stop, bool finish, bool end)
        {
            return bits::ORIF8(stop, STOP, finish, FINISH, end, END);
        }
 
        static constexpr const uint8_t NONE = 0;
        static constexpr const uint8_t NOT_NONE = bits::BV8(0);
        static constexpr const uint8_t WRITE = bits::BV8(1);
        static constexpr const uint8_t STOP = bits::BV8(2);
        static constexpr const uint8_t FINISH = bits::BV8(3);
        static constexpr const uint8_t END = bits::BV8(4);
 
        static constexpr uint8_t value(bool write, bool stop, bool finish, bool end)
        {
            return bits::ORIF8(true, NOT_NONE, write, WRITE, stop, STOP, finish, FINISH, end, END);
        }
 
        uint8_t value_ = NONE;
 
        template<typename> friend class I2CDevice;
        friend bool operator==(const I2CCommandType&, const I2CCommandType&);
        friend bool operator!=(const I2CCommandType&, const I2CCommandType&);
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, const I2CCommandType& t)
    {
        if (t.is_none()) return out << F("NONE");
        out << (t.is_write() ? F("WRITE") : F("READ"));
        if (t.is_stop())
            out << F("[STOP]");
        if (t.is_finish())
            out << F("[FINISH]");
        if (t.is_end())
            out << F("[END]");
        return out;
    }
    bool operator==(const I2CCommandType& a, const I2CCommandType& b);
    bool operator!=(const I2CCommandType& a, const I2CCommandType& b);
 
    class I2CLightCommand
    {
    public:
        constexpr I2CLightCommand() = default;
        constexpr I2CLightCommand(const I2CLightCommand&) = default;
 
        I2CCommandType type() const
        {
            return type_;
        }
        I2CCommandType& type()
        {
            return type_;
        }
        uint8_t byte_count() const
        {
            return byte_count_;
        }
 
    private:
        constexpr I2CLightCommand(I2CCommandType type, uint8_t byte_count) : type_{type}, byte_count_{byte_count} {}
 
        void decrement_byte_count()
        {
            --byte_count_;
        }
 
        void update_byte_count(uint8_t read_count, uint8_t write_count)
        {
            if (byte_count_ == 0)
                byte_count_ = (type_.is_write() ? write_count : read_count);
        }
 
        // Type of this command
        I2CCommandType type_ = I2CCommandType{};
        // The number of remaining bytes to be read or write
        uint8_t byte_count_ = 0;
 
        template<typename> friend class I2CDevice;
        template<typename, I2CMode, typename, bool, typename> friend class AbstractI2CSyncManager;
        template<I2CMode, I2CErrorPolicy, bool, typename, bool, typename> friend class AbstractI2CAsyncManager;
    };
 
    template<typename T> class I2CCommand : public I2CLightCommand
    {
    public:
        constexpr I2CCommand() = default;
        constexpr I2CCommand(const I2CCommand&) = default;
        constexpr I2CCommand& operator=(const I2CCommand&) = default;
 
        uint8_t target() const
        {
            return target_;
        }
        T& future() const
        {
            return *future_;
        }
 
    private:
        constexpr I2CCommand(
            const I2CLightCommand& that, uint8_t target, T& future)
            :   I2CLightCommand{that}, target_{target}, future_{&future} {}
 
        // Address of the target device (on 8 bits, already left-shifted)
        uint8_t target_ = 0;
        // A pointer to the future to be used for this command
        T* future_ = nullptr;
 
        template<I2CMode, I2CErrorPolicy, bool, typename, bool, typename> friend class AbstractI2CAsyncManager;
    };
 
    template<typename OSTREAM, typename T> OSTREAM& operator<<(OSTREAM& out, const I2CCommand<T>& c)
    {
        out << '{' << c.type() << ',';
        out.setf(streams::ios::hex, streams::ios::basefield);
        out << streams::hex << c.target() << '}';
        return out;
    }
 
    // Specific traits for I2CMode
    template<I2CMode MODE_ = I2CMode::STANDARD> struct I2CMode_trait
    {
        static constexpr I2CMode MODE = MODE_;
        static constexpr uint32_t RATE = 100'000UL;
        static constexpr uint32_t FREQUENCY = ((F_CPU / RATE) - 16UL) / 2;
        static constexpr const uint8_t T_HD_STA = utils::calculate_delay1_count(4.0);
        static constexpr const uint8_t T_LOW = utils::calculate_delay1_count(4.7);
        static constexpr const uint8_t T_HIGH = utils::calculate_delay1_count(4.0);
        static constexpr const uint8_t T_SU_STA = utils::calculate_delay1_count(4.7);
        static constexpr const uint8_t T_SU_STO = utils::calculate_delay1_count(4.0);
        static constexpr const uint8_t T_BUF = utils::calculate_delay1_count(4.7);
        static constexpr const uint8_t DELAY_AFTER_STOP = utils::calculate_delay1_count(4.0 + 4.7);
    };
    template<> struct I2CMode_trait<I2CMode::FAST>
    {
        static constexpr I2CMode MODE = I2CMode::FAST;
        static constexpr uint32_t RATE = 400'000UL;
        static constexpr uint32_t FREQUENCY = ((F_CPU / RATE) - 16UL) / 2;
        static constexpr const uint8_t T_HD_STA = utils::calculate_delay1_count(0.6);
        static constexpr const uint8_t T_LOW = utils::calculate_delay1_count(1.3);
        static constexpr const uint8_t T_HIGH = utils::calculate_delay1_count(0.6);
        static constexpr const uint8_t T_SU_STA = utils::calculate_delay1_count(0.6);
        static constexpr const uint8_t T_SU_STO = utils::calculate_delay1_count(0.6);
        static constexpr const uint8_t T_BUF = utils::calculate_delay1_count(1.3);
        static constexpr const uint8_t DELAY_AFTER_STOP = utils::calculate_delay1_count(0.6 + 1.3);
    };
 
    template<typename ARCH_HANDLER_, I2CMode MODE_, typename STATUS_HOOK_, bool HAS_DEBUG_, typename DEBUG_HOOK_>
    class AbstractI2CSyncManager
    {
    protected:
        using ARCH_HANDLER = ARCH_HANDLER_;
        using MODE_TRAIT = I2CMode_trait<MODE_>;
        using I2C_TRAIT = board_traits::TWI_trait;
        using REG8 = board_traits::REG8;
        using DEBUG = I2CDebugSupport<HAS_DEBUG_, DEBUG_HOOK_>;
 
    public:
        using ABSTRACT_FUTURE = future::AbstractFakeFuture;
 
        template<typename OUT, typename IN> using FUTURE = future::FakeFuture<OUT, IN>;
 
        void begin()
        {
            synchronized begin_();
        }
 
        void end()
        {
            synchronized end_();
        }
 
        void begin_()
        {
            handler_.begin_();
        }
 
        void end_()
        {
            handler_.end_();
        }
 
    protected:
        explicit AbstractI2CSyncManager(
            STATUS_HOOK_ status_hook = nullptr,
            DEBUG_HOOK_ debug_hook = nullptr)
            :   handler_{status_hook}, debug_hook_{debug_hook} {}
 
    private:
        bool ensure_num_commands_(UNUSED uint8_t num_commands) const
        {
            return true;
        }
 
        bool push_command_(
            I2CLightCommand command, uint8_t target, ABSTRACT_FUTURE& future)
        {
            // Check command is not empty
            const I2CCommandType type = command.type();
            if (type.is_none()) return true;
            if (clear_commands_) return false;
            // Execute command immediately, from start to optional stop
            bool ok = (no_stop_ ? exec_repeat_start_() : exec_start_());
            stopped_already_ = false;
            if (!ok)
                return handle_error(future);
 
            if (type.is_write())
            {
                // Send device address
                if (!exec_send_slaw_(target))
                    return handle_error(future);
                // Send content
                while (command.byte_count() > 0)
                    // In case of a NACK on data writing, we check if it is not last byte
                    if ((!exec_send_data_(command, future)) && (command.byte_count() > 0))
                        return handle_error(future);
            }
            else
            {
                // Send device address
                if (!exec_send_slar_(target))
                    return handle_error(future);
                // Receive content
                while (command.byte_count() > 0)
                    if (!exec_receive_data_(command, future))
                        return handle_error(future);
            }
 
            // Check if we must force finish the future
            if (type.is_finish())
                future.set_future_finish_();
            // Check if we must force a STOP
            if (type.is_stop())
                exec_stop_();
            // Ensure STOP is generated or not depending on latest command executed
            no_stop_ = !type.is_stop();
            return true;
        }
 
        void last_command_pushed_()
        {
            // Check if previously executed command already did a STOP (and needed one)
            if ((!no_stop_) && (!stopped_already_) && (!clear_commands_))
            {
                exec_stop_();
                no_stop_ = false;
            }
            clear_commands_ = false;
            stopped_already_ = false;
        }
 
        // Low-level methods to handle the bus in an asynchronous way
        bool exec_start_()
        {
            debug_hook_.call_hook(DebugStatus::START);
            return handler_.exec_start_();
        }
 
        bool exec_repeat_start_()
        {
            debug_hook_.call_hook(DebugStatus::REPEAT_START);
            return handler_.exec_repeat_start_();
        }
 
        bool exec_send_slar_(uint8_t target)
        {
            debug_hook_.call_hook(DebugStatus::SLAR, target);
            return handler_.exec_send_slar_(target);
        }
        
        bool exec_send_slaw_(uint8_t target)
        {
            debug_hook_.call_hook(DebugStatus::SLAW, target);
            return handler_.exec_send_slaw_(target);
        }
 
        bool exec_send_data_(I2CLightCommand& command, ABSTRACT_FUTURE& future)
        {
            // Determine next data byte
            uint8_t data = 0;
            bool ok = future.get_storage_value_(data);
            debug_hook_.call_hook(DebugStatus::SEND, data);
            debug_hook_.call_hook(ok ? DebugStatus::SEND_OK : DebugStatus::SEND_ERROR);
            // This should only happen if there are 2 concurrent consumers for that Future
            if (!ok)
            {
                future.set_future_error_(errors::EILSEQ);
                return false;
            }
            command.decrement_byte_count();
            return handler_.exec_send_data_(data);
        }
 
        bool exec_receive_data_(I2CLightCommand& command, ABSTRACT_FUTURE& future)
        {
            // Is this the last byte to receive?
            const bool last_byte = (command.byte_count() == 1);
            const DebugStatus debug = (last_byte ? DebugStatus::RECV_LAST : DebugStatus::RECV);
            debug_hook_.call_hook(debug);
 
            uint8_t data;
            if (handler_.exec_receive_data_(last_byte, data))
            {
                const bool ok = future.set_future_value_(data);
                debug_hook_.call_hook(ok ? DebugStatus::RECV_OK : DebugStatus::RECV_ERROR, data);
                // This should only happen in case there are 2 concurrent providers for this future
                if (ok)
                {
                    command.decrement_byte_count();
                }
                else
                {
                    future.set_future_error_(errors::EILSEQ);
                }
                return ok;
            }
            return false;
        }
 
        void exec_stop_()
        {
            debug_hook_.call_hook(DebugStatus::STOP);
            handler_.exec_stop_();
            // If so then delay 4.0us + 4.7us (100KHz) or 0.6us + 1.3us (400KHz)
            // (ATMEGA328P datasheet 29.7 Tsu;sto + Tbuf)
            _delay_loop_1(MODE_TRAIT::DELAY_AFTER_STOP);
            stopped_already_ = true;
        }
 
        // This method is called when an error has occurred
        bool handle_error(ABSTRACT_FUTURE& future)
        {
            if (future.status() != future::FutureStatus::ERROR)
                // The future must be marked as error
                future.set_future_error_(errors::EPROTO);
 
            // Clear command belonging to the same transaction (i.e. same future)
            // ie forbid any new command until last command (add new flag for that)
            clear_commands_ = true;
            // In case of an error, immediately send a STOP condition
            exec_stop_();
            return false;
        }
 
        // Flags for storing I2C transaction operation state
        bool no_stop_ = false;
        bool clear_commands_ = false;
        bool stopped_already_ = false;
 
        ARCH_HANDLER handler_;
        DEBUG debug_hook_;
 
        template<typename> friend class I2CDevice;
    };
 
    // Specific traits for I2C Manager
    template<typename T> struct I2CManager_trait
    {
        static constexpr bool IS_I2CMANAGER = false;
        static constexpr bool IS_ASYNC = false;
        static constexpr bool IS_DEBUG = false;
        static constexpr bool IS_STATUS = false;
        static constexpr I2CMode MODE = I2CMode::STANDARD;
    };
 
    template<bool IS_ASYNC_, bool IS_STATUS_, bool IS_DEBUG_, I2CMode MODE_>
    struct I2CManager_trait_impl
    {
        static constexpr bool IS_I2CMANAGER = true;
        static constexpr bool IS_ASYNC = IS_ASYNC_;
        static constexpr bool IS_DEBUG = IS_DEBUG_;
        static constexpr bool IS_STATUS = IS_STATUS_;
        static constexpr I2CMode MODE = MODE_;
    };
}
 
#endif /* I2C_HANDLER_COMMON_HH */