bus.h

Go to the documentation of this file.

#pragma once

 
#include "fl/stl/noexcept.h"
#include "fl/stl/static_assert.h"
#include "fl/stl/stdint.h"
#include "platforms/is_platform.h"
 
// Platform CMSIS/Arduino headers (pulled in transitively above) define
// peripheral pointer macros that collide with our `Bus` enumerator names.
// Sam3X8E in particular does:
//     #define UART ((Uart *)0x400E0800U)
//     #define SPI  ((Spi  *)0x40008000U)
// Without these undefs, the preprocessor expands those names inside
// `enum class Bus { ..., SPI, UART, ... }`, producing a syntax error
// (see FastLED sam3x8e_due CI failure). Push the originals so any
// downstream TU that needs the register macros keeps working.
#pragma push_macro("UART")
#pragma push_macro("SPI")
#pragma push_macro("I2S")
#undef UART
#undef SPI
#undef I2S
 
// Post-#2428 architecture: drivers do NOT auto-register with `ChannelManager`.
// Only the platform-default driver TU (named by the legacy clockless controller's
// Phase 5b pre-bind via `BusTraits<DefaultBus<Chipset>>::instancePtr()`) links
// into the binary. Users who need additional drivers at runtime call:
//   - `fl::enableDrivers<fl::Bus::X, ...>()` for selective opt-in,
//   - `FastLED.enableAllDrivers()` for 3.10.3-style universal enrollment,
//   - `FastLED.setExclusiveDriver<fl::Bus::X>()` to register a non-default driver
//     at high priority (must be called before `addLeds<>` to override the pre-bind).
//
// The historical `FASTLED_DISABLE_LEGACY_DRIVER_REGISTRY` opt-in macro has been
// removed; the previously opt-in behaviour is now the only behaviour.
 
namespace fl {
 
// Forward declarations. The chipset family types live in fl/channels/config.h,
// but DefaultBus<Chipset> only needs the type identity, not the layout.
struct ClocklessChipset;
struct SpiChipsetConfig;

enum class Bus : fl::u8 {
    AUTO = 0,        
    RMT,             
    PARLIO,          
    SPI,             
    I2S,             
    I2S_SPI,         
    LCD_RGB,         
    LCD_SPI,         
    LCD_CLOCKLESS,   
    UART,            
    FLEX_IO,         
    OBJECT_FLED,     
    LPUART,          
    BIT_BANG,        
    STUB,            
};

template<typename Chipset> struct DefaultBus;
 
// ---------------------------------------------------------------------------
// Per-platform DefaultBus<Chipset> specializations
// ---------------------------------------------------------------------------
//
// Each specialization sets `value` to the Bus identifier whose driver TU should
// be linked when the user does not name a bus explicitly.
 
#if defined(FL_IS_STUB) || defined(FL_IS_WASM)
 
template<> struct DefaultBus<ClocklessChipset> {
    static constexpr Bus value = Bus::STUB;
};
 
template<> struct DefaultBus<SpiChipsetConfig> {
    static constexpr Bus value = Bus::STUB;
};
 
#elif defined(FL_IS_ESP32)
 
// ESP32-P4 / C6 / H2 / C5 -- PARLIO is the highest-priority clockless driver.
// ESP32-dev / S2 / S3 -- RMT is the recommended clockless default.
// Mirrors the priority order used by channel_manager_esp32.cpp.hpp.
#if defined(FL_IS_ESP_32P4) || defined(FL_IS_ESP_32C6) || \
    defined(FL_IS_ESP_32H2) || defined(FL_IS_ESP_32C5)
template<> struct DefaultBus<ClocklessChipset> {
    static constexpr Bus value = Bus::PARLIO;
};
#else
template<> struct DefaultBus<ClocklessChipset> {
    static constexpr Bus value = Bus::RMT;
};
#endif
 
// True SPI chipsets (APA102, SK9822, HD108): pick the platform-native parallel
// SPI driver. ESP32-S3 uses LCD_SPI; original ESP32 uses I2S_SPI; other variants
// are intentionally undefined so users get a clear "specify Bus::X explicitly"
// error rather than a silent wrong default.
#if defined(FL_IS_ESP_32S3)
template<> struct DefaultBus<SpiChipsetConfig> {
    static constexpr Bus value = Bus::LCD_SPI;
};
#elif defined(FL_IS_ESP_32DEV)
template<> struct DefaultBus<SpiChipsetConfig> {
    static constexpr Bus value = Bus::I2S_SPI;
};
#endif
 
#elif defined(FL_IS_TEENSY_4X)
 
template<> struct DefaultBus<ClocklessChipset> {
    static constexpr Bus value = Bus::OBJECT_FLED;
};
// SpiChipsetConfig default for Teensy 4.x is intentionally unspecified -- users
// pick explicitly between Bus::BIT_BANG and any future hardware-SPI bus.
 
#endif

inline const char* busName(Bus b) FL_NOEXCEPT {
    switch (b) {
        case Bus::AUTO:          return "AUTO";
        case Bus::RMT:           return "RMT";
        case Bus::PARLIO:        return "PARLIO";
        case Bus::SPI:           return "SPI";
        case Bus::I2S:           return "I2S";
        case Bus::I2S_SPI:       return "I2S_SPI";
        case Bus::LCD_RGB:       return "LCD_RGB";
        case Bus::LCD_SPI:       return "LCD_SPI";
        case Bus::LCD_CLOCKLESS: return "LCD_CLOCKLESS";
        case Bus::UART:          return "UART";
        case Bus::FLEX_IO:       return "FLEX_IO";
        case Bus::OBJECT_FLED:   return "OBJECT_FLED";
        case Bus::LPUART:        return "LPUART";
        case Bus::BIT_BANG:      return "BIT_BANG";
        case Bus::STUB:          return "STUB";
    }
    return "";  // unreachable — silences -Wreturn-type on toolchains that miss the exhaustive switch
}
 
// Drift-prevention: if a new `Bus` enumerator is added, the switch above must
// gain a case. Update this assertion to the new last enumerator after you
// wire the case in — its failure is the prompt to revisit `busName()`.
FL_STATIC_ASSERT(static_cast<fl::u8>(Bus::STUB) == 14,
                 "Bus changed: add the new value to busName() in this file");  // ok plain enum
 
}  // namespace fl
 
// Restore the original platform macros for any downstream code that needs
// the CMSIS / Arduino register pointers.
#pragma pop_macro("I2S")
#pragma pop_macro("SPI")
#pragma pop_macro("UART")