eeprom.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 EEPROM_H
#define EEPROM_H
 
#include "boards/board_traits.h"
#include <avr/interrupt.h>
#include <avr/eeprom.h>
#include "interrupts.h"
#include "utilities.h"
#include "queue.h"
 
#define REGISTER_EEPROM_ISR()                \
    ISR(EE_READY_vect)                       \
    {                                        \
        eeprom::isr_handler::eeprom_ready(); \
    }
 
#define REGISTER_EEPROM_ISR_METHOD(HANDLER, CALLBACK)                  \
    ISR(EE_READY_vect)                                                 \
    {                                                                  \
        eeprom::isr_handler::eeprom_ready_method<HANDLER, CALLBACK>(); \
    }
 
#define REGISTER_EEPROM_ISR_FUNCTION(CALLBACK)                  \
    ISR(EE_READY_vect)                                          \
    {                                                           \
        eeprom::isr_handler::eeprom_ready_function<CALLBACK>(); \
    }
 
#define DECL_EEPROM_ISR_HANDLERS_FRIEND \
    friend struct eeprom::isr_handler;  \
    friend void ::EE_READY_vect();
 
namespace eeprom
{
    class EEPROM
    {
    public:
        EEPROM() = default;
        EEPROM(const EEPROM&) = delete;
        EEPROM& operator=(const EEPROM&) = delete;
 
        template<typename T> static bool read(const T* address, T& value)
        {
            return read((uint16_t) address, value);
        }
 
        template<typename T> static bool read(uint16_t address, T& value)
        {
            if (!check(address, sizeof(T))) return false;
            uint8_t* pvalue = (uint8_t*) &value;
            for (uint16_t i = 0; i < sizeof(T); ++i) blocked_read(address++, *pvalue++);
            return true;
        }
 
        template<typename T> static bool read(const T* address, T* value, uint16_t count)
        {
            return read((uint16_t) address, value, count);
        }
 
        template<typename T> static bool read(uint16_t address, T* value, uint16_t count)
        {
            if (!check(address, count * sizeof(T))) return false;
            uint8_t* pvalue = (uint8_t*) value;
            for (uint16_t i = 0; i < (count * sizeof(T)); ++i) blocked_read(address++, *pvalue++);
            return true;
        }
 
        static bool read(const uint8_t* address, uint8_t& value)
        {
            return read((uint16_t) address, value);
        }
 
        static bool read(uint16_t address, uint8_t& value)
        {
            if (!check(address, 1))
            {
                value = UINT8_MAX;
                return false;
            }
            blocked_read(address, value);
            return true;
        }
 
        template<typename T> static bool write(const T* address, const T& value)
        {
            return write((uint16_t) address, value);
        }
 
        template<typename T> static bool write(uint16_t address, const T& value)
        {
            if (!check(address, sizeof(T))) return false;
            uint8_t* pvalue = (uint8_t*) &value;
            for (uint8_t i = 0; i < sizeof(T); ++i) blocked_write(address++, *pvalue++);
            return true;
        }
 
        template<typename T> static bool write(const T* address, const T* value, uint16_t count)
        {
            return write((uint16_t) address, value, count);
        }
 
        template<typename T> static bool write(uint16_t address, const T* value, uint16_t count)
        {
            if (!check(address, count * sizeof(T))) return false;
            uint8_t* pvalue = (uint8_t*) value;
            for (uint8_t i = 0; i < (count * sizeof(T)); ++i) blocked_write(address++, *pvalue++);
            return true;
        }
 
        static bool write(const uint8_t* address, uint8_t value)
        {
            return write((uint16_t) address, value);
        }
 
        static bool write(uint16_t address, uint8_t value)
        {
            if (!check(address, 1)) return false;
            blocked_write(address, value);
            return true;
        }
 
        static void erase()
        {
            for (uint16_t address = 0; address < size(); ++address)
            {
                wait_until_ready();
                erase_address(address);
            }
        }
 
        static constexpr uint16_t size()
        {
            return E2END + 1;
        }
 
        static void wait_until_ready()
        {
            EECR_.loop_until_bit_clear(EEPE);
        }
 
    protected:
        static bool constexpr check(uint16_t address, uint16_t size)
        {
            return (size != 0) && (address <= E2END) && (size <= (E2END + 1)) && ((address + size) <= (E2END + 1));
        }
 
        static void blocked_read(uint16_t address, uint8_t& value)
        {
            wait_until_ready();
            read_byte(address, value);
        }
 
        static void read_byte(uint16_t address, uint8_t& value)
        {
            EEAR_ = address;
            EECR_ = bits::BV8(EERE);
            value = EEDR_;
        }
 
        static void blocked_write(uint16_t address, uint8_t value)
        {
            wait_until_ready();
            write_byte(address, value);
        }
 
        // In order to optimize write time we read current byte first, then compare it with new value
        // Then we choose between erase, write and erase+write based on comparison
        // This approach is detailed in ATmel note AVR103: Using the EEPROM Programming Modes
        // http://www.atmel.com/images/doc2578.pdf
        static void write_byte(uint16_t address, uint8_t value)
        {
            EEAR_ = address;
            EECR_ = bits::BV8(EERE);
            uint8_t old_value = EEDR_;
            uint8_t diff = old_value ^ value;
            if (diff & value)
            {
                // Some bits need to be erased (ie set to 1)
                if (value == UINT8_MAX)
                    // Erase only
                    EECR_ = bits::BV8(EEPM0);
                else
                    // Combine Erase/Write operation
                    EECR_ = 0;
            }
            else
            {
                // No bit to be erased
                if (diff)
                    // Some bits to be programmed (set to 0): Write only
                    EECR_ = bits::BV8(EEPM1);
                else
                    // old value == new value => do nothing
                    return;
            }
            EEDR_ = value;
            synchronized
            {
                EECR_ |= bits::BV8(EEMPE);
                EECR_ |= bits::BV8(EEPE);
            }
        }
 
        static bool erase_address(uint16_t address)
        {
            EEAR_ = address;
            EECR_ = bits::BV8(EERE);
            uint8_t value = EEDR;
            // Some bits need to be erased (ie set to 1)
            if (value == UINT8_MAX) return false;
            EECR_ = bits::BV8(EEPM0);
            EEDR_ = UINT8_MAX;
            synchronized
            {
                EECR_ |= bits::BV8(EEMPE);
                EECR_ |= bits::BV8(EEPE);
            }
            return true;
        }
 
    private:
        using REG8 = board_traits::REG8;
        using REG16 = board_traits::REG16;
        static constexpr const REG16 EEAR_{EEAR};
        static constexpr const REG8 EECR_{EECR};
        static constexpr const REG8 EEDR_{EEDR};
    };
 
    class QueuedWriter : private EEPROM
    {
    public:
        template<uint16_t SIZE>
        explicit QueuedWriter(uint8_t (&buffer)[SIZE]) : buffer_{buffer}
        {
            interrupt::register_handler(*this);
        }
 
        template<typename T> bool write(const T* address, const T& value)
        {
            return write((uint16_t) address, value);
        }
 
        template<typename T> bool write(uint16_t address, const T& value)
        {
            if (!check(address, sizeof(T))) return false;
            synchronized return write_data(address, (uint8_t*) &value, sizeof(T));
        }
 
        template<typename T> bool write(const T* address, const T* value, uint16_t count)
        {
            return write((uint16_t) address, value, count);
        }
 
        template<typename T> bool write(uint16_t address, const T* value, uint16_t count)
        {
            if (!check(address, count * sizeof(T))) return false;
            synchronized return write_data(address, (uint8_t*) value, count * sizeof(T));
        }
 
        bool write(const uint8_t* address, uint8_t value)
        {
            return write((uint16_t) address, value);
        }
 
        bool write(uint16_t address, uint8_t value)
        {
            if (!check(address, 1)) return false;
            synchronized return write_data(address, &value, 1);
        }
 
        void erase()
        {
            // First remove all pending writes
            synchronized
            {
                buffer_.clear_();
                current_.size = 0;
            }
            // Wait until current byte write is finished
            wait_until_done();
            synchronized
            {
                // Start erase
                erase_ = true;
                done_ = false;
                current_.address = 0;
                current_.size = size();
                // Start transmission if not done yet
                EECR_ = bits::BV8(EERIE);
            }
        }
 
        void wait_until_done() const
        {
            while (!done_)
                ;
        }
 
        bool is_done() const
        {
            return done_;
        }
 
    private:
        static const uint16_t ITEM_SIZE = 3;
 
        bool on_ready()
        {
            if (erase_)
            {
                if (current_.size)
                    erase_next();
                else
                {
                    // All erases are finished
                    erase_ = false;
                    // Mark all EEPROM work as finished if no write is pending in the queue
                    if (buffer_.empty_())
                    {
                        done_ = true;
                        EECR_ = 0;
                    }
                }
            }
            else if (current_.size)
                // There is one item being currently written, write next byte
                write_next();
            else if (!buffer_.empty_())
            {
                // Current item is finished writing but there is another item to be written in the queue
                // Get new item and start transmission of first byte
                current_ = next_item();
                write_next();
            }
            else
            {
                // All writes are finished
                done_ = true;
                EECR_ = 0;
            }
            return done_;
        }
 
        void write_next()
        {
            uint8_t value = 0;
            buffer_.pull_(value);
            EEPROM::write_byte(current_.address++, value);
            --current_.size;
            EECR_ |= bits::BV8(EERIE);
        }
 
        void erase_next()
        {
            EEPROM::erase_address(current_.address++);
            --current_.size;
            EECR_ |= bits::BV8(EERIE);
        }
 
        bool write_data(uint16_t address, uint8_t* value, uint16_t size)
        {
            // First check if there is enough space in buffer_ for this queued write
            if ((buffer_.free_() < (size + ITEM_SIZE)) || (size == 0)) return false;
            done_ = false;
            // Add new queued write to buffer
            buffer_.push_(WriteItem::value1(address, size));
            buffer_.push_(WriteItem::value2(address, size));
            buffer_.push_(WriteItem::value3(address, size));
            for (uint16_t i = 0; i < size; ++i) buffer_.push_(*value++);
 
            // Start transmission if not done yet
            EECR_ = bits::BV8(EERIE);
            return true;
        }
 
        struct WriteItem
        {
            WriteItem() = default;
            WriteItem(uint8_t value1, uint8_t value2, uint8_t value3)
            :   address{uint16_t(uint16_t(value1 << 4) | uint8_t(value2 >> 4))}, 
                size{uint16_t(utils::is_zero(((value2 & 0x0F) << 8) | value3, E2END + 1))} {}
 
            static uint8_t value1(uint16_t address, uint16_t size UNUSED)
            {
                return address >> 4;
            }
            static uint8_t value2(uint16_t address, uint16_t size)
            {
                return (address << 4) | (size >> 8);
            }
            static uint8_t value3(uint16_t address UNUSED, uint16_t size)
            {
                return size;
            }
 
            uint16_t address = 0;
            uint16_t size = 0;
        };
 
        WriteItem next_item()
        {
            uint8_t value1 = 0;
            buffer_.pull_(value1);
            uint8_t value2 = 0;
            buffer_.pull_(value2);
            uint8_t value3 = 0;
            buffer_.pull_(value3);
            return WriteItem{value1, value2, value3};
        }
 
        using REG8 = board_traits::REG8;
        using REG16 = board_traits::REG16;
        static constexpr const REG16 EEAR_{EEAR};
        static constexpr const REG8 EECR_{EECR};
        static constexpr const REG8 EEDR_{EEDR};
 
        containers::Queue<uint8_t, uint8_t> buffer_;
        WriteItem current_;
        volatile bool erase_ = false;
        volatile bool done_ = true;
 
        friend struct isr_handler;
    };
 
    struct isr_handler
    {
        static void eeprom_ready()
        {
            interrupt::HandlerHolder<eeprom::QueuedWriter>::handler()->on_ready();
        }
 
        template<void (*CALLBACK)()> static void eeprom_ready_function()
        {
            if (interrupt::HandlerHolder<eeprom::QueuedWriter>::handler()->on_ready())
                interrupt::CallbackHandler<void (*)(), CALLBACK>::call();
        }
 
        template<typename HANDLER, void (HANDLER::*CALLBACK)()> static void eeprom_ready_method()
        {
            if (interrupt::HandlerHolder<eeprom::QueuedWriter>::handler()->on_ready())
                interrupt::CallbackHandler<void (HANDLER::*)(), CALLBACK>::call();
        }
    };
}
 
#endif /* EEPROM_H */