[linux.git] / include / linux / devfreq.h

/*
 * devfreq: Generic Dynamic Voltage and Frequency Scaling (DVFS) Framework
 *	    for Non-CPU Devices.
 *
 * Copyright (C) 2011 Samsung Electronics
 *	MyungJoo Ham <[email protected]>
 *
 * 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_DEVFREQ_H__
#define __LINUX_DEVFREQ_H__

#include <linux/device.h>
#include <linux/notifier.h>
#include <linux/opp.h>

#define DEVFREQ_NAME_LEN 16

struct devfreq;

/**
 * struct devfreq_dev_status - Data given from devfreq user device to
 *			     governors. Represents the performance
 *			     statistics.
 * @total_time		The total time represented by this instance of
 *			devfreq_dev_status
 * @busy_time		The time that the device was working among the
 *			total_time.
 * @current_frequency	The operating frequency.
 * @private_data	An entry not specified by the devfreq framework.
 *			A device and a specific governor may have their
 *			own protocol with private_data. However, because
 *			this is governor-specific, a governor using this
 *			will be only compatible with devices aware of it.
 */
struct devfreq_dev_status {
	/* both since the last measure */
	unsigned long total_time;
	unsigned long busy_time;
	unsigned long current_frequency;
	void *private_data;
};

/*
 * The resulting frequency should be at most this. (this bound is the
 * least upper bound; thus, the resulting freq should be lower or same)
 * If the flag is not set, the resulting frequency should be at most the
 * bound (greatest lower bound)
 */
#define DEVFREQ_FLAG_LEAST_UPPER_BOUND		0x1

/**
 * struct devfreq_dev_profile - Devfreq's user device profile
 * @initial_freq	The operating frequency when devfreq_add_device() is
 *			called.
 * @polling_ms		The polling interval in ms. 0 disables polling.
 * @target		The device should set its operating frequency at
 *			freq or lowest-upper-than-freq value. If freq is
 *			higher than any operable frequency, set maximum.
 *			Before returning, target function should set
 *			freq at the current frequency.
 *			The "flags" parameter's possible values are
 *			explained above with "DEVFREQ_FLAG_*" macros.
 * @get_dev_status	The device should provide the current performance
 *			status to devfreq, which is used by governors.
 * @exit		An optional callback that is called when devfreq
 *			is removing the devfreq object due to error or
 *			from devfreq_remove_device() call. If the user
 *			has registered devfreq->nb at a notifier-head,
 *			this is the time to unregister it.
 */
struct devfreq_dev_profile {
	unsigned long initial_freq;
	unsigned int polling_ms;

	int (*target)(struct device *dev, unsigned long *freq, u32 flags);
	int (*get_dev_status)(struct device *dev,
			      struct devfreq_dev_status *stat);
	void (*exit)(struct device *dev);
};

/**
 * struct devfreq_governor - Devfreq policy governor
 * @name		Governor's name
 * @get_target_freq	Returns desired operating frequency for the device.
 *			Basically, get_target_freq will run
 *			devfreq_dev_profile.get_dev_status() to get the
 *			status of the device (load = busy_time / total_time).
 *			If no_central_polling is set, this callback is called
 *			only with update_devfreq() notified by OPP.
 * @init		Called when the devfreq is being attached to a device
 * @exit		Called when the devfreq is being removed from a
 *			device. Governor should stop any internal routines
 *			before return because related data may be
 *			freed after exit().
 * @no_central_polling	Do not use devfreq's central polling mechanism.
 *			When this is set, devfreq will not call
 *			get_target_freq with devfreq_monitor(). However,
 *			devfreq will call get_target_freq with
 *			devfreq_update() notified by OPP framework.
 *
 * Note that the callbacks are called with devfreq->lock locked by devfreq.
 */
struct devfreq_governor {
	const char name[DEVFREQ_NAME_LEN];
	int (*get_target_freq)(struct devfreq *this, unsigned long *freq);
	int (*init)(struct devfreq *this);
	void (*exit)(struct devfreq *this);
	const bool no_central_polling;
};

/**
 * struct devfreq - Device devfreq structure
 * @node	list node - contains the devices with devfreq that have been
 *		registered.
 * @lock	a mutex to protect accessing devfreq.
 * @dev		device registered by devfreq class. dev.parent is the device
 *		using devfreq.
 * @profile	device-specific devfreq profile
 * @governor	method how to choose frequency based on the usage.
 * @nb		notifier block used to notify devfreq object that it should
 *		reevaluate operable frequencies. Devfreq users may use
 *		devfreq.nb to the corresponding register notifier call chain.
 * @polling_jiffies	interval in jiffies.
 * @previous_freq	previously configured frequency value.
 * @next_polling	the number of remaining jiffies to poll with
 *			"devfreq_monitor" executions to reevaluate
 *			frequency/voltage of the device. Set by
 *			profile's polling_ms interval.
 * @data	Private data of the governor. The devfreq framework does not
 *		touch this.
 * @being_removed	a flag to mark that this object is being removed in
 *			order to prevent trying to remove the object multiple times.
 * @min_freq	Limit minimum frequency requested by user (0: none)
 * @max_freq	Limit maximum frequency requested by user (0: none)
 *
 * This structure stores the devfreq information for a give device.
 *
 * Note that when a governor accesses entries in struct devfreq in its
 * functions except for the context of callbacks defined in struct
 * devfreq_governor, the governor should protect its access with the
 * struct mutex lock in struct devfreq. A governor may use this mutex
 * to protect its own private data in void *data as well.
 */
struct devfreq {
	struct list_head node;

	struct mutex lock;
	struct device dev;
	struct devfreq_dev_profile *profile;
	const struct devfreq_governor *governor;
	struct notifier_block nb;

	unsigned long polling_jiffies;
	unsigned long previous_freq;
	unsigned int next_polling;

	void *data; /* private data for governors */

	bool being_removed;

	unsigned long min_freq;
	unsigned long max_freq;
};

#if defined(CONFIG_PM_DEVFREQ)
extern struct devfreq *devfreq_add_device(struct device *dev,
				  struct devfreq_dev_profile *profile,
				  const struct devfreq_governor *governor,
				  void *data);
extern int devfreq_remove_device(struct devfreq *devfreq);

/* Helper functions for devfreq user device driver with OPP. */
extern struct opp *devfreq_recommended_opp(struct device *dev,
					   unsigned long *freq, u32 flags);
extern int devfreq_register_opp_notifier(struct device *dev,
					 struct devfreq *devfreq);
extern int devfreq_unregister_opp_notifier(struct device *dev,
					   struct devfreq *devfreq);

#ifdef CONFIG_DEVFREQ_GOV_POWERSAVE
extern const struct devfreq_governor devfreq_powersave;
#endif
#ifdef CONFIG_DEVFREQ_GOV_PERFORMANCE
extern const struct devfreq_governor devfreq_performance;
#endif
#ifdef CONFIG_DEVFREQ_GOV_USERSPACE
extern const struct devfreq_governor devfreq_userspace;
#endif
#ifdef CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND
extern const struct devfreq_governor devfreq_simple_ondemand;
/**
 * struct devfreq_simple_ondemand_data - void *data fed to struct devfreq
 *	and devfreq_add_device
 * @ upthreshold	If the load is over this value, the frequency jumps.
 *			Specify 0 to use the default. Valid value = 0 to 100.
 * @ downdifferential	If the load is under upthreshold - downdifferential,
 *			the governor may consider slowing the frequency down.
 *			Specify 0 to use the default. Valid value = 0 to 100.
 *			downdifferential < upthreshold must hold.
 *
 * If the fed devfreq_simple_ondemand_data pointer is NULL to the governor,
 * the governor uses the default values.
 */
struct devfreq_simple_ondemand_data {
	unsigned int upthreshold;
	unsigned int downdifferential;
};
#endif

#else /* !CONFIG_PM_DEVFREQ */
static struct devfreq *devfreq_add_device(struct device *dev,
					  struct devfreq_dev_profile *profile,
					  struct devfreq_governor *governor,
					  void *data)
{
	return NULL;
}

static int devfreq_remove_device(struct devfreq *devfreq)
{
	return 0;
}

static struct opp *devfreq_recommended_opp(struct device *dev,
					   unsigned long *freq, u32 flags)
{
	return -EINVAL;
}

static int devfreq_register_opp_notifier(struct device *dev,
					 struct devfreq *devfreq)
{
	return -EINVAL;
}

static int devfreq_unregister_opp_notifier(struct device *dev,
					   struct devfreq *devfreq)
{
	return -EINVAL;
}

#define devfreq_powersave	NULL
#define devfreq_performance	NULL
#define devfreq_userspace	NULL
#define devfreq_simple_ondemand	NULL

#endif /* CONFIG_PM_DEVFREQ */

#endif /* __LINUX_DEVFREQ_H__ */
Commit	Line	Data
a3c98b8b MH	1	/*
	2	* devfreq: Generic Dynamic Voltage and Frequency Scaling (DVFS) Framework
	3	* for Non-CPU Devices.
	4	*
	5	* Copyright (C) 2011 Samsung Electronics
	6	* MyungJoo Ham <[email protected]>
	7	*
	8	* This program is free software; you can redistribute it and/or modify
	9	* it under the terms of the GNU General Public License version 2 as
	10	* published by the Free Software Foundation.
	11	*/
	12
	13	#ifndef __LINUX_DEVFREQ_H__
	14	#define __LINUX_DEVFREQ_H__
	15
	16	#include <linux/device.h>
	17	#include <linux/notifier.h>
	18	#include <linux/opp.h>
	19
	20	#define DEVFREQ_NAME_LEN 16
	21
	22	struct devfreq;
	23
	24	/**
	25	* struct devfreq_dev_status - Data given from devfreq user device to
	26	* governors. Represents the performance
	27	* statistics.
	28	* @total_time The total time represented by this instance of
	29	* devfreq_dev_status
	30	* @busy_time The time that the device was working among the
	31	* total_time.
	32	* @current_frequency The operating frequency.
	33	* @private_data An entry not specified by the devfreq framework.
	34	* A device and a specific governor may have their
	35	* own protocol with private_data. However, because
	36	* this is governor-specific, a governor using this
	37	* will be only compatible with devices aware of it.
	38	*/
	39	struct devfreq_dev_status {
	40	/* both since the last measure */
	41	unsigned long total_time;
	42	unsigned long busy_time;
	43	unsigned long current_frequency;
1a51cfdc	44	void *private_data;
a3c98b8b MH	45	};
a3c98b8b MH	46
ab5f299f MH	47	/*
	48	* The resulting frequency should be at most this. (this bound is the
	49	* least upper bound; thus, the resulting freq should be lower or same)
	50	* If the flag is not set, the resulting frequency should be at most the
	51	* bound (greatest lower bound)
	52	*/
	53	#define DEVFREQ_FLAG_LEAST_UPPER_BOUND 0x1
	54
a3c98b8b MH	55	/**
	56	* struct devfreq_dev_profile - Devfreq's user device profile
	57	* @initial_freq The operating frequency when devfreq_add_device() is
	58	* called.
	59	* @polling_ms The polling interval in ms. 0 disables polling.
	60	* @target The device should set its operating frequency at
	61	* freq or lowest-upper-than-freq value. If freq is
	62	* higher than any operable frequency, set maximum.
	63	* Before returning, target function should set
	64	* freq at the current frequency.
ab5f299f MH	65	* The "flags" parameter's possible values are
ab5f299f MH	66	* explained above with "DEVFREQ_FLAG_*" macros.
a3c98b8b MH	67	* @get_dev_status The device should provide the current performance
	68	* status to devfreq, which is used by governors.
	69	* @exit An optional callback that is called when devfreq
	70	* is removing the devfreq object due to error or
	71	* from devfreq_remove_device() call. If the user
	72	* has registered devfreq->nb at a notifier-head,
	73	* this is the time to unregister it.
	74	*/
	75	struct devfreq_dev_profile {
	76	unsigned long initial_freq;
	77	unsigned int polling_ms;
	78
ab5f299f	79	int (target)(struct device dev, unsigned long *freq, u32 flags);
a3c98b8b MH	80	int (get_dev_status)(struct device dev,
	81	struct devfreq_dev_status *stat);
	82	void (exit)(struct device dev);
	83	};
	84
	85	/**
	86	* struct devfreq_governor - Devfreq policy governor
	87	* @name Governor's name
	88	* @get_target_freq Returns desired operating frequency for the device.
	89	* Basically, get_target_freq will run
	90	* devfreq_dev_profile.get_dev_status() to get the
	91	* status of the device (load = busy_time / total_time).
	92	* If no_central_polling is set, this callback is called
	93	* only with update_devfreq() notified by OPP.
	94	* @init Called when the devfreq is being attached to a device
	95	* @exit Called when the devfreq is being removed from a
	96	* device. Governor should stop any internal routines
	97	* before return because related data may be
	98	* freed after exit().
	99	* @no_central_polling Do not use devfreq's central polling mechanism.
	100	* When this is set, devfreq will not call
	101	* get_target_freq with devfreq_monitor(). However,
	102	* devfreq will call get_target_freq with
	103	* devfreq_update() notified by OPP framework.
	104	*
	105	* Note that the callbacks are called with devfreq->lock locked by devfreq.
	106	*/
	107	struct devfreq_governor {
	108	const char name[DEVFREQ_NAME_LEN];
	109	int (get_target_freq)(struct devfreq this, unsigned long *freq);
	110	int (init)(struct devfreq this);
	111	void (exit)(struct devfreq this);
	112	const bool no_central_polling;
	113	};
	114
	115	/**
	116	* struct devfreq - Device devfreq structure
	117	* @node list node - contains the devices with devfreq that have been
	118	* registered.
	119	* @lock a mutex to protect accessing devfreq.
	120	* @dev device registered by devfreq class. dev.parent is the device
	121	* using devfreq.
	122	* @profile device-specific devfreq profile
	123	* @governor method how to choose frequency based on the usage.
	124	* @nb notifier block used to notify devfreq object that it should
	125	* reevaluate operable frequencies. Devfreq users may use
	126	* devfreq.nb to the corresponding register notifier call chain.
	127	* @polling_jiffies interval in jiffies.
	128	* @previous_freq previously configured frequency value.
	129	* @next_polling the number of remaining jiffies to poll with
	130	* "devfreq_monitor" executions to reevaluate
	131	* frequency/voltage of the device. Set by
	132	* profile's polling_ms interval.
	133	* @data Private data of the governor. The devfreq framework does not
	134	* touch this.
	135	* @being_removed a flag to mark that this object is being removed in
	136	* order to prevent trying to remove the object multiple times.
6530b9de MH	137	* @min_freq Limit minimum frequency requested by user (0: none)
6530b9de MH	138	* @max_freq Limit maximum frequency requested by user (0: none)
a3c98b8b MH	139	*
	140	* This structure stores the devfreq information for a give device.
	141	*
	142	* Note that when a governor accesses entries in struct devfreq in its
	143	* functions except for the context of callbacks defined in struct
	144	* devfreq_governor, the governor should protect its access with the
	145	* struct mutex lock in struct devfreq. A governor may use this mutex
	146	* to protect its own private data in void *data as well.
	147	*/
	148	struct devfreq {
	149	struct list_head node;
	150
	151	struct mutex lock;
	152	struct device dev;
	153	struct devfreq_dev_profile *profile;
	154	const struct devfreq_governor *governor;
	155	struct notifier_block nb;
	156
	157	unsigned long polling_jiffies;
	158	unsigned long previous_freq;
	159	unsigned int next_polling;
	160
	161	void data; / private data for governors */
	162
	163	bool being_removed;
6530b9de MH	164
	165	unsigned long min_freq;
	166	unsigned long max_freq;
a3c98b8b MH	167	};
	168
	169	#if defined(CONFIG_PM_DEVFREQ)
	170	extern struct devfreq devfreq_add_device(struct device dev,
	171	struct devfreq_dev_profile *profile,
	172	const struct devfreq_governor *governor,
	173	void *data);
	174	extern int devfreq_remove_device(struct devfreq *devfreq);
	175
	176	/* Helper functions for devfreq user device driver with OPP. */
	177	extern struct opp devfreq_recommended_opp(struct device dev,
ab5f299f	178	unsigned long *freq, u32 flags);
a3c98b8b MH	179	extern int devfreq_register_opp_notifier(struct device *dev,
	180	struct devfreq *devfreq);
	181	extern int devfreq_unregister_opp_notifier(struct device *dev,
	182	struct devfreq *devfreq);
	183
ce26c5bb MH	184	#ifdef CONFIG_DEVFREQ_GOV_POWERSAVE
	185	extern const struct devfreq_governor devfreq_powersave;
	186	#endif
	187	#ifdef CONFIG_DEVFREQ_GOV_PERFORMANCE
	188	extern const struct devfreq_governor devfreq_performance;
	189	#endif
	190	#ifdef CONFIG_DEVFREQ_GOV_USERSPACE
	191	extern const struct devfreq_governor devfreq_userspace;
	192	#endif
	193	#ifdef CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND
	194	extern const struct devfreq_governor devfreq_simple_ondemand;
	195	/**
	196	* struct devfreq_simple_ondemand_data - void *data fed to struct devfreq
	197	* and devfreq_add_device
	198	* @ upthreshold If the load is over this value, the frequency jumps.
	199	* Specify 0 to use the default. Valid value = 0 to 100.
	200	* @ downdifferential If the load is under upthreshold - downdifferential,
	201	* the governor may consider slowing the frequency down.
	202	* Specify 0 to use the default. Valid value = 0 to 100.
	203	* downdifferential < upthreshold must hold.
	204	*
	205	* If the fed devfreq_simple_ondemand_data pointer is NULL to the governor,
	206	* the governor uses the default values.
	207	*/
	208	struct devfreq_simple_ondemand_data {
	209	unsigned int upthreshold;
	210	unsigned int downdifferential;
	211	};
	212	#endif
	213
a3c98b8b MH	214	#else /* !CONFIG_PM_DEVFREQ */
	215	static struct devfreq devfreq_add_device(struct device dev,
	216	struct devfreq_dev_profile *profile,
	217	struct devfreq_governor *governor,
a95e1f5d	218	void *data)
a3c98b8b MH	219	{
	220	return NULL;
	221	}
	222
a95e1f5d	223	static int devfreq_remove_device(struct devfreq *devfreq)
a3c98b8b MH	224	{
	225	return 0;
	226	}
	227
	228	static struct opp devfreq_recommended_opp(struct device dev,
ab5f299f	229	unsigned long *freq, u32 flags)
a3c98b8b MH	230	{
	231	return -EINVAL;
	232	}
	233
	234	static int devfreq_register_opp_notifier(struct device *dev,
	235	struct devfreq *devfreq)
	236	{
	237	return -EINVAL;
	238	}
	239
	240	static int devfreq_unregister_opp_notifier(struct device *dev,
	241	struct devfreq *devfreq)
	242	{
	243	return -EINVAL;
	244	}
	245
ce26c5bb MH	246	#define devfreq_powersave NULL
	247	#define devfreq_performance NULL
	248	#define devfreq_userspace NULL
	249	#define devfreq_simple_ondemand NULL
	250
a3c98b8b MH	251	#endif /* CONFIG_PM_DEVFREQ */
	252
	253	#endif /* __LINUX_DEVFREQ_H__ */