drivers/gpu/arm/midgard/mali_kbase_config.h

   1 /*
   2  *
   3  * (C) COPYRIGHT ARM Limited. All rights reserved.
   4  *
   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
   8  * of such GNU licence.
   9  *
  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.
  13  *
  14  */
  15
  16
  17
  18
  19
  20 /**
  21  * @file mali_kbase_config.h
  22  * Configuration API and Attributes for KBase
  23  */
  24
  25 #ifndef _KBASE_CONFIG_H_
  26 #define _KBASE_CONFIG_H_
  27
  28 #include <malisw/mali_stdtypes.h>
  29
  30 /**
  31  * @addtogroup base_api
  32  * @{
  33  */
  34
  35 /**
  36  * @addtogroup base_kbase_api
  37  * @{
  38  */
  39
  40 /**
  41  * @addtogroup kbase_config Configuration API and Attributes
  42  * @{
  43  */
  44
  45 #if MALI_CUSTOMER_RELEASE == 0
  46 /* This flag is set for internal builds so we can run tests without credentials. */
  47 #define KBASE_HWCNT_DUMP_BYPASS_ROOT 1
  48 #else
  49 #define KBASE_HWCNT_DUMP_BYPASS_ROOT 0
  50 #endif
  51
  52 #include <linux/rbtree.h>
  53
  54 /**
  55  * Device wide configuration
  56  */
  57 enum {
  58         /**
  59          * Invalid attribute ID (reserve 0).
  60          *
  61          * Attached value: Ignored
  62          * Default value: NA
  63          * */
  64         KBASE_CONFIG_ATTR_INVALID,
  65
  66         /**
  67          * Maximum frequency GPU will be clocked at. Given in kHz.
  68          * This must be specified as there is no default value.
  69          *
  70          * Attached value: number in kHz
  71          * Default value: NA
  72          */
  73         KBASE_CONFIG_ATTR_GPU_FREQ_KHZ_MAX,
  74
  75         /**
  76          * Minimum frequency GPU will be clocked at. Given in kHz.
  77          * This must be specified as there is no default value.
  78          *
  79          * Attached value: number in kHz
  80          * Default value: NA
  81          */
  82         KBASE_CONFIG_ATTR_GPU_FREQ_KHZ_MIN,
  83
  84         /**
  85          * Irq throttle. It is the minimum desired time in between two
  86          * consecutive gpu interrupts (given in 'us'). The irq throttle
  87          * gpu register will be configured after this, taking into
  88          * account the configured max frequency.
  89          *
  90          * Attached value: number in micro seconds
  91          * Default value: see DEFAULT_IRQ_THROTTLE_TIME_US
  92          */
  93         KBASE_CONFIG_ATTR_GPU_IRQ_THROTTLE_TIME_US,
  94
  95         /*** Begin Job Scheduling Configs ***/
  96         /**
  97          * Job Scheduler scheduling tick granuality. This is in nanoseconds to
  98          * allow HR timer support.
  99          *
 100          * On each scheduling tick, the scheduler may decide to:
 101          * -# soft stop a job (the job will be re-run later, and other jobs will
 102          * be able to run on the GPU now). This effectively controls the
 103          * 'timeslice' given to a job.
 104          * -# hard stop a job (to kill a job if it has spent too long on the GPU
 105          * and didn't soft-stop).
 106          *
 107          * The numbers of ticks for these events are controlled by:
 108          * - @ref KBASE_CONFIG_ATTR_JS_SOFT_STOP_TICKS
 109          * - @ref KBASE_CONFIG_ATTR_JS_HARD_STOP_TICKS_SS
 110          * - @ref KBASE_CONFIG_ATTR_JS_HARD_STOP_TICKS_NSS
 111          *
 112          * A soft-stopped job will later be resumed, allowing it to use more GPU
 113          * time <em>in total</em> than that defined by any of the above. However,
 114          * the scheduling policy attempts to limit the amount of \em uninterrupted
 115          * time spent on the GPU using the above values (that is, the 'timeslice'
 116          * of a job)
 117          *
 118          * This value is supported by the following scheduling policies:
 119          * - The Completely Fair Share (CFS) policy
 120          *
 121          * Attached value: unsigned 32-bit kbasep_js_device_data::scheduling_tick_ns.
 122          * The value might be rounded down to lower precision. Must be non-zero
 123          * after rounding.<br>
 124          * Default value: @ref DEFAULT_JS_SCHEDULING_TICK_NS
 125          *
 126          * @note this value is allowed to be greater than
 127          * @ref KBASE_CONFIG_ATTR_JS_CTX_TIMESLICE_NS. This allows jobs to run on (much)
 128          * longer than the job-timeslice, but once this happens, the context gets
 129          * scheduled in (much) less frequently than others that stay within the
 130          * ctx-timeslice.
 131          */
 132         KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS,
 133
 134         /**
 135          * Job Scheduler minimum number of scheduling ticks before non-CL jobs
 136          * are soft-stopped.
 137          *
 138          * This defines the amount of time a job is allowed to stay on the GPU,
 139          * before it is soft-stopped to allow other jobs to run.
 140          *
 141          * That is, this defines the 'timeslice' of the job. It is separate from the
 142          * timeslice of the context that contains the job (see
 143          * @ref KBASE_CONFIG_ATTR_JS_CTX_TIMESLICE_NS).
 144          *
 145          * This value is supported by the following scheduling policies:
 146          * - The Completely Fair Share (CFS) policy
 147          *
 148          * Attached value: unsigned 32-bit kbasep_js_device_data::soft_stop_ticks<br>
 149          * Default value: @ref DEFAULT_JS_SOFT_STOP_TICKS
 150          *
 151          * @note a value of zero means "the quickest time to soft-stop a job",
 152          * which is somewhere between instant and one tick later.
 153          *
 154          * @note this value is allowed to be greater than
 155          * @ref KBASE_CONFIG_ATTR_JS_RESET_TICKS_SS or
 156          * @ref KBASE_CONFIG_ATTR_JS_RESET_TICKS_NSS. This effectively disables
 157          * soft-stop, and just uses hard-stop instead. In this case, this value
 158          * should be much greater than any of the hard stop values (to avoid
 159          * soft-stop-after-hard-stop)
 160          *
 161          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 162          */
 163         KBASE_CONFIG_ATTR_JS_SOFT_STOP_TICKS,
 164
 165         /**
 166          * Job Scheduler minimum number of scheduling ticks before CL jobs
 167          * are soft-stopped.
 168          *
 169          * This defines the amount of time a job is allowed to stay on the GPU,
 170          * before it is soft-stopped to allow other jobs to run.
 171          *
 172          * That is, this defines the 'timeslice' of the job. It is separate
 173          * from the timeslice of the context that contains the job (see
 174          * @ref KBASE_CONFIG_ATTR_JS_CTX_TIMESLICE_NS).
 175          *
 176          * This value is supported by the following scheduling policies:
 177          * - The Completely Fair Share (CFS) policy
 178          *
 179          * Attached value: unsigned 32-bit
 180          *                         kbasep_js_device_data::soft_stop_ticks_cl<br>
 181          * Default value: @ref DEFAULT_JS_SOFT_STOP_TICKS_CL
 182          *
 183          * @note a value of zero means "the quickest time to soft-stop a job",
 184          * which is somewhere between instant and one tick later.
 185          *
 186          * @note this value is allowed to be greater than
 187          * @ref KBASE_CONFIG_ATTR_JS_RESET_TICKS_CL. This effectively
 188          * disables soft-stop, and just uses hard-stop instead. In this case,
 189          * this value should be much greater than any of the hard stop values
 190          * (to avoid soft-stop-after-hard-stop)
 191          *
 192          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 193          */
 194         KBASE_CONFIG_ATTR_JS_SOFT_STOP_TICKS_CL,
 195
 196         /**
 197          * Job Scheduler minimum number of scheduling ticks before non-CL jobs
 198          * are hard-stopped.
 199          *
 200          * This defines the amount of time a job is allowed to spend on the GPU before it
 201          * is killed. Such jobs won't be resumed if killed.
 202          *
 203          * This value is supported by the following scheduling policies:
 204          * - The Completely Fair Share (CFS) policy
 205          *
 206          * Attached value: unsigned 32-bit kbasep_js_device_data::hard_stop_ticks_ss<br>
 207          * Default value: @ref DEFAULT_JS_HARD_STOP_TICKS_SS
 208          *
 209          * @note a value of zero means "the quickest time to hard-stop a job",
 210          * which is somewhere between instant and one tick later.
 211          *
 212          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 213          */
 214         KBASE_CONFIG_ATTR_JS_HARD_STOP_TICKS_SS,
 215
 216         /**
 217          * Job Scheduler minimum number of scheduling ticks before CL jobs are hard-stopped.
 218          *
 219          * This defines the amount of time a job is allowed to spend on the GPU before it
 220          * is killed. Such jobs won't be resumed if killed.
 221          *
 222          * This value is supported by the following scheduling policies:
 223          * - The Completely Fair Share (CFS) policy
 224          *
 225          * Attached value: unsigned 32-bit kbasep_js_device_data::hard_stop_ticks_cl<br>
 226          * Default value: @ref DEFAULT_JS_HARD_STOP_TICKS_CL
 227          *
 228          * @note a value of zero means "the quickest time to hard-stop a job",
 229          * which is somewhere between instant and one tick later.
 230          *
 231          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 232          */
 233         KBASE_CONFIG_ATTR_JS_HARD_STOP_TICKS_CL,
 234
 235         /**
 236          * Job Scheduler minimum number of scheduling ticks before jobs are hard-stopped
 237          * when dumping.
 238          *
 239          * This defines the amount of time a job is allowed to spend on the GPU before it
 240          * is killed. Such jobs won't be resumed if killed.
 241          *
 242          * This value is supported by the following scheduling policies:
 243          * - The Completely Fair Share (CFS) policy
 244          *
 245          * Attached value: unsigned 32-bit kbasep_js_device_data::hard_stop_ticks_nss<br>
 246          * Default value: @ref DEFAULT_JS_HARD_STOP_TICKS_NSS
 247          *
 248          * @note a value of zero means "the quickest time to hard-stop a job",
 249          * which is somewhere between instant and one tick later.
 250          *
 251          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 252          */
 253         KBASE_CONFIG_ATTR_JS_HARD_STOP_TICKS_NSS,
 254
 255         /**
 256          * Job Scheduler timeslice that a context is scheduled in for, in nanoseconds.
 257          *
 258          * When a context has used up this amount of time across its jobs, it is
 259          * scheduled out to let another run.
 260          *
 261          * @note the resolution is nanoseconds (ns) here, because that's the format
 262          * often used by the OS.
 263          *
 264          * This value controls affects the actual time defined by the following
 265          * config values:
 266          * - @ref KBASE_CONFIG_ATTR_JS_CFS_CTX_RUNTIME_INIT_SLICES
 267          * - @ref KBASE_CONFIG_ATTR_JS_CFS_CTX_RUNTIME_MIN_SLICES
 268          *
 269          * This value is supported by the following scheduling policies:
 270          * - The Completely Fair Share (CFS) policy
 271          *
 272          * Attached value: unsigned 32-bit kbasep_js_device_data::ctx_timeslice_ns.
 273          * The value might be rounded down to lower precision.<br>
 274          * Default value: @ref DEFAULT_JS_CTX_TIMESLICE_NS
 275          *
 276          * @note a value of zero models a "Round Robin" scheduling policy, and
 277          * disables @ref KBASE_CONFIG_ATTR_JS_CFS_CTX_RUNTIME_INIT_SLICES
 278          * (initially causing LIFO scheduling) and
 279          * @ref KBASE_CONFIG_ATTR_JS_CFS_CTX_RUNTIME_MIN_SLICES (allowing
 280          * not-run-often contexts to get scheduled in quickly, but to only use
 281          * a single timeslice when they get scheduled in).
 282          */
 283         KBASE_CONFIG_ATTR_JS_CTX_TIMESLICE_NS,
 284
 285         /**
 286          * Job Scheduler initial runtime of a context for the CFS Policy, in time-slices.
 287          *
 288          * This value is relative to that of the least-run context, and defines
 289          * where in the CFS queue a new context is added. A value of 1 means 'after
 290          * the least-run context has used its timeslice'. Therefore, when all
 291          * contexts consistently use the same amount of time, a value of 1 models a
 292          * FIFO. A value of 0 would model a LIFO.
 293          *
 294          * The value is represented in "numbers of time slices". Multiply this
 295          * value by that defined in @ref KBASE_CONFIG_ATTR_JS_CTX_TIMESLICE_NS to get
 296          * the time value for this in nanoseconds.
 297          *
 298          * Attached value: unsigned 32-bit kbasep_js_device_data::cfs_ctx_runtime_init_slices<br>
 299          * Default value: @ref DEFAULT_JS_CFS_CTX_RUNTIME_INIT_SLICES
 300          */
 301         KBASE_CONFIG_ATTR_JS_CFS_CTX_RUNTIME_INIT_SLICES,
 302
 303         /**
 304          * Job Scheduler minimum runtime value of a context for CFS, in time_slices
 305          * relative to that of the least-run context.
 306          *
 307          * This is a measure of how much preferrential treatment is given to a
 308          * context that is not run very often.
 309          *
 310          * Specficially, this value defines how many timeslices such a context is
 311          * (initially) allowed to use at once. Such contexts (e.g. 'interactive'
 312          * processes) will appear near the front of the CFS queue, and can initially
 313          * use more time than contexts that run continuously (e.g. 'batch'
 314          * processes).
 315          *
 316          * This limit \b prevents a "stored-up timeslices" DoS attack, where a ctx
 317          * not run for a long time attacks the system by using a very large initial
 318          * number of timeslices when it finally does run.
 319          *
 320          * Attached value: unsigned 32-bit kbasep_js_device_data::cfs_ctx_runtime_min_slices<br>
 321          * Default value: @ref DEFAULT_JS_CFS_CTX_RUNTIME_MIN_SLICES
 322          *
 323          * @note A value of zero allows not-run-often contexts to get scheduled in
 324          * quickly, but to only use a single timeslice when they get scheduled in.
 325          */
 326         KBASE_CONFIG_ATTR_JS_CFS_CTX_RUNTIME_MIN_SLICES,
 327
 328         /**
 329          * Job Scheduler minimum number of scheduling ticks before non-CL jobs
 330          * cause the GPU to be reset.
 331          *
 332          * This defines the amount of time a job is allowed to spend on the GPU before it
 333          * is assumed that the GPU has hung and needs to be reset. The assumes that the job
 334          * has been hard-stopped already and so the presence of a job that has remained on
 335          * the GPU for so long indicates that the GPU has in some way hung.
 336          *
 337          * This value is supported by the following scheduling policies:
 338          * - The Completely Fair Share (CFS) policy
 339          *
 340          * Attached value: unsigned 32-bit kbasep_js_device_data::gpu_reset_ticks_nss<br>
 341          * Default value: @ref DEFAULT_JS_RESET_TICKS_SS
 342          *
 343          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 344          */
 345         KBASE_CONFIG_ATTR_JS_RESET_TICKS_SS,
 346
 347         /**
 348          * Job Scheduler minimum number of scheduling ticks before CL jobs
 349          * cause the GPU to be reset.
 350          *
 351          * This defines the amount of time a job is allowed to spend on the GPU before it
 352          * is assumed that the GPU has hung and needs to be reset. The assumes that the job
 353          * has been hard-stopped already and so the presence of a job that has remained on
 354          * the GPU for so long indicates that the GPU has in some way hung.
 355          *
 356          * This value is supported by the following scheduling policies:
 357          * - The Completely Fair Share (CFS) policy
 358          *
 359          * Attached value: unsigned 32-bit kbasep_js_device_data::gpu_reset_ticks_cl<br>
 360          * Default value: @ref DEFAULT_JS_RESET_TICKS_CL
 361          *
 362          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 363          */
 364         KBASE_CONFIG_ATTR_JS_RESET_TICKS_CL,
 365
 366         /**
 367          * Job Scheduler minimum number of scheduling ticks before jobs cause the GPU to be
 368          * reset when dumping.
 369          *
 370          * This defines the amount of time a job is allowed to spend on the GPU before it
 371          * is assumed that the GPU has hung and needs to be reset. The assumes that the job
 372          * has been hard-stopped already and so the presence of a job that has remained on
 373          * the GPU for so long indicates that the GPU has in some way hung.
 374          *
 375          * This value is supported by the following scheduling policies:
 376          * - The Completely Fair Share (CFS) policy
 377          *
 378          * Attached value: unsigned 32-bit kbasep_js_device_data::gpu_reset_ticks_nss<br>
 379          * Default value: @ref DEFAULT_JS_RESET_TICKS_NSS
 380          *
 381          * @see KBASE_CONFIG_ATTR_JS_SCHEDULING_TICK_NS
 382          */
 383         KBASE_CONFIG_ATTR_JS_RESET_TICKS_NSS,
 384
 385         /**
 386          * Number of milliseconds given for other jobs on the GPU to be
 387          * soft-stopped when the GPU needs to be reset.
 388          *
 389          * Attached value: number in milliseconds
 390          * Default value: @ref DEFAULT_JS_RESET_TIMEOUT_MS
 391          */
 392         KBASE_CONFIG_ATTR_JS_RESET_TIMEOUT_MS,
 393         /*** End Job Scheduling Configs ***/
 394
 395         /** Power management configuration
 396          *
 397          * Attached value: pointer to @ref kbase_pm_callback_conf
 398          * Default value: See @ref kbase_pm_callback_conf
 399          */
 400         KBASE_CONFIG_ATTR_POWER_MANAGEMENT_CALLBACKS,
 401
 402         /**
 403          * Boolean indicating whether the driver is configured to be secure at
 404          * a potential loss of performance.
 405          *
 406          * This currently affects only r0p0-15dev0 HW and earlier.
 407          *
 408          * On r0p0-15dev0 HW and earlier, there are tradeoffs between security and
 409          * performance:
 410          *
 411          * - When this is set to MALI_TRUE, the driver remains fully secure,
 412          * but potentially loses performance compared with setting this to
 413          * MALI_FALSE.
 414          * - When set to MALI_FALSE, the driver is open to certain security
 415          * attacks.
 416          *
 417          * From r0p0-00rel0 and onwards, there is no security loss by setting
 418          * this to MALI_FALSE, and no performance loss by setting it to
 419          * MALI_TRUE.
 420          *
 421          * Attached value: mali_bool value
 422          * Default value: @ref DEFAULT_SECURE_BUT_LOSS_OF_PERFORMANCE
 423          */
 424         KBASE_CONFIG_ATTR_SECURE_BUT_LOSS_OF_PERFORMANCE,
 425
 426         /**
 427          * A pointer to a function that calculates the CPU clock
 428          * speed of the platform in MHz - see
 429          * @ref kbase_cpuprops_clock_speed_function for the function
 430          * prototype.
 431          *
 432          * Attached value: A @ref kbase_cpuprops_clock_speed_function.
 433          * Default Value:  Pointer to @ref DEFAULT_CPU_SPEED_FUNC -
 434          *                 returns a clock speed of 100 MHz.
 435          */
 436         KBASE_CONFIG_ATTR_CPU_SPEED_FUNC,
 437
 438         /**
 439          * A pointer to a function that calculates the GPU clock
 440          * speed of the platform in MHz - see
 441          * @ref kbase_gpuprops_clock_speed_function for the function
 442          * prototype.
 443          *
 444          * Attached value: A @ref kbase_gpuprops_clock_speed_function.
 445          * Default Value:  NULL (in which case the driver assumes a current
 446          *                 GPU frequency specified by KBASE_CONFIG_ATTR_GPU_FREQ_KHZ_MAX)
 447          */
 448         KBASE_CONFIG_ATTR_GPU_SPEED_FUNC,
 449
 450         /**
 451          * Platform specific configuration functions
 452          *
 453          * Attached value: pointer to @ref kbase_platform_funcs_conf
 454          * Default value: See @ref kbase_platform_funcs_conf
 455          */
 456         KBASE_CONFIG_ATTR_PLATFORM_FUNCS,
 457
 458         /**
 459          * Limit ARID width on the AXI bus.
 460          *
 461          * Attached value: u32 register value
 462          *    KBASE_AID_32 - use the full 32 IDs (5 ID bits)
 463          *    KBASE_AID_16 - use 16 IDs (4 ID bits)
 464          *    KBASE_AID_8  - use 8 IDs (3 ID bits)
 465          *    KBASE_AID_4  - use 4 IDs (2 ID bits)
 466          * Default value: KBASE_AID_32 (no limit). Note hardware implementation
 467          * may limit to a lower value.
 468          */
 469         KBASE_CONFIG_ATTR_ARID_LIMIT,
 470
 471         /**
 472          * Limit AWID width on the AXI bus.
 473          *
 474          * Attached value: u32 register value
 475          *    KBASE_AID_32 - use the full 32 IDs (5 ID bits)
 476          *    KBASE_AID_16 - use 16 IDs (4 ID bits)
 477          *    KBASE_AID_8  - use 8 IDs (3 ID bits)
 478          *    KBASE_AID_4  - use 4 IDs (2 ID bits)
 479          * Default value: KBASE_AID_32 (no limit). Note hardware implementation
 480          * may limit to a lower value.
 481          */
 482         KBASE_CONFIG_ATTR_AWID_LIMIT,
 483
 484         /**
 485          * Rate at which dvfs data should be collected.
 486          *
 487          * Attached value: u32 value
 488          * Default value: 500 Milliseconds
 489          */
 490         KBASE_CONFIG_ATTR_POWER_MANAGEMENT_DVFS_FREQ,
 491
 492         /**
 493          * Power Management poweroff tick granuality. This is in nanoseconds to
 494          * allow HR timer support.
 495          *
 496          * On each scheduling tick, the power manager core may decide to:
 497          * -# Power off one or more shader cores
 498          * -# Power off the entire GPU
 499          *
 500          * Attached value: number in nanoseconds
 501          * Default value: @ref DEFAULT_PM_GPU_POWEROFF_TICK_NS,
 502          */
 503         KBASE_CONFIG_ATTR_PM_GPU_POWEROFF_TICK_NS,
 504
 505         /**
 506          * Power Manager number of ticks before shader cores are powered off
 507          *
 508          * Attached value: unsigned 32-bit kbasep_pm_device_data::poweroff_shader_ticks<br>
 509          * Default value: @ref DEFAULT_PM_POWEROFF_TICK_SHADER
 510          *
 511          * @see KBASE_CONFIG_ATTR_PM_GPU_POWEROFF_TICK_NS
 512          */
 513         KBASE_CONFIG_ATTR_PM_POWEROFF_TICK_SHADER,
 514
 515         /**
 516          * Power Manager number of ticks before GPU is powered off
 517          *
 518          * Attached value: unsigned 32-bit kbasep_pm_device_data::poweroff_gpu_ticks<br>
 519          * Default value: @ref DEFAULT_PM_POWEROFF_TICK_GPU
 520          *
 521          * @see KBASE_CONFIG_ATTR_PM_GPU_POWEROFF_TICK_NS
 522          */
 523         KBASE_CONFIG_ATTR_PM_POWEROFF_TICK_GPU,
 524
 525         /**
 526          * End of attribute list indicator.
 527          * The configuration loader will stop processing any more elements
 528          * when it encounters this attribute.
 529          *
 530          * Default value: NA
 531          */
 532         KBASE_CONFIG_ATTR_END = 0x1FFFUL
 533 };
 534
 535 enum {
 536         /**
 537          * Use unrestricted Address ID width on the AXI bus.
 538          */
 539         KBASE_AID_32 = 0x0,
 540
 541         /**
 542          * Restrict GPU to a half of maximum Address ID count.
 543          * This will reduce performance, but reduce bus load due to GPU.
 544          */
 545         KBASE_AID_16 = 0x3,
 546
 547         /**
 548          * Restrict GPU to a quarter of maximum Address ID count.
 549          * This will reduce performance, but reduce bus load due to GPU.
 550          */
 551         KBASE_AID_8  = 0x2,
 552
 553         /**
 554          * Restrict GPU to an eighth of maximum Address ID count.
 555          * This will reduce performance, but reduce bus load due to GPU.
 556          */
 557         KBASE_AID_4  = 0x1
 558 };
 559
 560 /*
 561  * @brief specifies a single attribute
 562  *
 563  * Attribute is identified by attr field. Data is either integer or a pointer to attribute-specific structure.
 564  */
 565 typedef struct kbase_attribute {
 566         int id;
 567         uintptr_t data;
 568 } kbase_attribute;
 569
 570 /* Forward declaration of kbase_device */
 571 struct kbase_device;
 572
 573 /*
 574  * @brief Specifies the functions for platform specific initialization and termination
 575  *
 576  * By default no functions are required. No additional platform specific control is necessary.
 577  */
 578 typedef struct kbase_platform_funcs_conf {
 579         /**
 580          * Function pointer for platform specific initialization or NULL if no initialization function is required.
 581          * This function will be called \em before any other callbacks listed in the kbase_attribute struct (such as
 582          * Power Management callbacks).
 583          * The platform specific private pointer kbase_device::platform_context can be accessed (and possibly initialized) in here.
 584          */
 585         mali_bool(*platform_init_func) (struct kbase_device *kbdev);
 586         /**
 587          * Function pointer for platform specific termination or NULL if no termination function is required.
 588          * This function will be called \em after any other callbacks listed in the kbase_attribute struct (such as
 589          * Power Management callbacks).
 590          * The platform specific private pointer kbase_device::platform_context can be accessed (and possibly terminated) in here.
 591          */
 592         void (*platform_term_func) (struct kbase_device *kbdev);
 593
 594 } kbase_platform_funcs_conf;
 595
 596 /*
 597  * @brief Specifies the callbacks for power management
 598  *
 599  * By default no callbacks will be made and the GPU must not be powered off.
 600  */
 601 typedef struct kbase_pm_callback_conf {
 602         /** Callback for when the GPU is idle and the power to it can be switched off.
 603          *
 604          * The system integrator can decide whether to either do nothing, just switch off
 605          * the clocks to the GPU, or to completely power down the GPU.
 606          * The platform specific private pointer kbase_device::platform_context can be accessed and modified in here. It is the
 607          * platform \em callbacks responsiblity to initialize and terminate this pointer if used (see @ref kbase_platform_funcs_conf).
 608          */
 609         void (*power_off_callback) (struct kbase_device *kbdev);
 610
 611         /** Callback for when the GPU is about to become active and power must be supplied.
 612          *
 613          * This function must not return until the GPU is powered and clocked sufficiently for register access to
 614          * succeed.  The return value specifies whether the GPU was powered down since the call to power_off_callback.
 615          * If the GPU state has been lost then this function must return 1, otherwise it should return 0.
 616          * The platform specific private pointer kbase_device::platform_context can be accessed and modified in here. It is the
 617          * platform \em callbacks responsiblity to initialize and terminate this pointer if used (see @ref kbase_platform_funcs_conf).
 618          *
 619          * The return value of the first call to this function is ignored.
 620          *
 621          * @return 1 if the GPU state may have been lost, 0 otherwise.
 622          */
 623         int (*power_on_callback) (struct kbase_device *kbdev);
 624
 625         /** Callback for when the system is requesting a suspend and GPU power
 626          * must be switched off.
 627          *
 628          * Note that if this callback is present, then this may be called
 629          * without a preceding call to power_off_callback. Therefore this
 630          * callback must be able to take any action that might otherwise happen
 631          * in power_off_callback.
 632          *
 633          * The platform specific private pointer kbase_device::platform_context
 634          * can be accessed and modified in here. It is the platform \em
 635          * callbacks responsibility to initialize and terminate this pointer if
 636          * used (see @ref kbase_platform_funcs_conf).
 637          */
 638         void (*power_suspend_callback) (struct kbase_device *kbdev);
 639
 640         /** Callback for when the system is resuming from a suspend and GPU
 641          * power must be switched on.
 642          *
 643          * Note that if this callback is present, then this may be called
 644          * without a following call to power_on_callback. Therefore this
 645          * callback must be able to take any action that might otherwise happen
 646          * in power_on_callback.
 647          *
 648          * The platform specific private pointer kbase_device::platform_context
 649          * can be accessed and modified in here. It is the platform \em
 650          * callbacks responsibility to initialize and terminate this pointer if
 651          * used (see @ref kbase_platform_funcs_conf).
 652          */
 653         void (*power_resume_callback) (struct kbase_device *kbdev);
 654
 655         /** Callback for handling runtime power management initialization.
 656          *
 657          * The runtime power management callbacks @ref power_runtime_off_callback and @ref power_runtime_on_callback
 658          * will become active from calls made to the OS from within this function.
 659          * The runtime calls can be triggered by calls from @ref power_off_callback and @ref power_on_callback.
 660          * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
 661          *
 662          * @return MALI_ERROR_NONE on success, else mali_error erro code.
 663          */
 664          mali_error(*power_runtime_init_callback) (struct kbase_device *kbdev);
 665
 666         /** Callback for handling runtime power management termination.
 667          *
 668          * The runtime power management callbacks @ref power_runtime_off_callback and @ref power_runtime_on_callback
 669          * should no longer be called by the OS on completion of this function.
 670          * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
 671          */
 672         void (*power_runtime_term_callback) (struct kbase_device *kbdev);
 673
 674         /** Callback for runtime power-off power management callback
 675          *
 676          * For linux this callback will be called by the kernel runtime_suspend callback.
 677          * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
 678          *
 679          * @return 0 on success, else OS error code.
 680          */
 681         void (*power_runtime_off_callback) (struct kbase_device *kbdev);
 682
 683         /** Callback for runtime power-on power management callback
 684          *
 685          * For linux this callback will be called by the kernel runtime_resume callback.
 686          * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
 687          */
 688         int (*power_runtime_on_callback) (struct kbase_device *kbdev);
 689
 690 } kbase_pm_callback_conf;
 691
 692 /**
 693  * Type of the function pointer for KBASE_CONFIG_ATTR_CPU_SPEED_FUNC.
 694  *
 695  * @param clock_speed [out] Once called this will contain the current CPU clock speed in MHz.
 696  *                          This is mainly used to implement OpenCL's clGetDeviceInfo().
 697  *
 698  * @return 0 on success, 1 on error.
 699  */
 700 typedef int (*kbase_cpuprops_clock_speed_function) (u32 *clock_speed);
 701
 702 /**
 703  * Type of the function pointer for KBASE_CONFIG_ATTR_GPU_SPEED_FUNC.
 704  *
 705  * @param clock_speed [out] Once called this will contain the current GPU clock speed in MHz.
 706  *                          If the system timer is not available then this function is required
 707  *                          for the OpenCL queue profiling to return correct timing information.
 708  *
 709  * @return 0 on success, 1 on error. When an error is returned the caller assumes a current
 710  * GPU speed as specified by KBASE_CONFIG_ATTR_GPU_FREQ_KHZ_MAX.
 711  */
 712 typedef int (*kbase_gpuprops_clock_speed_function) (u32 *clock_speed);
 713
 714 #ifdef CONFIG_OF
 715 typedef struct kbase_platform_config {
 716         const kbase_attribute *attributes;
 717         u32 midgard_type;
 718 } kbase_platform_config;
 719 #else
 720
 721 /*
 722  * @brief Specifies start and end of I/O memory region.
 723  */
 724 typedef struct kbase_io_memory_region {
 725         u64 start;
 726         u64 end;
 727 } kbase_io_memory_region;
 728
 729 /*
 730  * @brief Specifies I/O related resources like IRQs and memory region for I/O operations.
 731  */
 732 typedef struct kbase_io_resources {
 733         u32 job_irq_number;
 734         u32 mmu_irq_number;
 735         u32 gpu_irq_number;
 736         kbase_io_memory_region io_memory_region;
 737 } kbase_io_resources;
 738
 739 typedef struct kbase_platform_config {
 740         const kbase_attribute *attributes;
 741         const kbase_io_resources *io_resources;
 742         u32 midgard_type;
 743 } kbase_platform_config;
 744
 745 #endif /* CONFIG_OF */
 746
 747 /**
 748  * @brief Return character string associated with the given midgard type.
 749  *
 750  * @param[in]  midgard_type - ID of midgard type
 751   *
 752  * @return  Pointer to NULL-terminated character array associated with the given midgard type
 753  */
 754 const char *kbasep_midgard_type_to_string(u32 midgard_type);
 755
 756 /**
 757  * @brief Gets the next config attribute with the specified ID from the array of attributes.
 758  *
 759  * Function gets the next attribute with specified attribute id within specified array. If no such attribute is found,
 760  * NULL is returned.
 761  *
 762  * @param[in]  attributes     Array of attributes in which lookup is performed
 763  * @param[in]  attribute_id   ID of attribute
 764  *
 765  * @return  Pointer to the first attribute matching id or NULL if none is found.
 766  */
 767 const kbase_attribute *kbasep_get_next_attribute(const kbase_attribute *attributes, int attribute_id);
 768
 769 /**
 770  * @brief Gets the value of a single config attribute.
 771  *
 772  * Function gets the value of attribute specified as parameter. If no such attribute is found in the array of
 773  * attributes, default value is used.
 774  *
 775  * @param[in]  kbdev          Kbase device pointer
 776  * @param[in]  attributes     Array of attributes in which lookup is performed
 777  * @param[in]  attribute_id   ID of attribute
 778  *
 779  * @return Value of attribute with the given id
 780  */
 781 uintptr_t kbasep_get_config_value(struct kbase_device *kbdev, const kbase_attribute *attributes, int attribute_id);
 782
 783 /**
 784  * @brief Validates configuration attributes
 785  *
 786  * Function checks validity of given configuration attributes. It will fail on any attribute with unknown id, attribute
 787  * with invalid value or attribute list that is not correctly terminated. It will also fail if
 788  * KBASE_CONFIG_ATTR_GPU_FREQ_KHZ_MIN or KBASE_CONFIG_ATTR_GPU_FREQ_KHZ_MAX are not specified.
 789  *
 790  * @param[in]  kbdev       Kbase device pointer
 791  * @param[in]  attributes  Array of attributes to validate
 792  *
 793  * @return   MALI_TRUE if no errors have been found in the config. MALI_FALSE otherwise.
 794  */
 795 mali_bool kbasep_validate_configuration_attributes(struct kbase_device *kbdev, const kbase_attribute *attributes);
 796
 797 /**
 798  * @brief Gets the pointer to platform config.
 799  *
 800  * @return Pointer to the platform config
 801  */
 802 kbase_platform_config *kbase_get_platform_config(void);
 803
 804 /**
 805  * @brief Gets the count of attributes in array
 806  *
 807  * Function gets the count of attributes in array. Note that end of list indicator is also included.
 808  *
 809  * @param[in]  attributes     Array of attributes
 810  *
 811  * @return  Number of attributes in the array including end of list indicator.
 812  */
 813 int kbasep_get_config_attribute_count(const kbase_attribute *attributes);
 814
 815 /**
 816  * @brief Platform specific call to initialize hardware
 817  *
 818  * Function calls a platform defined routine if specified in the configuration attributes.
 819  * The routine can initialize any hardware and context state that is required for the GPU block to function.
 820  *
 821  * @param[in]  kbdev       Kbase device pointer
 822  *
 823  * @return   MALI_TRUE if no errors have been found in the config. MALI_FALSE otherwise.
 824  */
 825 mali_bool kbasep_platform_device_init(struct kbase_device *kbdev);
 826
 827 /**
 828  * @brief Platform specific call to terminate hardware
 829  *
 830  * Function calls a platform defined routine if specified in the configuration attributes.
 831  * The routine can destroy any platform specific context state and shut down any hardware functionality that are
 832  * outside of the Power Management callbacks.
 833  *
 834  * @param[in]  kbdev       Kbase device pointer
 835  *
 836  */
 837 void kbasep_platform_device_term(struct kbase_device *kbdev);
 838
 839           /** @} *//* end group kbase_config */
 840           /** @} *//* end group base_kbase_api */
 841           /** @} *//* end group base_api */
 842
 843 #endif                          /* _KBASE_CONFIG_H_ */