cpuidle: Comment the driver's framework code (6d19cb93) · Commits · jan.koester / Linux

drivers/cpuidle/driver.c

+126 −6

Original line number	Diff line number	Diff line
		@@ -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();