Prerequisites

You should already be comfortable with device tree phandle references and the provider-side clocks/#clock-cells relationship covered earlier in this chapter, since the consumer binding is defined entirely in terms of what a provider node has already exposed.

The Consumer Device Tree Binding

A consumer node requests one or more clock lines through two device tree properties, at minimum:

ep_i2s: ep-i2s@03040000 {
    compatible = "ep,i2s-controller";
    reg = <0x03040000 0x2000>;
    interrupts = ;

    clocks = <&ep_clks EP_CLK_I2S_BUS>,
             <&ep_clks EP_CLK_I2S_MCLK>;
    clock-names = "bus", "mclk";

    status = "okay";
};

• clocks — a list of phandle references to provider clocks, each followed by however many index cells that provider’s #clock-cells declares. This is the same phandle-plus-args pattern used by of_clk_get_parent_name() internally, generalized here to any consumer.
• clock-names — a parallel array of strings, one per entry in clocks, naming each clock line from the consumer’s own point of view. This is the id string your driver will later pass to clk_get()/devm_clk_get() to retrieve the matching struct clk.

The clock-names strings should describe the consumer’s own input signal, never the provider’s internal naming. This is deliberate and important: a consumer node must never directly reference the provider’s clock-output-names property. clock-output-names exists purely for humans reading the provider’s own device tree source, and for of_clk_get_parent_name() to resolve names between provider-side clock nodes — it is not part of the consumer-facing contract, and consumer code should never assume it matches anything meaningful to the consumer driver itself.

Grabbing and Releasing Clocks

Once the binding is in place, the driver retrieves a struct clk handle with:

struct clk *clk_get(struct device *dev, const char *id);
void clk_put(struct clk *clk);
struct clk *devm_clk_get(struct device *dev, const char *id);

dev is the consuming device, and id is one of the strings you listed in clock-names. On success, clk_get() returns an opaque struct clk pointer that every other consumer-side API accepts. clk_put() releases it. clk_get() and clk_put() are defined in drivers/clk/clkdev.c, while the rest of the consumer API lives in drivers/clk/clk.c. devm_clk_get() is simply the resource-managed version of clk_get() — the clock is automatically released when the device is unbound, which is why it is the recommended choice in almost every modern platform driver rather than manually pairing clk_get()/clk_put() around every error path.

Preparing and Unpreparing

Before a clock can be enabled, it generally needs to be prepared:

void clk_prepare(struct clk *clk);
void clk_unprepare(struct clk *clk);

clk_prepare() and clk_unprepare() may sleep, which means they must never be called from atomic context — an interrupt handler, a spinlock-held region, or anywhere else blocking is not allowed. This sleep-capable design exists specifically so that clock providers whose hardware sits behind a slow bus, such as an I2C or SPI-controlled clock chip, have somewhere safe to do that bus transaction. Recall from earlier in this chapter that struct clk_gate’s enable/disable ops must not sleep, which is exactly why non-mmio gate clocks implement their register access inside the prepare/unprepare ops instead — this consumer-side contract (always prepare before enable, always unprepare after disable) is precisely what makes that provider-side workaround safe.

Enabling and Disabling

Gating and ungating the actual clock signal uses a separate, atomic-safe pair of calls:

int clk_enable(struct clk *clk);
void clk_disable(struct clk *clk);

clk_enable() must not sleep, and its job is strictly to ungate the clock — it returns 0 on success or a negative error code otherwise. clk_disable() reverses it. Because forgetting to call clk_prepare() before clk_enable() is a subtle and easy mistake, the framework provides a single convenience call that enforces the correct order internally:

int clk_prepare_enable(struct clk *clk);
void clk_disable_unprepare(struct clk *clk);

clk_prepare_enable() calls clk_prepare() followed by clk_enable() and returns the combined result; clk_disable_unprepare() is the exact mirror image for teardown. In modern driver code these two wrapper calls are used far more often than the four underlying calls used individually — reach for the split prepare/enable and disable/unprepare calls only when you specifically need to prepare a clock well ahead of actually enabling it, such as during a probe-time validation step before the hardware is touched.

Worked Example: ep_clk_consumer_lifecycle_demo

struct ep_i2s_priv {
    struct clk *bus_clk;
    struct clk *mclk;
};

static int ep_i2s_probe(struct platform_device *pdev)
{
    struct ep_i2s_priv *priv;
    int ret;

    priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv)
        return -ENOMEM;

    priv->bus_clk = devm_clk_get(&pdev->dev, "bus");
    if (IS_ERR(priv->bus_clk))
        return dev_err_probe(&pdev->dev, PTR_ERR(priv->bus_clk),
                              "failed to get bus clk\n");

    priv->mclk = devm_clk_get(&pdev->dev, "mclk");
    if (IS_ERR(priv->mclk))
        return dev_err_probe(&pdev->dev, PTR_ERR(priv->mclk),
                              "failed to get mclk\n");

    ret = clk_prepare_enable(priv->bus_clk);
    if (ret)
        return ret;

    ret = clk_prepare_enable(priv->mclk);
    if (ret) {
        clk_disable_unprepare(priv->bus_clk);
        return ret;
    }

    platform_set_drvdata(pdev, priv);
    dev_info(&pdev->dev, "ep_i2s clocks enabled\n");
    return 0;
}

static void ep_i2s_remove(struct platform_device *pdev)
{
    struct ep_i2s_priv *priv = platform_get_drvdata(pdev);

    clk_disable_unprepare(priv->mclk);
    clk_disable_unprepare(priv->bus_clk);
}

Build and Test Walkthrough

$ make -C /lib/modules/$(uname -r)/build M=$PWD modules
$ sudo insmod ep_i2s.ko
$ dmesg | tail
[   88.204112] ep_i2s ep-i2s@03040000: ep_i2s clocks enabled

$ sudo rmmod ep_i2s
$ dmesg | tail
[   95.667001] ep_i2s ep-i2s@03040000: ep_i2s: clocks disabled and unprepared

Common Mistakes

• Calling clk_enable() without ever calling clk_prepare() first — this happens to work on some mmio-only setups but breaks unpredictably on sleeping-bus clock providers, so it should never be relied upon.
• Referencing a provider’s clock-output-names value inside a consumer’s clock-names property — the two namespaces are unrelated, and the binding rule explicitly forbids this.
• Calling clk_prepare() or clk_unprepare() from inside an interrupt handler or other atomic context — both may sleep and will trigger a scheduling-while-atomic warning if misused this way.
• Leaking a clk_get() reference by forgetting the matching clk_put() in an error path — this is exactly why devm_clk_get() is preferred in nearly all cases.

Best Practices

• Default to devm_clk_get() and clk_prepare_enable()/clk_disable_unprepare() unless you have a specific reason to split prepare and enable into separate phases.
• Always check the return values of clk_get()/devm_clk_get() with IS_ERR() and propagate the error with dev_err_probe(), which also handles -EPROBE_DEFER cleanly if the provider has not registered yet.
• Name your clock-names strings after what the signal does for your device (bus, mclk, ref, pclk), not after anything the provider calls its own outputs.

Summary and Key Takeaways

The clock consumer API is intentionally small and hardware-agnostic: clocks/clock-names in the device tree map cleanly onto clk_get()/devm_clk_get() by id string, and every clock — regardless of whether its provider is an mmio gate, a mux, a composite block, or a sleeping I2C-controlled chip — goes through the same prepare/enable lifecycle from the consumer’s perspective. Getting the prepare-before-enable ordering right, and always releasing what you acquire, is what makes consumer drivers portable across radically different clock provider hardware. The next lecture completes the consumer API by covering rate functions (clk_get_rate(), clk_set_rate(), clk_round_rate()) and parent functions (clk_set_parent(), clk_get_parent()), finishing with a full real-world driver example that ties the entire consumer API together.

FAQ