UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity

cpuidle: Comment the driver's framework code 

Add kerneldoc (and other) comments to the cpuidle driver's framework
code.

Signed-off-by: Daniel Lezcano <daniel.lezcano@linaro.org>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
This commit is contained in:
Daniel Lezcano 2013-06-07 21:53:10 +00:00 committed by Rafael J. Wysocki
parent 82467a5a88
commit 6d19cb93d6
1 changed files with 126 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
drivers/cpuidle/driver.c
View File

@ -22,11 +22,26 @@ DEFINE_SPINLOCK(cpuidle_driver_lock);
static DEFINE_PER_CPU(struct cpuidle_driver *, cpuidle_drivers);
/**
* __cpuidle_get_cpu_driver - return the cpuidle driver tied to a CPU.
* @cpu: the CPU handled by the driver
*
* Returns a pointer to struct cpuidle_driver or NULL if no driver has been
* registered for @cpu.
*/
static struct cpuidle_driver *__cpuidle_get_cpu_driver(int cpu)
{
return per_cpu(cpuidle_drivers, cpu);
}
/**
* __cpuidle_unset_driver - unset per CPU driver variables.
* @drv: a valid pointer to a struct cpuidle_driver
*
* For each CPU in the driver's CPU mask, unset the registered driver per CPU
* variable. If @drv is different from the registered driver, the corresponding
* variable is not cleared.
*/
static inline void __cpuidle_unset_driver(struct cpuidle_driver *drv)
{
int cpu;
@ -40,6 +55,15 @@ static inline void __cpuidle_unset_driver(struct cpuidle_driver *drv)
}
}
/**
* __cpuidle_set_driver - set per CPU driver variables the the given driver.
* @drv: a valid pointer to a struct cpuidle_driver
*
* For each CPU in the driver's cpumask, unset the registered driver per CPU
* to @drv.
*
* Returns 0 on success, -EBUSY if the CPUs have driver(s) already.
*/
static inline int __cpuidle_set_driver(struct cpuidle_driver *drv)
{
int cpu;
@ -61,11 +85,24 @@ static inline int __cpuidle_set_driver(struct cpuidle_driver *drv)
static struct cpuidle_driver *cpuidle_curr_driver;
/**
* __cpuidle_get_cpu_driver - return the global cpuidle driver pointer.
* @cpu: ignored without the multiple driver support
*
* Return a pointer to a struct cpuidle_driver object or NULL if no driver was
* previously registered.
*/
static inline struct cpuidle_driver *__cpuidle_get_cpu_driver(int cpu)
{
return cpuidle_curr_driver;
}
/**
* __cpuidle_set_driver - assign the global cpuidle driver variable.
* @drv: pointer to a struct cpuidle_driver object
*
* Returns 0 on success, -EBUSY if the driver is already registered.
*/
static inline int __cpuidle_set_driver(struct cpuidle_driver *drv)
{
if (cpuidle_curr_driver)
@ -76,6 +113,13 @@ static inline int __cpuidle_set_driver(struct cpuidle_driver *drv)
return 0;
}
/**
* __cpuidle_unset_driver - unset the global cpuidle driver variable.
* @drv: a pointer to a struct cpuidle_driver
*
* Reset the global cpuidle variable to NULL. If @drv does not match the
* registered driver, do nothing.
*/
static inline void __cpuidle_unset_driver(struct cpuidle_driver *drv)
{
if (drv == cpuidle_curr_driver)
@ -84,21 +128,49 @@ static inline void __cpuidle_unset_driver(struct cpuidle_driver *drv)
#endif
/**
* cpuidle_setup_broadcast_timer - enable/disable the broadcast timer
* @arg: a void pointer used to match the SMP cross call API
*
* @arg is used as a value of type 'long' with on of the two values:
* - CLOCK_EVT_NOTIFY_BROADCAST_ON
* - CLOCK_EVT_NOTIFY_BROADCAST_OFF
*
* Set the broadcast timer notification for the current CPU. This function
* is executed per CPU by an SMP cross call. It not supposed to be called
* directly.
*/
static void cpuidle_setup_broadcast_timer(void *arg)
{
int cpu = smp_processor_id();
clockevents_notify((long)(arg), &cpu);
}
/**
* __cpuidle_driver_init - initialize the driver's internal data
* @drv: a valid pointer to a struct cpuidle_driver
*
* Returns 0 on success, a negative error code otherwise.
*/
static int __cpuidle_driver_init(struct cpuidle_driver *drv)
{
int i;
drv->refcnt = 0;
/*
* Use all possible CPUs as the default, because if the kernel boots
* with some CPUs offline and then we online one of them, the CPU
* notifier has to know which driver to assign.
*/
if (!drv->cpumask)
drv->cpumask = (struct cpumask *)cpu_possible_mask;
/*
* Look for the timer stop flag in the different states, so that we know
* if the broadcast timer has to be set up. The loop is in the reverse
* order, because usually on of the the deeper states has this flag set.
*/
for (i = drv->state_count - 1; i >= 0 ; i--) {
if (!(drv->states[i].flags & CPUIDLE_FLAG_TIMER_STOP))
@ -111,6 +183,19 @@ static int __cpuidle_driver_init(struct cpuidle_driver *drv)
return 0;
}
/**
* __cpuidle_register_driver: register the driver
* @drv: a valid pointer to a struct cpuidle_driver
*
* Do some sanity checks, initialize the driver, assign the driver to the
* global cpuidle driver variable(s) and set up the broadcast timer if the
* cpuidle driver has some states that shut down the local timer.
*
* Returns 0 on success, a negative error code otherwise:
* * -EINVAL if the driver pointer is NULL or no idle states are available
* * -ENODEV if the cpuidle framework is disabled
* * -EBUSY if the driver is already assigned to the global variable(s)
*/
static int __cpuidle_register_driver(struct cpuidle_driver *drv)
{
int ret;
@ -137,8 +222,13 @@ static int __cpuidle_register_driver(struct cpuidle_driver *drv)
}
/**
* cpuidle_unregister_driver - unregisters a driver
* @drv: the driver
* __cpuidle_unregister_driver - unregister the driver
* @drv: a valid pointer to a struct cpuidle_driver
*
* Check if the driver is no longer in use, reset the global cpuidle driver
* variable(s) and disable the timer broadcast notification mechanism if it was
* in use.
*
*/
static void __cpuidle_unregister_driver(struct cpuidle_driver *drv)
{
@ -156,7 +246,13 @@ static void __cpuidle_unregister_driver(struct cpuidle_driver *drv)
/**
* cpuidle_register_driver - registers a driver
* @drv: the driver
* @drv: a pointer to a valid struct cpuidle_driver
*
* Register the driver under a lock to prevent concurrent attempts to
* [un]register the driver from occuring at the same time.
*
* Returns 0 on success, a negative error code (returned by
* __cpuidle_register_driver()) otherwise.
*/
int cpuidle_register_driver(struct cpuidle_driver *drv)
{
@ -172,7 +268,11 @@ EXPORT_SYMBOL_GPL(cpuidle_register_driver);
/**
* cpuidle_unregister_driver - unregisters a driver
* @drv: the driver
* @drv: a pointer to a valid struct cpuidle_driver
*
* Unregisters the cpuidle driver under a lock to prevent concurrent attempts
* to [un]register the driver from occuring at the same time. @drv has to
* match the currently registered driver.
*/
void cpuidle_unregister_driver(struct cpuidle_driver *drv)
{
@ -183,7 +283,9 @@ void cpuidle_unregister_driver(struct cpuidle_driver *drv)
EXPORT_SYMBOL_GPL(cpuidle_unregister_driver);
/**
* cpuidle_get_driver - return the current driver
* cpuidle_get_driver - return the driver tied to the current CPU.
*
* Returns a struct cpuidle_driver pointer, or NULL if no driver is registered.
*/
struct cpuidle_driver *cpuidle_get_driver(void)
{
@ -199,7 +301,11 @@ struct cpuidle_driver *cpuidle_get_driver(void)
EXPORT_SYMBOL_GPL(cpuidle_get_driver);
/**
* cpuidle_get_cpu_driver - return the driver tied with a cpu
* cpuidle_get_cpu_driver - return the driver registered for a CPU.
* @dev: a valid pointer to a struct cpuidle_device
*
* Returns a struct cpuidle_driver pointer, or NULL if no driver is registered
* for the CPU associated with @dev.
*/
struct cpuidle_driver *cpuidle_get_cpu_driver(struct cpuidle_device *dev)
{
@ -210,6 +316,14 @@ struct cpuidle_driver *cpuidle_get_cpu_driver(struct cpuidle_device *dev)
}
EXPORT_SYMBOL_GPL(cpuidle_get_cpu_driver);
/**
* cpuidle_driver_ref - get a reference to the driver.
*
* Increment the reference counter of the cpuidle driver associated with
* the current CPU.
*
* Returns a pointer to the driver, or NULL if the current CPU has no driver.
*/
struct cpuidle_driver *cpuidle_driver_ref(void)
{
struct cpuidle_driver *drv;
@ -223,6 +337,12 @@ struct cpuidle_driver *cpuidle_driver_ref(void)
return drv;
}
/**
* cpuidle_driver_unref - puts down the refcount for the driver
*
* Decrement the reference counter of the cpuidle driver associated with
* the current CPU.
*/
void cpuidle_driver_unref(void)
{
struct cpuidle_driver *drv = cpuidle_get_driver();