resolveDynamicDriver()

FL_NO_INLINE fl::shared_ptr< IChannelDriver > fl::Channel::resolveDynamicDriver ( )

private

Cold slow-path helper for showPixels() when the driver was NOT pre-bound via setDriver().

Cold fallback for the non-pre-bound driver path.

Handles dynamic ChannelManager::selectDriverForChannel() lookup AND the bus-key-miss diagnostics (#2455 / #2459).

Marked FL_NO_INLINE so the legacy addLeds<> hot path stays compact — see #2773 item 2.1. Returns nullptr on a hard miss (caller should silently bail).

Handles dynamic ChannelManager::selectDriverForChannel lookup AND the bus-key-miss diagnostic chain. Hoisted out of showPixels so the hot legacy addLeds<> path stays compact — see #2773 item 2.1.

Marked noinline (via FL_NOINLINE) so the compiler doesn't fold the cold body back into showPixels. The whole helper is reachable only when mDriverPreBound == false, which on stock Blink is never true — LTO can use that across the call site to keep the cold body off the hot icache line.

Definition at line 391 of file channel.cpp.hpp.

                                                           {
#if defined(FASTLED_DISABLE_DYNAMIC_DRIVER) && FASTLED_DISABLE_DYNAMIC_DRIVER
    // Body excluded via FASTLED_DISABLE_DYNAMIC_DRIVER (#2926). The
    // showPixels call site is also gated so this is unreachable; the
    // empty body lets the linker dead-strip ChannelManager::findDriverByName
    // and selectDriverForChannel along with this symbol.
    return {};
#else
    // Build busKey only when we actually need it (mBus != AUTO).
    fl::string busKey;
    if (mBus != Bus::AUTO) {
        busKey = fl::string::from_literal(busName(mBus));
    }
 
    fl::shared_ptr<IChannelDriver> driver =
        ChannelManager::instance().selectDriverForChannel(mChannelData, busKey);
    mDriver = driver;
 
    // #2455 / #2459: one-shot diagnostic when a typed-Bus miss happens.
    // Probe via `findDriverByName` (silent) to distinguish "driver wasn't
    // instantiated" from "driver exists but canHandle() rejected this
    // chipset" — resolution paths differ. The mBusWarned guard suppresses
    // duplicate logs on subsequent shows of the same channel.
#if FASTLED_LOG_RUNTIME_ENABLED
    if (mBus != Bus::AUTO && !mBusWarned &&
        (!driver || driver->getName() != busKey)) {
        auto busDriver = ChannelManager::instance().findDriverByName(busKey);
        if (!busDriver) {
            // Typed Bus miss — emit the actionable hint with the three
            // currently-shipping remediations (option 3 added in #2460).
            FL_ERROR("Channel '" << mName << "': Driver '" << busKey
                << "' wasn't instantiated. Resolve with: "
                << "(1) fl::enableDrivers<fl::Bus::" << busKey << ">() "
                << "(links only this driver), "
                << "(2) FastLED.enableAllDrivers() (links every driver), or "
                << "(3) FastLED.addLeds<..., fl::Bus::" << busKey << ">(...) "
                << "(legacy API; pins Bus + triggers linker keep-alive). "
                << "Defaulting to AUTO/priority dispatch.");
        } else {
            // Registered, but canHandle() said no — bus/chipset mismatch.
            FL_ERROR("Channel '" << mName << "': Driver '" << busKey
                << "' is registered but cannot handle this channel's chipset "
                << "(bus/chipset mismatch). Defaulting to AUTO/priority dispatch.");
        }
        mBusWarned = true;
    }
    if (!driver) {
        FL_ERROR("Channel '" << mName << "': No compatible driver found - cannot transmit");
    }
#endif  // FASTLED_LOG_RUNTIME_ENABLED — release skips the per-frame
        // driver->getName() != busKey compare + the silent
        // findDriverByName probe (used only to differentiate the
        // FL_ERROR message). The functional return value below is
        // preserved in both builds. See #2952.
    return driver;
#endif  // !FASTLED_DISABLE_DYNAMIC_DRIVER
}

References fl::AUTO, fl::busName(), fl::ChannelManager::findDriverByName(), FL_ERROR, fl::string::from_literal(), fl::ChannelManager::instance(), mBus, mBusWarned, mChannelData, mDriver, mName, and fl::ChannelManager::selectDriverForChannel().

Referenced by showPixels().

Here is the call graph for this function:

Here is the caller graph for this function: