[mirror_ubuntu-zesty-kernel.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 <myungjoo.ham@samsung.com>
 *
 * 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;
};

/**
 * 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.
 * @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);
	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.
 *
 * 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;
};

#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);
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)
{
	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 <myungjoo.ham@samsung.com>
	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	};
	46
	47	/**
	48	* struct devfreq_dev_profile - Devfreq's user device profile
	49	* @initial_freq The operating frequency when devfreq_add_device() is
	50	* called.
	51	* @polling_ms The polling interval in ms. 0 disables polling.
	52	* @target The device should set its operating frequency at
	53	* freq or lowest-upper-than-freq value. If freq is
	54	* higher than any operable frequency, set maximum.
	55	* Before returning, target function should set
	56	* freq at the current frequency.
	57	* @get_dev_status The device should provide the current performance
	58	* status to devfreq, which is used by governors.
	59	* @exit An optional callback that is called when devfreq
	60	* is removing the devfreq object due to error or
	61	* from devfreq_remove_device() call. If the user
	62	* has registered devfreq->nb at a notifier-head,
	63	* this is the time to unregister it.
	64	*/
	65	struct devfreq_dev_profile {
	66	unsigned long initial_freq;
	67	unsigned int polling_ms;
	68
	69	int (target)(struct device dev, unsigned long *freq);
	70	int (get_dev_status)(struct device dev,
	71	struct devfreq_dev_status *stat);
	72	void (exit)(struct device dev);
	73	};
	74
	75	/**
	76	* struct devfreq_governor - Devfreq policy governor
	77	* @name Governor's name
	78	* @get_target_freq Returns desired operating frequency for the device.
	79	* Basically, get_target_freq will run
	80	* devfreq_dev_profile.get_dev_status() to get the
	81	* status of the device (load = busy_time / total_time).
	82	* If no_central_polling is set, this callback is called
	83	* only with update_devfreq() notified by OPP.
	84	* @init Called when the devfreq is being attached to a device
	85	* @exit Called when the devfreq is being removed from a
	86	* device. Governor should stop any internal routines
	87	* before return because related data may be
	88	* freed after exit().
	89	* @no_central_polling Do not use devfreq's central polling mechanism.
	90	* When this is set, devfreq will not call
	91	* get_target_freq with devfreq_monitor(). However,
	92	* devfreq will call get_target_freq with
	93	* devfreq_update() notified by OPP framework.
	94	*
	95	* Note that the callbacks are called with devfreq->lock locked by devfreq.
	96	*/
	97	struct devfreq_governor {
	98	const char name[DEVFREQ_NAME_LEN];
	99	int (get_target_freq)(struct devfreq this, unsigned long *freq);
	100	int (init)(struct devfreq this);
	101	void (exit)(struct devfreq this);
	102	const bool no_central_polling;
	103	};
	104
	105	/**
	106	* struct devfreq - Device devfreq structure
	107	* @node list node - contains the devices with devfreq that have been
	108	* registered.
109	* @lock a mutex to protect accessing devfreq.
110	* @dev device registered by devfreq class. dev.parent is the device
111	* using devfreq.
112	* @profile device-specific devfreq profile
113	* @governor method how to choose frequency based on the usage.
114	* @nb notifier block used to notify devfreq object that it should
115	* reevaluate operable frequencies. Devfreq users may use
116	* devfreq.nb to the corresponding register notifier call chain.
117	* @polling_jiffies interval in jiffies.
118	* @previous_freq previously configured frequency value.
119	* @next_polling the number of remaining jiffies to poll with
120	* "devfreq_monitor" executions to reevaluate
121	* frequency/voltage of the device. Set by
122	* profile's polling_ms interval.
123	* @data Private data of the governor. The devfreq framework does not
124	* touch this.
125	* @being_removed a flag to mark that this object is being removed in
126	* order to prevent trying to remove the object multiple times.
127	*
128	* This structure stores the devfreq information for a give device.
129	*
130	* Note that when a governor accesses entries in struct devfreq in its
131	* functions except for the context of callbacks defined in struct
132	* devfreq_governor, the governor should protect its access with the
133	* struct mutex lock in struct devfreq. A governor may use this mutex
134	* to protect its own private data in void *data as well.
135	*/
136	struct devfreq {
137	struct list_head node;
138
139	struct mutex lock;
140	struct device dev;
141	struct devfreq_dev_profile *profile;
142	const struct devfreq_governor *governor;
143	struct notifier_block nb;
144
145	unsigned long polling_jiffies;
146	unsigned long previous_freq;
147	unsigned int next_polling;
148
149	void data; / private data for governors */
150
151	bool being_removed;
152	};
153
154	#if defined(CONFIG_PM_DEVFREQ)
155	extern struct devfreq devfreq_add_device(struct device dev,
156	struct devfreq_dev_profile *profile,
157	const struct devfreq_governor *governor,
158	void *data);
159	extern int devfreq_remove_device(struct devfreq *devfreq);
160
161	/* Helper functions for devfreq user device driver with OPP. */
162	extern struct opp devfreq_recommended_opp(struct device dev,
163	unsigned long *freq);
164	extern int devfreq_register_opp_notifier(struct device *dev,
165	struct devfreq *devfreq);
166	extern int devfreq_unregister_opp_notifier(struct device *dev,
167	struct devfreq *devfreq);
168
ce26c5bb MH	169	#ifdef CONFIG_DEVFREQ_GOV_POWERSAVE
	170	extern const struct devfreq_governor devfreq_powersave;
	171	#endif
	172	#ifdef CONFIG_DEVFREQ_GOV_PERFORMANCE
	173	extern const struct devfreq_governor devfreq_performance;
	174	#endif
	175	#ifdef CONFIG_DEVFREQ_GOV_USERSPACE
	176	extern const struct devfreq_governor devfreq_userspace;
	177	#endif
	178	#ifdef CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND
	179	extern const struct devfreq_governor devfreq_simple_ondemand;
	180	/**
	181	* struct devfreq_simple_ondemand_data - void *data fed to struct devfreq
	182	* and devfreq_add_device
	183	* @ upthreshold If the load is over this value, the frequency jumps.
	184	* Specify 0 to use the default. Valid value = 0 to 100.
	185	* @ downdifferential If the load is under upthreshold - downdifferential,
	186	* the governor may consider slowing the frequency down.
	187	* Specify 0 to use the default. Valid value = 0 to 100.
	188	* downdifferential < upthreshold must hold.
	189	*
	190	* If the fed devfreq_simple_ondemand_data pointer is NULL to the governor,
	191	* the governor uses the default values.
	192	*/
	193	struct devfreq_simple_ondemand_data {
	194	unsigned int upthreshold;
	195	unsigned int downdifferential;
	196	};
	197	#endif
	198
a3c98b8b MH	199	#else /* !CONFIG_PM_DEVFREQ */
	200	static struct devfreq devfreq_add_device(struct device dev,
	201	struct devfreq_dev_profile *profile,
	202	struct devfreq_governor *governor,
	203	void *data);
	204	{
	205	return NULL;
	206	}
	207
	208	static int devfreq_remove_device(struct devfreq *devfreq);
	209	{
	210	return 0;
	211	}
	212
	213	static struct opp devfreq_recommended_opp(struct device dev,
	214	unsigned long *freq)
	215	{
	216	return -EINVAL;
	217	}
	218
	219	static int devfreq_register_opp_notifier(struct device *dev,
	220	struct devfreq *devfreq)
	221	{
	222	return -EINVAL;
	223	}
	224
	225	static int devfreq_unregister_opp_notifier(struct device *dev,
	226	struct devfreq *devfreq)
	227	{
	228	return -EINVAL;
	229	}
	230
ce26c5bb MH	231	#define devfreq_powersave NULL
	232	#define devfreq_performance NULL
	233	#define devfreq_userspace NULL
	234	#define devfreq_simple_ondemand NULL
	235
a3c98b8b MH	236	#endif /* CONFIG_PM_DEVFREQ */
	237
	238	#endif /* __LINUX_DEVFREQ_H__ */