i2c_device.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_HH
#define I2C_DEVICE_HH
 
#include "initializer_list.h"
#include "iterator.h"
#include "errors.h"
#include "i2c.h"
#include "future.h"
#include "i2c_handler.h"
#include "utilities.h"
 
namespace i2c
{
    // Forward declaration
    template<typename MANAGER> class I2CFutureHelper;
 
    // Trick to support MODE as I2CDevice constructor template argument (deducible)
    template<I2CMode MODE> struct Mode {};
 
    static constexpr Mode I2C_STANDARD = Mode<I2CMode::STANDARD>{};
    static constexpr Mode I2C_FAST = Mode<I2CMode::FAST>{};
    
    // Internal (private) utility class to start/end synchronization or do nothing at all
    template<bool DISABLE = true> class DisableInterrupts
    {
        DisableInterrupts()
        {
            cli();
        }
        ~DisableInterrupts()
        {
            SREG = sreg_;
        }
 
        const uint8_t sreg_ = SREG;
 
        template<typename> friend class I2CDevice;
    };
    template<> class DisableInterrupts<false>
    {
        DisableInterrupts() = default;
 
        template<typename> friend class I2CDevice;
    };
 
    template<typename MANAGER_>
    class I2CDevice
    {
    public:
        using MANAGER = MANAGER_;
 
    private:
        using MANAGER_TRAIT = I2CManager_trait<MANAGER>;
        // Ensure MANAGER is an accepted I2C Manager type
        static_assert(
            MANAGER_TRAIT::IS_I2CMANAGER, "MANAGER_ must be a valid I2C Manager type");
 
    protected:
        using ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE;
 
        template<typename OUT, typename IN> using FUTURE = typename MANAGER::template FUTURE<OUT, IN>;
 
        template<I2CMode MODE>
        I2CDevice(MANAGER& manager, uint8_t device, UNUSED Mode<MODE> mode, bool auto_stop) 
        : device_{device}, handler_{manager}, auto_stop_flags_{I2CCommandType::flags(auto_stop, true, true)}
        {
            // Ensure that MANAGER I2C mode is compliant with the best mode for this device
            static_assert((MODE == I2CMode::FAST) || (MODE == MANAGER_TRAIT::MODE),
                "MANAGER_ I2CMode must be compliant with this device best mode");
        }
 
        I2CDevice(const I2CDevice&) = delete;
        I2CDevice& operator=(const I2CDevice&) = delete;
 
        void set_device(uint8_t device)
        {
            device_ = device;
        }
 
        static constexpr I2CLightCommand read(uint8_t read_count = 0, bool finish_future = false, bool stop = false)
        {
            const I2CCommandType type{false, stop, finish_future, false};
            return I2CLightCommand{type, read_count};
        }
 
        static constexpr I2CLightCommand write(uint8_t write_count = 0, bool finish_future = false, bool stop = false)
        {
            const I2CCommandType type{true, stop, finish_future, false};
            return I2CLightCommand{type, write_count};
        }
 
        int launch_commands(
            ABSTRACT_FUTURE& future, utils::range<I2CLightCommand> commands)
        {
            uint8_t num_commands = commands.size();
            if (num_commands == 0) return errors::EINVAL;
            {
                // Truly asynchronous mode (ATmega only)
                // The whole code block in launch_commands() must be synchronized
                UNUSED auto outer_sync = DisableInterrupts<MANAGER_TRAIT::IS_ASYNC>{};
                uint8_t max_read;
                uint8_t max_write;
                {
                    // Synchronous mode
                    // Only the next few method calls shall be synchronized
                    UNUSED auto inner_sync = DisableInterrupts<!MANAGER_TRAIT::IS_ASYNC>{};
                    // pre-conditions (must be synchronized)
                    if (!handler_.ensure_num_commands_(num_commands)) return errors::EAGAIN;
                    max_read = future.get_future_value_size_();
                    max_write = future.get_storage_value_size_();
                }
 
                // That check is normally usefull only in debug mode
                if (MANAGER_TRAIT::IS_DEBUG && (!check_commands(max_write, max_read, commands)))
                        return errors::EINVAL;
 
                // Now push each command to the I2C Manager
                int error = 0;
                for (I2CLightCommand command : commands)
                {
                    // update command.byte_count if 0
                    command.update_byte_count(max_read, max_write);
                    // force future finish for last command in transaction
                    --num_commands;
                    if (num_commands == 0)
                        command.type().add_flags(auto_stop_flags_);
                    // Note: on ATtiny, this method blocks until I2C command is finished!
                    if (!handler_.push_command_(command, device_, future))
                    {
                        error = errors::EPROTO;
                        break;
                    }
                }
                // Notify handler that transaction is complete
                handler_.last_command_pushed_();
                return error;
            }
        }
 
        template<typename F> int async_read(F& future, bool stop = true)
        {
            return launch_commands(future, {write(), read(0, false, stop)});
        }
 
        template<typename F, typename T = uint8_t> bool sync_read(T& result)
        {
            F future{};
            if (async_read<F>(future) != 0) return false;
            return future.get(result);
        }
 
        template<typename F> int async_write(F& future, bool stop = true)
        {
            return launch_commands(future, {write(0, false, stop)});
        }
 
        template<typename F> int async_multi_write(F& future, bool stop = true)
        {
            constexpr uint8_t NUM_WRITES = F::NUM_WRITES;
            constexpr uint8_t WRITE_SIZE = F::WRITE_SIZE;
            I2CLightCommand writes[NUM_WRITES];
            prepare_multi_write_commands(writes, NUM_WRITES, WRITE_SIZE, stop);
            return launch_commands(future, utils::range(writes, NUM_WRITES));
        }
 
        template<typename F, typename T = uint8_t> bool sync_write(const T& value)
        {
            F future{value};
            if (async_write<F>(future) != 0) return false;
            return (future.await() == future::FutureStatus::READY);
        }
 
        template<typename F> bool sync_write()
        {
            F future{};
            if (async_write<F>(future) != 0) return false;
            return (future.await() == future::FutureStatus::READY);
        }
 
    private:
        static bool check_commands(
            uint8_t max_write, uint8_t max_read, const utils::range<I2CLightCommand>& commands)
        {
            // Limit total number of bytes read or written in a transaction to 255
            uint8_t total_read = 0;
            uint8_t total_write = 0;
            for (const I2CLightCommand& command : commands)
            {
                // Count number of bytes read and written
                if (command.type().is_write())
                    total_write += (command.byte_count() ? command.byte_count() : max_write);
                else
                    total_read += (command.byte_count() ? command.byte_count() : max_read);
            }
            // check sum of read commands byte_count matches future output size
            // check sum of write commands byte_count matches future input size
            return (total_write == max_write) && (total_read == max_read);
        }
 
        void prepare_multi_write_commands(I2CLightCommand* commands, uint8_t count, uint8_t write_size, bool stop)
        {
            I2CLightCommand command = write(write_size, false, stop);
            for (uint8_t i = 0; i < count; ++i)
                *commands++ = command;
        }
 
        uint8_t device_ = 0;
        MANAGER& handler_;
        const uint8_t auto_stop_flags_;
        friend class I2CFutureHelper<MANAGER>;
    };
}
 
#endif /* I2C_DEVICE_HH */