/* * * (C) COPYRIGHT 2010-2013 ARM Limited. All rights reserved. * * This program is free software and is provided to you under the terms of the * GNU General Public License version 2 as published by the Free Software * Foundation, and any use by you of this program is subject to the terms * of such GNU licence. * * A copy of the licence is included with the program, and can also be obtained * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. * */ /** * @file mali_kbase_pm_policy.h * Power policy API definitions */ #ifndef _KBASE_PM_POLICY_H_ #define _KBASE_PM_POLICY_H_ /** List of policy IDs */ typedef enum kbase_pm_policy_id { KBASE_PM_POLICY_ID_DEMAND = 1, KBASE_PM_POLICY_ID_ALWAYS_ON, KBASE_PM_POLICY_ID_COARSE_DEMAND, #if MALI_CUSTOMER_RELEASE == 0 KBASE_PM_POLICY_ID_DEMAND_ALWAYS_POWERED, KBASE_PM_POLICY_ID_FAST_START #endif } kbase_pm_policy_id; typedef u32 kbase_pm_policy_flags; /** Power policy structure. * * Each power policy exposes a (static) instance of this structure which contains function pointers to the * policy's methods. */ typedef struct kbase_pm_policy { /** The name of this policy */ char *name; /** Function called when the policy is selected * * This should initialize the kbdev->pm.pm_policy_data structure. It should not attempt * to make any changes to hardware state. * * It is undefined what state the cores are in when the function is called. * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void (*init) (struct kbase_device *kbdev); /** Function called when the policy is unselected. * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void (*term) (struct kbase_device *kbdev); /** Function called to get the current shader core mask * * The returned mask should meet or exceed (kbdev->shader_needed_bitmap | kbdev->shader_inuse_bitmap). * * @param kbdev The kbase device structure for the device (must be a valid pointer) * * @return The mask of shader cores to be powered */ u64 (*get_core_mask) (struct kbase_device *kbdev); /** Function called to get the current overall GPU power state * * This function should consider the state of kbdev->pm.active_count. If this count is greater than 0 then * there is at least one active context on the device and the GPU should be powered. If it is equal to 0 * then there are no active contexts and the GPU could be powered off if desired. * * @param kbdev The kbase device structure for the device (must be a valid pointer) * * @return MALI_TRUE if the GPU should be powered, MALI_FALSE otherwise */ mali_bool (*get_core_active) (struct kbase_device *kbdev); /** Field indicating flags for this policy */ kbase_pm_policy_flags flags; /** Field indicating an ID for this policy. This is not necessarily the * same as its index in the list returned by kbase_pm_list_policies(). * It is used purely for debugging. */ kbase_pm_policy_id id; } kbase_pm_policy; /** Initialize power policy framework * * Must be called before calling any other policy function * * @param kbdev The kbase device structure for the device (must be a valid pointer) * * @return MALI_ERROR_NONE if the power policy framework was successfully initialized. */ mali_error kbase_pm_policy_init(struct kbase_device *kbdev); /** Terminate power policy framework * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void kbase_pm_policy_term(struct kbase_device *kbdev); /** Update the active power state of the GPU * Calls into the current power policy * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void kbase_pm_update_active(struct kbase_device *kbdev); /** Update the desired core state of the GPU * Calls into the current power policy * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void kbase_pm_update_cores(struct kbase_device *kbdev); /** Get the current policy. * Returns the policy that is currently active. * * @param kbdev The kbase device structure for the device (must be a valid pointer) * * @return The current policy */ const kbase_pm_policy *kbase_pm_get_policy(struct kbase_device *kbdev); /** Change the policy to the one specified. * * @param kbdev The kbase device structure for the device (must be a valid pointer) * @param policy The policy to change to (valid pointer returned from @ref kbase_pm_list_policies) */ void kbase_pm_set_policy(struct kbase_device *kbdev, const kbase_pm_policy *policy); /** Retrieve a static list of the available policies. * @param[out] policies An array pointer to take the list of policies. This may be NULL. * The contents of this array must not be modified. * * @return The number of policies */ int kbase_pm_list_policies(const kbase_pm_policy * const **policies); typedef enum kbase_pm_cores_ready { KBASE_CORES_NOT_READY = 0, KBASE_NEW_AFFINITY = 1, KBASE_CORES_READY = 2 } kbase_pm_cores_ready; /** Synchronous variant of kbase_pm_request_cores() * * When this function returns, the @a shader_cores and @a tiler_cores will be * in the READY state. * * This is safe variant of kbase_pm_check_transitions_sync(): it handles the * work of ensuring the requested cores will remain powered until a matching * call to kbase_pm_unrequest_cores()/kbase_pm_release_cores() (as appropriate) * is made. * * @param kbdev The kbase device structure for the device * @param shader_cores A bitmask of shader cores which are necessary for the job * @param tiler_cores A bitmask of tiler cores which are necessary for the job */ void kbase_pm_request_cores_sync(struct kbase_device *kbdev, mali_bool tiler_required, u64 shader_cores); /** Mark one or more cores as being required for jobs to be submitted. * * This function is called by the job scheduler to mark one or both cores * as being required to submit jobs that are ready to run. * * The cores requested are reference counted and a subsequent call to @ref kbase_pm_register_inuse_cores or * @ref kbase_pm_unrequest_cores should be made to dereference the cores as being 'needed'. * * The active power policy will meet or exceed the requirements of the * requested cores in the system. Any core transitions needed will be begun * immediately, but they might not complete/the cores might not be available * until a Power Management IRQ. * * @param kbdev The kbase device structure for the device * @param shader_cores A bitmask of shader cores which are necessary for the job * @param tiler_cores A bitmask of tiler cores which are necessary for the job * * @return MALI_ERROR_NONE if the cores were successfully requested. */ void kbase_pm_request_cores(struct kbase_device *kbdev, mali_bool tiler_required, u64 shader_cores); /** Unmark one or more cores as being required for jobs to be submitted. * * This function undoes the effect of @ref kbase_pm_request_cores. It should be used when a job is not * going to be submitted to the hardware (e.g. the job is cancelled before it is enqueued). * * The active power policy will meet or exceed the requirements of the * requested cores in the system. Any core transitions needed will be begun * immediately, but they might not complete until a Power Management IRQ. * * The policy may use this as an indication that it can power down cores. * * @param kbdev The kbase device structure for the device * @param shader_cores A bitmask of shader cores (as given to @ref kbase_pm_request_cores) * @param tiler_cores A bitmask of tiler cores (as given to @ref kbase_pm_request_cores) */ void kbase_pm_unrequest_cores(struct kbase_device *kbdev, mali_bool tiler_required, u64 shader_cores); /** Register a set of cores as in use by a job. * * This function should be called after @ref kbase_pm_request_cores when the job is about to be submitted to * the hardware. It will check that the necessary cores are available and if so update the 'needed' and 'inuse' * bitmasks to reflect that the job is now committed to being run. * * If the necessary cores are not currently available then the function will return MALI_FALSE and have no effect. * * @param kbdev The kbase device structure for the device * @param shader_cores A bitmask of shader cores (as given to @ref kbase_pm_request_cores) * @param tiler_cores A bitmask of tiler cores (as given to @ref kbase_pm_request_cores) * * @return MALI_TRUE if the job can be submitted to the hardware or MALI_FALSE if the job is not ready to run. */ mali_bool kbase_pm_register_inuse_cores(struct kbase_device *kbdev, mali_bool tiler_required, u64 shader_cores); /** Release cores after a job has run. * * This function should be called when a job has finished running on the hardware. A call to @ref * kbase_pm_register_inuse_cores must have previously occurred. The reference counts of the specified cores will be * decremented which may cause the bitmask of 'inuse' cores to be reduced. The power policy may then turn off any * cores which are no longer 'inuse'. * * @param kbdev The kbase device structure for the device * @param shader_cores A bitmask of shader cores (as given to @ref kbase_pm_register_inuse_cores) * @param tiler_cores A bitmask of tiler cores (as given to @ref kbase_pm_register_inuse_cores) */ void kbase_pm_release_cores(struct kbase_device *kbdev, mali_bool tiler_required, u64 shader_cores); /** Request the use of l2 caches for all core groups, power up, wait and prevent the power manager from * powering down the l2 caches. * * This tells the power management that the caches should be powered up, and they * should remain powered, irrespective of the usage of shader cores. This does not * return until the l2 caches are powered up. * * The caller must call @ref kbase_pm_release_l2_caches when they are finished to * allow normal power management of the l2 caches to resume. * * This should only be used when power management is active. * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void kbase_pm_request_l2_caches(struct kbase_device *kbdev); /** Release the use of l2 caches for all core groups and allow the power manager to * power them down when necessary. * * This tells the power management that the caches can be powered down if necessary, with respect * to the usage of shader cores. * * The caller must have called @ref kbase_pm_request_l2_caches prior to a call to this. * * This should only be used when power management is active. * * @param kbdev The kbase device structure for the device (must be a valid pointer) */ void kbase_pm_release_l2_caches(struct kbase_device *kbdev); #endif /* _KBASE_PM_POLICY_H_ */