1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2010-2022 ARM Limited. All rights reserved. 5 * 6 * This program is free software and is provided to you under the terms of the 7 * GNU General Public License version 2 as published by the Free Software 8 * Foundation, and any use by you of this program is subject to the terms 9 * of such GNU license. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, you can access it online at 18 * http://www.gnu.org/licenses/gpl-2.0.html. 19 * 20 */ 21 22 /** 23 * DOC: Power management API definitions 24 */ 25 26 #ifndef _KBASE_PM_H_ 27 #define _KBASE_PM_H_ 28 29 #include "mali_kbase_hwaccess_pm.h" 30 31 #define PM_ENABLE_IRQS 0x01 32 #define PM_HW_ISSUES_DETECT 0x02 33 34 #ifdef CONFIG_MALI_ARBITER_SUPPORT 35 /* In the case that the GPU was granted by the Arbiter, it will have 36 * already been reset. The following flag ensures it is not reset 37 * twice. 38 */ 39 #define PM_NO_RESET 0x04 40 #endif 41 42 /** 43 * kbase_pm_init - Initialize the power management framework. 44 * 45 * @kbdev: The kbase device structure for the device 46 * (must be a valid pointer) 47 * 48 * Must be called before any other power management function 49 * 50 * Return: 0 if the power management framework was successfully initialized. 51 */ 52 int kbase_pm_init(struct kbase_device *kbdev); 53 54 /** 55 * kbase_pm_powerup - Power up GPU after all modules have been initialized 56 * and interrupt handlers installed. 57 * 58 * @kbdev: The kbase device structure for the device (must be a valid pointer) 59 * @flags: Flags to pass on to kbase_pm_init_hw 60 * 61 * Return: 0 if powerup was successful. 62 */ 63 int kbase_pm_powerup(struct kbase_device *kbdev, unsigned int flags); 64 65 /** 66 * kbase_pm_halt - Halt the power management framework. 67 * 68 * @kbdev: The kbase device structure for the device (must be a valid pointer) 69 * 70 * Should ensure that no new interrupts are generated, 71 * but allow any currently running interrupt handlers to complete successfully. 72 * The GPU is forced off by the time this function returns, regardless of 73 * whether or not the active power policy asks for the GPU to be powered off. 74 */ 75 void kbase_pm_halt(struct kbase_device *kbdev); 76 77 /** 78 * kbase_pm_term - Terminate the power management framework. 79 * 80 * @kbdev: The kbase device structure for the device (must be a valid pointer) 81 * 82 * No power management functions may be called after this 83 * (except @ref kbase_pm_init) 84 */ 85 void kbase_pm_term(struct kbase_device *kbdev); 86 87 /** 88 * kbase_pm_context_active - Increment the count of active contexts. 89 * 90 * @kbdev: The kbase device structure for the device (must be a valid pointer) 91 * 92 * This function should be called when a context is about to submit a job. 93 * It informs the active power policy that the GPU is going to be in use shortly 94 * and the policy is expected to start turning on the GPU. 95 * 96 * This function will block until the GPU is available. 97 * 98 * This function ASSERTS if a suspend is occuring/has occurred whilst this is 99 * in use. Use kbase_pm_contect_active_unless_suspending() instead. 100 * 101 * @note a Suspend is only visible to Kernel threads; user-space threads in a 102 * syscall cannot witness a suspend, because they are frozen before the suspend 103 * begins. 104 */ 105 void kbase_pm_context_active(struct kbase_device *kbdev); 106 107 108 /** Handler codes for doing kbase_pm_context_active_handle_suspend() */ 109 enum kbase_pm_suspend_handler { 110 /** A suspend is not expected/not possible - this is the same as 111 * kbase_pm_context_active() 112 */ 113 KBASE_PM_SUSPEND_HANDLER_NOT_POSSIBLE, 114 /** If we're suspending, fail and don't increase the active count */ 115 KBASE_PM_SUSPEND_HANDLER_DONT_INCREASE, 116 /** If we're suspending, succeed and allow the active count to increase 117 * if it didn't go from 0->1 (i.e., we didn't re-activate the GPU). 118 * 119 * This should only be used when there is a bounded time on the activation 120 * (e.g. guarantee it's going to be idled very soon after) 121 */ 122 KBASE_PM_SUSPEND_HANDLER_DONT_REACTIVATE, 123 #ifdef CONFIG_MALI_ARBITER_SUPPORT 124 /** Special case when Arbiter has notified we can use GPU. 125 * Active count should always start at 0 in this case. 126 */ 127 KBASE_PM_SUSPEND_HANDLER_VM_GPU_GRANTED, 128 #endif /* CONFIG_MALI_ARBITER_SUPPORT */ 129 }; 130 131 /** 132 * kbase_pm_context_active_handle_suspend - Suspend 'safe' variant of kbase_pm_context_active() 133 * 134 * @kbdev: The kbase device structure for the device (must be a valid pointer) 135 * @suspend_handler: The handler code for how to handle a suspend that might occur 136 * 137 * If a suspend is in progress, this allows for various different ways of 138 * handling the suspend. Refer to @ref enum kbase_pm_suspend_handler for details. 139 * 140 * We returns a status code indicating whether we're allowed to keep the GPU 141 * active during the suspend, depending on the handler code. If the status code 142 * indicates a failure, the caller must abort whatever operation it was 143 * attempting, and potentially queue it up for after the OS has resumed. 144 * 145 * Return: 0 on success, non-zero othrewise. 146 */ 147 int kbase_pm_context_active_handle_suspend(struct kbase_device *kbdev, enum kbase_pm_suspend_handler suspend_handler); 148 149 /** 150 * kbase_pm_context_idle - Decrement the reference count of active contexts. 151 * 152 * @kbdev: The kbase device structure for the device (must be a valid pointer) 153 * 154 * This function should be called when a context becomes idle. 155 * After this call the GPU may be turned off by the power policy so the calling 156 * code should ensure that it does not access the GPU's registers. 157 */ 158 void kbase_pm_context_idle(struct kbase_device *kbdev); 159 160 /* NOTE: kbase_pm_is_active() is in mali_kbase.h, because it is an inline 161 * function 162 */ 163 164 /** 165 * kbase_pm_suspend - Suspend the GPU and prevent any further register accesses 166 * to it from Kernel threads. 167 * 168 * @kbdev: The kbase device structure for the device (must be a valid pointer) 169 * 170 * This is called in response to an OS suspend event, and calls into the various 171 * kbase components to complete the suspend. 172 * 173 * @note the mechanisms used here rely on all user-space threads being frozen 174 * by the OS before we suspend. Otherwise, an IOCTL could occur that powers up 175 * the GPU e.g. via atom submission. 176 * 177 * Return: 0 on success. 178 */ 179 int kbase_pm_suspend(struct kbase_device *kbdev); 180 181 /** 182 * kbase_pm_resume - Resume the GPU, allow register accesses to it, 183 * and resume running atoms on the GPU. 184 * 185 * @kbdev: The kbase device structure for the device (must be a valid pointer) 186 * 187 * This is called in response to an OS resume event, and calls into the various 188 * kbase components to complete the resume. 189 * 190 * Also called when using VM arbiter, when GPU access has been granted. 191 */ 192 void kbase_pm_resume(struct kbase_device *kbdev); 193 194 /** 195 * kbase_pm_vsync_callback - vsync callback 196 * 197 * @buffer_updated: 1 if a new frame was displayed, 0 otherwise 198 * @data: Pointer to the kbase device as returned by kbase_find_device() 199 * 200 * Callback function used to notify the power management code that a vsync has 201 * occurred on the display. 202 */ 203 void kbase_pm_vsync_callback(int buffer_updated, void *data); 204 205 /** 206 * kbase_pm_driver_suspend() - Put GPU and driver in suspend state 207 * @kbdev: The kbase device structure for the device (must be a valid pointer) 208 * 209 * Suspend the GPU and prevent any further register accesses to it from Kernel 210 * threads. 211 * 212 * This is called in response to an OS suspend event, and calls into the various 213 * kbase components to complete the suspend. 214 * 215 * Despite kbase_pm_suspend(), it will ignore to update Arbiter 216 * status if MALI_ARBITER_SUPPORT is enabled. 217 * 218 * @note the mechanisms used here rely on all user-space threads being frozen 219 * by the OS before we suspend. Otherwise, an IOCTL could occur that powers up 220 * the GPU e.g. via atom submission. 221 * 222 * Return: 0 on success. 223 */ 224 int kbase_pm_driver_suspend(struct kbase_device *kbdev); 225 226 /** 227 * kbase_pm_driver_resume() - Put GPU and driver in resume 228 * @kbdev: The kbase device structure for the device (must be a valid pointer) 229 * @arb_gpu_start: Arbiter has notified we can use GPU 230 * 231 * Resume the GPU, allow register accesses to it, and resume running atoms on 232 * the GPU. 233 * 234 * This is called in response to an OS resume event, and calls into the various 235 * kbase components to complete the resume. 236 * 237 * Also called when using VM arbiter, when GPU access has been granted. 238 * 239 * Despite kbase_pm_resume(), it will ignore to update Arbiter 240 * status if MALI_ARBITER_SUPPORT is enabled. 241 */ 242 void kbase_pm_driver_resume(struct kbase_device *kbdev, bool arb_gpu_start); 243 244 #ifdef CONFIG_MALI_ARBITER_SUPPORT 245 /** 246 * kbase_pm_handle_gpu_lost() - Handle GPU Lost for the VM 247 * @kbdev: Device pointer 248 * 249 * Handles the case that the Arbiter has forced the GPU away from the VM, 250 * so that interrupts will not be received and registers are no longer 251 * accessible because replaced by dummy RAM. 252 * Kill any running tasks and put the driver into a GPU powered-off state. 253 */ 254 void kbase_pm_handle_gpu_lost(struct kbase_device *kbdev); 255 #endif /* CONFIG_MALI_ARBITER_SUPPORT */ 256 257 #endif /* _KBASE_PM_H_ */ 258