i2c_device_utilities.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_DEVICE_UTILITIES_H
#define I2C_DEVICE_UTILITIES_H
 
#include "flash.h"
#include "functors.h"
#include "future.h"
#include "initializer_list.h"
#include "iterator.h"
#include "time.h"
#include "utilities.h"
#include "i2c_device.h"
 
namespace i2c
{
    // Internal type used by WriteRegisterFuture
    template<typename T, typename FUNCTOR = functor::Identity<T>> class WriteContent
    {
        using ARG_TYPE = typename FUNCTOR::ARG_TYPE;
    public:
        WriteContent() = default;
        WriteContent(uint8_t reg, const ARG_TYPE& value)
            :   register_{reg}, value_{functor::Functor<FUNCTOR>::call(value)} {}
 
        uint8_t reg() const
        {
            return register_;
        }
 
    private:
        uint8_t register_{};
        T value_{}; 
    };
 
    template<typename MANAGER, typename T, typename FUNCTOR = functor::Identity<T>>
    class ReadRegisterFuture: public MANAGER::template FUTURE<T, uint8_t>
    {
        using ARG_TYPE = typename FUNCTOR::ARG_TYPE;
        using PARENT = typename MANAGER::template FUTURE<T, uint8_t>;
 
    protected:
        using ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE;
 
        uint8_t reg() const
        {
            return this->get_input();
        }
 
    public:
        explicit ReadRegisterFuture(uint8_t reg,
            future::FutureNotification notification = future::FutureNotification::NONE)
            :   PARENT{reg, notification} {}
        bool get(T& result)
        {
            ARG_TYPE temp;
            if (!PARENT::get(temp)) return false;
            result = functor::Functor<FUNCTOR>::call(temp);
            return true;
        }
    };
 
    template<typename MANAGER, uint8_t REGISTER, typename T, typename FUNCTOR = functor::Identity<T>>
    class TReadRegisterFuture: public ReadRegisterFuture<MANAGER, T, FUNCTOR>
    {
        using PARENT = ReadRegisterFuture<MANAGER, T, FUNCTOR>;
    public:
        explicit TReadRegisterFuture(
            future::FutureNotification notification = future::FutureNotification::NONE)
            :   PARENT{REGISTER, notification} {}
        void reset_()
        {
            PARENT::reset_(REGISTER);
        }
    };
 
    template<typename MANAGER, typename T, typename FUNCTOR = functor::Identity<T>>
    class WriteRegisterFuture: public MANAGER::template FUTURE<void, WriteContent<T, FUNCTOR>>
    {
        using CONTENT = WriteContent<T, FUNCTOR>;
        using ARG_TYPE = typename FUNCTOR::ARG_TYPE;
        using PARENT = typename MANAGER::template FUTURE<void, CONTENT>;
 
    protected:
        using ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE;
 
        uint8_t reg() const
        {
            return this->get_input().reg();
        }
 
    public:
        explicit WriteRegisterFuture(
            uint8_t reg, const ARG_TYPE& value, 
            future::FutureNotification notification = future::FutureNotification::NONE)
            :   PARENT{CONTENT{reg, value}, notification} {}
    };
 
    template<typename MANAGER, uint8_t REGISTER, typename T, typename FUNCTOR = functor::Identity<T>>
    class TWriteRegisterFuture: public WriteRegisterFuture<MANAGER, T, FUNCTOR>
    {
        using ARG_TYPE = typename FUNCTOR::ARG_TYPE;
        using CONTENT = WriteContent<T, FUNCTOR>;
        using PARENT = WriteRegisterFuture<MANAGER, T, FUNCTOR>;
    public:
        explicit TWriteRegisterFuture(const ARG_TYPE& value = ARG_TYPE{},
            future::FutureNotification notification = future::FutureNotification::NONE)
            :   PARENT{REGISTER, value, notification} {}
        void reset_(const T& input = T{})
        {
            PARENT::reset_(CONTENT{REGISTER, input});
        }
    };
 
    template<typename T>
    class WriteMultiContentBase
    {
    protected:
        WriteMultiContentBase() = default;
 
        struct Pair
        {
            Pair() = default;
            Pair(uint8_t reg, T value = T{}) : reg_{reg}, value_{value} {}
            uint8_t reg_ = 0;
            T value_{};
        };
 
        static void init(Pair* content, std::initializer_list<T> values)
        {
            const T* val_ptr = values.begin();
            while (val_ptr != values.end())
            {
                (*content).value_ = *val_ptr++;
                ++content;
            }
        }
    };
 
    template<typename T, uint8_t... REGISTERS>
    class WriteMultiContent : public WriteMultiContentBase<T>
    {
        using PARENT = WriteMultiContentBase<T>;
    public:
        explicit constexpr WriteMultiContent(std::initializer_list<T> values) : content_{ REGISTERS... }
        {
            PARENT::init(content_, values);
        }
 
        T value(uint8_t index) const
        {
            return content_[index].value_;
        }
 
    private:
        typename PARENT::Pair content_[sizeof...(REGISTERS)];
    };
 
    template<typename MANAGER, typename T, uint8_t... REGISTERS>
    class TWriteMultiRegisterFuture: public MANAGER::template FUTURE<void, WriteMultiContent<T, REGISTERS...>>
    {
        using CONTENT = WriteMultiContent<T, REGISTERS...>;
        using PARENT = typename MANAGER::template FUTURE<void, CONTENT>;
 
    protected:
        using ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE;
 
    public:
        static constexpr uint8_t NUM_WRITES = sizeof...(REGISTERS);
 
        static constexpr uint8_t WRITE_SIZE = sizeof(T) + 1;
        
        explicit TWriteMultiRegisterFuture(
            std::initializer_list<T> values, 
            future::FutureNotification notification = future::FutureNotification::NONE)
            :   PARENT{CONTENT{values}, notification} {}
        void reset_(std::initializer_list<T> values)
        {
            PARENT::reset_(CONTENT{values});
        }
    };
 
    // Forward declaration of I2CDevice
    template<typename MANAGER> class I2CDevice;
    template<typename MANAGER> bool await_same_future_group(
        I2CDevice<MANAGER>& device,const uint8_t* buffer, uint8_t size);
 
    template<typename MANAGER> class I2CFutureHelper
    {
        static_assert(I2CManager_trait<MANAGER>::IS_I2CMANAGER, "MANAGER must be an I2C Manager");
 
    protected:
        using DEVICE = I2CDevice<MANAGER>;
        using ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE;
 
        I2CFutureHelper() = default;
 
        // Check launch_commands() return and update own status if needed
        bool check_error(int error, ABSTRACT_FUTURE& target)
        {
            if (error == 0) return true;
            target.set_future_error_(error);
            return false;
        }
 
        bool check_status(const ABSTRACT_FUTURE& source, future::FutureStatus status, ABSTRACT_FUTURE& target)
        {
            // First check that current future was executed successfully
            if (status != future::FutureStatus::READY)
            {
                target.set_future_error_(source.error());
                return false;
            }
            return true;
        }
 
        static constexpr I2CLightCommand read(uint8_t read_count = 0, bool finish_future = false, bool stop = false)
        {
            return DEVICE::read(read_count, finish_future, stop);
        }
 
        static constexpr I2CLightCommand write(uint8_t write_count = 0, bool finish_future = false, bool stop = false)
        {
            return DEVICE::write(write_count, finish_future, stop);
        }
 
        int launch_commands(ABSTRACT_FUTURE& future, utils::range<I2CLightCommand> commands)
        {
            return device_->launch_commands(future, commands);
        }
 
        void set_device(DEVICE& device)
        {
            device_ = &device;
        }
 
        DEVICE& device()
        {
            return *device_;
        }
 
    private:
        // The device that uses this future
        DEVICE* device_ = nullptr;
        friend DEVICE;
    };
 
    template<typename MANAGER> class AbstractI2CFuturesGroup : 
        public future::AbstractFuturesGroup<typename MANAGER::ABSTRACT_FUTURE>,
        public I2CFutureHelper<MANAGER>
    {
        using HELPER = I2CFutureHelper<MANAGER>;
        using GROUP = future::AbstractFuturesGroup<typename MANAGER::ABSTRACT_FUTURE>;
 
    protected:
        using ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE;
 
        explicit AbstractI2CFuturesGroup(future::FutureNotification notification = future::FutureNotification::NONE) 
            : GROUP{notification} {}
 
        // Check launch_commands() return and update own status if needed
        bool check_error(int error)
        {
            return HELPER::check_error(error, *this);
        }
 
        bool check_status(const ABSTRACT_FUTURE& source, future::FutureStatus status)
        {
            return HELPER::check_status(source, status, *this);
        }
    };
 
    template<typename MANAGER> class I2CFuturesGroup : 
        public AbstractI2CFuturesGroup<MANAGER>
    {
        using PARENT = AbstractI2CFuturesGroup<MANAGER>;
        using MANAGER_TRAIT = I2CManager_trait<MANAGER>;
        using ABSTRACT_FUTURE = typename PARENT::ABSTRACT_FUTURE;
 
    protected:
        I2CFuturesGroup(ABSTRACT_FUTURE** futures, uint8_t size, 
            future::FutureNotification notification = future::FutureNotification::NONE)
            : PARENT{notification}, futures_{futures}, size_{size} {}
 
        bool start(typename PARENT::DEVICE& device)
        {
            PARENT::set_device(device);
            if (MANAGER_TRAIT::IS_ASYNC)
            {
                return next_future();
            }
            else
            {
                // In sync mode, we replace recursive calls (generated by on_status_change()) by a loop
                while (index_ != size_)
                {
                    if (!next_future()) return false;
                }
                return true;
            }
        }
 
        void on_status_change(const ABSTRACT_FUTURE& future, future::FutureStatus status)
        {
            // First check if it is one of our futures!
            if (!is_own_future(future)) return;
            PARENT::on_status_change_pre_step(future, status);
            // In sync mode, we must avoid recursive calls generated by on_status_change()!
            if (MANAGER_TRAIT::IS_ASYNC)
            {
                // First check that current future was executed successfully
                if (status == future::FutureStatus::READY)
                    next_future();
            }
        }
 
    private:
        bool is_own_future(const ABSTRACT_FUTURE& future) const
        {
            uint8_t i = size_;
            ABSTRACT_FUTURE** ptr = futures_;
            while (i != 0)
            {
                if (*ptr == &future) return true;
                ++ptr;
                --i;
            }
            return false;
        }
 
        bool next_future()
        {
            if (index_ == size_)
                // Future is finished
                return false;
 
            ABSTRACT_FUTURE& future = *futures_[index_++];
            // Check if future has read, write or both
            const bool stop = (index_ == size_);
            const bool read = future.get_future_value_size_();
            const bool write = future.get_storage_value_size_();
            int error = 0;
            if (read && write)
            {
                error = PARENT::launch_commands(future, {PARENT::write(), PARENT::read(0, false, stop)});
            }
            else if (read)
            {
                error = PARENT::launch_commands(future, {PARENT::read(0, false, stop)});
            }
            else if (write)
            {
                error = PARENT::launch_commands(future, {PARENT::write(0, false, stop)});
            }
            else
            {
                //FIXME we consider that any other future is an I2CFuturesGroup, which might not always be correct!
                I2CFuturesGroup& group = static_cast<I2CFuturesGroup&>(future);
                if (!group.start(PARENT::device()))
                    error = errors::EILSEQ;
            }
            return PARENT::check_error(error);
        }
 
        ABSTRACT_FUTURE** futures_;
        uint8_t size_;
        uint8_t index_ = 0;
 
        DECL_FUTURE_LISTENERS_FRIEND
    };
 
    template<typename MANAGER> class I2CSameFutureGroup : public AbstractI2CFuturesGroup<MANAGER>
    {
        using PARENT = AbstractI2CFuturesGroup<MANAGER>;
        using MANAGER_TRAIT = I2CManager_trait<MANAGER>;
        using ABSTRACT_FUTURE = typename PARENT::ABSTRACT_FUTURE;
        using F = WriteRegisterFuture<MANAGER, uint8_t>;
        using CONTENT = WriteContent<uint8_t>;
        static constexpr uint8_t FUTURE_SIZE = F::IN_SIZE;
 
    public:
        I2CSameFutureGroup(uint16_t address, uint8_t size, 
            future::FutureNotification notification = future::FutureNotification::NONE)
            : PARENT{notification}, address_{address}, size_{size}
        {
            PARENT::init({&future_}, size / FUTURE_SIZE);
            interrupt::register_handler(*this);
        }
 
        ~I2CSameFutureGroup()
        {
            interrupt::unregister_handler(*this);
        }
 
        bool start(typename PARENT::DEVICE& device)
        {
            PARENT::set_device(device);
            if (MANAGER_TRAIT::IS_ASYNC)
            {
                return next_future();
            }
            else
            {
                // In sync mode, we replace recursive calls (generated by on_status_change()) by a loop
                while (size_)
                {
                    if (!next_future()) return false;
                }
                return true;
            }
        }
 
    private:
        bool next_future()
        {
            if (size_ == 0)
                // Future is finished already
                return false;
 
            uint8_t reg = next_byte();
            uint8_t val = next_byte();
            const bool stop = (size_ == 0);
            future_.reset_(CONTENT{reg, val});
            return PARENT::check_error(
                PARENT::launch_commands(future_, {PARENT::write(0, false, stop)}));
        }
 
        // Get the next byte, from the flash
        uint8_t next_byte()
        {
            uint8_t data = 0;
            --size_;
            return flash::read_flash(address_++, data);
        }
 
        void on_status_change(const ABSTRACT_FUTURE& future, future::FutureStatus status)
        {
            if (&future != &future_) return;
            PARENT::on_status_change_pre_step(future, status);
            // In sync mode, we must avoid recursive calls generated by on_status_change()!
            if (MANAGER_TRAIT::IS_ASYNC)
            {
                // First check that current future was executed successfully
                if (status == future::FutureStatus::READY)
                    next_future();
            }
        }
 
        // Address of flah mempry holding information about bytes to write
        uint16_t address_;
        uint8_t size_;
        // The future reused for all writes
        F future_{0, 0, future::FutureNotification::STATUS};
 
        DECL_FUTURE_LISTENERS_FRIEND
        friend bool await_same_future_group<MANAGER>(I2CDevice<MANAGER>&, const uint8_t*, uint8_t);
    };
 
    template<typename MANAGER>
    bool await_same_future_group(I2CDevice<MANAGER>& device,const uint8_t* buffer, uint8_t size)
    {
        I2CSameFutureGroup<MANAGER> future{uint16_t(buffer), size};
        if (!future.start(device)) return false;
        return (future.await() == future::FutureStatus::READY);
    }
 
#ifdef EXPERIMENTAL_API
    namespace actions
    {
        static constexpr uint8_t END = 0x00;
        static constexpr uint8_t WRITE = 0x10;
        static constexpr uint8_t READ = 0x20;
        static constexpr uint8_t MARKER = 0x30;
        static constexpr uint8_t LOOP = 0x31;
        static constexpr uint8_t INCLUDE = 0x40;
 
        static constexpr uint8_t STOP_MASK = 0x80;
        static constexpr uint8_t ACTION_MASK = 0x70;
        static constexpr uint8_t COUNT_MASK = 0x0F;
 
        static constexpr uint8_t write(uint8_t count, bool stop = false)
        {
            return WRITE | (count & COUNT_MASK) | (stop ? STOP_MASK : 0x00);
        }
        static constexpr uint8_t read(uint8_t count, bool stop = false)
        {
            return READ | (count & COUNT_MASK) | (stop ? STOP_MASK : 0x00);
        }
        static constexpr bool is_write(uint8_t action)
        {
            return (action & ACTION_MASK) == WRITE;
        }
        static constexpr bool is_read(uint8_t action)
        {
            return (action & ACTION_MASK) == READ;
        }
        static constexpr bool is_stop(uint8_t action)
        {
            return action & STOP_MASK;
        }
        static constexpr uint8_t count(uint8_t action)
        {
            return action & COUNT_MASK;
        }
    }
 
    //FIXME wont't work in SYNC mode (too many recursion calls through future listeners)!!!
    template<typename MANAGER> class ComplexI2CFuturesGroup : public AbstractI2CFuturesGroup<MANAGER>
    {
        using PARENT = AbstractI2CFuturesGroup<MANAGER>;
        using MANAGER_TRAIT = I2CManager_trait<MANAGER>;
        using ABSTRACT_FUTURE = typename PARENT::ABSTRACT_FUTURE;
 
    protected:
        ComplexI2CFuturesGroup(uint16_t flash_config, 
            future::FutureNotification notification = future::FutureNotification::NONE)
            : PARENT{notification}, address_{flash_config} {}
 
        enum class ProcessAction : uint8_t
        {
            DONE,
            MARKER,
            INCLUDE,
            READ,
            WRITE
        };
 
        //TODO Find better API to do the most in superclass instead of subclass (and avoid templates)
        ProcessAction process_action()
        {
            while ((action_ = next_byte()) == actions::LOOP)
            {
                // Store loop address for later use and skip to next action
                loop_ = address_;
            }
            if (action_ == actions::END)
            {
                // Future is finished
                PARENT::set_future_finish_();
                return ProcessAction::DONE;
            }
            if (action_ == actions::MARKER) return ProcessAction::MARKER;
            if (action_ == actions::INCLUDE) return ProcessAction::INCLUDE;
            if (actions::is_read(action_)) return ProcessAction::READ;
            if (actions::is_write(action_)) return ProcessAction::WRITE;
 
            // Error: unrecognized action code
            PARENT::check_error(errors::EILSEQ);
            return ProcessAction::DONE;
        }
 
        void loop()
        {
            address_ = loop_;
        }
 
        // Get the next byte, from the flash
        uint8_t next_byte()
        {
            uint8_t data = 0;
            return flash::read_flash(address_++, data);
        }
 
        bool is_stop() const
        {
            return actions::is_stop(action_);
        }
 
        uint8_t count() const
        {
            return actions::count(action_);
        }
 
    private:
        // Information, read from flash, about futures to create and launch
        uint16_t address_;
        // Address to restart from in case of a loop
        uint16_t loop_ = 0;
        // Current action code
        uint8_t action_ = 0;
    };
#endif
}
 
#endif /* I2C_DEVICE_UTILITIES_H */