1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2010-2017, 2019-2021 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: Configuration API and Attributes for KBase 24 */ 25 26 #ifndef _KBASE_CONFIG_H_ 27 #define _KBASE_CONFIG_H_ 28 29 #include <linux/mm.h> 30 #include <mali_malisw.h> 31 #include <backend/gpu/mali_kbase_backend_config.h> 32 #include <linux/rbtree.h> 33 34 /* Forward declaration of struct kbase_device */ 35 struct kbase_device; 36 37 #if !MALI_USE_CSF 38 /* Forward declaration of struct kbase_context */ 39 struct kbase_context; 40 41 /* Forward declaration of struct kbase_atom */ 42 struct kbase_jd_atom; 43 #endif 44 45 /** 46 * struct kbase_platform_funcs_conf - Specifies platform integration function 47 * pointers for DDK events such as device init and term. 48 * 49 * Specifies the functions pointers for platform specific initialization and 50 * termination as well as other events. By default no functions are required. 51 * No additional platform specific control is necessary. 52 */ 53 struct kbase_platform_funcs_conf { 54 /** 55 * @platform_init_func: platform specific init function pointer 56 * @kbdev - kbase_device pointer 57 * 58 * Returns 0 on success, negative error code otherwise. 59 * 60 * Function pointer for platform specific initialization or NULL if no 61 * initialization function is required. At the point this the GPU is 62 * not active and its power and clocks are in unknown (platform specific 63 * state) as kbase doesn't yet have control of power and clocks. 64 * 65 * The platform specific private pointer kbase_device::platform_context 66 * can be accessed (and possibly initialized) in here. 67 */ 68 int (*platform_init_func)(struct kbase_device *kbdev); 69 /** 70 * @platform_term_func: platform specific termination function pointer 71 * @kbdev - kbase_device pointer 72 * 73 * Function pointer for platform specific termination or NULL if no 74 * termination function is required. At the point this the GPU will be 75 * idle but still powered and clocked. 76 * 77 * The platform specific private pointer kbase_device::platform_context 78 * can be accessed (and possibly terminated) in here. 79 */ 80 void (*platform_term_func)(struct kbase_device *kbdev); 81 82 /** 83 * @platform_late_init_func: platform specific late init function pointer 84 * @kbdev - kbase_device pointer 85 * 86 * Function pointer to inform that the kbase driver initialization completed 87 * or NULL if no such function is required. At this point the GPU driver will be 88 * fully initialized. 89 * 90 * The platform specific private pointer kbase_device::platform_context 91 * can be accessed (and possibly terminated) in here. 92 */ 93 int (*platform_late_init_func)(struct kbase_device *kbdev); 94 95 /** 96 * @platform_late_term_func: platform specific late termination function pointer 97 * @kbdev - kbase_device pointer 98 * 99 * Function pointer for platform specific termination or NULL if no 100 * termination function is required. At this point the GPU driver will complete 101 * termination process 102 * 103 * The platform specific private pointer kbase_device::platform_context 104 * can be accessed (and possibly terminated) in here. 105 */ 106 void (*platform_late_term_func)(struct kbase_device *kbdev); 107 108 #if !MALI_USE_CSF 109 /** 110 * @platform_handler_context_init_func: platform specific handler for 111 * when a new kbase_context is created. 112 * @kctx - kbase_context pointer 113 * 114 * Returns 0 on success, negative error code otherwise. 115 * 116 * Function pointer for platform specific initialization of a kernel 117 * context or NULL if not required. Called at the last stage of kernel 118 * context initialization. 119 */ 120 int (*platform_handler_context_init_func)(struct kbase_context *kctx); 121 /** 122 * @platform_handler_context_term_func: platform specific handler for 123 * when a kbase_context is terminated. 124 * @kctx - kbase_context pointer 125 * 126 * Function pointer for platform specific termination of a kernel 127 * context or NULL if not required. Called at the first stage of kernel 128 * context termination. 129 */ 130 void (*platform_handler_context_term_func)(struct kbase_context *kctx); 131 /** 132 * @platform_handler_atom_submit_func: platform specific handler for 133 * when a kbase_jd_atom is submitted. 134 * @katom - kbase_jd_atom pointer 135 * 136 * Function pointer for platform specific handling at the point when an 137 * atom is submitted to the GPU or set to NULL if not required. The 138 * function cannot assume that it is running in a process context. 139 * 140 * Context: The caller must hold the hwaccess_lock. Function must be 141 * runnable in an interrupt context. 142 */ 143 void (*platform_handler_atom_submit_func)(struct kbase_jd_atom *katom); 144 /** 145 * @platform_handler_atom_complete_func: platform specific handler for 146 * when a kbase_jd_atom completes. 147 * @katom - kbase_jd_atom pointer 148 * 149 * Function pointer for platform specific handling at the point when an 150 * atom stops running on the GPU or set to NULL if not required. The 151 * function cannot assume that it is running in a process context. 152 * 153 * Context: The caller must hold the hwaccess_lock. Function must be 154 * runnable in an interrupt context. 155 */ 156 void (*platform_handler_atom_complete_func)( 157 struct kbase_jd_atom *katom); 158 #endif 159 }; 160 161 /* 162 * @brief Specifies the callbacks for power management 163 * 164 * By default no callbacks will be made and the GPU must not be powered off. 165 */ 166 struct kbase_pm_callback_conf { 167 /** Callback for when the GPU is idle and the power to it can be switched off. 168 * 169 * The system integrator can decide whether to either do nothing, just switch off 170 * the clocks to the GPU, or to completely power down the GPU. 171 * The platform specific private pointer kbase_device::platform_context can be accessed and modified in here. It is the 172 * platform \em callbacks responsibility to initialize and terminate this pointer if used (see @ref kbase_platform_funcs_conf). 173 * 174 * If runtime PM is enabled and @power_runtime_gpu_idle_callback is used 175 * then this callback should power off the GPU (or switch off the clocks 176 * to GPU) immediately. If @power_runtime_gpu_idle_callback is not used, 177 * then this callback can set the autosuspend timeout (if desired) and 178 * let the GPU be powered down later. 179 */ 180 void (*power_off_callback)(struct kbase_device *kbdev); 181 182 /** Callback for when the GPU is about to become active and power must be supplied. 183 * 184 * This function must not return until the GPU is powered and clocked sufficiently for register access to 185 * succeed. The return value specifies whether the GPU was powered down since the call to power_off_callback. 186 * If the GPU state has been lost then this function must return 1, otherwise it should return 0. 187 * The platform specific private pointer kbase_device::platform_context can be accessed and modified in here. It is the 188 * platform \em callbacks responsibility to initialize and terminate this pointer if used (see @ref kbase_platform_funcs_conf). 189 * 190 * The return value of the first call to this function is ignored. 191 * 192 * @return 1 if the GPU state may have been lost, 0 otherwise. 193 */ 194 int (*power_on_callback)(struct kbase_device *kbdev); 195 196 /** Callback for when the system is requesting a suspend and GPU power 197 * must be switched off. 198 * 199 * Note that if this callback is present, then this may be called 200 * without a preceding call to power_off_callback. Therefore this 201 * callback must be able to take any action that might otherwise happen 202 * in power_off_callback. 203 * 204 * The platform specific private pointer kbase_device::platform_context 205 * can be accessed and modified in here. It is the platform \em 206 * callbacks responsibility to initialize and terminate this pointer if 207 * used (see @ref kbase_platform_funcs_conf). 208 */ 209 void (*power_suspend_callback)(struct kbase_device *kbdev); 210 211 /** Callback for when the system is resuming from a suspend and GPU 212 * power must be switched on. 213 * 214 * Note that if this callback is present, then this may be called 215 * without a following call to power_on_callback. Therefore this 216 * callback must be able to take any action that might otherwise happen 217 * in power_on_callback. 218 * 219 * The platform specific private pointer kbase_device::platform_context 220 * can be accessed and modified in here. It is the platform \em 221 * callbacks responsibility to initialize and terminate this pointer if 222 * used (see @ref kbase_platform_funcs_conf). 223 */ 224 void (*power_resume_callback)(struct kbase_device *kbdev); 225 226 /** Callback for handling runtime power management initialization. 227 * 228 * The runtime power management callbacks @ref power_runtime_off_callback and @ref power_runtime_on_callback 229 * will become active from calls made to the OS from within this function. 230 * The runtime calls can be triggered by calls from @ref power_off_callback and @ref power_on_callback. 231 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature. 232 * 233 * @return 0 on success, else int error code. 234 */ 235 int (*power_runtime_init_callback)(struct kbase_device *kbdev); 236 237 /** Callback for handling runtime power management termination. 238 * 239 * The runtime power management callbacks @ref power_runtime_off_callback and @ref power_runtime_on_callback 240 * should no longer be called by the OS on completion of this function. 241 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature. 242 */ 243 void (*power_runtime_term_callback)(struct kbase_device *kbdev); 244 245 /** Callback for runtime power-off power management callback 246 * 247 * For linux this callback will be called by the kernel runtime_suspend callback. 248 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature. 249 * 250 * @return 0 on success, else OS error code. 251 */ 252 void (*power_runtime_off_callback)(struct kbase_device *kbdev); 253 254 /** Callback for runtime power-on power management callback 255 * 256 * For linux this callback will be called by the kernel runtime_resume callback. 257 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature. 258 */ 259 int (*power_runtime_on_callback)(struct kbase_device *kbdev); 260 261 /* 262 * Optional callback for checking if GPU can be suspended when idle 263 * 264 * This callback will be called by the runtime power management core 265 * when the reference count goes to 0 to provide notification that the 266 * GPU now seems idle. 267 * 268 * If this callback finds that the GPU can't be powered off, or handles 269 * suspend by powering off directly or queueing up a power off, a 270 * non-zero value must be returned to prevent the runtime PM core from 271 * also triggering a suspend. 272 * 273 * Returning 0 will cause the runtime PM core to conduct a regular 274 * autosuspend. 275 * 276 * This callback is optional and if not provided regular autosuspend 277 * will be triggered. 278 * 279 * Note: The Linux kernel must have CONFIG_PM_RUNTIME enabled to use 280 * this feature. 281 * 282 * Return 0 if GPU can be suspended, positive value if it can not be 283 * suspeneded by runtime PM, else OS error code 284 */ 285 int (*power_runtime_idle_callback)(struct kbase_device *kbdev); 286 287 /* 288 * Optional callback for software reset 289 * 290 * This callback will be called by the power management core to trigger 291 * a GPU soft reset. 292 * 293 * Return 0 if the soft reset was successful and the RESET_COMPLETED 294 * interrupt will be raised, or a positive value if the interrupt won't 295 * be raised. On error, return the corresponding OS error code. 296 */ 297 int (*soft_reset_callback)(struct kbase_device *kbdev); 298 299 /* 300 * Optional callback invoked after GPU becomes idle, not supported on 301 * JM GPUs. 302 * 303 * This callback will be invoked by the Kbase when GPU becomes idle. 304 * For JM GPUs or when runtime PM is disabled, Kbase will not invoke 305 * this callback and @power_off_callback will be invoked directly. 306 * 307 * This callback is supposed to decrement the runtime PM core reference 308 * count to zero and trigger the auto-suspend timer, which implies that 309 * @power_off_callback shouldn't initiate the runtime suspend. 310 * 311 * GPU registers still remain accessible until @power_off_callback gets 312 * invoked later on the expiry of auto-suspend timer. 313 * 314 * Note: The Linux kernel must have CONFIG_PM_RUNTIME enabled to use 315 * this feature. 316 */ 317 void (*power_runtime_gpu_idle_callback)(struct kbase_device *kbdev); 318 319 /* 320 * Optional callback invoked to change the runtime PM core state to 321 * active. 322 * 323 * This callback will be invoked by Kbase when GPU needs to be 324 * reactivated, but only if @power_runtime_gpu_idle_callback was invoked 325 * previously. So both @power_runtime_gpu_idle_callback and this 326 * callback needs to be implemented at the same time. 327 * 328 * Kbase will invoke @power_on_callback first before invoking this 329 * callback if the GPU was powered down previously, otherwise directly. 330 * 331 * This callback is supposed to increment the runtime PM core reference 332 * count to 1, which implies that @power_on_callback shouldn't initiate 333 * the runtime resume. The runtime resume may not happen synchronously 334 * to avoid a potential deadlock due to the runtime suspend happening 335 * simultaneously from some other thread. 336 * 337 * Note: The Linux kernel must have CONFIG_PM_RUNTIME enabled to use 338 * this feature. 339 */ 340 void (*power_runtime_gpu_active_callback)(struct kbase_device *kbdev); 341 }; 342 343 /* struct kbase_gpu_clk_notifier_data - Data for clock rate change notifier. 344 * 345 * Pointer to this structure is supposed to be passed to the gpu clock rate 346 * change notifier function. This structure is deliberately aligned with the 347 * common clock framework notification structure 'struct clk_notifier_data' 348 * and such alignment should be maintained. 349 * 350 * @gpu_clk_handle: Handle of the GPU clock for which notifier was registered. 351 * @old_rate: Previous rate of this GPU clock in Hz. 352 * @new_rate: New rate of this GPU clock in Hz. 353 */ 354 struct kbase_gpu_clk_notifier_data { 355 void *gpu_clk_handle; 356 unsigned long old_rate; 357 unsigned long new_rate; 358 }; 359 360 /** 361 * struct kbase_clk_rate_trace_op_conf - Specifies GPU clock rate trace 362 * operations. 363 * 364 * Specifies the functions pointers for platform specific GPU clock rate trace 365 * operations. By default no functions are required. 366 */ 367 struct kbase_clk_rate_trace_op_conf { 368 /** 369 * @enumerate_gpu_clk: Enumerate a GPU clock on the given index 370 * @kbdev - kbase_device pointer 371 * @index - GPU clock index 372 * 373 * Returns a handle unique to the given GPU clock, or NULL if the clock 374 * array has been exhausted at the given index value. 375 * 376 * Kbase will use this function pointer to enumerate the existence of a 377 * GPU clock on the given index. 378 */ 379 void *(*enumerate_gpu_clk)(struct kbase_device *kbdev, 380 unsigned int index); 381 382 /** 383 * @get_gpu_clk_rate: Get the current rate for an enumerated clock. 384 * @kbdev - kbase_device pointer 385 * @gpu_clk_handle - Handle unique to the enumerated GPU clock 386 * 387 * Returns current rate of the GPU clock in unit of Hz. 388 */ 389 unsigned long (*get_gpu_clk_rate)(struct kbase_device *kbdev, 390 void *gpu_clk_handle); 391 392 /** 393 * @gpu_clk_notifier_register: Register a clock rate change notifier. 394 * @kbdev - kbase_device pointer 395 * @gpu_clk_handle - Handle unique to the enumerated GPU clock 396 * @nb - notifier block containing the callback function 397 * pointer 398 * 399 * Returns 0 on success, negative error code otherwise. 400 * 401 * This function pointer is used to register a callback function that 402 * is supposed to be invoked whenever the rate of clock corresponding 403 * to @gpu_clk_handle changes. 404 * @nb contains the pointer to callback function. 405 * The callback function expects the pointer of type 406 * 'struct kbase_gpu_clk_notifier_data' as the third argument. 407 */ 408 int (*gpu_clk_notifier_register)(struct kbase_device *kbdev, 409 void *gpu_clk_handle, struct notifier_block *nb); 410 411 /** 412 * @gpu_clk_notifier_unregister: Unregister clock rate change notifier 413 * @kbdev - kbase_device pointer 414 * @gpu_clk_handle - Handle unique to the enumerated GPU clock 415 * @nb - notifier block containing the callback function 416 * pointer 417 * 418 * This function pointer is used to unregister a callback function that 419 * was previously registered to get notified of the change in rate 420 * of clock corresponding to @gpu_clk_handle. 421 */ 422 void (*gpu_clk_notifier_unregister)(struct kbase_device *kbdev, 423 void *gpu_clk_handle, struct notifier_block *nb); 424 }; 425 426 #if IS_ENABLED(CONFIG_OF) 427 struct kbase_platform_config { 428 }; 429 #else 430 431 /* 432 * @brief Specifies start and end of I/O memory region. 433 */ 434 struct kbase_io_memory_region { 435 u64 start; 436 u64 end; 437 }; 438 439 /* 440 * @brief Specifies I/O related resources like IRQs and memory region for I/O operations. 441 */ 442 struct kbase_io_resources { 443 u32 job_irq_number; 444 u32 mmu_irq_number; 445 u32 gpu_irq_number; 446 struct kbase_io_memory_region io_memory_region; 447 }; 448 449 struct kbase_platform_config { 450 const struct kbase_io_resources *io_resources; 451 }; 452 453 #endif /* CONFIG_OF */ 454 455 /** 456 * kbase_get_platform_config - Gets the pointer to platform config. 457 * 458 * @return Pointer to the platform config 459 */ 460 struct kbase_platform_config *kbase_get_platform_config(void); 461 462 /** 463 * kbasep_platform_device_init: - Platform specific call to initialize hardware 464 * @kbdev: kbase device pointer 465 * 466 * Function calls a platform defined routine if specified in the configuration 467 * attributes. The routine can initialize any hardware and context state that 468 * is required for the GPU block to function. 469 * 470 * Return: 0 if no errors have been found in the config. 471 * Negative error code otherwise. 472 */ 473 int kbasep_platform_device_init(struct kbase_device *kbdev); 474 475 /** 476 * kbasep_platform_device_term - Platform specific call to terminate hardware 477 * @kbdev: Kbase device pointer 478 * 479 * Function calls a platform defined routine if specified in the configuration 480 * attributes. The routine can destroy any platform specific context state and 481 * shut down any hardware functionality that are outside of the Power Management 482 * callbacks. 483 * 484 */ 485 void kbasep_platform_device_term(struct kbase_device *kbdev); 486 487 /** 488 * kbasep_platform_device_late_init: - Platform specific call to finish hardware 489 * initialization 490 * @kbdev: kbase device pointer 491 * 492 * Function calls a platform defined routine if specified in the configuration 493 * attributes. The routine can initialize any hardware and context state that 494 * is required for the GPU block to function. 495 * 496 * Return: 0 if no errors have been found in the config. 497 * Negative error code otherwise. 498 */ 499 int kbasep_platform_device_late_init(struct kbase_device *kbdev); 500 501 /** 502 * kbasep_platform_device_late_term - Platform specific call to finish hardware 503 * termination 504 * @kbdev: Kbase device pointer 505 * 506 * Function calls a platform defined routine if specified in the configuration 507 * attributes. The routine can destroy any platform specific context state and 508 * shut down any hardware functionality that are outside of the Power Management 509 * callbacks. 510 * 511 */ 512 void kbasep_platform_device_late_term(struct kbase_device *kbdev); 513 514 #if !MALI_USE_CSF 515 /** 516 * kbasep_platform_context_init - Platform specific callback when a kernel 517 * context is created 518 * @kctx: kbase_context pointer 519 * 520 * Function calls a platform defined routine if specified in the configuration 521 * attributes. The routine can initialize any per kernel context structures 522 * that are required for the GPU block to function. 523 * 524 * Return: 0 if no errors were encountered. Negative error code otherwise. 525 */ 526 int kbasep_platform_context_init(struct kbase_context *kctx); 527 528 /** 529 * kbasep_platform_context_term - Platform specific callback when a kernel 530 * context is terminated 531 * @kctx: kbase_context pointer 532 * 533 * Function calls a platform defined routine if specified in the configuration 534 * attributes. The routine should terminate any per kernel context structures 535 * created as part of &kbasep_platform_context_init. 536 * 537 */ 538 void kbasep_platform_context_term(struct kbase_context *kctx); 539 540 /** 541 * kbasep_platform_event_atom_submit - Platform specific callback when an atom 542 * is submitted to the GPU 543 * @katom: kbase_jd_atom pointer 544 * 545 * Function calls a platform defined routine if specified in the configuration 546 * attributes. The routine should not assume that it is in a process context. 547 * 548 * Return: 0 if no errors were encountered. Negative error code otherwise. 549 */ 550 void kbasep_platform_event_atom_submit(struct kbase_jd_atom *katom); 551 552 /** 553 * kbasep_platform_event_atom_complete - Platform specific callback when an atom 554 * has stopped running on the GPU 555 * @katom: kbase_jd_atom pointer 556 * 557 * Function calls a platform defined routine if specified in the configuration 558 * attributes. The routine should not assume that it is in a process context. 559 * 560 */ 561 void kbasep_platform_event_atom_complete(struct kbase_jd_atom *katom); 562 #endif 563 564 #ifndef CONFIG_OF 565 /** 566 * kbase_platform_register - Register a platform device for the GPU 567 * 568 * This can be used to register a platform device on systems where device tree 569 * is not enabled and the platform initialisation code in the kernel doesn't 570 * create the GPU device. Where possible device tree should be used instead. 571 * 572 * Return: 0 for success, any other fail causes module initialisation to fail 573 */ 574 int kbase_platform_register(void); 575 576 /** 577 * kbase_platform_unregister - Unregister a fake platform device 578 * 579 * Unregister the platform device created with kbase_platform_register() 580 */ 581 void kbase_platform_unregister(void); 582 #endif 583 584 #endif /* _KBASE_CONFIG_H_ */ 585