capabilities.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/bitset.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/optional.h"
#include "fl/stl/span.h"
#include "fl/stl/stdint.h"
#include "fl/stl/string_view.h"
 
namespace fl {
 
// =====================================================================
// Protocol — what bus shape the channel uses.
// =====================================================================
 
enum class Protocol : fl::u8 {
    Clockless = 0,  
    Spi       = 1,  
};
 
 
// =====================================================================
// FreqRange / NanosRange — inclusive [min, max] ranges with explicit
// "unspecified" sentinels.
//
// All-zero is intentionally NOT the unspecified state — that would
// silently match every legitimate value. Use any() / exactly() /
// atLeast() / atMost() to construct.
// =====================================================================
 
struct FreqRange {
    fl::u32 min_hz;
    fl::u32 max_hz;
 
    static constexpr FreqRange any() FL_NO_EXCEPT {
        return {0u, 0xFFFFFFFFu};
    }
    static constexpr FreqRange exactly(fl::u32 hz) FL_NO_EXCEPT {
        return {hz, hz};
    }
    static constexpr FreqRange atLeast(fl::u32 hz) FL_NO_EXCEPT {
        return {hz, 0xFFFFFFFFu};
    }
    static constexpr FreqRange atMost(fl::u32 hz) FL_NO_EXCEPT {
        return {0u, hz};
    }
 
    constexpr bool isUnspecified() const FL_NO_EXCEPT {
        return min_hz == 0u && max_hz == 0xFFFFFFFFu;
    }
    constexpr bool contains(fl::u32 hz) const FL_NO_EXCEPT {
        return hz >= min_hz && hz <= max_hz;
    }
};
 
struct NanosRange {
    fl::u32 min_ns;
    fl::u32 max_ns;
 
    static constexpr NanosRange any() FL_NO_EXCEPT {
        return {0u, 0xFFFFFFFFu};
    }
    static constexpr NanosRange exactly(fl::u32 ns) FL_NO_EXCEPT {
        return {ns, ns};
    }
    static constexpr NanosRange atLeast(fl::u32 ns) FL_NO_EXCEPT {
        return {ns, 0xFFFFFFFFu};
    }
    static constexpr NanosRange atMost(fl::u32 ns) FL_NO_EXCEPT {
        return {0u, ns};
    }
 
    constexpr bool isUnspecified() const FL_NO_EXCEPT {
        return min_ns == 0u && max_ns == 0xFFFFFFFFu;
    }
    constexpr bool contains(fl::u32 ns) const FL_NO_EXCEPT {
        return ns >= min_ns && ns <= max_ns;
    }
};
 
 
// =====================================================================
// PinSet — discriminated pin allowlist (bitset-backed).
//
// Four conceptual shapes, three encodings:
//   None          — slot not applicable (e.g. clock on a Clockless group)
//   AnyOutputPin  — any GPIO output (RMT5-style flexibility)
//   Allowlist size = 1 — fixed pin (LPUART per-instance TX, SPI IO_MUX)
//   Allowlist size N>1 — flex within an allowlist (FlexIO shifters)
// =====================================================================

static constexpr fl::u32 kPinSetCapacity = 128u;
 
using PinBitset = fl::bitset_fixed<kPinSetCapacity>;
 
enum class PinSetKind : fl::u8 {
    None         = 0,
    AnyOutputPin = 1,
    Allowlist    = 2,
};
 
struct PinSet {
    PinSetKind kind;
    PinBitset pins;  
 
    constexpr PinSet() FL_NO_EXCEPT : kind(PinSetKind::None), pins() {}
    constexpr PinSet(PinSetKind k) FL_NO_EXCEPT : kind(k), pins() {}
    constexpr PinSet(PinSetKind k, const PinBitset& b) FL_NO_EXCEPT : kind(k), pins(b) {}

    static constexpr PinSet none() FL_NO_EXCEPT { return PinSet(PinSetKind::None); }

    static constexpr PinSet anyOutput() FL_NO_EXCEPT { return PinSet(PinSetKind::AnyOutputPin); }

    template <fl::size N>
    static PinSet allowlist(const fl::i16 (&arr)[N]) FL_NO_EXCEPT {
        PinSet ps(PinSetKind::Allowlist);
        for (fl::size i = 0; i < N; ++i) {
            if (arr[i] >= 0 && static_cast<fl::u32>(arr[i]) < kPinSetCapacity) {
                ps.pins.set(static_cast<fl::u32>(arr[i]));
            }
        }
        return ps;
    }

    static PinSet fixed(fl::i16 pin) FL_NO_EXCEPT;

    bool accepts(fl::i16 pin) const FL_NO_EXCEPT;

    bool acceptsAll(const PinBitset& request) const FL_NO_EXCEPT;
};
 
 
// =====================================================================
// ClocklessTimingCapability — driver's clock-tree model.
//
// Captures the physics: tick width = base_clock_hz / divider, phases
// are held for an integer number of ticks. Compatibility with a
// chipset's tolerance windows is determined by whether an integer N
// exists such that N * tick_ns falls inside each window.
//
// DMA-fed drivers (PARLIO, I2S) also fit: their "tick" is the divided
// peripheral clock, their "phase" is consecutive same-state bits in a
// shaped data pattern.
// =====================================================================
 
struct ClocklessTimingCapability {
    fl::u32 base_clock_hz;     
    fl::u16 min_divider;        
    fl::u16 max_divider;        
    fl::u16 max_phase_ticks;    
 
    static constexpr ClocklessTimingCapability unspecified() FL_NO_EXCEPT {
        return {0u, 0u, 0u, 0u};
    }
    constexpr bool isUnspecified() const FL_NO_EXCEPT {
        return base_clock_hz == 0u;
    }
};
 
 
// =====================================================================
// PinGroup — one independent hardware resource.
//
// Multiple groups per driver describe distinct slots (RMT channels,
// FlexIO instances, LPUART instances). Each can independently match
// some subset of requests.
// =====================================================================
 
struct PinGroup {
    fl::u16    instance_id;             
    Protocol   protocol;                 
 
    PinSet data_pins;                    
    PinSet clock_pins;                   
 
    fl::u8 max_concurrent;               

    FreqRange frequency;

    fl::u8 shared_clock_domain_id;

    fl::u8 shared_budget_id;

    bool pins_must_be_contiguous;
 
    constexpr PinGroup() FL_NO_EXCEPT
        : instance_id(0)
        , protocol(Protocol::Clockless)
        , data_pins()
        , clock_pins()
        , max_concurrent(1)
        , frequency(FreqRange::any())
        , shared_clock_domain_id(0)
        , shared_budget_id(0)
        , pins_must_be_contiguous(false) {}
};
 
 
// =====================================================================
// DriverCapabilities — tiny constant-header descriptor.
//
// Note: there is intentionally NO supported_chipsets field. Chipset
// support is a derived consequence of timing — if a chipset's tolerance
// windows can be hit by the driver's clock tree, the chipset is
// supported. New chipsets work automatically without driver updates.
// =====================================================================
 
struct DriverCapabilities {
    fl::string_view name;       
    fl::u8 priority;            
    bool supports_clockless;
    bool supports_spi;
    fl::u8 max_total_channels;  

    FreqRange clockless_frequency;
    FreqRange spi_frequency;

    ClocklessTimingCapability clockless_timing;

    struct Flags {
        fl::u8 synchronized_start    : 1;  
        fl::u8 requires_dma_memory   : 1;  
        fl::u8 open_drain_capable    : 1;
        fl::u8 mixed_protocols_ok    : 1;  
        fl::u8 reserved              : 4;
    } flags;

    DriverCapabilities() FL_NO_EXCEPT;
};
 
 
// =====================================================================
// ChipsetClocklessTiming — chipset's per-phase tolerance windows.
//
// Each window is the inclusive [min, max] in nanoseconds that the
// driver's quantized output must land inside for the chipset to be
// driven correctly. e.g. WS2812 T0H is nominally 350 ns ± 150 ns,
// so t0h_window = {200, 500}.
// =====================================================================
 
struct ChipsetClocklessTiming {
    NanosRange t0h_window;
    NanosRange t0l_window;
    NanosRange t1h_window;
    NanosRange t1l_window;
 
    static constexpr ChipsetClocklessTiming unspecified() FL_NO_EXCEPT {
        return {NanosRange::any(), NanosRange::any(),
                NanosRange::any(), NanosRange::any()};
    }
};
 
 
// =====================================================================
// ChannelRequest — passive input to canMatch.
//
// One type for both single-pin and ganged-multi-pin requests: data_pins
// is a bitset, so a single-pin request just has one bit set. Drivers
// that fan out to N independent groups vs gang into one group is the
// resolver's concern (not the request's).
//
// Requests are NOT a first-class API surface — sketches don't construct
// them. The Channel Manager builds them from addLeds<>() calls and
// hands them to fl::canMatch against each driver's published capability
// data.
// =====================================================================
 
struct ChannelRequest {
    Protocol protocol;
    PinBitset data_pins;                    
    fl::i16 clock_pin;                      
    ChipsetClocklessTiming timing;          
    fl::optional<fl::u32> frequency_hz;     
 
    ChannelRequest() FL_NO_EXCEPT
        : protocol(Protocol::Clockless)
        , data_pins()
        , clock_pin(-1)
        , timing(ChipsetClocklessTiming::unspecified())
        , frequency_hz() {}

    static ChannelRequest singlePin(
            Protocol p, fl::i16 data, fl::i16 clock,
            const ChipsetClocklessTiming& t = ChipsetClocklessTiming::unspecified(),
            fl::optional<fl::u32> freq = fl::optional<fl::u32>()) FL_NO_EXCEPT;
};
 
 
// =====================================================================
// HandleResult — outcome of canMatch / canMatchBulk.
// =====================================================================
 
enum class HandleResult : fl::u8 {
    Yes          = 0,
    NoProtocol   = 1,   
    NoPin        = 2,   
    NoPinPair    = 3,   
    NoFrequency  = 4,   
    NoTiming     = 5,   
    NoCapacity   = 6,   
};

constexpr bool isYes(HandleResult r) FL_NO_EXCEPT {
    return r == HandleResult::Yes;
}
 
}  // namespace fl