3 * (C) COPYRIGHT 2010-2012 ARM Limited. All rights reserved.
5 * This program is free software and is provided to you under the terms of the GNU General Public License version 2
6 * as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
8 * A copy of the licence is included with the program, and can also be obtained from Free Software
9 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * @file mali_kbase_pm.h
17 * Power management API definitions
23 #include <kbase/src/common/mali_midg_regmap.h>
25 #include "mali_kbase_pm_always_on.h"
26 #include "mali_kbase_pm_demand.h"
28 /* Forward definition - see mali_kbase.h */
31 /** The types of core in a GPU.
33 * These enumerated values are used in calls to @ref kbase_pm_invoke_power_up, @ref kbase_pm_invoke_power_down, @ref
34 * kbase_pm_get_present_cores, @ref kbase_pm_get_active_cores, @ref kbase_pm_get_trans_cores, @ref
35 * kbase_pm_get_ready_cores. The specify which type of core should be acted on.
36 * These values are set in a manner that allows @ref core_type_to_reg function to be simpler and more efficient.
38 typedef enum kbase_pm_core_type
40 KBASE_PM_CORE_L3 = L3_PRESENT_LO, /**< The L3 cache */
41 KBASE_PM_CORE_L2 = L2_PRESENT_LO, /**< The L2 cache */
42 KBASE_PM_CORE_SHADER = SHADER_PRESENT_LO, /**< Shader cores */
43 KBASE_PM_CORE_TILER = TILER_PRESENT_LO /**< Tiler cores */
46 /** Initialize the power management framework.
48 * Must be called before any other power management function
50 * @param kbdev The kbase device structure for the device (must be a valid pointer)
52 * @return MALI_ERROR_NONE if the power management framework was successfully initialized.
54 mali_error kbase_pm_init(struct kbase_device *kbdev);
56 /** Power up GPU after all modules have been initialized and interrupt handlers installed.
58 * @param kbdev The kbase device structure for the device (must be a valid pointer)
60 * @return MALI_ERROR_NONE if powerup was successful.
62 mali_error kbase_pm_powerup(struct kbase_device *kbdev);
65 * Halt the power management framework.
66 * Should ensure that no new interrupts are generated,
67 * but allow any currently running interrupt handlers to complete successfully.
68 * No event can make the pm system turn on the GPU after this function returns.
69 * The active policy is sent @ref KBASE_PM_EVENT_SYSTEM_SUSPEND.
71 * @param kbdev The kbase device structure for the device (must be a valid pointer)
73 void kbase_pm_halt(struct kbase_device *kbdev);
75 /** Terminate the power management framework.
77 * No power management functions may be called after this
78 * (except @ref kbase_pm_init)
80 * @param kbdev The kbase device structure for the device (must be a valid pointer)
82 void kbase_pm_term(struct kbase_device *kbdev);
84 /** Events that can be sent to a power policy.
86 * Power policies are expected to handle all these events, although they may choose to take no action.
88 typedef enum kbase_pm_event
90 /* helper for tests */
91 KBASEP_PM_EVENT_FIRST,
93 /** Initialize the power policy.
95 * This event is sent immediately after the @ref kbase_pm_policy.init function of the policy returns.
97 * The policy may decide to transition the cores to its 'normal' state (e.g. an always on policy would turn all
98 * the cores on). The policy should assume that the GPU is in active use (i.e. as if the @ref
99 * KBASE_PM_EVENT_GPU_ACTIVE event had been received), if this is not the case then @ref KBASE_PM_EVENT_GPU_IDLE
100 * will be called after this event has been handled.
102 KBASE_PM_EVENT_POLICY_INIT = KBASEP_PM_EVENT_FIRST,
103 /** The power state of the device has changed.
105 * This event is sent when the GPU raises an interrupt to announce that a power transition has finished. Because
106 * there may be multiple power transitions the power policy must interrogate the state of the GPU to check whether
107 * all expected transitions have finished. If the GPU has just turned on or off then the policy must call @ref
108 * kbase_pm_power_up_done or @ref kbase_pm_power_down_done as appropriate.
110 KBASE_PM_EVENT_GPU_STATE_CHANGED,
111 /** The GPU is becoming active.
113 * This event is sent when the first context is about to use the GPU.
115 * If the core is turned off then this event must cause the core to turn on. This is done asynchronously and the
116 * policy must call the function kbase_pm_power_up_done to signal that the core is turned on sufficiently to allow
119 KBASE_PM_EVENT_GPU_ACTIVE,
120 /** The GPU is becoming idle.
122 * This event is sent when the last context has finished using the GPU.
124 * The power policy may turn the GPU off entirely (e.g. turn the clocks or power off).
126 KBASE_PM_EVENT_GPU_IDLE,
127 /** The system has requested a change of power policy.
129 * The current policy receives this message when a request to change policy occurs. It must ensure that all active
130 * power transitions are completed and then call the @ref kbase_pm_change_policy function.
132 * This event is only delivered when the policy has been informed that the GPU is 'active' (the power management
133 * code internally increments the context active counter during a policy change).
135 KBASE_PM_EVENT_POLICY_CHANGE,
136 /** The system is requesting to suspend the GPU.
138 * The power policy should ensure that the GPU is shut down sufficiently for the system to suspend the device.
139 * Once the GPU is ready the policy should call @ref kbase_pm_power_down_done.
141 KBASE_PM_EVENT_SYSTEM_SUSPEND,
142 /** The system is requesting to resume the GPU.
144 * The power policy should restore the GPU to the state it was before the previous
145 * @ref KBASE_PM_EVENT_SYSTEM_SUSPEND event. If the GPU is being powered up then it should call
146 * @ref kbase_pm_power_transitioning before changing the state and @ref kbase_pm_power_up_done when
147 * the transition is complete.
149 KBASE_PM_EVENT_SYSTEM_RESUME,
150 /** The job scheduler is requesting to power up/down cores.
152 * This event is sent when:
153 * - powered down cores are needed to complete a job
154 * - powered up cores are not needed anymore
156 KBASE_PM_EVENT_CHANGE_GPU_STATE,
158 /* helpers for tests */
159 KBASEP_PM_EVENT_LAST = KBASE_PM_EVENT_CHANGE_GPU_STATE,
160 KBASEP_PM_EVENT_INVALID
163 typedef union kbase_pm_policy_data
165 kbasep_pm_policy_always_on always_on;
166 kbasep_pm_policy_demand demand;
167 } kbase_pm_policy_data;
169 /** Power policy structure.
171 * Each power management policy exposes a (static) instance of this structure which contains function pointers to the
174 typedef struct kbase_pm_policy
176 /** The name of this policy */
179 /** Function called when the policy is selected
181 * This should initialize the kbdev->pm.policy_data pointer to the policy's data structure. It should not attempt
182 * to make any changes to hardware state.
184 * It is undefined what state the cores are in when the function is called, however no power transitions should be
187 * @param kbdev The kbase device structure for the device (must be a valid pointer)
189 void (*init)(struct kbase_device *kbdev);
190 /** Function called when the policy is unselected.
192 * This should free any data allocated with \c init
194 * @param kbdev The kbase device structure for the device (must be a valid pointer)
196 void (*term)(struct kbase_device *kbdev);
197 /** Function called when there is an event to process
199 * @param kbdev The kbase device structure for the device (must be a valid pointer)
200 * @param event The event to process
202 void (*event)(struct kbase_device *kbdev, kbase_pm_event event);
205 /** Metrics data collected for use by the power management framework.
208 typedef struct kbasep_pm_metrics_data
213 osk_ticks time_period_start;
216 mali_bool gpu_active;
218 osk_spinlock_irq lock;
221 mali_bool timer_active;
223 void * platform_data;
224 } kbasep_pm_metrics_data;
226 /** Actions for DVFS.
228 * kbase_pm_get_dvfs_action will return one of these enumerated values to
229 * describe the action that the DVFS system should take.
231 typedef enum kbase_pm_dvfs_action
233 KBASE_PM_DVFS_NOP, /**< No change in clock frequency is requested */
234 KBASE_PM_DVFS_CLOCK_UP, /**< The clock frequency should be increased if possible */
235 KBASE_PM_DVFS_CLOCK_DOWN /**< The clock frequency should be decreased if possible */
236 } kbase_pm_dvfs_action;
238 /** A value for an atomic @ref work_active,
239 * which tracks whether the work unit has been enqueued.
241 typedef enum kbase_pm_work_active_state
243 KBASE_PM_WORK_ACTIVE_STATE_INACTIVE = 0x00u, /**< There are no work units enqueued and @ref kbase_pm_worker is not running. */
244 KBASE_PM_WORK_ACTIVE_STATE_ENQUEUED = 0x01u, /**< There is a work unit enqueued, but @ref kbase_pm_worker is not running. */
245 KBASE_PM_WORK_ACTIVE_STATE_PROCESSING = 0x02u, /**< @ref kbase_pm_worker is running. */
246 KBASE_PM_WORK_ACTIVE_STATE_PENDING_EVT = 0x03u /**< Processing and there's an event outstanding.
247 @ref kbase_pm_worker is running, but @ref pending_events
248 has been updated since it started so
249 it should recheck the list of pending events before exiting. */
250 } kbase_pm_work_active_state;
252 /** Data stored per device for power management.
254 * This structure contains data for the power management framework. There is one instance of this structure per device
257 typedef struct kbase_pm_device_data
259 /** The policy that is currently actively controlling the power state. */
260 const kbase_pm_policy *current_policy;
261 /** The policy that the system is transitioning to. */
262 const kbase_pm_policy *new_policy;
263 /** The data needed for the current policy. This is considered private to the policy. */
264 kbase_pm_policy_data policy_data;
265 /** The workqueue that the policy callbacks are executed on. */
267 /** A bit mask of events that are waiting to be delivered to the active policy. */
268 osk_atomic pending_events;
269 /** The work unit that is enqueued onto the workqueue. */
271 /** An atomic which tracks whether the work unit has been enqueued.
272 * For list of possible values please refer to @ref kbase_pm_work_active_state.
274 osk_atomic work_active;
275 /** The wait queue for power up events. */
276 osk_waitq power_up_waitqueue;
277 /** The wait queue for power down events. */
278 osk_waitq power_down_waitqueue;
279 /** Wait queue for whether there is an outstanding event for the policy */
280 osk_waitq policy_outstanding_event;
282 /** The reference count of active contexts on this device. */
284 /** Lock to protect active_count */
285 osk_spinlock_irq active_count_lock;
286 /** The reference count of active gpu cycle counter users */
287 int gpu_cycle_counter_requests;
288 /** Lock to protect gpu_cycle_counter_requests */
289 osk_spinlock_irq gpu_cycle_counter_requests_lock;
290 /** A bit mask identifying the shader cores that the power policy would like to be on.
291 * The current state of the cores may be different, but there should be transitions in progress that will
292 * eventually achieve this state (assuming that the policy doesn't change its mind in the mean time.
294 u64 desired_shader_state;
295 /** A bit mask identifying the tiler cores that the power policy would like to be on.
296 * @see kbase_pm_device_data:desired_shader_state */
297 u64 desired_tiler_state;
299 /** Lock protecting the power state of the device.
301 * This lock must be held when accessing the shader_available_bitmap, tiler_available_bitmap, shader_inuse_bitmap
302 * and tiler_inuse_bitmap fields of kbase_device. It is also held when the hardware power registers are being
303 * written to, to ensure that two threads do not conflict over the power transitions that the hardware should
306 osk_spinlock_irq power_change_lock;
308 /** Set to true when the GPU is powered and register accesses are possible, false otherwise */
309 mali_bool gpu_powered;
310 /** Spinlock that must be held when writing gpu_powered */
311 osk_spinlock_irq gpu_powered_lock;
313 /** Structure to hold metrics for the GPU */
314 kbasep_pm_metrics_data metrics;
316 /** Callback when the GPU needs to be turned on. See @ref kbase_pm_callback_conf
318 * @param kbdev The kbase device
320 * @return 1 if GPU state was lost, 0 otherwise
322 int (*callback_power_on)(struct kbase_device *kbdev);
324 /** Callback when the GPU may be turned off. See @ref kbase_pm_callback_conf
326 * @param kbdev The kbase device
328 void (*callback_power_off)(struct kbase_device *kbdev);
330 /** Indicator if system clock to mail-t604 is active */
332 /** cmd & pmu lock */
333 osk_spinlock_irq cmu_pmu_lock;
335 } kbase_pm_device_data;
337 /** Get the current policy.
338 * Returns the policy that is currently active.
340 * @param kbdev The kbase device structure for the device (must be a valid pointer)
342 * @return The current policy
344 const kbase_pm_policy *kbase_pm_get_policy(struct kbase_device *kbdev);
346 /** Change the policy to the one specified.
348 * @param kbdev The kbase device structure for the device (must be a valid pointer)
349 * @param policy The policy to change to (valid pointer returned from @ref kbase_pm_list_policies)
351 void kbase_pm_set_policy(struct kbase_device *kbdev, const kbase_pm_policy *policy);
353 /** Retrieve a static list of the available policies.
354 * @param[out] policies An array pointer to take the list of policies. This may be NULL.
355 * The contents of this array must not be modified.
357 * @return The number of policies
359 int kbase_pm_list_policies(const kbase_pm_policy * const **policies);
361 /** The current policy is ready to change to the new policy
363 * The current policy must ensure that all cores have finished transitioning before calling this function.
364 * The new policy is sent an @ref KBASE_PM_EVENT_POLICY_INIT event.
366 * @param kbdev The kbase device structure for the device (must be a valid pointer)
368 void kbase_pm_change_policy(struct kbase_device *kbdev);
372 * The OS may choose to turn off idle devices
374 * @param kbdev The kbase device structure for the device (must be a valid pointer)
376 void kbase_pm_dev_idle(struct kbase_device *kbdev);
378 /** The GPU is active.
380 * The OS should avoid opportunistically turning off the GPU while it is active
382 * @param kbdev The kbase device structure for the device (must be a valid pointer)
384 void kbase_pm_dev_activate(struct kbase_device *kbdev);
386 /** Send an event to the active power policy.
388 * The event is queued for sending to the active power policy. The event is merged with the current queue by the @ref
389 * kbasep_pm_merge_event function which may decide to drop events.
391 * Note that this function may be called in an atomic context on Linux which implies that it must not sleep.
393 * @param kbdev The kbase device structure for the device (must be a valid pointer)
394 * @param event The event that should be queued
396 void kbase_pm_send_event(struct kbase_device *kbdev, kbase_pm_event event);
398 /** Turn one or more cores on.
400 * This function is called by the active power policy to turn one or more cores on.
402 * @param kbdev The kbase device structure for the device (must be a valid pointer)
403 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
404 * @param cores A bitmask of cores to turn on
406 void kbase_pm_invoke_power_up(struct kbase_device *kbdev, kbase_pm_core_type type, u64 cores);
408 /** Turn one or more cores off.
410 * This function is called by the active power policy to turn one or more core off.
412 * @param kbdev The kbase device structure for the device (must be a valid pointer)
413 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
414 * @param cores A bitmask of cores to turn off
416 void kbase_pm_invoke_power_down(struct kbase_device *kbdev, kbase_pm_core_type type, u64 cores);
418 /** Get details of the cores that are present in the device.
420 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type)
421 * present in the GPU device and also a count of the number of cores.
423 * @param kbdev The kbase device structure for the device (must be a valid pointer)
424 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
426 * @return The bit mask of cores present
428 u64 kbase_pm_get_present_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
430 /** Get details of the cores that are currently active in the device.
432 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type) that
433 * are actively processing work (i.e. turned on *and* busy).
435 * @param kbdev The kbase device structure for the device (must be a valid pointer)
436 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
438 * @return The bit mask of active cores
440 u64 kbase_pm_get_active_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
442 /** Get details of the cores that are currently transitioning between power states.
444 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type) that
445 * are currently transitioning between power states.
447 * @param kbdev The kbase device structure for the device (must be a valid pointer)
448 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
450 * @return The bit mask of transitioning cores
452 u64 kbase_pm_get_trans_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
454 /** Get details of the cores that are currently powered and ready for jobs.
456 * This function can be called by the active power policy to return a bitmask of the cores (of a specified type) that
457 * are powered and ready for jobs (they may or may not be currently executing jobs).
459 * @param kbdev The kbase device structure for the device (must be a valid pointer)
460 * @param type The type of core (see the @ref kbase_pm_core_type enumeration)
462 * @return The bit mask of ready cores
464 u64 kbase_pm_get_ready_cores(struct kbase_device *kbdev, kbase_pm_core_type type);
466 /** Return whether the power manager is active
468 * This function will return true when there are cores (of any time) that are currently transitioning between power
471 * It can be used on receipt of the @ref KBASE_PM_EVENT_GPU_STATE_CHANGED message to determine whether the requested power
472 * transitions have completely finished or not.
474 * @param kbdev The kbase device structure for the device (must be a valid pointer)
476 * @return true when there are cores transitioning between power states, false otherwise
478 mali_bool kbase_pm_get_pwr_active(struct kbase_device *kbdev);
480 /** Turn the clock for the device on.
482 * This function can be used by a power policy to turn the clock for the GPU on. It should be modified during
483 * integration to perform the necessary actions to ensure that the GPU is fully powered and clocked.
485 * @param kbdev The kbase device structure for the device (must be a valid pointer)
487 void kbase_pm_clock_on(struct kbase_device *kbdev);
489 /** Turn the clock for the device off.
491 * This function can be used by a power policy to turn the clock for the GPU off. It should be modified during
492 * integration to perform the necessary actions to turn the clock off (if this is possible in the integration).
494 * @param kbdev The kbase device structure for the device (must be a valid pointer)
496 void kbase_pm_clock_off(struct kbase_device *kbdev);
498 /** Enable interrupts on the device.
500 * This function should be called by the active power policy immediately after calling @ref kbase_pm_clock_on to
501 * ensure that interrupts are enabled on the device.
503 * @param kbdev The kbase device structure for the device (must be a valid pointer)
505 void kbase_pm_enable_interrupts(struct kbase_device *kbdev);
507 /** Disable interrupts on the device.
509 * This function should be called by the active power policy after shutting down the device (i.e. in the @ref
510 * KBASE_PM_EVENT_GPU_STATE_CHANGED handler after confirming that all cores have powered off). It prevents interrupt
511 * delivery to the CPU so no further @ref KBASE_PM_EVENT_GPU_STATE_CHANGED messages will be received until @ref
512 * kbase_pm_enable_interrupts is called.
514 * @param kbdev The kbase device structure for the device (must be a valid pointer)
516 void kbase_pm_disable_interrupts(struct kbase_device *kbdev);
518 /** Initialize the hardware
520 * This function checks the GPU ID register to ensure that the GPU is supported by the driver and performs a reset on
521 * the device so that it is in a known state before the device is used.
523 * @param kbdev The kbase device structure for the device (must be a valid pointer)
525 * @return MALI_ERROR_NONE if the device is supported and successfully reset.
527 mali_error kbase_pm_init_hw(struct kbase_device *kbdev);
529 /** Inform the power management system that the power state of the device is transitioning.
531 * This function must be called by the active power policy before transitioning the core between an 'off state' and an
532 * 'on state'. It resets the wait queues that are waited on by @ref kbase_pm_wait_for_power_up and @ref
533 * kbase_pm_wait_for_power_down.
535 * @param kbdev The kbase device structure for the device (must be a valid pointer)
537 void kbase_pm_power_transitioning(struct kbase_device *kbdev);
539 /** The GPU has been powered up successfully.
541 * This function must be called by the active power policy when the GPU has been powered up successfully. It signals
542 * to the rest of the system that jobs can start being submitted to the device.
544 * @param kbdev The kbase device structure for the device (must be a valid pointer)
546 void kbase_pm_power_up_done(struct kbase_device *kbdev);
548 /** The GPU has been reset successfully.
550 * This function must be called by the GPU interrupt handler when the RESET_COMPLETED bit is set. It signals to the
551 * power management initialization code that the GPU has been successfully reset.
553 * @param kbdev The kbase device structure for the device (must be a valid pointer)
555 void kbase_pm_reset_done(struct kbase_device *kbdev);
557 /** The GPU has been powered down successfully.
559 * This function must be called by the active power policy when the GPU has been powered down successfully. It signals
560 * to the rest of the system that a system suspend can now take place.
562 * @param kbdev The kbase device structure for the device (must be a valid pointer)
564 void kbase_pm_power_down_done(struct kbase_device *kbdev);
566 /** Wait for the power policy to signal power up.
568 * This function waits for the power policy to signal power up by calling @ref kbase_pm_power_up_done. After the power
569 * policy has signalled this the function will return immediately until the power policy calls @ref
570 * kbase_pm_power_transitioning.
572 * @param kbdev The kbase device structure for the device (must be a valid pointer)
574 void kbase_pm_wait_for_power_up(struct kbase_device *kbdev);
576 /** Wait for the power policy to signal power down.
578 * This function waits for the power policy to signal power down by calling @ref kbase_pm_power_down_done. After the
579 * power policy has signalled this the function will return immediately until the power policy calls @ref
580 * kbase_pm_power_transitioning.
582 * @param kbdev The kbase device structure for the device (must be a valid pointer)
584 void kbase_pm_wait_for_power_down(struct kbase_device *kbdev);
586 /** Increment the count of active contexts.
588 * This function should be called when a context is about to submit a job. It informs the active power policy that the
589 * GPU is going to be in use shortly and the policy is expected to start turning on the GPU.
591 * This function will block until the GPU is available.
593 * @param kbdev The kbase device structure for the device (must be a valid pointer)
595 void kbase_pm_context_active(struct kbase_device *kbdev);
597 /** Decrement the reference count of active contexts.
599 * This function should be called when a context becomes idle. After this call the GPU may be turned off by the power
600 * policy so the calling code should ensure that it does not access the GPU's registers.
602 * @param kbdev The kbase device structure for the device (must be a valid pointer)
604 void kbase_pm_context_idle(struct kbase_device *kbdev);
606 /** Check if there are any power transitions to make, and if so start them.
608 * This function will check the desired_xx_state members of kbase_pm_device_data and the actual status of the
609 * hardware to see if any power transitions can be made at this time to make the hardware state closer to the state
610 * desired by the power policy.
612 * @param kbdev The kbase device structure for the device (must be a valid pointer)
614 void kbase_pm_check_transitions(struct kbase_device *kbdev);
616 /** Read the bitmasks of present cores.
618 * This information is cached to avoid having to perform register reads whenever the information is required.
620 * @param kbdev The kbase device structure for the device (must be a valid pointer)
622 void kbasep_pm_read_present_cores(struct kbase_device *kbdev);
624 /** Mark one or more cores as being required for jobs to be submitted.
626 * This function is called by the job scheduler to mark one or both cores
627 * as being required to submit jobs that are ready to run.
629 * The cores requested are reference counted and a subsequent call to @ref kbase_pm_register_inuse_cores or
630 * @ref kbase_pm_unrequest_cores should be made to dereference the cores as being 'needed'.
632 * The current running policy is sent an @ref KBASE_PM_EVENT_CHANGE_GPU_STATE if power up of requested core is
635 * The policy is expected to make these cores available at some point in the future,
636 * but may take an arbitrary length of time to reach this state.
638 * @param kbdev The kbase device structure for the device
639 * @param shader_cores A bitmask of shader cores which are necessary for the job
640 * @param tiler_cores A bitmask of tiler cores which are necessary for the job
642 * @return MALI_ERROR_NONE if the cores were successfully requested.
644 mali_error kbase_pm_request_cores(struct kbase_device *kbdev, u64 shader_cores, u64 tiler_cores);
646 /** Unmark one or more cores as being required for jobs to be submitted.
648 * This function undoes the effect of @ref kbase_pm_request_cores. It should be used when a job is not
649 * going to be submitted to the hardware (e.g. the job is cancelled before it is enqueued).
651 * The current running policy is sent an @ref KBASE_PM_EVENT_CHANGE_GPU_STATE if power down of requested core
654 * The policy may use this as an indication that it can power down cores.
656 * @param kbdev The kbase device structure for the device
657 * @param shader_cores A bitmask of shader cores (as given to @ref kbase_pm_request_cores)
658 * @param tiler_cores A bitmask of tiler cores (as given to @ref kbase_pm_request_cores)
660 void kbase_pm_unrequest_cores(struct kbase_device *kbdev, u64 shader_cores, u64 tiler_cores);
662 /** Register a set of cores as in use by a job.
664 * This function should be called after @ref kbase_pm_request_cores when the job is about to be submitted to
665 * the hardware. It will check that the necessary cores are available and if so update the 'needed' and 'inuse'
666 * bitmasks to reflect that the job is now committed to being run.
668 * If the necessary cores are not currently available then the function will return MALI_FALSE and have no effect.
670 * @param kbdev The kbase device structure for the device
671 * @param shader_cores A bitmask of shader cores (as given to @ref kbase_pm_request_cores)
672 * @param tiler_cores A bitmask of tiler cores (as given to @ref kbase_pm_request_cores)
674 * @return MALI_TRUE if the job can be submitted to the hardware or MALI_FALSE if the job is not ready to run.
676 mali_bool kbase_pm_register_inuse_cores(struct kbase_device *kbdev, u64 shader_cores, u64 tiler_cores);
678 /** Release cores after a job has run.
680 * This function should be called when a job has finished running on the hardware. A call to @ref
681 * kbase_pm_register_inuse_cores must have previously occurred. The reference counts of the specified cores will be
682 * decremented which may cause the bitmask of 'inuse' cores to be reduced. The power policy may then turn off any
683 * cores which are no longer 'inuse'.
685 * @param kbdev The kbase device structure for the device
686 * @param shader_cores A bitmask of shader cores (as given to @ref kbase_pm_register_inuse_cores)
687 * @param tiler_cores A bitmask of tiler cores (as given to @ref kbase_pm_register_inuse_cores)
689 void kbase_pm_release_cores(struct kbase_device *kbdev, u64 shader_cores, u64 tiler_cores);
691 /** Initialize the metrics gathering framework.
693 * This must be called before other metric gathering APIs are called.
695 * @param kbdev The kbase device structure for the device (must be a valid pointer)
697 * @return MALI_ERROR_NONE on success, MALI_ERROR_FUNCTION_FAILED on error
699 mali_error kbasep_pm_metrics_init(struct kbase_device *kbdev);
701 /** Terminate the metrics gathering framework.
703 * This must be called when metric gathering is no longer required. It is an error to call any metrics gathering
704 * function (other than kbasep_pm_metrics_init) after calling this function.
706 * @param kbdev The kbase device structure for the device (must be a valid pointer)
708 void kbasep_pm_metrics_term(struct kbase_device *kbdev);
710 /** Record that the GPU is active.
712 * This records that the GPU is now active. The previous GPU state must have been idle, the function will assert if
713 * this is not true in a debug build.
715 * @param kbdev The kbase device structure for the device (must be a valid pointer)
717 void kbasep_pm_record_gpu_active(struct kbase_device *kbdev);
719 /** Record that the GPU is idle.
721 * This records that the GPU is now idle. The previous GPU state must have been active, the function will assert if
722 * this is not true in a debug build.
724 * @param kbdev The kbase device structure for the device (must be a valid pointer)
726 void kbasep_pm_record_gpu_idle(struct kbase_device *kbdev);
728 /** Function to be called by the frame buffer driver to update the vsync metric.
730 * This function should be called by the frame buffer driver to update whether the system is hitting the vsync target
731 * or not. buffer_updated should be true if the vsync corresponded with a new frame being displayed, otherwise it
732 * should be false. This function does not need to be called every vsync, but only when the value of buffer_updated
733 * differs from a previous call.
735 * @param kbdev The kbase device structure for the device (must be a valid pointer)
736 * @param buffer_updated True if the buffer has been updated on this VSync, false otherwise
738 void kbase_pm_report_vsync(struct kbase_device *kbdev, int buffer_updated);
740 /** Configure the frame buffer device to set the vsync callback.
742 * This function should do whatever is necessary for this integration to ensure that kbase_pm_report_vsync is
743 * called appropriately.
745 * This function will need porting as part of the integration for a device.
747 * @param kbdev The kbase device structure for the device (must be a valid pointer)
749 void kbase_pm_register_vsync_callback(struct kbase_device *kbdev);
751 /** Free any resources that kbase_pm_register_vsync_callback allocated.
753 * This function should perform any cleanup required from the call to kbase_pm_register_vsync_callback.
754 * No call backs should occur after this function has returned.
756 * This function will need porting as part of the integration for a device.
758 * @param kbdev The kbase device structure for the device (must be a valid pointer)
760 void kbase_pm_unregister_vsync_callback(struct kbase_device *kbdev);
762 /** Determine whether the DVFS system should change the clock speed of the GPU.
764 * This function should be called regularly by the DVFS system to check whether the clock speed of the GPU needs
765 * updating. It will return one of three enumerated values of kbase_pm_dvfs_action:
767 * @param kbdev The kbase device structure for the device (must be a valid pointer)
768 * @retval KBASE_PM_DVFS_NOP The clock does not need changing
769 * @retval KBASE_PM_DVFS_CLOCK_UP, The clock frequency should be increased if possible.
770 * @retval KBASE_PM_DVFS_CLOCK_DOWN The clock frequency should be decreased if possible.
772 kbase_pm_dvfs_action kbase_pm_get_dvfs_action(struct kbase_device *kbdev);
774 /** Mark that the GPU cycle counter is needed, if the caller is the first caller
775 * then the GPU cycle counters will be enabled.
777 * The GPU must be powered when calling this function (i.e. @ref kbase_pm_context_active must have been called).
779 * @param kbdev The kbase device structure for the device (must be a valid pointer)
782 void kbase_pm_request_gpu_cycle_counter(struct kbase_device *kbdev);
784 /** Mark that the GPU cycle counter is no longer in use, if the caller is the last
785 * caller then the GPU cycle counters will be disabled. A request must have been made
786 * before a call to this.
788 * @param kbdev The kbase device structure for the device (must be a valid pointer)
791 void kbase_pm_release_gpu_cycle_counter(struct kbase_device *kbdev);
793 #endif /* _KBASE_PM_H_ */