The Common Clk Framework¶

Author:: Mike Turquette <mturquette@ti.com>

This document endeavours to explain the common clk framework details, and how to port a platform over to this framework. It is not yet a detailed explanation of the clock api in include/linux/clk.h, but perhaps someday it will include that information.

Introduction and interface split¶

The common clk framework is an interface to control the clock nodes available on various devices today. This may come in the form of clock gating, rate adjustment, muxing or other operations. This framework is enabled with the CONFIG_COMMON_CLK option.

The interface itself is divided into two halves, each shielded from the details of its counterpart. First is the common definition of struct clk which unifies the framework-level accounting and infrastructure that has traditionally been duplicated across a variety of platforms. Second is a common implementation of the clk.h api, defined in drivers/clk/clk.c. Finally there is struct clk_ops, whose operations are invoked by the clk api implementation.

The second half of the interface is comprised of the hardware-specific callbacks registered with struct clk_ops and the corresponding hardware-specific structures needed to model a particular clock. For the remainder of this document any reference to a callback in struct clk_ops, such as .enable or .set_rate, implies the hardware-specific implementation of that code. Likewise, references to struct clk_foo serve as a convenient shorthand for the implementation of the hardware-specific bits for the hypothetical “foo” hardware.

Tying the two halves of this interface together is struct clk_hw, which is defined in struct clk_foo and pointed to within struct clk_core. This allows for easy navigation between the two discrete halves of the common clock interface.

Common data structures and api¶

struct clk_core¶: The internal state of a clk in the clk tree.

Definition:

struct clk_core {
    const char              *name;
    const struct clk_ops    *ops;
    struct clk_hw           *hw;
    struct module           *owner;
    struct device           *dev;
    struct hlist_node       rpm_node;
    struct device_node      *of_node;
    struct clk_core         *parent;
    struct clk_parent_map   *parents;
    u8 num_parents;
    u8 new_parent_index;
    unsigned long           rate;
    unsigned long           req_rate;
    unsigned long           new_rate;
    struct clk_core         *new_parent;
    struct clk_core         *new_child;
    unsigned long           flags;
    bool orphan;
    bool rpm_enabled;
    unsigned int            enable_count;
    unsigned int            prepare_count;
    unsigned int            protect_count;
    unsigned long           min_rate;
    unsigned long           max_rate;
    unsigned long           accuracy;
    int phase;
    struct clk_duty         duty;
    struct hlist_head       children;
    struct hlist_node       child_node;
    struct hlist_node       hashtable_node;
    struct hlist_head       clks;
    unsigned int            notifier_count;
#ifdef CONFIG_DEBUG_FS;
    struct dentry           *dentry;
    struct hlist_node       debug_node;
#endif;
    struct kref             ref;
};

Members

name: Unique name of the clk for identification.
ops: Pointer to hardware-specific operations for this clk.
hw: Pointer for traversing from a struct clk to its corresponding hardware-specific structure.
owner: Kernel module owning this clk (for reference counting).
dev: Device associated with this clk (optional)
rpm_node: Node for runtime power management list management.
of_node: Device tree node associated with this clk (if applicable)
parent: Pointer to the current parent in the clock tree.
parents: Array of possible parents (for muxes/selectable parents).
num_parents: Number of possible parents.
new_parent_index: Index of the new parent during parent change operations.
rate: Current cached clock rate (Hz).
req_rate: The last rate requested by a call to clk_set_rate(). It’s initialized to clk_core->rate. It’s also updated to clk_core->rate every time the clock is reparented, and when we’re doing the orphan -> !orphan transition.
new_rate: New rate to be set during a rate change operation.
new_parent: Pointer to new parent during parent change. This is also used when a clk’s rate is changed.
new_child: Pointer to new child during reparenting. This is also used when a clk’s rate is changed.
flags: Clock property and capability flags. See clk framework flags.
orphan: True if this clk is currently orphaned.
rpm_enabled: True if runtime power management is enabled for this clk.
enable_count: Reference count of enables.
prepare_count: Reference count of prepares.
protect_count: Protection reference count against disable.
min_rate: Minimum supported clock rate (Hz).
max_rate: Maximum supported clock rate (Hz).
accuracy: Accuracy of the clock rate (parts per billion).
phase: Current phase (degrees).
duty: Current duty cycle configuration (as ratio: num/den).
children: All of the children of this clk.
child_node: Node for linking as a child in the parent’s list.
hashtable_node: Node for hash table that allows fast clk lookup by name.
clks: All of the clk consumers registered.
notifier_count: Number of notifiers registered for this clk.
dentry: DebugFS entry for this clk.
debug_node: DebugFS node for this clk.
ref: Reference count for structure lifetime management.

Description

Managed by the clk framework. Clk providers and consumers do not interact with this structure directly. Instead, clk operations flow through the framework and the framework manipulates this structure to keep track of parent/child relationships, rate, enable state, etc.

The members above make up the core of the clk tree topology. The clk api itself defines several driver-facing functions which operate on struct clk. That api is documented in include/linux/clk.h.

Platforms and devices utilizing the common struct clk_core use the struct clk_ops pointer in struct clk_core to perform the hardware-specific parts of the operations defined in clk-provider.h, and can set one or more framework-level flags documented below.

struct clk_ops¶: Callback operations for hardware clocks; these are to be provided by the clock implementation, and will be called by drivers through the clk_* api.

Definition:

struct clk_ops {
    int (*prepare)(struct clk_hw *hw);
    void (*unprepare)(struct clk_hw *hw);
    int (*is_prepared)(struct clk_hw *hw);
    void (*unprepare_unused)(struct clk_hw *hw);
    int (*enable)(struct clk_hw *hw);
    void (*disable)(struct clk_hw *hw);
    int (*is_enabled)(struct clk_hw *hw);
    void (*disable_unused)(struct clk_hw *hw);
    int (*save_context)(struct clk_hw *hw);
    void (*restore_context)(struct clk_hw *hw);
    unsigned long   (*recalc_rate)(struct clk_hw *hw, unsigned long parent_rate);
    int (*determine_rate)(struct clk_hw *hw, struct clk_rate_request *req);
    int (*set_parent)(struct clk_hw *hw, u8 index);
    u8 (*get_parent)(struct clk_hw *hw);
    int (*set_rate)(struct clk_hw *hw, unsigned long rate, unsigned long parent_rate);
    int (*set_rate_and_parent)(struct clk_hw *hw, unsigned long rate, unsigned long parent_rate, u8 index);
    int (*set_spread_spectrum)(struct clk_hw *hw, const struct clk_spread_spectrum *ss_conf);
    unsigned long   (*recalc_accuracy)(struct clk_hw *hw, unsigned long parent_accuracy);
    int (*get_phase)(struct clk_hw *hw);
    int (*set_phase)(struct clk_hw *hw, int degrees);
    int (*get_duty_cycle)(struct clk_hw *hw, struct clk_duty *duty);
    int (*set_duty_cycle)(struct clk_hw *hw, struct clk_duty *duty);
    int (*init)(struct clk_hw *hw);
    void (*terminate)(struct clk_hw *hw);
    void (*debug_init)(struct clk_hw *hw, struct dentry *dentry);
};

Members

prepare: Prepare the clock for enabling. This must not return until the clock is fully prepared, and it’s safe to call clk_enable. This callback is intended to allow clock implementations to do any initialisation that may sleep. Called with prepare_lock held.
unprepare: Release the clock from its prepared state. This will typically undo any work done in the prepare callback. Called with prepare_lock held.
is_prepared: Queries the hardware to determine if the clock is prepared. This function is allowed to sleep. Optional, if this op is not set then the prepare count will be used.
unprepare_unused: Unprepare the clock atomically. Only called from clk_disable_unused for prepare clocks with special needs. Called with prepare mutex held. This function may sleep.
enable: Enable the clock atomically. This must not return until the clock is generating a valid clock signal, usable by consumer devices. Called with enable_lock held. This function must not sleep.
disable: Disable the clock atomically. Called with enable_lock held. This function must not sleep.
is_enabled: Queries the hardware to determine if the clock is enabled. This function must not sleep. Optional, if this op is not set then the enable count will be used.
disable_unused: Disable the clock atomically. Only called from clk_disable_unused for gate clocks with special needs. Called with enable_lock held. This function must not sleep.
save_context: Save the context of the clock in prepration for poweroff.
restore_context: Restore the context of the clock after a restoration of power.
recalc_rate: Recalculate the rate of this clock, by querying hardware. The parent rate is an input parameter. It is up to the caller to ensure that the prepare_mutex is held across this call. If the driver cannot figure out a rate for this clock, it must return 0. Returns the calculated rate. Optional, but recommended - if this op is not set then clock rate will be initialized to 0.
determine_rate: Given a target rate as input, returns the closest rate actually supported by the clock, and optionally the parent clock that should be used to provide the clock rate.
set_parent: Change the input source of this clock; for clocks with multiple possible parents specify a new parent by passing in the index as a u8 corresponding to the parent in either the .parent_names or .parents arrays. This function in affect translates an array index into the value programmed into the hardware. Returns 0 on success, -EERROR otherwise.
get_parent: Queries the hardware to determine the parent of a clock. The return value is a u8 which specifies the index corresponding to the parent clock. This index can be applied to either the .parent_names or .parents arrays. In short, this function translates the parent value read from hardware into an array index. Currently only called when the clock is initialized by __clk_init. This callback is mandatory for clocks with multiple parents. It is optional (and unnecessary) for clocks with 0 or 1 parents.
set_rate: Change the rate of this clock. The requested rate is specified by the second argument, which should typically be the return of .determine_rate call. The third argument gives the parent rate which is likely helpful for most .set_rate implementation. Returns 0 on success, -EERROR otherwise.
set_rate_and_parent: Change the rate and the parent of this clock. The requested rate is specified by the second argument, which should typically be the return of clk_round_rate() call. The third argument gives the parent rate which is likely helpful for most .set_rate_and_parent implementation. The fourth argument gives the parent index. This callback is optional (and unnecessary) for clocks with 0 or 1 parents as well as for clocks that can tolerate switching the rate and the parent separately via calls to .set_parent and .set_rate. Returns 0 on success, -EERROR otherwise.
set_spread_spectrum: Optional callback used to configure the spread spectrum modulation frequency, percentage, and method to reduce EMI by spreading the clock frequency over a wider range. Returns 0 on success, -EERROR otherwise.
recalc_accuracy: Recalculate the accuracy of this clock. The clock accuracy is expressed in ppb (parts per billion). The parent accuracy is an input parameter. Returns the calculated accuracy. Optional - if this op is not set then clock accuracy will be initialized to parent accuracy or 0 (perfect clock) if clock has no parent.
get_phase: Queries the hardware to get the current phase of a clock. Returned values are 0-359 degrees on success, negative error codes on failure.
set_phase: Shift the phase this clock signal in degrees specified by the second argument. Valid values for degrees are 0-359. Return 0 on success, otherwise -EERROR.
get_duty_cycle: Queries the hardware to get the current duty cycle ratio of a clock. Returned values denominator cannot be 0 and must be superior or equal to the numerator.
set_duty_cycle: Apply the duty cycle ratio to this clock signal specified by the numerator (2nd argurment) and denominator (3rd argument). Argument must be a valid ratio (denominator > 0 and >= numerator) Return 0 on success, otherwise -EERROR.
init: Perform platform-specific initialization magic. This is not used by any of the basic clock types. This callback exist for HW which needs to perform some initialisation magic for CCF to get an accurate view of the clock. It may also be used dynamic resource allocation is required. It shall not used to deal with clock parameters, such as rate or parents. Returns 0 on success, -EERROR otherwise.
terminate: Free any resource allocated by init.
debug_init: Set up type-specific debugfs entries for this clock. This is called once, after the debugfs directory entry for this clock has been created. The dentry pointer representing that directory is provided as an argument. Called with prepare_lock held. Returns 0 on success, -EERROR otherwise.

Description

The clk_enable/clk_disable and clk_prepare/clk_unprepare pairs allow implementations to split any work between atomic (enable) and sleepable (prepare) contexts. If enabling a clock requires code that might sleep, this must be done in clk_prepare. Clock enable code that will never be called in a sleepable context may be implemented in clk_enable.

Typically, drivers will call clk_prepare when a clock may be needed later (eg. when a device is opened), and clk_enable when the clock is actually required (eg. from an interrupt). Note that clk_prepare MUST have been called before clk_enable.

Core flags¶

Flags used across common struct clk. These flags should only affect the top-level framework. Custom flags for dealing with hardware specifics belong in struct clk_foo.

CLK_SET_RATE_GATE - must be gated across rate change
CLK_SET_PARENT_GATE - must be gated across re-parent
CLK_SET_RATE_PARENT - propagate rate change up one level
CLK_IGNORE_UNUSED - do not gate even if unused
CLK_GET_RATE_NOCACHE - do not use the cached clk rate
CLK_SET_RATE_NO_REPARENT - don’t re-parent on rate change
CLK_GET_ACCURACY_NOCACHE - do not use the cached clk accuracy
CLK_RECALC_NEW_RATES - recalc rates after notifications
CLK_SET_RATE_UNGATE - clock needs to run to set rate
CLK_IS_CRITICAL - do not gate, ever
CLK_OPS_PARENT_ENABLE - parents need enable during gate/ungate, set rate and re-parent
CLK_DUTY_CYCLE_PARENT - duty cycle call may be forwarded to the parent clock

Hardware clk implementations¶

The strength of the common struct clk_core comes from its .ops and .hw pointers which abstract the details of struct clk from the hardware-specific bits, and vice versa. To illustrate consider the simple gateable clk implementation in drivers/clk/clk-gate.c:

struct clk_gate {
        struct clk_hw   hw;
        void __iomem    *reg;
        u8              bit_idx;
        ...
};

struct clk_gate contains struct clk_hw hw as well as hardware-specific knowledge about which register and bit controls this clk’s gating. Nothing about clock topology or accounting, such as enable_count or notifier_count, is needed here. That is all handled by the common framework code and struct clk_core.

Let’s walk through enabling this clk from driver code:

struct clk *clk;
clk = clk_get(NULL, "my_gateable_clk");

clk_prepare(clk);
clk_enable(clk);

The call graph for clk_enable is very simple:

clk_enable(clk);
        clk->ops->enable(clk->hw);
        [resolves to...]
                clk_gate_enable(hw);
                [resolves struct clk gate with to_clk_gate(hw)]
                        clk_gate_set_bit(gate);

And the definition of clk_gate_set_bit:

static void clk_gate_set_bit(struct clk_gate *gate)
{
        u32 reg;

        reg = __raw_readl(gate->reg);
        reg |= BIT(gate->bit_idx);
        writel(reg, gate->reg);
}

Note that to_clk_gate is defined as:

#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)

This pattern of abstraction is used for every clock hardware representation.

Supporting your own clk hardware¶

When implementing support for a new type of clock it is only necessary to include the following header:

#include <linux/clk-provider.h>

To construct a clk hardware structure for your platform you must define the following:

struct clk_foo {
        struct clk_hw hw;
        ... hardware specific data goes here ...
};

To take advantage of your data you’ll need to support valid operations for your clk:

struct clk_ops clk_foo_ops = {
        .enable         = &clk_foo_enable,
        .disable        = &clk_foo_disable,
};

Implement the above functions using container_of:

#define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)

int clk_foo_enable(struct clk_hw *hw)
{
        struct clk_foo *foo;

        foo = to_clk_foo(hw);

        ... perform magic on foo ...

        return 0;
};

Below is a matrix detailing which clk_ops are mandatory based upon the hardware capabilities of that clock. A cell marked as “y” means mandatory, a cell marked as “n” implies that either including that callback is invalid or otherwise unnecessary. Empty cells are either optional or must be evaluated on a case-by-case basis.

clock hardware characteristics¶
	gate	change rate	single parent	multiplexer	root
.prepare
.unprepare

.enable	y
.disable	y
.is_enabled	y

.recalc_rate		y
.determine_rate		y
.set_rate		y

.set_parent			n	y	n
.get_parent			n	y	n

.recalc_accuracy

.init

Finally, register your clock at run-time with a hardware-specific registration function. This function simply populates struct clk_foo’s data and then passes the common struct clk parameters to the framework with a call to:

clk_register(...)

See the basic clock types in drivers/clk/clk-*.c for examples.

Disabling clock gating of unused clocks¶

Sometimes during development it can be useful to be able to bypass the default disabling of unused clocks. For example, if drivers aren’t enabling clocks properly but rely on them being on from the bootloader, bypassing the disabling means that the driver will remain functional while the issues are sorted out.

You can see which clocks have been disabled by booting your kernel with these parameters:

tp_printk trace_event=clk:clk_disable

To bypass this disabling, include “clk_ignore_unused” in the bootargs to the kernel.

Locking¶

The common clock framework uses two global locks, the prepare lock and the enable lock.

The enable lock is a spinlock and is held across calls to the .enable, .disable operations. Those operations are thus not allowed to sleep, and calls to the clk_enable(), clk_disable() API functions are allowed in atomic context.

For clk_is_enabled() API, it is also designed to be allowed to be used in atomic context. However, it doesn’t really make any sense to hold the enable lock in core, unless you want to do something else with the information of the enable state with that lock held. Otherwise, seeing if a clk is enabled is a one-shot read of the enabled state, which could just as easily change after the function returns because the lock is released. Thus the user of this API needs to handle synchronizing the read of the state with whatever they’re using it for to make sure that the enable state doesn’t change during that time.

The prepare lock is a mutex and is held across calls to all other operations. All those operations are allowed to sleep, and calls to the corresponding API functions are not allowed in atomic context.

This effectively divides operations in two groups from a locking perspective.

Drivers don’t need to manually protect resources shared between the operations of one group, regardless of whether those resources are shared by multiple clocks or not. However, access to resources that are shared between operations of the two groups needs to be protected by the drivers. An example of such a resource would be a register that controls both the clock rate and the clock enable/disable state.

The clock framework is reentrant, in that a driver is allowed to call clock framework functions from within its implementation of clock operations. This can for instance cause a .set_rate operation of one clock being called from within the .set_rate operation of another clock. This case must be considered in the driver implementations, but the code flow is usually controlled by the driver in that case.

Note that locking must also be considered when code outside of the common clock framework needs to access resources used by the clock operations. This is considered out of scope of this document.

The Linux Kernel

Contents

This Page