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
59 * This structure stores the OPP information for a given device.
62 struct list_head node;
68 struct device_opp *dev_opp;
73 * struct device_opp - Device opp structure
74 * @node: list node - contains the devices with OPPs that
75 * have been registered. Nodes once added are not modified in this
77 * RCU usage: nodes are not modified in the list of device_opp,
78 * however addition is possible and is secured by dev_opp_list_lock
79 * @dev: device pointer
80 * @head: notifier head to notify the OPP availability changes.
81 * @opp_list: list of opps
83 * This is an internal data structure maintaining the link to opps attached to
84 * a device. This structure is not meant to be shared to users as it is
85 * meant for book keeping and private to OPP library
88 struct list_head node;
91 struct srcu_notifier_head head;
92 struct list_head opp_list;
96 * The root of the list of all devices. All device_opp structures branch off
97 * from here, with each device_opp containing the list of opp it supports in
98 * various states of availability.
100 static LIST_HEAD(dev_opp_list);
101 /* Lock to allow exclusive modification to the device and opp lists */
102 static DEFINE_MUTEX(dev_opp_list_lock);
105 * find_device_opp() - find device_opp struct using device pointer
106 * @dev: device pointer used to lookup device OPPs
108 * Search list of device OPPs for one containing matching device. Does a RCU
109 * reader operation to grab the pointer needed.
111 * Returns pointer to 'struct device_opp' if found, otherwise -ENODEV or
112 * -EINVAL based on type of error.
114 * Locking: This function must be called under rcu_read_lock(). device_opp
115 * is a RCU protected pointer. This means that device_opp is valid as long
116 * as we are under RCU lock.
118 static struct device_opp *find_device_opp(struct device *dev)
120 struct device_opp *tmp_dev_opp, *dev_opp = ERR_PTR(-ENODEV);
122 if (unlikely(IS_ERR_OR_NULL(dev))) {
123 pr_err("%s: Invalid parameters\n", __func__);
124 return ERR_PTR(-EINVAL);
127 list_for_each_entry_rcu(tmp_dev_opp, &dev_opp_list, node) {
128 if (tmp_dev_opp->dev == dev) {
129 dev_opp = tmp_dev_opp;
138 * opp_get_voltage() - Gets the voltage corresponding to an available opp
139 * @opp: opp for which voltage has to be returned for
141 * Return voltage in micro volt corresponding to the opp, else
144 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
145 * protected pointer. This means that opp which could have been fetched by
146 * opp_find_freq_{exact,ceil,floor} functions is valid as long as we are
147 * under RCU lock. The pointer returned by the opp_find_freq family must be
148 * used in the same section as the usage of this function with the pointer
149 * prior to unlocking with rcu_read_unlock() to maintain the integrity of the
152 unsigned long opp_get_voltage(struct opp *opp)
157 tmp_opp = rcu_dereference(opp);
158 if (unlikely(IS_ERR_OR_NULL(tmp_opp)) || !tmp_opp->available)
159 pr_err("%s: Invalid parameters\n", __func__);
165 EXPORT_SYMBOL_GPL(opp_get_voltage);
168 * opp_get_freq() - Gets the frequency corresponding to an available opp
169 * @opp: opp for which frequency has to be returned for
171 * Return frequency in hertz corresponding to the opp, else
174 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
175 * protected pointer. This means that opp which could have been fetched by
176 * opp_find_freq_{exact,ceil,floor} functions is valid as long as we are
177 * under RCU lock. The pointer returned by the opp_find_freq family must be
178 * used in the same section as the usage of this function with the pointer
179 * prior to unlocking with rcu_read_unlock() to maintain the integrity of the
182 unsigned long opp_get_freq(struct opp *opp)
187 tmp_opp = rcu_dereference(opp);
188 if (unlikely(IS_ERR_OR_NULL(tmp_opp)) || !tmp_opp->available)
189 pr_err("%s: Invalid parameters\n", __func__);
195 EXPORT_SYMBOL_GPL(opp_get_freq);
198 * opp_get_opp_count() - Get number of opps available in the opp list
199 * @dev: device for which we do this operation
201 * This function returns the number of available opps if there are any,
202 * else returns 0 if none or the corresponding error value.
204 * Locking: This function must be called under rcu_read_lock(). This function
205 * internally references two RCU protected structures: device_opp and opp which
206 * are safe as long as we are under a common RCU locked section.
208 int opp_get_opp_count(struct device *dev)
210 struct device_opp *dev_opp;
211 struct opp *temp_opp;
214 dev_opp = find_device_opp(dev);
215 if (IS_ERR(dev_opp)) {
216 int r = PTR_ERR(dev_opp);
217 dev_err(dev, "%s: device OPP not found (%d)\n", __func__, r);
221 list_for_each_entry_rcu(temp_opp, &dev_opp->opp_list, node) {
222 if (temp_opp->available)
228 EXPORT_SYMBOL_GPL(opp_get_opp_count);
231 * opp_find_freq_exact() - search for an exact frequency
232 * @dev: device for which we do this operation
233 * @freq: frequency to search for
234 * @available: true/false - match for available opp
236 * Searches for exact match in the opp list and returns pointer to the matching
237 * opp if found, else returns ERR_PTR in case of error and should be handled
238 * using IS_ERR. Error return values can be:
239 * EINVAL: for bad pointer
240 * ERANGE: no match found for search
241 * ENODEV: if device not found in list of registered devices
243 * Note: available is a modifier for the search. if available=true, then the
244 * match is for exact matching frequency and is available in the stored OPP
245 * table. if false, the match is for exact frequency which is not available.
247 * This provides a mechanism to enable an opp which is not available currently
248 * or the opposite as well.
250 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
251 * protected pointer. The reason for the same is that the opp pointer which is
252 * returned will remain valid for use with opp_get_{voltage, freq} only while
253 * under the locked area. The pointer returned must be used prior to unlocking
254 * with rcu_read_unlock() to maintain the integrity of the pointer.
256 struct opp *opp_find_freq_exact(struct device *dev, unsigned long freq,
259 struct device_opp *dev_opp;
260 struct opp *temp_opp, *opp = ERR_PTR(-ERANGE);
262 dev_opp = find_device_opp(dev);
263 if (IS_ERR(dev_opp)) {
264 int r = PTR_ERR(dev_opp);
265 dev_err(dev, "%s: device OPP not found (%d)\n", __func__, r);
269 list_for_each_entry_rcu(temp_opp, &dev_opp->opp_list, node) {
270 if (temp_opp->available == available &&
271 temp_opp->rate == freq) {
279 EXPORT_SYMBOL_GPL(opp_find_freq_exact);
282 * opp_find_freq_ceil() - Search for an rounded ceil freq
283 * @dev: device for which we do this operation
284 * @freq: Start frequency
286 * Search for the matching ceil *available* OPP from a starting freq
289 * Returns matching *opp and refreshes *freq accordingly, else returns
290 * ERR_PTR in case of error and should be handled using IS_ERR. Error return
292 * EINVAL: for bad pointer
293 * ERANGE: no match found for search
294 * ENODEV: if device not found in list of registered devices
296 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
297 * protected pointer. The reason for the same is that the opp pointer which is
298 * returned will remain valid for use with opp_get_{voltage, freq} only while
299 * under the locked area. The pointer returned must be used prior to unlocking
300 * with rcu_read_unlock() to maintain the integrity of the pointer.
302 struct opp *opp_find_freq_ceil(struct device *dev, unsigned long *freq)
304 struct device_opp *dev_opp;
305 struct opp *temp_opp, *opp = ERR_PTR(-ERANGE);
308 dev_err(dev, "%s: Invalid argument freq=%p\n", __func__, freq);
309 return ERR_PTR(-EINVAL);
312 dev_opp = find_device_opp(dev);
314 return ERR_CAST(dev_opp);
316 list_for_each_entry_rcu(temp_opp, &dev_opp->opp_list, node) {
317 if (temp_opp->available && temp_opp->rate >= *freq) {
326 EXPORT_SYMBOL_GPL(opp_find_freq_ceil);
329 * opp_find_freq_floor() - Search for a rounded floor freq
330 * @dev: device for which we do this operation
331 * @freq: Start frequency
333 * Search for the matching floor *available* OPP from a starting freq
336 * Returns matching *opp and refreshes *freq accordingly, else returns
337 * ERR_PTR in case of error and should be handled using IS_ERR. Error return
339 * EINVAL: for bad pointer
340 * ERANGE: no match found for search
341 * ENODEV: if device not found in list of registered devices
343 * Locking: This function must be called under rcu_read_lock(). opp is a rcu
344 * protected pointer. The reason for the same is that the opp pointer which is
345 * returned will remain valid for use with opp_get_{voltage, freq} only while
346 * under the locked area. The pointer returned must be used prior to unlocking
347 * with rcu_read_unlock() to maintain the integrity of the pointer.
349 struct opp *opp_find_freq_floor(struct device *dev, unsigned long *freq)
351 struct device_opp *dev_opp;
352 struct opp *temp_opp, *opp = ERR_PTR(-ERANGE);
355 dev_err(dev, "%s: Invalid argument freq=%p\n", __func__, freq);
356 return ERR_PTR(-EINVAL);
359 dev_opp = find_device_opp(dev);
361 return ERR_CAST(dev_opp);
363 list_for_each_entry_rcu(temp_opp, &dev_opp->opp_list, node) {
364 if (temp_opp->available) {
365 /* go to the next node, before choosing prev */
366 if (temp_opp->rate > *freq)
377 EXPORT_SYMBOL_GPL(opp_find_freq_floor);
380 * opp_add() - Add an OPP table from a table definitions
381 * @dev: device for which we do this operation
382 * @freq: Frequency in Hz for this OPP
383 * @u_volt: Voltage in uVolts for this OPP
385 * This function adds an opp definition to the opp list and returns status.
386 * The opp is made available by default and it can be controlled using
387 * opp_enable/disable functions.
389 * Locking: The internal device_opp and opp structures are RCU protected.
390 * Hence this function internally uses RCU updater strategy with mutex locks
391 * to keep the integrity of the internal data structures. Callers should ensure
392 * that this function is *NOT* called under RCU protection or in contexts where
393 * mutex cannot be locked.
395 int opp_add(struct device *dev, unsigned long freq, unsigned long u_volt)
397 struct device_opp *dev_opp = NULL;
398 struct opp *opp, *new_opp;
399 struct list_head *head;
401 /* allocate new OPP node */
402 new_opp = kzalloc(sizeof(struct opp), GFP_KERNEL);
404 dev_warn(dev, "%s: Unable to create new OPP node\n", __func__);
408 /* Hold our list modification lock here */
409 mutex_lock(&dev_opp_list_lock);
411 /* Check for existing list for 'dev' */
412 dev_opp = find_device_opp(dev);
413 if (IS_ERR(dev_opp)) {
415 * Allocate a new device OPP table. In the infrequent case
416 * where a new device is needed to be added, we pay this
419 dev_opp = kzalloc(sizeof(struct device_opp), GFP_KERNEL);
421 mutex_unlock(&dev_opp_list_lock);
424 "%s: Unable to create device OPP structure\n",
430 srcu_init_notifier_head(&dev_opp->head);
431 INIT_LIST_HEAD(&dev_opp->opp_list);
433 /* Secure the device list modification */
434 list_add_rcu(&dev_opp->node, &dev_opp_list);
437 /* populate the opp table */
438 new_opp->dev_opp = dev_opp;
439 new_opp->rate = freq;
440 new_opp->u_volt = u_volt;
441 new_opp->available = true;
443 /* Insert new OPP in order of increasing frequency */
444 head = &dev_opp->opp_list;
445 list_for_each_entry_rcu(opp, &dev_opp->opp_list, node) {
446 if (new_opp->rate < opp->rate)
452 list_add_rcu(&new_opp->node, head);
453 mutex_unlock(&dev_opp_list_lock);
456 * Notify the changes in the availability of the operable
457 * frequency/voltage list.
459 srcu_notifier_call_chain(&dev_opp->head, OPP_EVENT_ADD, new_opp);
464 * opp_set_availability() - helper to set the availability of an opp
465 * @dev: device for which we do this operation
466 * @freq: OPP frequency to modify availability
467 * @availability_req: availability status requested for this opp
469 * Set the availability of an OPP with an RCU operation, opp_{enable,disable}
470 * share a common logic which is isolated here.
472 * Returns -EINVAL for bad pointers, -ENOMEM if no memory available for the
473 * copy operation, returns 0 if no modifcation was done OR modification was
476 * Locking: The internal device_opp and opp structures are RCU protected.
477 * Hence this function internally uses RCU updater strategy with mutex locks to
478 * keep the integrity of the internal data structures. Callers should ensure
479 * that this function is *NOT* called under RCU protection or in contexts where
480 * mutex locking or synchronize_rcu() blocking calls cannot be used.
482 static int opp_set_availability(struct device *dev, unsigned long freq,
483 bool availability_req)
485 struct device_opp *tmp_dev_opp, *dev_opp = ERR_PTR(-ENODEV);
486 struct opp *new_opp, *tmp_opp, *opp = ERR_PTR(-ENODEV);
489 /* keep the node allocated */
490 new_opp = kmalloc(sizeof(struct opp), GFP_KERNEL);
492 dev_warn(dev, "%s: Unable to create OPP\n", __func__);
496 mutex_lock(&dev_opp_list_lock);
498 /* Find the device_opp */
499 list_for_each_entry(tmp_dev_opp, &dev_opp_list, node) {
500 if (dev == tmp_dev_opp->dev) {
501 dev_opp = tmp_dev_opp;
505 if (IS_ERR(dev_opp)) {
506 r = PTR_ERR(dev_opp);
507 dev_warn(dev, "%s: Device OPP not found (%d)\n", __func__, r);
511 /* Do we have the frequency? */
512 list_for_each_entry(tmp_opp, &dev_opp->opp_list, node) {
513 if (tmp_opp->rate == freq) {
523 /* Is update really needed? */
524 if (opp->available == availability_req)
526 /* copy the old data over */
529 /* plug in new node */
530 new_opp->available = availability_req;
532 list_replace_rcu(&opp->node, &new_opp->node);
533 mutex_unlock(&dev_opp_list_lock);
534 kfree_rcu(opp, head);
536 /* Notify the change of the OPP availability */
537 if (availability_req)
538 srcu_notifier_call_chain(&dev_opp->head, OPP_EVENT_ENABLE,
541 srcu_notifier_call_chain(&dev_opp->head, OPP_EVENT_DISABLE,
547 mutex_unlock(&dev_opp_list_lock);
553 * opp_enable() - Enable a specific OPP
554 * @dev: device for which we do this operation
555 * @freq: OPP frequency to enable
557 * Enables a provided opp. If the operation is valid, this returns 0, else the
558 * corresponding error value. It is meant to be used for users an OPP available
559 * after being temporarily made unavailable with opp_disable.
561 * Locking: The internal device_opp and opp structures are RCU protected.
562 * Hence this function indirectly uses RCU and mutex locks to keep the
563 * integrity of the internal data structures. Callers should ensure that
564 * this function is *NOT* called under RCU protection or in contexts where
565 * mutex locking or synchronize_rcu() blocking calls cannot be used.
567 int opp_enable(struct device *dev, unsigned long freq)
569 return opp_set_availability(dev, freq, true);
571 EXPORT_SYMBOL_GPL(opp_enable);
574 * opp_disable() - Disable a specific OPP
575 * @dev: device for which we do this operation
576 * @freq: OPP frequency to disable
578 * Disables a provided opp. If the operation is valid, this returns
579 * 0, else the corresponding error value. It is meant to be a temporary
580 * control by users to make this OPP not available until the circumstances are
581 * right to make it available again (with a call to opp_enable).
583 * Locking: The internal device_opp and opp structures are RCU protected.
584 * Hence this function indirectly uses RCU and mutex locks to keep the
585 * integrity of the internal data structures. Callers should ensure that
586 * this function is *NOT* called under RCU protection or in contexts where
587 * mutex locking or synchronize_rcu() blocking calls cannot be used.
589 int opp_disable(struct device *dev, unsigned long freq)
591 return opp_set_availability(dev, freq, false);
593 EXPORT_SYMBOL_GPL(opp_disable);
595 #ifdef CONFIG_CPU_FREQ
597 * opp_init_cpufreq_table() - create a cpufreq table for a device
598 * @dev: device for which we do this operation
599 * @table: Cpufreq table returned back to caller
601 * Generate a cpufreq table for a provided device- this assumes that the
602 * opp list is already initialized and ready for usage.
604 * This function allocates required memory for the cpufreq table. It is
605 * expected that the caller does the required maintenance such as freeing
606 * the table as required.
608 * Returns -EINVAL for bad pointers, -ENODEV if the device is not found, -ENOMEM
609 * if no memory available for the operation (table is not populated), returns 0
610 * if successful and table is populated.
612 * WARNING: It is important for the callers to ensure refreshing their copy of
613 * the table if any of the mentioned functions have been invoked in the interim.
615 * Locking: The internal device_opp and opp structures are RCU protected.
616 * To simplify the logic, we pretend we are updater and hold relevant mutex here
617 * Callers should ensure that this function is *NOT* called under RCU protection
618 * or in contexts where mutex locking cannot be used.
620 int opp_init_cpufreq_table(struct device *dev,
621 struct cpufreq_frequency_table **table)
623 struct device_opp *dev_opp;
625 struct cpufreq_frequency_table *freq_table;
628 /* Pretend as if I am an updater */
629 mutex_lock(&dev_opp_list_lock);
631 dev_opp = find_device_opp(dev);
632 if (IS_ERR(dev_opp)) {
633 int r = PTR_ERR(dev_opp);
634 mutex_unlock(&dev_opp_list_lock);
635 dev_err(dev, "%s: Device OPP not found (%d)\n", __func__, r);
639 freq_table = kzalloc(sizeof(struct cpufreq_frequency_table) *
640 (opp_get_opp_count(dev) + 1), GFP_KERNEL);
642 mutex_unlock(&dev_opp_list_lock);
643 dev_warn(dev, "%s: Unable to allocate frequency table\n",
648 list_for_each_entry(opp, &dev_opp->opp_list, node) {
649 if (opp->available) {
650 freq_table[i].index = i;
651 freq_table[i].frequency = opp->rate / 1000;
655 mutex_unlock(&dev_opp_list_lock);
657 freq_table[i].index = i;
658 freq_table[i].frequency = CPUFREQ_TABLE_END;
660 *table = &freq_table[0];
664 EXPORT_SYMBOL_GPL(opp_init_cpufreq_table);
667 * opp_free_cpufreq_table() - free the cpufreq table
668 * @dev: device for which we do this operation
669 * @table: table to free
671 * Free up the table allocated by opp_init_cpufreq_table
673 void opp_free_cpufreq_table(struct device *dev,
674 struct cpufreq_frequency_table **table)
682 EXPORT_SYMBOL_GPL(opp_free_cpufreq_table);
683 #endif /* CONFIG_CPU_FREQ */
686 * opp_get_notifier() - find notifier_head of the device with opp
687 * @dev: device pointer used to lookup device OPPs.
689 struct srcu_notifier_head *opp_get_notifier(struct device *dev)
691 struct device_opp *dev_opp = find_device_opp(dev);
694 return ERR_CAST(dev_opp); /* matching type */
696 return &dev_opp->head;
701 * of_init_opp_table() - Initialize opp table from device tree
702 * @dev: device pointer used to lookup device OPPs.
704 * Register the initial OPP table with the OPP library for given device.
706 int of_init_opp_table(struct device *dev)
708 const struct property *prop;
712 prop = of_find_property(dev->of_node, "operating-points", NULL);
719 * Each OPP is a set of tuples consisting of frequency and
720 * voltage like <freq-kHz vol-uV>.
722 nr = prop->length / sizeof(u32);
724 dev_err(dev, "%s: Invalid OPP list\n", __func__);
730 unsigned long freq = be32_to_cpup(val++) * 1000;
731 unsigned long volt = be32_to_cpup(val++);
733 if (opp_add(dev, freq, volt)) {
734 dev_warn(dev, "%s: Failed to add OPP %ld\n",
743 EXPORT_SYMBOL_GPL(of_init_opp_table);