driver.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/channels/can_match.h"      // free fl::canMatch / canMatchBulk
#include "fl/channels/capabilities.h"   // DriverCapabilities, PinGroup, ChannelRequest, HandleResult
#include "fl/stl/atomic.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/span.h"
#include "fl/stl/string.h"  // IWYU pragma: keep
 
namespace fl {
 
// Forward declarations
class ChannelData;
FASTLED_SHARED_PTR(ChannelData);

class IChannelDriver {
public:
    struct PollNeededCallback {
        using Callback = void (*)(void*);
 
        Callback callback = nullptr;
        void* context = nullptr;
 
        constexpr PollNeededCallback() FL_NO_EXCEPT = default;
        constexpr PollNeededCallback(Callback cb, void* ctx) FL_NO_EXCEPT
            : callback(cb), context(ctx) {}
 
        bool isValid() const FL_NO_EXCEPT { return callback != nullptr; }
        explicit operator bool() const FL_NO_EXCEPT { return isValid(); }
 
        void invoke() const FL_NO_EXCEPT {
            if (callback != nullptr) {
                callback(context);
            }
        }
    };

    class PollNeededCallbackSlot {
      private:
        struct Snapshot {
            explicit Snapshot(PollNeededCallback cb) FL_NO_EXCEPT
                : callback(cb), next(nullptr) {}
 
            PollNeededCallback callback;
            Snapshot* next;
        };
 
      public:
        PollNeededCallbackSlot() FL_NO_EXCEPT
            : mSnapshot(nullptr), mRetired(nullptr) {}
 
        ~PollNeededCallbackSlot() FL_NO_EXCEPT {
            Snapshot* active =
                mSnapshot.exchange(nullptr, fl::memory_order_acq_rel);
            destroySnapshots(active);
            destroySnapshots(mRetired);
            mRetired = nullptr;
        }
 
        void set(PollNeededCallback callback) FL_NO_EXCEPT {
            if (callback.callback == nullptr) {
                clear();
                return;
            }
            Snapshot* snapshot = new Snapshot(callback); // ok bare allocation
            retire(mSnapshot.exchange(snapshot, fl::memory_order_acq_rel));
        }
 
        void clear() FL_NO_EXCEPT {
            retire(mSnapshot.exchange(nullptr, fl::memory_order_acq_rel));
        }
 
        void invoke() const FL_NO_EXCEPT {
            Snapshot* snapshot = mSnapshot.load(fl::memory_order_acquire);
            if (snapshot == nullptr) {
                return;
            }
            snapshot->callback.invoke();
        }
 
      private:
        void retire(Snapshot* snapshot) FL_NO_EXCEPT {
            if (snapshot == nullptr) {
                return;
            }
            // An ISR may already have loaded this pointer, so reclaim only when
            // the slot is destroyed and driver teardown has quiesced callbacks.
            snapshot->next = mRetired;
            mRetired = snapshot;
        }
 
        static void destroySnapshots(Snapshot* snapshot) FL_NO_EXCEPT {
            while (snapshot != nullptr) {
                Snapshot* next = snapshot->next;
                delete snapshot; // ok bare allocation
                snapshot = next;
            }
        }
 
        fl::atomic<Snapshot*> mSnapshot;
        Snapshot* mRetired;
    };

    struct Capabilities {
        bool supportsClockless;  
        bool supportsSpi;        

        constexpr Capabilities() FL_NO_EXCEPT : supportsClockless(false), supportsSpi(false) {}

        constexpr Capabilities(bool clockless, bool spi) FL_NO_EXCEPT
            : supportsClockless(clockless), supportsSpi(spi) {}
    };

    struct DriverState {
        enum Value {
            READY,      
            BUSY,       
            DRAINING,   
            ERROR,      
        };
 
        Value state;        
        fl::string error;   

        DriverState(Value v) FL_NO_EXCEPT : state(v), error() {}

        DriverState(Value v, const fl::string& e) FL_NO_EXCEPT : state(v), error(e) {}

        operator Value() const FL_NO_EXCEPT { return state; }

        bool operator==(Value v) const FL_NO_EXCEPT { return state == v; }
        bool operator!=(Value v) const FL_NO_EXCEPT { return state != v; }
    };

    virtual void enqueue(ChannelDataPtr channelData) FL_NO_EXCEPT = 0;

    virtual void show() FL_NO_EXCEPT = 0;

    virtual DriverState poll() FL_NO_EXCEPT = 0;

    virtual fl::string getName() const FL_NO_EXCEPT { return fl::string::from_literal(""); }

    virtual Capabilities getCapabilities() const FL_NO_EXCEPT = 0;

    virtual bool canHandle(const ChannelDataPtr& data) const FL_NO_EXCEPT = 0;
 
    // ================================================================
    // #3186 declarative-capabilities surface — drivers publish data;
    // the base class implements the matching virtuals by delegating to
    // free fl::canMatch / fl::canMatchBulk against the published data.
    // ================================================================

    virtual DriverCapabilities getDriverCapabilities() const FL_NO_EXCEPT {
        Capabilities legacy = getCapabilities();
        DriverCapabilities caps;
        caps.supports_clockless = legacy.supportsClockless;
        caps.supports_spi       = legacy.supportsSpi;
        return caps;
    }

    virtual fl::span<const PinGroup> getPinGroups() const FL_NO_EXCEPT {
        return fl::span<const PinGroup>();
    }

    HandleResult canMatch(const ChannelRequest& request) const FL_NO_EXCEPT {
        return fl::canMatch(getDriverCapabilities(), getPinGroups(), request);
    }

    bool waitForReady(u32 timeoutMs = 1000) FL_NO_EXCEPT;
    bool waitForReadyOrDraining(u32 timeoutMs = 1000) FL_NO_EXCEPT;

    virtual void setPollNeededCallback(PollNeededCallback callback) FL_NO_EXCEPT {
        (void)callback;
    }

    virtual bool waitDone(u32 timeoutMs = 1000) FL_NO_EXCEPT {
        return waitForReady(timeoutMs);
    }

    virtual ~IChannelDriver() FL_NO_EXCEPT = default;
 
protected:
    IChannelDriver() FL_NO_EXCEPT = default;
 
    // Non-copyable, non-movable
    IChannelDriver(const IChannelDriver&) FL_NO_EXCEPT = delete;
    IChannelDriver& operator=(const IChannelDriver&) FL_NO_EXCEPT = delete;
    IChannelDriver(IChannelDriver&&) FL_NO_EXCEPT = delete;
    IChannelDriver& operator=(IChannelDriver&&) FL_NO_EXCEPT = delete;
 
    template<typename Condition>
    bool waitForCondition(Condition condition, u32 timeoutMs = 1000) FL_NO_EXCEPT;
};
 
}  // namespace fl