BitBangI2C.hxx

Go to the documentation of this file.

 
#ifndef _FREERTOS_DRIVERS_COMMON_BITBANG_I2C_HXX_
#define _FREERTOS_DRIVERS_COMMON_BITBANG_I2C_HXX_
 
#include "I2C.hxx"
#include "os/Gpio.hxx"
#include "os/OS.hxx"
 
class BitBangI2CStates
{
protected:
    BitBangI2CStates()
    {
    }
 
    enum class State : uint8_t
    {
        START, 
        ADDRESS, 
        DATA_TX, 
        DATA_RX, 
        RECOVERY, 
        STOP, 
    };
 
    enum class StateStart : uint8_t
    {
        SDA_SET, 
        SCL_SET, 
        SDA_CLR, 
        FIRST = SDA_SET, 
        LAST = SDA_CLR, 
    };
 
    enum class StateStop : uint8_t
    {
        SDA_CLR, 
        SCL_SET, 
        SDA_SET, 
        FIRST = SDA_CLR, 
        LAST = SDA_SET, 
    };
 
    enum class StateTx : uint8_t
    {
        DATA_7_SCL_CLR, 
        DATA_7_SCL_SET, 
        DATA_6_SCL_CLR, 
        DATA_6_SCL_SET, 
        DATA_5_SCL_CLR, 
        DATA_5_SCL_SET, 
        DATA_4_SCL_CLR, 
        DATA_4_SCL_SET, 
        DATA_3_SCL_CLR, 
        DATA_3_SCL_SET, 
        DATA_2_SCL_CLR, 
        DATA_2_SCL_SET, 
        DATA_1_SCL_CLR, 
        DATA_1_SCL_SET, 
        DATA_0_SCL_CLR, 
        DATA_0_SCL_SET, 
        ACK_SDA_SET_SCL_CLR, 
        ACK_SCL_SET, 
        ACK_SCL_CLR, 
        FIRST = DATA_7_SCL_CLR, 
        LAST = ACK_SCL_CLR, 
    };
 
    enum class StateRx : uint8_t
    {
        DATA_7_SCL_SET, 
        DATA_7_SCL_CLR, 
        DATA_6_SCL_SET, 
        DATA_6_SCL_CLR, 
        DATA_5_SCL_SET, 
        DATA_5_SCL_CLR, 
        DATA_4_SCL_SET, 
        DATA_4_SCL_CLR, 
        DATA_3_SCL_SET, 
        DATA_3_SCL_CLR, 
        DATA_2_SCL_SET, 
        DATA_2_SCL_CLR, 
        DATA_1_SCL_SET, 
        DATA_1_SCL_CLR, 
        DATA_0_SCL_SET, 
        DATA_0_SCL_CLR, 
        ACK_SDA_SCL_SET, 
        ACK_SCL_CLR, 
        FIRST = DATA_7_SCL_SET, 
        LAST = ACK_SCL_CLR, 
    };
 
    enum class StateRecovery : uint8_t
    {
        SDA_SET,        
        DATA_7_SCL_SET, 
        DATA_7_SCL_CLR, 
        DATA_6_SCL_SET, 
        DATA_6_SCL_CLR, 
        DATA_5_SCL_SET, 
        DATA_5_SCL_CLR, 
        DATA_4_SCL_SET, 
        DATA_4_SCL_CLR, 
        DATA_3_SCL_SET, 
        DATA_3_SCL_CLR, 
        DATA_2_SCL_SET, 
        DATA_2_SCL_CLR, 
        DATA_1_SCL_SET, 
        DATA_1_SCL_CLR, 
        DATA_0_SCL_SET, 
        DATA_0_SCL_CLR, 
        ACK_SCL_SET, 
        ACK_SCL_CLR, 
        FIRST = SDA_SET, 
        LAST = ACK_SCL_CLR, 
    };
 
    friend StateStart &operator++(StateStart &);
 
    friend StateStop &operator++(StateStop &);
 
    friend StateTx &operator++(StateTx &);
 
    friend StateRx &operator++(StateRx &);
 
    friend StateRecovery &operator++(StateRecovery &);
};
 
template <class HW> class BitBangI2C : protected BitBangI2CStates
                                     , public I2C
                                     , private Atomic
{
public:
    BitBangI2C(const char *name)
        : I2C(name)
        , msg_(nullptr)
        , sem_()
        , count_(0)
        , state_(State::STOP) // start-up with a stop sequence
        , stateStop_(StateStop::SDA_CLR)
        , stop_(true)
        , clockStretchActive_(false)
    {
        HW::SDA_Pin::set(1);
        HW::SCL_Pin::set(0);
    }
 
    ~BitBangI2C()
    {
    }
 
    inline void tick_interrupt();
 
private:
    inline bool state_start();
 
    inline bool state_stop();
 
    inline bool state_tx(uint8_t data);
 
    inline bool state_rx(uint8_t *data, bool nack);
 
    inline bool state_recovery();
 
    void enable() override {} 
    void disable() override {} 
    inline int transfer(struct i2c_msg *msg, bool stop) override;
 
    struct i2c_msg *msg_; 
    OSSem sem_; 
    int count_; 
    State state_; 
    union
    {
        StateStart stateStart_; 
        StateStop stateStop_; 
        StateTx stateTx_; 
        StateRx stateRx_; 
        StateRecovery stateRecovery_; 
    };
    bool stop_; 
    bool clockStretchActive_; 
};
 
inline BitBangI2CStates::StateStart &operator++(BitBangI2CStates::StateStart &x)
{
    if (x >= BitBangI2CStates::StateStart::FIRST &&
        x < BitBangI2CStates::StateStart::LAST)
    {
        x = static_cast<BitBangI2CStates::StateStart>(static_cast<int>(x) + 1);
    }
    return x;
}
 
inline BitBangI2CStates::StateStop &operator++(BitBangI2CStates::StateStop &x)
{
    if (x >= BitBangI2CStates::StateStop::FIRST &&
        x < BitBangI2CStates::StateStop::LAST)
    {
        x = static_cast<BitBangI2CStates::StateStop>(static_cast<int>(x) + 1);
    }
    return x;
}
 
inline BitBangI2CStates::StateTx &operator++(BitBangI2CStates::StateTx &x)
{
    if (x >= BitBangI2CStates::StateTx::FIRST &&
        x < BitBangI2CStates::StateTx::LAST)
    {
        x = static_cast<BitBangI2CStates::StateTx>(static_cast<int>(x) + 1);
    }
    return x;
}
 
inline BitBangI2CStates::StateRx &operator++(BitBangI2CStates::StateRx &x)
{
    if (x >= BitBangI2CStates::StateRx::FIRST &&
        x < BitBangI2CStates::StateRx::LAST)
    {
        x = static_cast<BitBangI2CStates::StateRx>(static_cast<int>(x) + 1);
    }
    return x;
}
 
inline BitBangI2CStates::StateRecovery &operator++(
    BitBangI2CStates::StateRecovery &x)
{
    if (x >= BitBangI2CStates::StateRecovery::FIRST &&
        x < BitBangI2CStates::StateRecovery::LAST)
    {
        x = static_cast<BitBangI2CStates::StateRecovery>(
            static_cast<int>(x) + 1);
    }
    return x;
}
 
//
// BitBangI2C::tick_interrupt()
//
template <class HW> __attribute__((optimize("-O3")))
inline void BitBangI2C<HW>::tick_interrupt()
{
    bool exit = false;
    switch (state_)
    {
        // start sequence
        case State::START:
            if (state_start())
            {
                // start done, send the address
                state_ = State::ADDRESS;
                stateTx_ = StateTx::FIRST;
            }
            break;
        case State::ADDRESS:
        {
            uint8_t address = msg_->addr << 1;
            if (msg_->flags & I2C_M_RD)
            {
                address |= 0x1;
            }
            if (state_tx(address))
            {
                if (count_ < 0)
                {
                    // Some error occured, likely an unexpected NACK. Send a
                    // stop in order to shutdown gracefully.
                    state_ = State::STOP;
                    stateStop_ = StateStop::FIRST;
                }
                else
                {
                    if (msg_->flags & I2C_M_RD)
                    {
                        state_ = State::DATA_RX;
                        stateRx_ = StateRx::FIRST;
                    }
                    else
                    {
                        state_ = State::DATA_TX;
                        stateTx_ = StateTx::FIRST;
                    }
                }
            }
            break;
        }
        case State::DATA_TX:
            if (state_tx(msg_->buf[count_]))
            {
                if (count_ < 0)
                {
                    // Some error occured, likely an unexpected NACK. Send a
                    // stop in order to shutdown gracefully.
                    state_ = State::STOP;
                    stateStop_ = StateStop::FIRST;
                }
                else if (++count_ >= msg_->len)
                {
                    // All of the data has been transmitted.
                    if (stop_)
                    {
                        state_ = State::STOP;
                        stateStop_ = StateStop::FIRST;
                    }
                    else
                    {
                        exit = true;
                    }
                }
                else
                {
                    // Setup the next byte TX
                    stateTx_ = StateTx::FIRST;
                }
            }
            break;
        case State::DATA_RX:
            if (state_rx(msg_->buf + count_, (count_ + 1 >= msg_->len)))
            {
                if (count_ < 0)
                {
                    // Some error occured, likely an unexpected NACK. Send a
                    // stop in order to shutdown gracefully.
                    state_ = State::STOP;
                    stateStop_ = StateStop::FIRST;
                }
                else if (++count_ >= msg_->len)
                {
                    // All of the data has been received.
                    if (stop_)
                    {
                        state_ = State::STOP;
                        stateStop_ = StateStop::FIRST;
                    }
                    else
                    {
                        exit = true;
                    }
                }
                else
                {
                    // Setup the next byte RX
                    stateRx_ = StateRx::FIRST;
                }
            }
            break;
        case State::RECOVERY:
            if (state_recovery())
            {
                // Recovery always concludes with a stop condition
                state_ = State::STOP;
                stateStop_ = StateStop::FIRST;
            }
            break;
        case State::STOP:
            exit = state_stop();
            break;
    }
 
    if (exit)
    {
        HW::tick_disable();
        int woken = 0;
        sem_.post_from_isr(&woken);
        os_isr_exit_yield_test(woken);
    }
}
 
//
// BitBangI2C::state_start()
//
template <class HW> __attribute__((optimize("-O3")))
inline bool BitBangI2C<HW>::state_start()
{
    switch (stateStart_)
    {
        // start sequence
        case StateStart::SDA_SET:
            HW::SDA_Pin::set(1);
            ++stateStart_;
            break;
        case StateStart::SCL_SET:
            HW::SCL_Pin::set(1);
            ++stateStart_;
            break;
        case StateStart::SDA_CLR:
            HW::SDA_Pin::set(0);
            ++stateStart_;
            return true;
    }
    return false;
}
 
//
// BitBangI2C::state_stop()
//
template <class HW> __attribute__((optimize("-O3")))
inline bool BitBangI2C<HW>::state_stop()
{
    switch (stateStop_)
    {
        case StateStop::SDA_CLR:
            HW::SDA_Pin::set(0);
            ++stateStop_;
            break;
        case StateStop::SCL_SET:
            HW::SCL_Pin::set(1);
            ++stateStop_;
            break;
        case StateStop::SDA_SET:
            HW::SDA_Pin::set(1);
            stop_ = false;
            return true; // exit
    }
    return false;
}
 
//
// BitBangI2C::state_tx()
//
template <class HW> __attribute__((optimize("-O3")))
inline bool BitBangI2C<HW>::state_tx(uint8_t data)
{
    // I2C is specified such that the data on the SDA line must be stable
    // during the high period of the clock, and the data line can only change
    // when SCL is Low.
    //
    // This means that the sequence always has to be
    // 1a. SCL := low
    // 1b. set/clear SDA
    // 2. wait a cycle for lines to settle
    // 3a. SCL := high
    // 3b. this edge is when the receiver samples
    // 4. wait a cycle, lines are stable
    switch(stateTx_)
    {
        case StateTx::DATA_7_SCL_CLR:
        case StateTx::DATA_6_SCL_CLR:
        case StateTx::DATA_5_SCL_CLR:
        case StateTx::DATA_4_SCL_CLR:
        case StateTx::DATA_3_SCL_CLR:
        case StateTx::DATA_2_SCL_CLR:
        case StateTx::DATA_1_SCL_CLR:
        case StateTx::DATA_0_SCL_CLR:
        {
            // We can only change the data when SCL is low.
            HW::SCL_Pin::set(0);
            // The divide by 2 factor (shift right by 1) is because the enum
            // states alternate between *_SCL_SET and *_SCL_CLR states in
            // increasing value.
            uint8_t mask = 0x80 >>
                ((static_cast<int>(stateTx_) -
                  static_cast<int>(StateTx::DATA_7_SCL_CLR)) >> 1);
            if (data & mask)
            {
                HW::SDA_Pin::set(1);
            }
            else
            {
                HW::SDA_Pin::set(0);
            }
            ++stateTx_;
            break;
        }
        case StateTx::DATA_7_SCL_SET:
        case StateTx::DATA_6_SCL_SET:
        case StateTx::DATA_5_SCL_SET:
        case StateTx::DATA_4_SCL_SET:
        case StateTx::DATA_3_SCL_SET:
        case StateTx::DATA_2_SCL_SET:
        case StateTx::DATA_1_SCL_SET:
        case StateTx::DATA_0_SCL_SET:
            // Data is sampled by the slave following this state transition.
            HW::SCL_Pin::set(1);
            ++stateTx_;
            break;
        case StateTx::ACK_SDA_SET_SCL_CLR:
            HW::SCL_Pin::set(0);
            HW::SDA_Pin::set(1);
            ++stateTx_;
            break;
        case StateTx::ACK_SCL_SET:
            HW::SCL_Pin::set(1);
            ++stateTx_;
            break;
        case StateTx::ACK_SCL_CLR:
            if (HW::SCL_Pin::get() == false)
            {
                // Clock stretching, do the same state again.
                clockStretchActive_ = true;
                break;
            }
            if (clockStretchActive_)
            {
                // I2C spec requires minimum 4 microseconds after the SCL line
                // goes high following a clock stretch for the SCL line to be
                // pulled low again by the master. Do the same state one more
                // time to ensure this.
                clockStretchActive_ = false;
                break;
            }
            bool ack = (HW::SDA_Pin::get() == false);
            HW::SCL_Pin::set(0);
            if (!ack)
            {
                count_ = -EIO;
            }
            return true; // done
    }
    return false;
}
 
//
// BitBangI2C::state_rx()
//
template <class HW> __attribute__((optimize("-O3")))
inline bool BitBangI2C<HW>::state_rx(uint8_t *data, bool nack)
{
    switch(stateRx_)
    {
        case StateRx::DATA_7_SCL_SET:
            HW::SDA_Pin::set(1); // Always start with SDA high.
            // fall through
        case StateRx::DATA_6_SCL_SET:
        case StateRx::DATA_5_SCL_SET:
        case StateRx::DATA_4_SCL_SET:
        case StateRx::DATA_3_SCL_SET:
        case StateRx::DATA_2_SCL_SET:
        case StateRx::DATA_1_SCL_SET:
        case StateRx::DATA_0_SCL_SET:
            HW::SCL_Pin::set(1);
            ++stateRx_;
            break;
        case StateRx::DATA_7_SCL_CLR:
        case StateRx::DATA_6_SCL_CLR:
        case StateRx::DATA_5_SCL_CLR:
        case StateRx::DATA_4_SCL_CLR:
        case StateRx::DATA_3_SCL_CLR:
        case StateRx::DATA_2_SCL_CLR:
        case StateRx::DATA_1_SCL_CLR:
        case StateRx::DATA_0_SCL_CLR:
            if (HW::SCL_Pin::get() == false)
            {
                // Clock stretching, do the same state again.
                clockStretchActive_ = true;
                break;
            }
            if (clockStretchActive_)
            {
                // I2C spec requires minimum 4 microseconds after the SCL line
                // goes high following a clock stretch for the SCL line to be
                // pulled low again by the master or for the master to sample
                // the SDA data. Do the same state one more time to ensure this.
                clockStretchActive_ = false;
                break;
            }
            *data <<= 1;
            if (HW::SDA_Pin::get() == true)
            {
                *data |= 0x01;
            }
            HW::SCL_Pin::set(0);
            if (stateRx_ == StateRx::DATA_0_SCL_CLR && !nack)
            {
                // Send the ACK. If a NACK, SDA is already set.
                HW::SDA_Pin::set(0);
            }
            ++stateRx_;
            break;
        case StateRx::ACK_SDA_SCL_SET:
            HW::SCL_Pin::set(1);
            ++stateRx_;
            break;
        case StateRx::ACK_SCL_CLR:
            if (HW::SCL_Pin::get() == false)
            {
                // Clock stretching, do the same state again.
                clockStretchActive_ = true;
                break;
            }
            if (clockStretchActive_)
            {
                // I2C spec requires minimum 4 microseconds after the SCL line
                // goes high following a clock stretch for the SCL line to be
                // pulled low again by the master. Do the same state one more
                // time to ensure this.
                clockStretchActive_ = false;
                break;
            }
            HW::SCL_Pin::set(0);
            HW::SDA_Pin::set(1);
            return true;
    }
    return false;
}
 
//
// BitBangI2C::state_rx()
//
template <class HW> __attribute__((optimize("-O3")))
inline bool BitBangI2C<HW>::state_recovery()
{
    switch(stateRecovery_)
    {
        case StateRecovery::SDA_SET:
            HW::SDA_Pin::set(1); // Always start with SDA high.
            break;
        case StateRecovery::DATA_7_SCL_SET:
        case StateRecovery::DATA_6_SCL_SET:
        case StateRecovery::DATA_5_SCL_SET:
        case StateRecovery::DATA_4_SCL_SET:
        case StateRecovery::DATA_3_SCL_SET:
        case StateRecovery::DATA_2_SCL_SET:
        case StateRecovery::DATA_1_SCL_SET:
        case StateRecovery::DATA_0_SCL_SET:
        case StateRecovery::ACK_SCL_SET:
            HW::SCL_Pin::set(1);
            break;
        case StateRecovery::DATA_7_SCL_CLR:
        case StateRecovery::DATA_6_SCL_CLR:
        case StateRecovery::DATA_5_SCL_CLR:
        case StateRecovery::DATA_4_SCL_CLR:
        case StateRecovery::DATA_3_SCL_CLR:
        case StateRecovery::DATA_2_SCL_CLR:
        case StateRecovery::DATA_1_SCL_CLR:
        case StateRecovery::DATA_0_SCL_CLR:
        case StateRecovery::ACK_SCL_CLR:
            HW::SCL_Pin::set(0);
            break;
    }
    if (stateRecovery_ == StateRecovery::LAST)
    {
        return true;
    }
 
    ++stateRecovery_;
    return false;
}
 
//
// BitBangI2C::transfer()
//
template <class HW>
inline int BitBangI2C<HW>::transfer(struct i2c_msg *msg, bool stop)
{
    while (stop_)
    {
        // No need for a timed wait here because the stop state machine is not
        // gated by what happens on the bus (e.g. zero stretching).
        sem_.wait();
    }
    if (msg->len == 0)
    {
        // Message must have length of at least 1.
        return -EINVAL;
    }
 
    // Flush/reset semaphore.
    while (sem_.timedwait(0) == 0)
    {
    }
 
    {
        AtomicHolder h(this);
        // Reset state for a start/restart.
        msg_ = msg;
        count_ = 0;
        stop_ = stop;
        state_ = State::START;
        stateStart_ = StateStart::FIRST;
 
        // Enable tick timer.
        HW::tick_enable();
    }
 
    // We wait a minimum of 10 msec to account for any rounding in the "tick"
    // rate conversion. msg_->len is at least 1. We assume that worst ~50kHz
    // is the slowest that anyone will try to run the I2C bus, which will
    // result in just under 200 microseconds per byte. This leaves some room
    // for clock stretching.
    long long wait = std::max(MSEC_TO_NSEC(msg_->len), MSEC_TO_NSEC(10));
    if (sem_.timedwait(wait) == 0)
    {
        return count_;
    }
    else
    {
        // Flush/reset semaphore.
        while (sem_.timedwait(0) == 0)
        {
        }
 
        // Some kind of problem occured. Try a recovery operation.
        {
            AtomicHolder h(this);
            state_ = State::RECOVERY;
            stateRecovery_ = StateRecovery::FIRST;
        }
 
        // We don't care about the sempahore return value because there is
        // isn't much more we can do anyways. Just ensure stop_ is false and
        // ticks are disabled. There is actually no reason to expect the
        // semaphore to timeout, so this is really just defensive programming.
        sem_.timedwait(wait);
 
        // stop_ must be false for the next call of this method. It should only
        // be true on first entry at start to "reset" the bus to a known state.
        // On a timeout, it may not have been reset back to false.
        {
            AtomicHolder h(this);
            stop_ = false;
            HW::tick_disable();
        }
 
        return -ETIMEDOUT;
    }
}
 
#endif // _FREERTOS_DRIVERS_COMMON_BITBANG_I2C_HXX_