clk: introduce the common clock framework

config HAVE_MACH_CLKDEV

	bool

menuconfig COMMON_CLK

	bool "Common Clock Framework"

	select HAVE_CLK_PREPARE

	---help---

	  The common clock framework is a single definition of struct

	  clk, useful across many platforms, as well as an

	  implementation of the clock API in include/linux/clk.h.

	  Architectures utilizing the common struct clk should select

	  this automatically, but it may be necessary to manually select

	  this option for loadable modules requiring the common clock

	  framework.

	  If in doubt, say "N".

if COMMON_CLK

config COMMON_CLK_DISABLE_UNUSED

	bool "Disabled unused clocks at boot"

	depends on COMMON_CLK

	---help---

	  Traverses the entire clock tree and disables any clocks that are

	  enabled in hardware but have not been enabled by any device drivers.

	  This saves power and keeps the software model of the clock in line

	  with reality.

	  If in doubt, say "N".

config COMMON_CLK_DEBUG

	bool "DebugFS representation of clock tree"

	depends on COMMON_CLK

	select DEBUG_FS

	---help---

	  Creates a directory hierchy in debugfs for visualizing the clk

	  tree structure.  Each directory contains read-only members

	  that export information specific to that clk node: clk_rate,

	  clk_flags, clk_prepare_count, clk_enable_count &

	  clk_notifier_count.

endif

obj-$(CONFIG_CLKDEV_LOOKUP)	+= clkdev.o

obj-$(CONFIG_COMMON_CLK)	+= clk.o

/*

 *  linux/include/linux/clk-private.h

 *

 *  Copyright (c) 2010-2011 Jeremy Kerr <jeremy.kerr@canonical.com>

 *  Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation.

 */

#ifndef __LINUX_CLK_PRIVATE_H

#define __LINUX_CLK_PRIVATE_H

#include <linux/clk-provider.h>

#include <linux/list.h>

/*

 * WARNING: Do not include clk-private.h from any file that implements struct

 * clk_ops.  Doing so is a layering violation!

 *

 * This header exists only to allow for statically initialized clock data.  Any

 * static clock data must be defined in a separate file from the logic that

 * implements the clock operations for that same data.

 */

#ifdef CONFIG_COMMON_CLK

struct clk {

	const char		*name;

	const struct clk_ops	*ops;

	struct clk_hw		*hw;

	struct clk		*parent;

	char			**parent_names;

	struct clk		**parents;

	u8			num_parents;

	unsigned long		rate;

	unsigned long		new_rate;

	unsigned long		flags;

	unsigned int		enable_count;

	unsigned int		prepare_count;

	struct hlist_head	children;

	struct hlist_node	child_node;

	unsigned int		notifier_count;

#ifdef CONFIG_COMMON_CLK_DEBUG

	struct dentry		*dentry;

#endif

};

/**

 * __clk_init - initialize the data structures in a struct clk

 * @dev:	device initializing this clk, placeholder for now

 * @clk:	clk being initialized

 *

 * Initializes the lists in struct clk, queries the hardware for the

 * parent and rate and sets them both.

 *

 * Any struct clk passed into __clk_init must have the following members

 * populated:

 * 	.name

 * 	.ops

 * 	.hw

 * 	.parent_names

 * 	.num_parents

 * 	.flags

 *

 * It is not necessary to call clk_register if __clk_init is used directly with

 * statically initialized clock data.

 */

void __clk_init(struct device *dev, struct clk *clk);

#endif /* CONFIG_COMMON_CLK */

#endif /* CLK_PRIVATE_H */

/*

 *  linux/include/linux/clk-provider.h

 *

 *  Copyright (c) 2010-2011 Jeremy Kerr <jeremy.kerr@canonical.com>

 *  Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation.

 */

#ifndef __LINUX_CLK_PROVIDER_H

#define __LINUX_CLK_PROVIDER_H

#include <linux/clk.h>

#ifdef CONFIG_COMMON_CLK

/**

 * struct clk_hw - handle for traversing from a struct clk to its corresponding

 * hardware-specific structure.  struct clk_hw should be declared within struct

 * clk_foo and then referenced by the struct clk instance that uses struct

 * clk_foo's clk_ops

 *

 * clk: pointer to the struct clk instance that points back to this struct

 * clk_hw instance

 */

struct clk_hw {

	struct clk *clk;

};

/*

 * 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

 */

#define CLK_SET_RATE_GATE	BIT(0) /* must be gated across rate change */

#define CLK_SET_PARENT_GATE	BIT(1) /* must be gated across re-parent */

#define CLK_SET_RATE_PARENT	BIT(2) /* propagate rate change up one level */

#define CLK_IGNORE_UNUSED	BIT(3) /* do not gate even if unused */

#define CLK_IS_ROOT		BIT(4) /* root clk, has no parent */

/**

 * 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.

 *

 * @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.

 *

 * @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.

 *

 * @recalc_rate	Recalculate the rate of this clock, by quering hardware.  The

 * 		parent rate is an input parameter.  It is up to the caller to

 * 		insure that the prepare_mutex is held across this call.

 * 		Returns the calculated rate.  Optional, but recommended - if

 * 		this op is not set then clock rate will be initialized to 0.

 *

 * @round_rate:	Given a target rate as input, returns the closest rate actually

 * 		supported by the clock.

 *

 * @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_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.

 *

 * @set_rate:	Change the rate of this clock. If this callback returns

 * 		CLK_SET_RATE_PARENT, the rate change will be propagated to the

 * 		parent clock (which may propagate again if the parent clock

 * 		also sets this flag). The requested rate of the parent is

 * 		passed back from the callback in the second 'unsigned long *'

 * 		argument.  Note that it is up to the hardware clock's set_rate

 * 		implementation to insure that clocks do not run out of spec

 * 		when propgating the call to set_rate up to the parent.  One way

 * 		to do this is to gate the clock (via clk_disable and/or

 * 		clk_unprepare) before calling clk_set_rate, then ungating it

 * 		afterward.  If your clock also has the CLK_GATE_SET_RATE flag

 * 		set then this will insure safety.  Returns 0 on success,

 * 		-EERROR otherwise.

 *

 * 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 implement 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.

 */

struct clk_ops {

	int		(*prepare)(struct clk_hw *hw);

	void		(*unprepare)(struct clk_hw *hw);

	int		(*enable)(struct clk_hw *hw);

	void		(*disable)(struct clk_hw *hw);

	int		(*is_enabled)(struct clk_hw *hw);

	unsigned long	(*recalc_rate)(struct clk_hw *hw,

					unsigned long parent_rate);

	long		(*round_rate)(struct clk_hw *hw, unsigned long,

					unsigned long *);

	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);

	void		(*init)(struct clk_hw *hw);

};

/**

 * clk_register - allocate a new clock, register it and return an opaque cookie

 * @dev: device that is registering this clock

 * @name: clock name

 * @ops: operations this clock supports

 * @hw: link to hardware-specific clock data

 * @parent_names: array of string names for all possible parents

 * @num_parents: number of possible parents

 * @flags: framework-level hints and quirks

 *

 * clk_register is the primary interface for populating the clock tree with new

 * clock nodes.  It returns a pointer to the newly allocated struct clk which

 * cannot be dereferenced by driver code but may be used in conjuction with the

 * rest of the clock API.

 */

struct clk *clk_register(struct device *dev, const char *name,

		const struct clk_ops *ops, struct clk_hw *hw,

		char **parent_names, u8 num_parents, unsigned long flags);

/* helper functions */

const char *__clk_get_name(struct clk *clk);

struct clk_hw *__clk_get_hw(struct clk *clk);

u8 __clk_get_num_parents(struct clk *clk);

struct clk *__clk_get_parent(struct clk *clk);

inline int __clk_get_enable_count(struct clk *clk);

inline int __clk_get_prepare_count(struct clk *clk);

unsigned long __clk_get_rate(struct clk *clk);

unsigned long __clk_get_flags(struct clk *clk);

int __clk_is_enabled(struct clk *clk);

struct clk *__clk_lookup(const char *name);

/*

 * FIXME clock api without lock protection

 */

int __clk_prepare(struct clk *clk);

void __clk_unprepare(struct clk *clk);

void __clk_reparent(struct clk *clk, struct clk *new_parent);

unsigned long __clk_round_rate(struct clk *clk, unsigned long rate);

#endif /* CONFIG_COMMON_CLK */

#endif /* CLK_PROVIDER_H */