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>hifive-unleashed-5.1
Daniel Lezcano
Rafael J. Wysocki
parent
82467a5a88
commit
6d19cb93d6
|
|
@ -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();
|
||||
|
|
|
|||
Loading…
Reference in New Issue