2 * Generic OPP Interface
4 * Copyright (C) 2009-2010 Texas Instruments Incorporated.
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License version 2 as
11 * published by the Free Software Foundation.
14 #include <linux/kernel.h>
15 #include <linux/errno.h>
16 #include <linux/err.h>
17 #include <linux/init.h>
18 #include <linux/slab.h>
19 #include <linux/cpufreq.h>
20 #include <linux/device.h>
21 #include <linux/list.h>
22 #include <linux/rculist.h>
23 #include <linux/rcupdate.h>
24 #include <linux/opp.h>
26 #include <linux/export.h>
29 * Internal data structure organization with the OPP layer library is as
32 * |- device 1 (represents voltage domain 1)
33 * | |- opp 1 (availability, freq, voltage)
37 * |- device 2 (represents the next voltage domain)
39 * `- device m (represents mth voltage domain)
40 * device 1, 2.. are represented by dev_opp structure while each opp
41 * is represented by the opp structure.
45 * struct opp - Generic OPP description structure
46 * @node: opp list node. The nodes are maintained throughout the lifetime
47 * of boot. It is expected only an optimal set of OPPs are
48 * added to the library by the SoC framework.
49 * RCU usage: opp list is traversed with RCU locks. node
50 * modification is possible realtime, hence the modifications
51 * are protected by the dev_opp_list_lock for integrity.
52 * IMPORTANT: the opp nodes should be maintained in increasing
54 * @available: true/false - marks if this OPP as available or not
55 * @rate: Frequency in hertz
56 * @u_volt: Nominal voltage in microvolts corresponding to this OPP
57 * @dev_opp: points back to the device_opp struct this opp belongs to
58 * @head: RCU callback head used for deferred freeing
60 * This structure stores the OPP information for a given device.
63 struct list_head node
;
69 struct device_opp
*dev_opp
;
74 * struct device_opp - Device opp structure
75 * @node: list node - contains the devices with OPPs that
76 * have been registered. Nodes once added are not modified in this
78 * RCU usage: nodes are not modified in the list of device_opp,
79 * however addition is possible and is secured by dev_opp_list_lock
80 * @dev: device pointer
81 * @head: notifier head to notify the OPP availability changes.
82 * @opp_list: list of opps
84 * This is an internal data structure maintaining the link to opps attached to
85 * a device. This structure is not meant to be shared to users as it is
86 * meant for book keeping and private to OPP library
89 struct list_head node
;
92 struct srcu_notifier_head head
;
93 struct list_head opp_list
;
97 * The root of the list of all devices. All device_opp structures branch off
98 * from here, with each device_opp containing the list of opp it supports in
99 * various states of availability.
101 static LIST_HEAD(dev_opp_list
);
102 /* Lock to allow exclusive modification to the device and opp lists */
103 static DEFINE_MUTEX(dev_opp_list_lock
);
106 * find_device_opp() - find device_opp struct using device pointer
107 * @dev: device pointer used to lookup device OPPs
109 * Search list of device OPPs for one containing matching device. Does a RCU
110 * reader operation to grab the pointer needed.
112 * Returns pointer to 'struct device_opp' if found, otherwise -ENODEV or
113 * -EINVAL based on type of error.
115 * Locking: This function must be called under rcu_read_lock(). device_opp
116 * is a RCU protected pointer. This means that device_opp is valid as long
117 * as we are under RCU lock.
119 static struct device_opp
*find_device_opp(struct device
*dev
)
121 struct device_opp
*tmp_dev_opp
, *dev_opp
= ERR_PTR(-ENODEV
);
123 if (unlikely(IS_ERR_OR_NULL(dev
))) {
124 pr_err("%s: Invalid parameters\n", __func__
);
125 return ERR_PTR(-EINVAL
);
128 list_for_each_entry_rcu(tmp_dev_opp
, &dev_opp_list
, node
) {
129 if (tmp_dev_opp
->dev
== dev
) {
130 dev_opp
= tmp_dev_opp
;
139 * opp_get_voltage() - Gets the voltage corresponding to an available opp
140 * @opp: opp for which voltage has to be returned for
142 * Return voltage in micro volt corresponding to the opp, else
145 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
146 * protected pointer. This means that opp which could have been fetched by
147 * opp_find_freq_{exact,ceil,floor} functions is valid as long as we are
148 * under RCU lock. The pointer returned by the opp_find_freq family must be
149 * used in the same section as the usage of this function with the pointer
150 * prior to unlocking with rcu_read_unlock() to maintain the integrity of the
153 unsigned long opp_get_voltage(struct opp
*opp
)
158 tmp_opp
= rcu_dereference(opp
);
159 if (unlikely(IS_ERR_OR_NULL(tmp_opp
)) || !tmp_opp
->available
)
160 pr_err("%s: Invalid parameters\n", __func__
);
166 EXPORT_SYMBOL_GPL(opp_get_voltage
);
169 * opp_get_freq() - Gets the frequency corresponding to an available opp
170 * @opp: opp for which frequency has to be returned for
172 * Return frequency in hertz corresponding to the opp, else
175 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
176 * protected pointer. This means that opp which could have been fetched by
177 * opp_find_freq_{exact,ceil,floor} functions is valid as long as we are
178 * under RCU lock. The pointer returned by the opp_find_freq family must be
179 * used in the same section as the usage of this function with the pointer
180 * prior to unlocking with rcu_read_unlock() to maintain the integrity of the
183 unsigned long opp_get_freq(struct opp
*opp
)
188 tmp_opp
= rcu_dereference(opp
);
189 if (unlikely(IS_ERR_OR_NULL(tmp_opp
)) || !tmp_opp
->available
)
190 pr_err("%s: Invalid parameters\n", __func__
);
196 EXPORT_SYMBOL_GPL(opp_get_freq
);
199 * opp_get_opp_count() - Get number of opps available in the opp list
200 * @dev: device for which we do this operation
202 * This function returns the number of available opps if there are any,
203 * else returns 0 if none or the corresponding error value.
205 * Locking: This function must be called under rcu_read_lock(). This function
206 * internally references two RCU protected structures: device_opp and opp which
207 * are safe as long as we are under a common RCU locked section.
209 int opp_get_opp_count(struct device
*dev
)
211 struct device_opp
*dev_opp
;
212 struct opp
*temp_opp
;
215 dev_opp
= find_device_opp(dev
);
216 if (IS_ERR(dev_opp
)) {
217 int r
= PTR_ERR(dev_opp
);
218 dev_err(dev
, "%s: device OPP not found (%d)\n", __func__
, r
);
222 list_for_each_entry_rcu(temp_opp
, &dev_opp
->opp_list
, node
) {
223 if (temp_opp
->available
)
229 EXPORT_SYMBOL_GPL(opp_get_opp_count
);
232 * opp_find_freq_exact() - search for an exact frequency
233 * @dev: device for which we do this operation
234 * @freq: frequency to search for
235 * @available: true/false - match for available opp
237 * Searches for exact match in the opp list and returns pointer to the matching
238 * opp if found, else returns ERR_PTR in case of error and should be handled
239 * using IS_ERR. Error return values can be:
240 * EINVAL: for bad pointer
241 * ERANGE: no match found for search
242 * ENODEV: if device not found in list of registered devices
244 * Note: available is a modifier for the search. if available=true, then the
245 * match is for exact matching frequency and is available in the stored OPP
246 * table. if false, the match is for exact frequency which is not available.
248 * This provides a mechanism to enable an opp which is not available currently
249 * or the opposite as well.
251 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
252 * protected pointer. The reason for the same is that the opp pointer which is
253 * returned will remain valid for use with opp_get_{voltage, freq} only while
254 * under the locked area. The pointer returned must be used prior to unlocking
255 * with rcu_read_unlock() to maintain the integrity of the pointer.
257 struct opp
*opp_find_freq_exact(struct device
*dev
, unsigned long freq
,
260 struct device_opp
*dev_opp
;
261 struct opp
*temp_opp
, *opp
= ERR_PTR(-ERANGE
);
263 dev_opp
= find_device_opp(dev
);
264 if (IS_ERR(dev_opp
)) {
265 int r
= PTR_ERR(dev_opp
);
266 dev_err(dev
, "%s: device OPP not found (%d)\n", __func__
, r
);
270 list_for_each_entry_rcu(temp_opp
, &dev_opp
->opp_list
, node
) {
271 if (temp_opp
->available
== available
&&
272 temp_opp
->rate
== freq
) {
280 EXPORT_SYMBOL_GPL(opp_find_freq_exact
);
283 * opp_find_freq_ceil() - Search for an rounded ceil freq
284 * @dev: device for which we do this operation
285 * @freq: Start frequency
287 * Search for the matching ceil *available* OPP from a starting freq
290 * Returns matching *opp and refreshes *freq accordingly, else returns
291 * ERR_PTR in case of error and should be handled using IS_ERR. Error return
293 * EINVAL: for bad pointer
294 * ERANGE: no match found for search
295 * ENODEV: if device not found in list of registered devices
297 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
298 * protected pointer. The reason for the same is that the opp pointer which is
299 * returned will remain valid for use with opp_get_{voltage, freq} only while
300 * under the locked area. The pointer returned must be used prior to unlocking
301 * with rcu_read_unlock() to maintain the integrity of the pointer.
303 struct opp
*opp_find_freq_ceil(struct device
*dev
, unsigned long *freq
)
305 struct device_opp
*dev_opp
;
306 struct opp
*temp_opp
, *opp
= ERR_PTR(-ERANGE
);
309 dev_err(dev
, "%s: Invalid argument freq=%p\n", __func__
, freq
);
310 return ERR_PTR(-EINVAL
);
313 dev_opp
= find_device_opp(dev
);
315 return ERR_CAST(dev_opp
);
317 list_for_each_entry_rcu(temp_opp
, &dev_opp
->opp_list
, node
) {
318 if (temp_opp
->available
&& temp_opp
->rate
>= *freq
) {
327 EXPORT_SYMBOL_GPL(opp_find_freq_ceil
);
330 * opp_find_freq_floor() - Search for a rounded floor freq
331 * @dev: device for which we do this operation
332 * @freq: Start frequency
334 * Search for the matching floor *available* OPP from a starting freq
337 * Returns matching *opp and refreshes *freq accordingly, else returns
338 * ERR_PTR in case of error and should be handled using IS_ERR. Error return
340 * EINVAL: for bad pointer
341 * ERANGE: no match found for search
342 * ENODEV: if device not found in list of registered devices
344 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
345 * protected pointer. The reason for the same is that the opp pointer which is
346 * returned will remain valid for use with opp_get_{voltage, freq} only while
347 * under the locked area. The pointer returned must be used prior to unlocking
348 * with rcu_read_unlock() to maintain the integrity of the pointer.
350 struct opp
*opp_find_freq_floor(struct device
*dev
, unsigned long *freq
)
352 struct device_opp
*dev_opp
;
353 struct opp
*temp_opp
, *opp
= ERR_PTR(-ERANGE
);
356 dev_err(dev
, "%s: Invalid argument freq=%p\n", __func__
, freq
);
357 return ERR_PTR(-EINVAL
);
360 dev_opp
= find_device_opp(dev
);
362 return ERR_CAST(dev_opp
);
364 list_for_each_entry_rcu(temp_opp
, &dev_opp
->opp_list
, node
) {
365 if (temp_opp
->available
) {
366 /* go to the next node, before choosing prev */
367 if (temp_opp
->rate
> *freq
)
378 EXPORT_SYMBOL_GPL(opp_find_freq_floor
);
381 * opp_add() - Add an OPP table from a table definitions
382 * @dev: device for which we do this operation
383 * @freq: Frequency in Hz for this OPP
384 * @u_volt: Voltage in uVolts for this OPP
386 * This function adds an opp definition to the opp list and returns status.
387 * The opp is made available by default and it can be controlled using
388 * opp_enable/disable functions.
390 * Locking: The internal device_opp and opp structures are RCU protected.
391 * Hence this function internally uses RCU updater strategy with mutex locks
392 * to keep the integrity of the internal data structures. Callers should ensure
393 * that this function is *NOT* called under RCU protection or in contexts where
394 * mutex cannot be locked.
396 int opp_add(struct device
*dev
, unsigned long freq
, unsigned long u_volt
)
398 struct device_opp
*dev_opp
= NULL
;
399 struct opp
*opp
, *new_opp
;
400 struct list_head
*head
;
402 /* allocate new OPP node */
403 new_opp
= kzalloc(sizeof(struct opp
), GFP_KERNEL
);
405 dev_warn(dev
, "%s: Unable to create new OPP node\n", __func__
);
409 /* Hold our list modification lock here */
410 mutex_lock(&dev_opp_list_lock
);
412 /* Check for existing list for 'dev' */
413 dev_opp
= find_device_opp(dev
);
414 if (IS_ERR(dev_opp
)) {
416 * Allocate a new device OPP table. In the infrequent case
417 * where a new device is needed to be added, we pay this
420 dev_opp
= kzalloc(sizeof(struct device_opp
), GFP_KERNEL
);
422 mutex_unlock(&dev_opp_list_lock
);
425 "%s: Unable to create device OPP structure\n",
431 srcu_init_notifier_head(&dev_opp
->head
);
432 INIT_LIST_HEAD(&dev_opp
->opp_list
);
434 /* Secure the device list modification */
435 list_add_rcu(&dev_opp
->node
, &dev_opp_list
);
438 /* populate the opp table */
439 new_opp
->dev_opp
= dev_opp
;
440 new_opp
->rate
= freq
;
441 new_opp
->u_volt
= u_volt
;
442 new_opp
->available
= true;
444 /* Insert new OPP in order of increasing frequency */
445 head
= &dev_opp
->opp_list
;
446 list_for_each_entry_rcu(opp
, &dev_opp
->opp_list
, node
) {
447 if (new_opp
->rate
< opp
->rate
)
453 list_add_rcu(&new_opp
->node
, head
);
454 mutex_unlock(&dev_opp_list_lock
);
457 * Notify the changes in the availability of the operable
458 * frequency/voltage list.
460 srcu_notifier_call_chain(&dev_opp
->head
, OPP_EVENT_ADD
, new_opp
);
463 EXPORT_SYMBOL_GPL(opp_add
);
466 * opp_set_availability() - helper to set the availability of an opp
467 * @dev: device for which we do this operation
468 * @freq: OPP frequency to modify availability
469 * @availability_req: availability status requested for this opp
471 * Set the availability of an OPP with an RCU operation, opp_{enable,disable}
472 * share a common logic which is isolated here.
474 * Returns -EINVAL for bad pointers, -ENOMEM if no memory available for the
475 * copy operation, returns 0 if no modifcation was done OR modification was
478 * Locking: The internal device_opp and opp structures are RCU protected.
479 * Hence this function internally uses RCU updater strategy with mutex locks to
480 * keep the integrity of the internal data structures. Callers should ensure
481 * that this function is *NOT* called under RCU protection or in contexts where
482 * mutex locking or synchronize_rcu() blocking calls cannot be used.
484 static int opp_set_availability(struct device
*dev
, unsigned long freq
,
485 bool availability_req
)
487 struct device_opp
*tmp_dev_opp
, *dev_opp
= ERR_PTR(-ENODEV
);
488 struct opp
*new_opp
, *tmp_opp
, *opp
= ERR_PTR(-ENODEV
);
491 /* keep the node allocated */
492 new_opp
= kmalloc(sizeof(struct opp
), GFP_KERNEL
);
494 dev_warn(dev
, "%s: Unable to create OPP\n", __func__
);
498 mutex_lock(&dev_opp_list_lock
);
500 /* Find the device_opp */
501 list_for_each_entry(tmp_dev_opp
, &dev_opp_list
, node
) {
502 if (dev
== tmp_dev_opp
->dev
) {
503 dev_opp
= tmp_dev_opp
;
507 if (IS_ERR(dev_opp
)) {
508 r
= PTR_ERR(dev_opp
);
509 dev_warn(dev
, "%s: Device OPP not found (%d)\n", __func__
, r
);
513 /* Do we have the frequency? */
514 list_for_each_entry(tmp_opp
, &dev_opp
->opp_list
, node
) {
515 if (tmp_opp
->rate
== freq
) {
525 /* Is update really needed? */
526 if (opp
->available
== availability_req
)
528 /* copy the old data over */
531 /* plug in new node */
532 new_opp
->available
= availability_req
;
534 list_replace_rcu(&opp
->node
, &new_opp
->node
);
535 mutex_unlock(&dev_opp_list_lock
);
536 kfree_rcu(opp
, head
);
538 /* Notify the change of the OPP availability */
539 if (availability_req
)
540 srcu_notifier_call_chain(&dev_opp
->head
, OPP_EVENT_ENABLE
,
543 srcu_notifier_call_chain(&dev_opp
->head
, OPP_EVENT_DISABLE
,
549 mutex_unlock(&dev_opp_list_lock
);
555 * opp_enable() - Enable a specific OPP
556 * @dev: device for which we do this operation
557 * @freq: OPP frequency to enable
559 * Enables a provided opp. If the operation is valid, this returns 0, else the
560 * corresponding error value. It is meant to be used for users an OPP available
561 * after being temporarily made unavailable with opp_disable.
563 * Locking: The internal device_opp and opp structures are RCU protected.
564 * Hence this function indirectly uses RCU and mutex locks to keep the
565 * integrity of the internal data structures. Callers should ensure that
566 * this function is *NOT* called under RCU protection or in contexts where
567 * mutex locking or synchronize_rcu() blocking calls cannot be used.
569 int opp_enable(struct device
*dev
, unsigned long freq
)
571 return opp_set_availability(dev
, freq
, true);
573 EXPORT_SYMBOL_GPL(opp_enable
);
576 * opp_disable() - Disable a specific OPP
577 * @dev: device for which we do this operation
578 * @freq: OPP frequency to disable
580 * Disables a provided opp. If the operation is valid, this returns
581 * 0, else the corresponding error value. It is meant to be a temporary
582 * control by users to make this OPP not available until the circumstances are
583 * right to make it available again (with a call to opp_enable).
585 * Locking: The internal device_opp and opp structures are RCU protected.
586 * Hence this function indirectly uses RCU and mutex locks to keep the
587 * integrity of the internal data structures. Callers should ensure that
588 * this function is *NOT* called under RCU protection or in contexts where
589 * mutex locking or synchronize_rcu() blocking calls cannot be used.
591 int opp_disable(struct device
*dev
, unsigned long freq
)
593 return opp_set_availability(dev
, freq
, false);
595 EXPORT_SYMBOL_GPL(opp_disable
);
597 #ifdef CONFIG_CPU_FREQ
599 * opp_init_cpufreq_table() - create a cpufreq table for a device
600 * @dev: device for which we do this operation
601 * @table: Cpufreq table returned back to caller
603 * Generate a cpufreq table for a provided device- this assumes that the
604 * opp list is already initialized and ready for usage.
606 * This function allocates required memory for the cpufreq table. It is
607 * expected that the caller does the required maintenance such as freeing
608 * the table as required.
610 * Returns -EINVAL for bad pointers, -ENODEV if the device is not found, -ENOMEM
611 * if no memory available for the operation (table is not populated), returns 0
612 * if successful and table is populated.
614 * WARNING: It is important for the callers to ensure refreshing their copy of
615 * the table if any of the mentioned functions have been invoked in the interim.
617 * Locking: The internal device_opp and opp structures are RCU protected.
618 * To simplify the logic, we pretend we are updater and hold relevant mutex here
619 * Callers should ensure that this function is *NOT* called under RCU protection
620 * or in contexts where mutex locking cannot be used.
622 int opp_init_cpufreq_table(struct device
*dev
,
623 struct cpufreq_frequency_table
**table
)
625 struct device_opp
*dev_opp
;
627 struct cpufreq_frequency_table
*freq_table
;
630 /* Pretend as if I am an updater */
631 mutex_lock(&dev_opp_list_lock
);
633 dev_opp
= find_device_opp(dev
);
634 if (IS_ERR(dev_opp
)) {
635 int r
= PTR_ERR(dev_opp
);
636 mutex_unlock(&dev_opp_list_lock
);
637 dev_err(dev
, "%s: Device OPP not found (%d)\n", __func__
, r
);
641 freq_table
= kzalloc(sizeof(struct cpufreq_frequency_table
) *
642 (opp_get_opp_count(dev
) + 1), GFP_KERNEL
);
644 mutex_unlock(&dev_opp_list_lock
);
645 dev_warn(dev
, "%s: Unable to allocate frequency table\n",
650 list_for_each_entry(opp
, &dev_opp
->opp_list
, node
) {
651 if (opp
->available
) {
652 freq_table
[i
].driver_data
= i
;
653 freq_table
[i
].frequency
= opp
->rate
/ 1000;
657 mutex_unlock(&dev_opp_list_lock
);
659 freq_table
[i
].driver_data
= i
;
660 freq_table
[i
].frequency
= CPUFREQ_TABLE_END
;
662 *table
= &freq_table
[0];
666 EXPORT_SYMBOL_GPL(opp_init_cpufreq_table
);
669 * opp_free_cpufreq_table() - free the cpufreq table
670 * @dev: device for which we do this operation
671 * @table: table to free
673 * Free up the table allocated by opp_init_cpufreq_table
675 void opp_free_cpufreq_table(struct device
*dev
,
676 struct cpufreq_frequency_table
**table
)
684 EXPORT_SYMBOL_GPL(opp_free_cpufreq_table
);
685 #endif /* CONFIG_CPU_FREQ */
688 * opp_get_notifier() - find notifier_head of the device with opp
689 * @dev: device pointer used to lookup device OPPs.
691 struct srcu_notifier_head
*opp_get_notifier(struct device
*dev
)
693 struct device_opp
*dev_opp
= find_device_opp(dev
);
696 return ERR_CAST(dev_opp
); /* matching type */
698 return &dev_opp
->head
;
703 * of_init_opp_table() - Initialize opp table from device tree
704 * @dev: device pointer used to lookup device OPPs.
706 * Register the initial OPP table with the OPP library for given device.
708 int of_init_opp_table(struct device
*dev
)
710 const struct property
*prop
;
714 prop
= of_find_property(dev
->of_node
, "operating-points", NULL
);
721 * Each OPP is a set of tuples consisting of frequency and
722 * voltage like <freq-kHz vol-uV>.
724 nr
= prop
->length
/ sizeof(u32
);
726 dev_err(dev
, "%s: Invalid OPP list\n", __func__
);
732 unsigned long freq
= be32_to_cpup(val
++) * 1000;
733 unsigned long volt
= be32_to_cpup(val
++);
735 if (opp_add(dev
, freq
, volt
)) {
736 dev_warn(dev
, "%s: Failed to add OPP %ld\n",
745 EXPORT_SYMBOL_GPL(of_init_opp_table
);