3 * (C) COPYRIGHT ARM Limited. All rights reserved.
5 * This program is free software and is provided to you under the terms of the
6 * GNU General Public License version 2 as published by the Free Software
7 * Foundation, and any use by you of this program is subject to the terms
10 * A copy of the licence is included with the program, and can also be obtained
11 * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
12 * Boston, MA 02110-1301, USA.
21 * @file mali_kbase_pm.h
22 * Power management API definitions
28 #include <mali_midg_regmap.h>
29 #include <linux/atomic.h>
31 /* Forward definition - see mali_kbase.h */
34 #include "mali_kbase_pm_ca.h"
35 #include "mali_kbase_pm_policy.h"
37 #include "mali_kbase_pm_ca_fixed.h"
38 #if MALI_CUSTOMER_RELEASE == 0
39 #include "mali_kbase_pm_ca_random.h"
42 #include "mali_kbase_pm_always_on.h"
43 #include "mali_kbase_pm_coarse_demand.h"
44 #include "mali_kbase_pm_demand.h"
45 #if MALI_CUSTOMER_RELEASE == 0
46 #include "mali_kbase_pm_demand_always_powered.h"
47 #include "mali_kbase_pm_fast_start.h"
50 /** The types of core in a GPU.
52 * These enumerated values are used in calls to:
53 * - @ref kbase_pm_get_present_cores
54 * - @ref kbase_pm_get_active_cores
55 * - @ref kbase_pm_get_trans_cores
56 * - @ref kbase_pm_get_ready_cores.
58 * They specify which type of core should be acted on. These values are set in
59 * a manner that allows @ref core_type_to_reg function to be simpler and more
62 typedef enum kbase_pm_core_type {
63 KBASE_PM_CORE_L3 = L3_PRESENT_LO, /**< The L3 cache */
64 KBASE_PM_CORE_L2 = L2_PRESENT_LO, /**< The L2 cache */
65 KBASE_PM_CORE_SHADER = SHADER_PRESENT_LO, /**< Shader cores */
66 KBASE_PM_CORE_TILER = TILER_PRESENT_LO /**< Tiler cores */
69 /** Initialize the power management framework.
71 * Must be called before any other power management function
73 * @param kbdev The kbase device structure for the device (must be a valid pointer)
75 * @return MALI_ERROR_NONE if the power management framework was successfully initialized.
77 mali_error kbase_pm_init(struct kbase_device *kbdev);
79 /** Power up GPU after all modules have been initialized and interrupt handlers installed.
81 * @param kbdev The kbase device structure for the device (must be a valid pointer)
83 * @return MALI_ERROR_NONE if powerup was successful.
85 mali_error kbase_pm_powerup(struct kbase_device *kbdev);
88 * Halt the power management framework.
89 * Should ensure that no new interrupts are generated,
90 * but allow any currently running interrupt handlers to complete successfully.
91 * The GPU is forced off by the time this function returns, regardless of
92 * whether or not the active power policy asks for the GPU to be powered off.
94 * @param kbdev The kbase device structure for the device (must be a valid pointer)
96 void kbase_pm_halt(struct kbase_device *kbdev);
98 /** Terminate the power management framework.
100 * No power management functions may be called after this
101 * (except @ref kbase_pm_init)
103 * @param kbdev The kbase device structure for the device (must be a valid pointer)
105 void kbase_pm_term(struct kbase_device *kbdev);
107 /** Metrics data collected for use by the power management framework.
110 typedef struct kbasep_pm_metrics_data {
113 ktime_t time_period_start;
116 mali_bool gpu_active;
120 struct hrtimer timer;
121 mali_bool timer_active;
124 struct kbase_device *kbdev;
125 } kbasep_pm_metrics_data;
127 /** Actions for DVFS.
129 * kbase_pm_get_dvfs_action will return one of these enumerated values to
130 * describe the action that the DVFS system should take.
132 typedef enum kbase_pm_dvfs_action {
133 KBASE_PM_DVFS_NOP, /**< No change in clock frequency is requested */
134 KBASE_PM_DVFS_CLOCK_UP, /**< The clock frequency should be increased if possible */
135 KBASE_PM_DVFS_CLOCK_DOWN /**< The clock frequency should be decreased if possible */
136 } kbase_pm_dvfs_action;
138 typedef union kbase_pm_policy_data {
139 kbasep_pm_policy_always_on always_on;
140 kbasep_pm_policy_coarse_demand coarse_demand;
141 kbasep_pm_policy_demand demand;
142 #if MALI_CUSTOMER_RELEASE == 0
143 kbasep_pm_policy_demand_always_powered demand_always_powered;
144 kbasep_pm_policy_fast_start fast_start;
146 } kbase_pm_policy_data;
148 typedef union kbase_pm_ca_policy_data {
149 kbasep_pm_ca_policy_fixed fixed;
150 #if MALI_CUSTOMER_RELEASE == 0
151 kbasep_pm_ca_policy_random random;
153 } kbase_pm_ca_policy_data;
155 /** Data stored per device for power management.
157 * This structure contains data for the power management framework. There is one instance of this structure per device
160 typedef struct kbase_pm_device_data {
161 /** The lock protecting Power Management structures accessed
164 * This lock must also be held whenever the GPU is being powered on or off.
168 /** The policy that is currently actively controlling core availability.
170 * @note: During an IRQ, this can be NULL when the policy is being changed
171 * with kbase_pm_ca_set_policy(). The change is protected under
172 * kbase_device::pm::power_change_lock. Direct access to this from IRQ
173 * context must therefore check for NULL. If NULL, then
174 * kbase_pm_ca_set_policy() will re-issue the policy functions that would've
175 * been done under IRQ.
177 const kbase_pm_ca_policy *ca_current_policy;
179 /** The policy that is currently actively controlling the power state.
181 * @note: During an IRQ, this can be NULL when the policy is being changed
182 * with kbase_pm_set_policy(). The change is protected under
183 * kbase_device::pm::power_change_lock. Direct access to this from IRQ
184 * context must therefore check for NULL. If NULL, then
185 * kbase_pm_set_policy() will re-issue the policy functions that would've
186 * been done under IRQ.
188 const kbase_pm_policy *pm_current_policy;
190 /** Private data for current CA policy */
191 kbase_pm_ca_policy_data ca_policy_data;
193 /** Private data for current PM policy */
194 kbase_pm_policy_data pm_policy_data;
196 /** Flag indicating when core availability policy is transitioning cores.
197 * The core availability policy must set this when a change in core availability
200 * power_change_lock must be held when accessing this. */
201 mali_bool ca_in_transition;
203 /** Waiting for reset and a queue to wait for changes */
204 mali_bool reset_done;
205 wait_queue_head_t reset_done_wait;
207 /** Wait queue for whether the l2 cache has been powered as requested */
208 wait_queue_head_t l2_powered_wait;
209 /** State indicating whether all the l2 caches are powered.
210 * Non-zero indicates they're *all* powered
211 * Zero indicates that some (or all) are not powered */
214 /** The reference count of active contexts on this device. */
216 /** Flag indicating suspending/suspended */
217 mali_bool suspending;
218 /* Wait queue set when active_count == 0 */
219 wait_queue_head_t zero_active_count_wait;
221 /** The reference count of active gpu cycle counter users */
222 int gpu_cycle_counter_requests;
223 /** Lock to protect gpu_cycle_counter_requests */
224 spinlock_t gpu_cycle_counter_requests_lock;
226 /** A bit mask identifying the shader cores that the power policy would like to be on.
227 * The current state of the cores may be different, but there should be transitions in progress that will
228 * eventually achieve this state (assuming that the policy doesn't change its mind in the mean time.
230 u64 desired_shader_state;
231 /** bit mask indicating which shader cores are currently in a power-on transition */
232 u64 powering_on_shader_state;
233 /** A bit mask identifying the tiler cores that the power policy would like to be on.
234 * @see kbase_pm_device_data:desired_shader_state */
235 u64 desired_tiler_state;
236 /** bit mask indicating which tiler core are currently in a power-on transition */
237 u64 powering_on_tiler_state;
239 /** bit mask indicating which l2-caches are currently in a power-on transition */
240 u64 powering_on_l2_state;
241 /** bit mask indicating which l3-caches are currently in a power-on transition */
242 u64 powering_on_l3_state;
244 /** Lock protecting the power state of the device.
246 * This lock must be held when accessing the shader_available_bitmap, tiler_available_bitmap, l2_available_bitmap,
247 * shader_inuse_bitmap and tiler_inuse_bitmap fields of kbase_device, and the ca_in_transition and shader_poweroff_pending
248 * fields of kbase_pm_device_data. It is also held when the hardware power registers are being written to, to ensure
249 * that two threads do not conflict over the power transitions that the hardware should make.
251 spinlock_t power_change_lock;
253 /** This flag is set iff the GPU is powered as requested by the
254 * desired_xxx_state variables */
255 mali_bool gpu_in_desired_state;
256 /* Wait queue set when gpu_in_desired_state != 0 */
257 wait_queue_head_t gpu_in_desired_state_wait;
259 /** Set to true when the GPU is powered and register accesses are possible, false otherwise */
260 mali_bool gpu_powered;
262 /** A bit mask identifying the available shader cores that are specified via sysfs */
265 /** Set to true when instrumentation is enabled, false otherwise */
266 mali_bool instr_enabled;
268 mali_bool cg1_disabled;
270 #ifdef CONFIG_MALI_DEBUG
271 /** Debug state indicating whether sufficient initialization of the driver
272 * has occurred to handle IRQs */
273 mali_bool driver_ready_for_irqs;
274 #endif /* CONFIG_MALI_DEBUG */
276 /** Spinlock that must be held when:
277 * - writing gpu_powered
278 * - accessing driver_ready_for_irqs (in CONFIG_MALI_DEBUG builds) */
279 spinlock_t gpu_powered_lock;
281 /** Time in milliseconds between each dvfs sample */
283 u32 platform_dvfs_frequency;
285 /** Structure to hold metrics for the GPU */
287 kbasep_pm_metrics_data metrics;
289 /** Set to the number of poweroff timer ticks until the GPU is powered off */
290 int gpu_poweroff_pending;
292 /** Set to the number of poweroff timer ticks until shaders are powered off */
293 int shader_poweroff_pending_time;
295 /** Timer for powering off GPU */
296 struct hrtimer gpu_poweroff_timer;
298 struct workqueue_struct *gpu_poweroff_wq;
300 struct work_struct gpu_poweroff_work;
302 /** Period of GPU poweroff timer */
303 ktime_t gpu_poweroff_time;
305 /** Bit mask of shaders to be powered off on next timer callback */
306 u64 shader_poweroff_pending;
308 /** Set to MALI_TRUE if the poweroff timer is currently running, MALI_FALSE otherwise */
309 mali_bool poweroff_timer_running;
311 int poweroff_shader_ticks;
313 int poweroff_gpu_ticks;
315 /** Callback when the GPU needs to be turned on. See @ref kbase_pm_callback_conf
317 * @param kbdev The kbase device
319 * @return 1 if GPU state was lost, 0 otherwise
321 int (*callback_power_on) (struct kbase_device *kbdev);
323 /** Callback when the GPU may be turned off. See @ref kbase_pm_callback_conf
325 * @param kbdev The kbase device
327 void (*callback_power_off) (struct kbase_device *kbdev);
329 /** Callback when a suspend occurs and the GPU needs to be turned off.
330 * See @ref kbase_pm_callback_conf
332 * @param kbdev The kbase device
334 void (*callback_power_suspend) (struct kbase_device *kbdev);
336 /** Callback when a resume occurs and the GPU needs to be turned on.
337 * See @ref kbase_pm_callback_conf
339 * @param kbdev The kbase device
341 void (*callback_power_resume) (struct kbase_device *kbdev);
343 /** Callback for initializing the runtime power management.
345 * @param kbdev The kbase device
347 * @return MALI_ERROR_NONE on success, else error code
349 mali_error(*callback_power_runtime_init) (struct kbase_device *kbdev);
351 /** Callback for terminating the runtime power management.
353 * @param kbdev The kbase device
355 void (*callback_power_runtime_term) (struct kbase_device *kbdev);
357 /** Callback when the GPU needs to be turned on. See @ref kbase_pm_callback_conf
359 * @param kbdev The kbase device
361 * @return 1 if GPU state was lost, 0 otherwise
363 int (*callback_power_runtime_on) (struct kbase_device *kbdev);
365 /** Callback when the GPU may be turned off. See @ref kbase_pm_callback_conf
367 * @param kbdev The kbase device
369 void (*callback_power_runtime_off) (struct kbase_device *kbdev);
371 } kbase_pm_device_data;
375 * The OS may choose to turn off idle devices
377 * @param kbdev The kbase device structure for the device (must be a valid pointer)
379 void kbase_pm_dev_idle(struct kbase_device *kbdev);
381 /** The GPU is active.
383 * The OS should avoid opportunistically turning off the GPU while it is active
385 * @param kbdev The kbase device structure for the device (must be a valid pointer)
387 void kbase_pm_dev_activate(struct kbase_device *kbdev);
389 /** Get details of the cores that are present in the device.
391 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type)
392 * present in the GPU device and also a count of the number of cores.
394 * @param kbdev The kbase device structure for the device (must be a valid pointer)
395 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
397 * @return The bit mask of cores present
399 u64 kbase_pm_get_present_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
401 /** Get details of the cores that are currently active in the device.
403 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type) that
404 * are actively processing work (i.e. turned on *and* busy).
406 * @param kbdev The kbase device structure for the device (must be a valid pointer)
407 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
409 * @return The bit mask of active cores
411 u64 kbase_pm_get_active_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
413 /** Get details of the cores that are currently transitioning between power states.
415 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type) that
416 * are currently transitioning between power states.
418 * @param kbdev The kbase device structure for the device (must be a valid pointer)
419 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
421 * @return The bit mask of transitioning cores
423 u64 kbase_pm_get_trans_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
425 /** Get details of the cores that are currently powered and ready for jobs.
427 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type) that
428 * are powered and ready for jobs (they may or may not be currently executing jobs).
430 * @param kbdev The kbase device structure for the device (must be a valid pointer)
431 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
433 * @return The bit mask of ready cores
435 u64 kbase_pm_get_ready_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
437 /** Turn the clock for the device on, and enable device interrupts.
439 * This function can be used by a power policy to turn the clock for the GPU on. It should be modified during
440 * integration to perform the necessary actions to ensure that the GPU is fully powered and clocked.
442 * @param kbdev The kbase device structure for the device (must be a valid pointer)
443 * @param is_resume MALI_TRUE if clock on due to resume after suspend,
444 * MALI_FALSE otherwise
446 void kbase_pm_clock_on(struct kbase_device *kbdev, mali_bool is_resume);
448 /** Disable device interrupts, and turn the clock for the device off.
450 * This function can be used by a power policy to turn the clock for the GPU off. It should be modified during
451 * integration to perform the necessary actions to turn the clock off (if this is possible in the integration).
453 * @param kbdev The kbase device structure for the device (must be a valid pointer)
454 * @param is_suspend MALI_TRUE if clock off due to suspend, MALI_FALSE otherwise
456 void kbase_pm_clock_off(struct kbase_device *kbdev, mali_bool is_suspend);
458 /** Enable interrupts on the device.
460 * Interrupts are also enabled after a call to kbase_pm_clock_on().
462 * @param kbdev The kbase device structure for the device (must be a valid pointer)
464 void kbase_pm_enable_interrupts(struct kbase_device *kbdev);
466 /** Disable interrupts on the device.
468 * This prevents delivery of Power Management interrupts to the CPU so that
469 * kbase_pm_check_transitions_nolock() will not be called from the IRQ handler
470 * until @ref kbase_pm_enable_interrupts or kbase_pm_clock_on() is called.
472 * Interrupts are also disabled after a call to kbase_pm_clock_off().
474 * @param kbdev The kbase device structure for the device (must be a valid pointer)
476 void kbase_pm_disable_interrupts(struct kbase_device *kbdev);
478 /** Initialize the hardware
480 * This function checks the GPU ID register to ensure that the GPU is supported by the driver and performs a reset on
481 * the device so that it is in a known state before the device is used.
483 * @param kbdev The kbase device structure for the device (must be a valid pointer)
484 * @param enable_irqs When set to MALI_TRUE gpu irqs will be enabled after this call, else
485 * they will be left disabled.
487 * @return MALI_ERROR_NONE if the device is supported and successfully reset.
489 mali_error kbase_pm_init_hw(struct kbase_device *kbdev, mali_bool enable_irqs );
491 /** The GPU has been reset successfully.
493 * This function must be called by the GPU interrupt handler when the RESET_COMPLETED bit is set. It signals to the
494 * power management initialization code that the GPU has been successfully reset.
496 * @param kbdev The kbase device structure for the device (must be a valid pointer)
498 void kbase_pm_reset_done(struct kbase_device *kbdev);
500 /** Increment the count of active contexts.
502 * This function should be called when a context is about to submit a job. It informs the active power policy that the
503 * GPU is going to be in use shortly and the policy is expected to start turning on the GPU.
505 * This function will block until the GPU is available.
507 * This function ASSERTS if a suspend is occuring/has occurred whilst this is
508 * in use. Use kbase_pm_contect_active_unless_suspending() instead.
510 * @note a Suspend is only visible to Kernel threads; user-space threads in a
511 * syscall cannot witness a suspend, because they are frozen before the suspend
514 * @param kbdev The kbase device structure for the device (must be a valid pointer)
516 void kbase_pm_context_active(struct kbase_device *kbdev);
519 /** Handler codes for doing kbase_pm_context_active_handle_suspend() */
521 /** A suspend is not expected/not possible - this is the same as
522 * kbase_pm_context_active() */
523 KBASE_PM_SUSPEND_HANDLER_NOT_POSSIBLE,
524 /** If we're suspending, fail and don't increase the active count */
525 KBASE_PM_SUSPEND_HANDLER_DONT_INCREASE,
526 /** If we're suspending, succeed and allow the active count to increase iff
527 * it didn't go from 0->1 (i.e., we didn't re-activate the GPU).
529 * This should only be used when there is a bounded time on the activation
530 * (e.g. guarantee it's going to be idled very soon after) */
531 KBASE_PM_SUSPEND_HANDLER_DONT_REACTIVATE
532 } kbase_pm_suspend_handler;
534 /** Suspend 'safe' variant of kbase_pm_context_active()
536 * If a suspend is in progress, this allows for various different ways of
537 * handling the suspend. Refer to @ref kbase_pm_suspend_handler for details.
539 * We returns a status code indicating whether we're allowed to keep the GPU
540 * active during the suspend, depending on the handler code. If the status code
541 * indicates a failure, the caller must abort whatever operation it was
542 * attempting, and potentially queue it up for after the OS has resumed.
544 * @param kbdev The kbase device structure for the device (must be a valid pointer)
545 * @param suspend_handler The handler code for how to handle a suspend that might occur
546 * @return zero Indicates success
547 * @return non-zero Indicates failure due to the system being suspending/suspended.
549 int kbase_pm_context_active_handle_suspend(struct kbase_device *kbdev, kbase_pm_suspend_handler suspend_handler);
551 /** Decrement the reference count of active contexts.
553 * This function should be called when a context becomes idle. After this call the GPU may be turned off by the power
554 * policy so the calling code should ensure that it does not access the GPU's registers.
556 * @param kbdev The kbase device structure for the device (must be a valid pointer)
558 void kbase_pm_context_idle(struct kbase_device *kbdev);
560 /** Check if there are any power transitions to make, and if so start them.
562 * This function will check the desired_xx_state members of kbase_pm_device_data and the actual status of the
563 * hardware to see if any power transitions can be made at this time to make the hardware state closer to the state
564 * desired by the power policy.
566 * The return value can be used to check whether all the desired cores are
567 * available, and so whether it's worth submitting a job (e.g. from a Power
570 * Note that this still returns MALI_TRUE when desired_xx_state has no
571 * cores. That is: of the no cores desired, none were <em>un</em>available. In
572 * this case, the caller may still need to try submitting jobs. This is because
573 * the Core Availability Policy might have taken us to an intermediate state
574 * where no cores are powered, before powering on more cores (e.g. for core
577 * The caller must hold kbase_device::pm::power_change_lock
579 * @param kbdev The kbase device structure for the device (must be a valid pointer)
580 * @return non-zero when all desired cores are available. That is,
581 * it's worthwhile for the caller to submit a job.
582 * @return MALI_FALSE otherwise
584 mali_bool kbase_pm_check_transitions_nolock(struct kbase_device *kbdev);
586 /** Synchronous and locking variant of kbase_pm_check_transitions_nolock()
588 * On returning, the desired state at the time of the call will have been met.
590 * @note There is nothing to stop the core being switched off by calls to
591 * kbase_pm_release_cores() or kbase_pm_unrequest_cores(). Therefore, the
592 * caller must have already made a call to
593 * kbase_pm_request_cores()/kbase_pm_request_cores_sync() previously.
595 * The usual use-case for this is to ensure cores are 'READY' after performing
598 * Unlike kbase_pm_check_transitions_nolock(), the caller must not hold
599 * kbase_device::pm::power_change_lock, because this function will take that
602 * @param kbdev The kbase device structure for the device (must be a valid pointer)
604 void kbase_pm_check_transitions_sync(struct kbase_device *kbdev);
606 /** Variant of kbase_pm_update_cores_state() where the caller must hold
607 * kbase_device::pm::power_change_lock
609 * @param kbdev The kbase device structure for the device (must be a valid
612 void kbase_pm_update_cores_state_nolock(struct kbase_device *kbdev);
614 /** Update the desired state of shader cores from the Power Policy, and begin
615 * any power transitions.
617 * This function will update the desired_xx_state members of
618 * kbase_pm_device_data by calling into the current Power Policy. It will then
619 * begin power transitions to make the hardware acheive the desired shader core
622 * @param kbdev The kbase device structure for the device (must be a valid
625 void kbase_pm_update_cores_state(struct kbase_device *kbdev);
627 /** Cancel any pending requests to power off the GPU and/or shader cores.
629 * This should be called by any functions which directly power off the GPU.
631 * @param kbdev The kbase device structure for the device (must be a valid
634 void kbase_pm_cancel_deferred_poweroff(struct kbase_device *kbdev);
636 /** Read the bitmasks of present cores.
638 * This information is cached to avoid having to perform register reads whenever the information is required.
640 * @param kbdev The kbase device structure for the device (must be a valid pointer)
642 void kbasep_pm_read_present_cores(struct kbase_device *kbdev);
644 /** Initialize the metrics gathering framework.
646 * This must be called before other metric gathering APIs are called.
648 * @param kbdev The kbase device structure for the device (must be a valid pointer)
650 * @return MALI_ERROR_NONE on success, MALI_ERROR_FUNCTION_FAILED on error
652 mali_error kbasep_pm_metrics_init(struct kbase_device *kbdev);
654 /** Terminate the metrics gathering framework.
656 * This must be called when metric gathering is no longer required. It is an error to call any metrics gathering
657 * function (other than kbasep_pm_metrics_init) after calling this function.
659 * @param kbdev The kbase device structure for the device (must be a valid pointer)
661 void kbasep_pm_metrics_term(struct kbase_device *kbdev);
663 /** Record that the GPU is active.
665 * This records that the GPU is now active. The previous GPU state must have been idle, the function will assert if
666 * this is not true in a debug build.
668 * @param kbdev The kbase device structure for the device (must be a valid pointer)
670 void kbasep_pm_record_gpu_active(struct kbase_device *kbdev);
672 /** Record that the GPU is idle.
674 * This records that the GPU is now idle. The previous GPU state must have been active, the function will assert if
675 * this is not true in a debug build.
677 * @param kbdev The kbase device structure for the device (must be a valid pointer)
679 void kbasep_pm_record_gpu_idle(struct kbase_device *kbdev);
681 /** Function to be called by the frame buffer driver to update the vsync metric.
683 * This function should be called by the frame buffer driver to update whether the system is hitting the vsync target
684 * or not. buffer_updated should be true if the vsync corresponded with a new frame being displayed, otherwise it
685 * should be false. This function does not need to be called every vsync, but only when the value of buffer_updated
686 * differs from a previous call.
688 * @param kbdev The kbase device structure for the device (must be a valid pointer)
689 * @param buffer_updated True if the buffer has been updated on this VSync, false otherwise
691 void kbase_pm_report_vsync(struct kbase_device *kbdev, int buffer_updated);
693 /** Configure the frame buffer device to set the vsync callback.
695 * This function should do whatever is necessary for this integration to ensure that kbase_pm_report_vsync is
696 * called appropriately.
698 * This function will need porting as part of the integration for a device.
700 * @param kbdev The kbase device structure for the device (must be a valid pointer)
702 void kbase_pm_register_vsync_callback(struct kbase_device *kbdev);
704 /** Free any resources that kbase_pm_register_vsync_callback allocated.
706 * This function should perform any cleanup required from the call to kbase_pm_register_vsync_callback.
707 * No call backs should occur after this function has returned.
709 * This function will need porting as part of the integration for a device.
711 * @param kbdev The kbase device structure for the device (must be a valid pointer)
713 void kbase_pm_unregister_vsync_callback(struct kbase_device *kbdev);
715 /** Determine whether the DVFS system should change the clock speed of the GPU.
717 * This function should be called regularly by the DVFS system to check whether the clock speed of the GPU needs
718 * updating. It will return one of three enumerated values of kbase_pm_dvfs_action:
720 * @param kbdev The kbase device structure for the device (must be a valid pointer)
721 * @retval KBASE_PM_DVFS_NOP The clock does not need changing
722 * @retval KBASE_PM_DVFS_CLOCK_UP, The clock frequency should be increased if possible.
723 * @retval KBASE_PM_DVFS_CLOCK_DOWN The clock frequency should be decreased if possible.
725 kbase_pm_dvfs_action kbase_pm_get_dvfs_action(struct kbase_device *kbdev);
727 /** Mark that the GPU cycle counter is needed, if the caller is the first caller
728 * then the GPU cycle counters will be enabled.
730 * The GPU must be powered when calling this function (i.e. @ref kbase_pm_context_active must have been called).
732 * @param kbdev The kbase device structure for the device (must be a valid pointer)
735 void kbase_pm_request_gpu_cycle_counter(struct kbase_device *kbdev);
737 /** Mark that the GPU cycle counter is no longer in use, if the caller is the last
738 * caller then the GPU cycle counters will be disabled. A request must have been made
739 * before a call to this.
741 * @param kbdev The kbase device structure for the device (must be a valid pointer)
744 void kbase_pm_release_gpu_cycle_counter(struct kbase_device *kbdev);
746 /** Enables access to the GPU registers before power management has powered up the GPU
747 * with kbase_pm_powerup().
749 * Access to registers should be done using kbase_os_reg_read/write() at this stage,
750 * not kbase_reg_read/write().
752 * This results in the power management callbacks provided in the driver configuration
753 * to get called to turn on power and/or clocks to the GPU.
754 * See @ref kbase_pm_callback_conf.
756 * This should only be used before power management is powered up with kbase_pm_powerup()
758 * @param kbdev The kbase device structure for the device (must be a valid pointer)
760 void kbase_pm_register_access_enable(struct kbase_device *kbdev);
762 /** Disables access to the GPU registers enabled earlier by a call to
763 * kbase_pm_register_access_enable().
765 * This results in the power management callbacks provided in the driver configuration
766 * to get called to turn off power and/or clocks to the GPU.
767 * See @ref kbase_pm_callback_conf
769 * This should only be used before power management is powered up with kbase_pm_powerup()
771 * @param kbdev The kbase device structure for the device (must be a valid pointer)
773 void kbase_pm_register_access_disable(struct kbase_device *kbdev);
776 * Suspend the GPU and prevent any further register accesses to it from Kernel
779 * This is called in response to an OS suspend event, and calls into the various
780 * kbase components to complete the suspend.
782 * @note the mechanisms used here rely on all user-space threads being frozen
783 * by the OS before we suspend. Otherwise, an IOCTL could occur that powers up
784 * the GPU e.g. via atom submission.
786 * @param kbdev The kbase device structure for the device (must be a valid pointer)
788 void kbase_pm_suspend(struct kbase_device *kbdev);
791 * Resume the GPU, allow register accesses to it, and resume running atoms on
794 * This is called in response to an OS resume event, and calls into the various
795 * kbase components to complete the resume.
797 * @param kbdev The kbase device structure for the device (must be a valid pointer)
799 void kbase_pm_resume(struct kbase_device *kbdev);
801 /* NOTE: kbase_pm_is_suspending is in mali_kbase.h, because it is an inline function */
804 * Check if the power management metrics collection is active.
806 * Note that this returns if the power management metrics collection was
807 * active at the time of calling, it is possible that after the call the metrics
808 * collection enable may have changed state.
810 * The caller must handle the consequence that the state may have changed.
812 * @param kbdev The kbase device structure for the device (must be a valid pointer)
813 * @return MALI_TRUE if metrics collection was active else MALI_FALSE.
816 mali_bool kbase_pm_metrics_is_active(struct kbase_device *kbdev);
819 * Power on the GPU, and any cores that are requested.
821 * @param kbdev The kbase device structure for the device (must be a valid pointer)
822 * @param is_resume MALI_TRUE if power on due to resume after suspend,
823 * MALI_FALSE otherwise
825 void kbase_pm_do_poweron(struct kbase_device *kbdev, mali_bool is_resume);
828 * Power off the GPU, and any cores that have been requested.
830 * @param kbdev The kbase device structure for the device (must be a valid pointer)
831 * @param is_suspend MALI_TRUE if power off due to suspend,
832 * MALI_FALSE otherwise
834 void kbase_pm_do_poweroff(struct kbase_device *kbdev, mali_bool is_suspend);
836 #ifdef CONFIG_MALI_MIDGARD_DVFS
839 * Function provided by platform specific code when DVFS is enabled to allow
840 * the power management metrics system to report utilisation.
842 * @param kbdev The kbase device structure for the device (must be a valid pointer)
843 * @param utilisation The current calculated utilisation by the metrics system.
844 * @return Returns 0 on failure and non zero on success.
847 int kbase_platform_dvfs_event(struct kbase_device *kbdev, u32 utilisation);
849 #endif /* _KBASE_PM_H_ */