resolveDynamicDriver()

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

private

Cold slow-path helper for showPixels().

Resolve the driver for this channel.

Handles dynamic ChannelManager::selectDriverForChannel() lookup AND the bus-key-miss diagnostics (#2455 / #2459). This is now the only driver-resolution path.

Marked FL_NO_INLINE to keep showPixels() 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 path stays compact – see #2773 item 2.1. This is the only driver-resolution path; there is no pre-bound fast path.

Marked noinline (via FL_NO_INLINE) so the compiler doesn't fold the cold body back into showPixels.

Definition at line 829 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(busDriverName(mBus, mBusWhich, isSpi()));
    }
 
    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::busDriverName(), fl::ChannelManager::findDriverByName(), FL_ERROR, fl::FL_NO_EXCEPT, fl::string::from_literal(), fl::ChannelManager::instance(), isSpi(), mBus, mBusWarned, mBusWhich, 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: