1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @defgroup APerformanceHint Performance Hint Manager 19 * 20 * APerformanceHint allows apps to create performance hint sessions for groups 21 * of threads, and provide hints to the system about the workload of those threads, 22 * to help the system more accurately allocate resources for them. It is the NDK 23 * counterpart to the Java PerformanceHintManager SDK API. 24 * 25 * This API is intended for periodic workloads, such as frame production. Clients are 26 * expected to create an instance of APerformanceHintManager, create a session with 27 * that, and then set a target duration for the session. Then, they can report the actual 28 * work duration at the end of each cycle to inform the framework about how long those 29 * workloads are taking. The framework will then compare the actual durations to the target 30 * duration and attempt to help the client reach a steady state under the target. 31 * 32 * Unlike reportActualWorkDuration, the "notifyWorkload..." hints are intended to be sent in 33 * advance of large changes in the workload, to prevent them from going over the target 34 * when there is a sudden, unforseen change. Their effects are intended to last for only 35 * one cycle, after which reportActualWorkDuration will have a chance to catch up. 36 * These hints should be used judiciously, only in cases where the workload is changing 37 * substantially. To enforce that, they are tracked using a per-app rate limiter to avoid 38 * excessive hinting and encourage clients to be mindful about when to send them. 39 * @{ 40 */ 41 42 /** 43 * @file performance_hint.h 44 * @brief API for creating and managing a hint session. 45 */ 46 47 48 #ifndef ANDROID_NATIVE_PERFORMANCE_HINT_H 49 #define ANDROID_NATIVE_PERFORMANCE_HINT_H 50 51 #include <sys/cdefs.h> 52 #include <jni.h> 53 54 /****************************************************************** 55 * 56 * IMPORTANT NOTICE: 57 * 58 * This file is part of Android's set of stable system headers 59 * exposed by the Android NDK (Native Development Kit). 60 * 61 * Third-party source AND binary code relies on the definitions 62 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 63 * 64 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 65 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 66 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 67 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 68 */ 69 70 #include <stdbool.h> 71 #include <stdint.h> 72 #include <unistd.h> 73 74 #if !defined(__DEPRECATED_IN) 75 #define __DEPRECATED_IN(__api_level, ...) __attribute__((__deprecated__)) 76 #endif 77 78 __BEGIN_DECLS 79 80 struct APerformanceHintManager; 81 struct APerformanceHintSession; 82 struct AWorkDuration; 83 struct ANativeWindow; 84 struct ASurfaceControl; 85 86 /** 87 * {@link AWorkDuration} is an opaque type that represents the breakdown of the 88 * actual workload duration in each component internally. 89 * 90 * A new {@link AWorkDuration} can be obtained using 91 * {@link AWorkDuration_create()}, when the client finishes using 92 * {@link AWorkDuration}, {@link AWorkDuration_release()} must be 93 * called to destroy and free up the resources associated with 94 * {@link AWorkDuration}. 95 * 96 * This file provides a set of functions to allow clients to set the measured 97 * work duration of each component on {@link AWorkDuration}. 98 * 99 * - AWorkDuration_setWorkPeriodStartTimestampNanos() 100 * - AWorkDuration_setActualTotalDurationNanos() 101 * - AWorkDuration_setActualCpuDurationNanos() 102 * - AWorkDuration_setActualGpuDurationNanos() 103 */ 104 typedef struct AWorkDuration AWorkDuration; 105 106 /** 107 * An opaque type representing a handle to a performance hint manager. 108 * 109 * To use:<ul> 110 * <li>Obtain the performance hint manager instance by calling 111 * {@link APerformanceHint_getManager} function.</li> 112 * <li>Create an {@link APerformanceHintSession} with 113 * {@link APerformanceHint_createSession}.</li> 114 * <li>Get the preferred update rate in nanoseconds with 115 * {@link APerformanceHint_getPreferredUpdateRateNanos}.</li> 116 */ 117 typedef struct APerformanceHintManager APerformanceHintManager; 118 119 /** 120 * An opaque type representing a handle to a performance hint session creation configuration. 121 * It is consumed by {@link APerformanceHint_createSessionUsingConfig}. 122 * 123 * A session creation config encapsulates the required information for creating a session. The only 124 * mandatory parameter is the set of TIDs, set using {@link ASessionCreationConfig_setTids}. Only 125 * parameters relevant to the session need to be set, and any unspecified functionality will be 126 * treated as unused on the session. Configurations without a valid set of TIDs, or which try to 127 * enable automatic timing without the graphics pipeline mode, are considered invalid. 128 * 129 * The caller may reuse this object and modify the settings in it to create additional sessions. 130 */ 131 typedef struct ASessionCreationConfig ASessionCreationConfig; 132 133 /** 134 * An opaque type representing a handle to a performance hint session. 135 * A session can only be acquired from a {@link APerformanceHintManager} 136 * with {@link APerformanceHint_createSession} 137 * or {@link APerformanceHint_createSessionUsingConfig}. It must be 138 * freed with {@link APerformanceHint_closeSession} after use. 139 * 140 * A Session represents a group of threads with an inter-related workload such that hints for 141 * their performance should be considered as a unit. The threads in a given session should be 142 * long-lived and not created or destroyed dynamically. 143 * 144 * The work duration API can be used with periodic workloads to dynamically adjust thread 145 * performance and keep the work on schedule while optimizing the available power budget. 146 * When using the work duration API, the starting target duration should be specified 147 * while creating the session, and can later be adjusted with 148 * {@link APerformanceHint_updateTargetWorkDuration}. While using the work duration 149 * API, the client is expected to call {@link APerformanceHint_reportActualWorkDuration} each 150 * cycle to report the actual time taken to complete to the system. 151 * 152 * Note, methods of {@link APerformanceHintSession_*} are not thread safe so callers must 153 * ensure thread safety. 154 * 155 * All timings should be from `std::chrono::steady_clock` or `clock_gettime(CLOCK_MONOTONIC, ...)` 156 */ 157 typedef struct APerformanceHintSession APerformanceHintSession; 158 159 typedef struct ANativeWindow ANativeWindow; 160 typedef struct ASurfaceControl ASurfaceControl; 161 162 /** 163 * Acquire an instance of the performance hint manager. 164 * 165 * @return APerformanceHintManager instance on success, nullptr on failure. 166 */ 167 APerformanceHintManager* _Nullable APerformanceHint_getManager() 168 __INTRODUCED_IN(__ANDROID_API_T__); 169 170 /** 171 * Creates a session for the given set of threads and sets their initial target work 172 * duration. 173 * 174 * @param manager The performance hint manager instance. 175 * @param threadIds The list of threads to be associated with this session. They must be part of 176 * this process' thread group. 177 * @param size The size of the list of threadIds. 178 * @param initialTargetWorkDurationNanos The target duration in nanoseconds for the new session. 179 * This must be positive if using the work duration API, or 0 otherwise. 180 * @return APerformanceHintSession pointer on success, nullptr on failure. 181 */ 182 APerformanceHintSession* _Nullable APerformanceHint_createSession( 183 APerformanceHintManager* _Nonnull manager, 184 const int32_t* _Nonnull threadIds, size_t size, 185 int64_t initialTargetWorkDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__); 186 187 /** 188 * Creates a session using arguments from a corresponding {@link ASessionCreationConfig}. 189 * 190 * Note: when using graphics pipeline mode, using too many cumulative graphics pipeline threads is 191 * not a failure and will still create a session, but it will cause all graphics pipeline sessions 192 * to have undefined behavior and the method will return EBUSY. 193 * 194 * @param manager The performance hint manager instance. 195 * @param config The configuration struct containing required information 196 * to create a session. 197 * @param sessionOut A client-provided pointer, which will be set to the new APerformanceHintSession 198 * on success or EBUSY, and to nullptr on failure. 199 * 200 * @return 0 on success. 201 * EINVAL if the creation config is in an invalid state. 202 * EPIPE if communication failed. 203 * ENOTSUP if hint sessions are not supported, or if auto timing is enabled but unsupported. 204 * EBUSY if too many graphics pipeline threads are passed. 205 */ 206 int APerformanceHint_createSessionUsingConfig( 207 APerformanceHintManager* _Nonnull manager, 208 ASessionCreationConfig* _Nonnull config, 209 APerformanceHintSession * _Nullable * _Nonnull sessionOut) __INTRODUCED_IN(36); 210 211 /** 212 * Get preferred update rate information for this device. 213 * 214 * @deprecated Client side rate limiting is not necessary, rate limiting is handled in the 215 * framework. If you were using this to check for hint session support, please use 216 * {@link APerformanceHint_isFeatureSupported} instead. 217 * 218 * @param manager The performance hint manager instance. 219 * @return the preferred update rate supported by device software. 220 */ 221 int64_t APerformanceHint_getPreferredUpdateRateNanos( 222 APerformanceHintManager* _Nonnull manager) 223 __INTRODUCED_IN(__ANDROID_API_T__) __DEPRECATED_IN(36, "Client-side rate limiting is not" 224 " necessary, use APerformanceHint_isFeatureSupported for support checking."); 225 226 /** 227 * Get maximum number of graphics pipieline threads per-app for this device. 228 * 229 * @param manager The performance hint manager instance. 230 * @return the maximum number of graphics pipeline threads supported by device. 231 */ 232 int APerformanceHint_getMaxGraphicsPipelineThreadsCount( 233 APerformanceHintManager* _Nonnull manager) __INTRODUCED_IN(36); 234 235 /** 236 * Updates this session's target duration for each cycle of work. 237 * 238 * @param session The performance hint session instance to update. 239 * @param targetDurationNanos The new desired duration in nanoseconds. This must be positive for the 240 * session to report work durations, and may be zero to disable this functionality. 241 * 242 * @return 0 on success. 243 * EINVAL if targetDurationNanos is less than zero. 244 * EPIPE if communication with the system service has failed. 245 */ 246 int APerformanceHint_updateTargetWorkDuration( 247 APerformanceHintSession* _Nonnull session, 248 int64_t targetDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__); 249 250 /** 251 * Reports the actual duration for the last cycle of work. 252 * 253 * The system will attempt to adjust the scheduling and performance of the 254 * threads within the thread group to bring the actual duration close to the target duration. 255 * 256 * @param session The performance hint session instance to update. 257 * @param actualDurationNanos The duration of time the thread group took to complete its last 258 * task in nanoseconds. This must be positive. 259 * @return 0 on success. 260 * EINVAL if actualDurationNanos is not positive or the target it not positive. 261 * EPIPE if communication with the system service has failed. 262 */ 263 int APerformanceHint_reportActualWorkDuration( 264 APerformanceHintSession* _Nonnull session, 265 int64_t actualDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__); 266 267 /** 268 * Release the performance hint manager pointer acquired via 269 * {@link APerformanceHint_createSession}. 270 * 271 * This cannot be used to close a Java PerformanceHintManager.Session, as its 272 * lifecycle is tied to the object in the SDK. 273 * 274 * @param session The performance hint session instance to release. 275 */ 276 void APerformanceHint_closeSession( 277 APerformanceHintSession* _Nonnull session) __INTRODUCED_IN(__ANDROID_API_T__); 278 279 /** 280 * Set a list of threads to the performance hint session. This operation will replace 281 * the current list of threads with the given list of threads. 282 * 283 * Note: when using a session with the graphics pipeline mode enabled, using too many cumulative 284 * graphics pipeline threads is not a failure, but it will cause all graphics pipeline sessions to 285 * have undefined behavior and the method will return EBUSY. 286 * 287 * @param session The performance hint session instance to update. 288 * @param threadIds The list of threads to be associated with this session. They must be part of 289 * this app's thread group. 290 * @param size The size of the list of threadIds. 291 * @return 0 on success. 292 * EINVAL if the list of thread ids is empty or if any of the thread ids are not part of 293 * the thread group. 294 * EPIPE if communication with the system service has failed. 295 * EPERM if any thread id doesn't belong to the application. 296 * EBUSY if too many graphics pipeline threads were passed. 297 */ 298 int APerformanceHint_setThreads( 299 APerformanceHintSession* _Nonnull session, 300 const pid_t* _Nonnull threadIds, 301 size_t size) __INTRODUCED_IN(__ANDROID_API_U__); 302 303 /** 304 * This tells the session that these threads can be 305 * safely scheduled to prefer power efficiency over performance. 306 * 307 * @param session The performance hint session instance to update. 308 * @param enabled The flag which sets whether this session will use power-efficient scheduling. 309 * @return 0 on success. 310 * EPIPE if communication with the system service has failed. 311 */ 312 int APerformanceHint_setPreferPowerEfficiency( 313 APerformanceHintSession* _Nonnull session, 314 bool enabled) __INTRODUCED_IN(__ANDROID_API_V__); 315 316 /** 317 * Reports the durations for the last cycle of work. 318 * 319 * The system will attempt to adjust the scheduling and performance of the 320 * threads within the thread group to bring the actual duration close to the target duration. 321 * 322 * @param session The {@link APerformanceHintSession} instance to update. 323 * @param workDuration The {@link AWorkDuration} structure of times the thread group took to 324 * complete its last task in nanoseconds breaking down into different components. 325 * 326 * The work period start timestamp and actual total duration must be greater than zero. 327 * 328 * The actual CPU and GPU durations must be greater than or equal to zero, and at least one 329 * of them must be greater than zero. When one of them is equal to zero, it means that type 330 * of work was not measured for this workload. 331 * 332 * @return 0 on success. 333 * EINVAL if any duration is an invalid number. 334 * EPIPE if communication with the system service has failed. 335 */ 336 int APerformanceHint_reportActualWorkDuration2( 337 APerformanceHintSession* _Nonnull session, 338 AWorkDuration* _Nonnull workDuration) __INTRODUCED_IN(__ANDROID_API_V__); 339 340 /** 341 * Informs the framework of an upcoming increase in the workload of this session. 342 * The user can specify whether the increase is expected to be on the CPU, GPU, or both. 343 * 344 * These hints should be sent shortly before the start of the cycle where the workload is going to 345 * change, or as early as possible during that cycle for maximum effect. Hints sent towards the end 346 * of the cycle may be interpreted as applying to the next cycle. Any unsupported hints will be 347 * silently dropped, to avoid the need for excessive support checking each time they are sent, and 348 * sending a hint for both CPU and GPU will count as two separate hints for the rate limiter. These 349 * hints should not be sent repeatedly for an ongoing expensive workload, as workload time reporting 350 * is intended to handle this. 351 * 352 * @param session The {@link APerformanceHintSession} instance to send a hint for. 353 * @param cpu Indicates if the workload increase is expected to affect the CPU. 354 * @param gpu Indicates if the workload increase is expected to affect the GPU. 355 * @param identifier A required string used to distinguish this specific hint, using utf-8 encoding. 356 * This string will only be held for the duration of the method, and can be discarded after. 357 * 358 * @return 0 on success. 359 * EBUSY if the hint was rate limited. 360 * EPIPE if communication with the system service has failed. 361 */ 362 int APerformanceHint_notifyWorkloadIncrease( 363 APerformanceHintSession* _Nonnull session, 364 bool cpu, bool gpu, const char* _Nonnull identifier) __INTRODUCED_IN(36); 365 366 /** 367 * Informs the framework that the workload associated with this session is about to start, or that 368 * it is about to completely change, and that the system should discard any assumptions about its 369 * characteristics inferred from previous activity. The user can specify whether the reset is 370 * expected to affect the CPU, GPU, or both. 371 * 372 * These hints should be sent shortly before the start of the cycle where the workload is going to 373 * change, or as early as possible during that cycle for maximum effect. Hints sent towards the end 374 * of the cycle may be interpreted as applying to the next cycle. Any unsupported hints will be 375 * silently dropped, to avoid the need for excessive support checking each time they are sent, and 376 * sending a hint for both CPU and GPU will count as two separate hints for the rate limiter. These 377 * hints should not be sent repeatedly for an ongoing expensive workload, as workload time reporting 378 * is intended to handle this. 379 * 380 * @param session The {@link APerformanceHintSession} instance to send a hint for. 381 * @param cpu Indicates if the workload reset is expected to affect the CPU. 382 * @param gpu Indicates if the workload reset is expected to affect the GPU. 383 * @param identifier A required string used to distinguish this specific hint, using utf-8 encoding. 384 * This string will only be held for the duration of the method, and can be discarded after. 385 * 386 * @return 0 on success. 387 * EBUSY if the hint was rate limited. 388 * EPIPE if communication with the system service has failed. 389 */ 390 int APerformanceHint_notifyWorkloadReset( 391 APerformanceHintSession* _Nonnull session, 392 bool cpu, bool gpu, const char* _Nonnull identifier) __INTRODUCED_IN(36); 393 394 /** 395 * Informs the framework of an upcoming one-off expensive workload cycle for a given session. 396 * This cycle will be treated as not representative of the workload as a whole, and it will be 397 * discarded the purposes of load tracking. The user can specify whether the workload spike is 398 * expected to be on the CPU, GPU, or both. 399 * 400 * These hints should be sent shortly before the start of the cycle where the workload is going to 401 * change, or as early as possible during that cycle for maximum effect. Hints sent towards the end 402 * of the cycle may be interpreted as applying to the next cycle. Any unsupported hints will be 403 * silently dropped, to avoid the need for excessive support checking each time they are sent, and 404 * sending a hint for both CPU and GPU will count as two separate hints for the rate limiter. These 405 * hints should not be sent repeatedly for an ongoing expensive workload, as workload time reporting 406 * is intended to handle this. 407 * 408 * @param session The {@link APerformanceHintSession} instance to send a hint for. 409 * @param cpu Indicates if the workload spike is expected to affect the CPU. 410 * @param gpu Indicates if the workload spike is expected to affect the GPU. 411 * @param identifier A required string used to distinguish this specific hint, using utf-8 encoding. 412 * This string will only be held for the duration of the method, and can be discarded after. 413 * 414 * @return 0 on success. 415 * EBUSY if the hint was rate limited. 416 * EPIPE if communication with the system service has failed. 417 */ 418 int APerformanceHint_notifyWorkloadSpike( 419 APerformanceHintSession* _Nonnull session, 420 bool cpu, bool gpu, const char* _Nonnull identifier) __INTRODUCED_IN(36); 421 422 /** 423 * Associates a session with any {@link ASurfaceControl} or {@link ANativeWindow} 424 * instances managed by this session. Any previously associated objects that are not passed 425 * in again lose their association. Invalid or dead instances are ignored, and passing both 426 * lists as null drops all current associations. 427 * 428 * This method is primarily intended for sessions that manage the timing of an entire 429 * graphics pipeline end-to-end for frame pacing, such as those using the 430 * {@link ASessionCreationConfig_setGraphicsPipeline} API. However, any session directly 431 * or indirectly managing a graphics pipeline should still associate themselves with 432 * directly relevant ASurfaceControl or ANativeWindow instances for better optimization. 433 * Additionally, if the surface associated with a session changes, this method should be called 434 * again to re-create the association. 435 * 436 * To see any benefit from this method, the client must make sure they are updating the frame rate 437 * of attached surfaces using methods such as {@link ANativeWindow_setFrameRate}, or by updating 438 * any associated ASurfaceControls with transactions that have {ASurfaceTransaction_setFrameRate}. 439 * 440 * @param session The {@link APerformanceHintSession} instance to update. 441 * @param nativeWindows A pointer to a list of ANativeWindows associated with this session. 442 * nullptr can be passed to indicate there are no associated ANativeWindows. 443 * @param nativeWindowsSize The number of ANativeWindows in the list. 444 * @param surfaceControls A pointer to a list of ASurfaceControls associated with this session. 445 * nullptr can be passed to indicate there are no associated ASurfaceControls. 446 * @param surfaceControlsSize The number of ASurfaceControls in the list. 447 * 448 * @return 0 on success. 449 * EPIPE if communication has failed. 450 * ENOTSUP if this is not supported on the device. 451 */ 452 453 int APerformanceHint_setNativeSurfaces(APerformanceHintSession* _Nonnull session, 454 ANativeWindow* _Nonnull* _Nullable nativeWindows, size_t nativeWindowsSize, 455 ASurfaceControl* _Nonnull* _Nullable surfaceControls, size_t surfaceControlsSize) 456 __INTRODUCED_IN(36); 457 458 /** 459 * This enum represents different aspects of performance hint functionality. These can be passed 460 * to {@link APerformanceHint_isFeatureSupported} to determine whether the device exposes support 461 * for that feature. 462 * 463 * Some of these features will not expose failure to the client if used when unsupported, to prevent 464 * the client from needing to worry about handling different logic for each possible support 465 * configuration. The exception to this is features with important user-facing side effects, such as 466 * {@link APERF_HINT_AUTO_CPU} and {@link APERF_HINT_AUTO_GPU} modes which expect the client not to 467 * report durations while they are active. 468 */ 469 typedef enum APerformanceHintFeature : int32_t { 470 /** 471 * This value represents all APerformanceHintSession functionality. Using the Performance Hint 472 * API at all if this is not enabled will likely result in either 473 * {@link APerformanceHintManager} or {@link APerformanceHintSession} failing to create, or the 474 * session having little to no benefit even if creation succeeds. 475 */ 476 APERF_HINT_SESSIONS, 477 478 /** 479 * This value represents the power efficiency mode, as exposed by 480 * {@link ASessionCreationConfig_setPreferPowerEfficiency} and 481 * {@link APerformanceHint_setPreferPowerEfficiency}. 482 */ 483 APERF_HINT_POWER_EFFICIENCY, 484 485 /** 486 * This value the ability for sessions to bind to surfaces using 487 * {@link APerformanceHint_setNativeSurfaces} or 488 * {@link ASessionCreationConfig_setNativeSurfaces} 489 */ 490 APERF_HINT_SURFACE_BINDING, 491 492 /** 493 * This value represents the "graphics pipeline" mode, as exposed by 494 * {@link ASessionCreationConfig_setGraphicsPipeline}. 495 */ 496 APERF_HINT_GRAPHICS_PIPELINE, 497 498 /** 499 * This value represents the automatic CPU timing feature, as exposed by 500 * {@link ASessionCreationConfig_setUseAutoTiming}. 501 */ 502 APERF_HINT_AUTO_CPU, 503 504 /** 505 * This value represents the automatic GPU timing feature, as exposed by 506 * {@link ASessionCreationConfig_setUseAutoTiming}. 507 */ 508 APERF_HINT_AUTO_GPU, 509 } APerformanceHintFeature; 510 511 /** 512 * Checks whether the device exposes support for a specific feature. 513 * 514 * @param feature The specific feature enum to check. 515 * 516 * @return false if unsupported, true if supported. 517 */ 518 bool APerformanceHint_isFeatureSupported(APerformanceHintFeature feature) __INTRODUCED_IN(36); 519 520 /** 521 * Creates a new AWorkDuration. When the client finishes using {@link AWorkDuration}, it should 522 * call {@link AWorkDuration_release()} to destroy {@link AWorkDuration} and release all resources 523 * associated with it. 524 * 525 * @return AWorkDuration pointer. 526 */ 527 AWorkDuration* _Nonnull AWorkDuration_create() __INTRODUCED_IN(__ANDROID_API_V__); 528 529 /** 530 * Destroys a {@link AWorkDuration} and frees all resources associated with it. 531 * 532 * @param aWorkDuration The {@link AWorkDuration} created by calling {@link AWorkDuration_create()} 533 */ 534 void AWorkDuration_release(AWorkDuration* _Nonnull aWorkDuration) 535 __INTRODUCED_IN(__ANDROID_API_V__); 536 537 /** 538 * Sets the work period start timestamp in nanoseconds. 539 * 540 * @param aWorkDuration The {@link AWorkDuration} created by calling {@link AWorkDuration_create()} 541 * @param workPeriodStartTimestampNanos The work period start timestamp in nanoseconds based on 542 * CLOCK_MONOTONIC about when the work starts. This timestamp must be greater than zero. 543 */ 544 void AWorkDuration_setWorkPeriodStartTimestampNanos(AWorkDuration* _Nonnull aWorkDuration, 545 int64_t workPeriodStartTimestampNanos) __INTRODUCED_IN(__ANDROID_API_V__); 546 547 /** 548 * Sets the actual total work duration in nanoseconds. 549 * 550 * @param aWorkDuration The {@link AWorkDuration} created by calling {@link AWorkDuration_create()} 551 * @param actualTotalDurationNanos The actual total work duration in nanoseconds. This number must 552 * be greater than zero. 553 */ 554 void AWorkDuration_setActualTotalDurationNanos(AWorkDuration* _Nonnull aWorkDuration, 555 int64_t actualTotalDurationNanos) __INTRODUCED_IN(__ANDROID_API_V__); 556 557 /** 558 * Sets the actual CPU work duration in nanoseconds. 559 * 560 * @param aWorkDuration The {@link AWorkDuration} created by calling {@link AWorkDuration_create()} 561 * @param actualCpuDurationNanos The actual CPU work duration in nanoseconds. This number must be 562 * greater than or equal to zero. If it is equal to zero, that means the CPU was not 563 * measured. 564 */ 565 void AWorkDuration_setActualCpuDurationNanos(AWorkDuration* _Nonnull aWorkDuration, 566 int64_t actualCpuDurationNanos) __INTRODUCED_IN(__ANDROID_API_V__); 567 568 /** 569 * Sets the actual GPU work duration in nanoseconds. 570 * 571 * @param aWorkDuration The {@link AWorkDuration} created by calling {@link AWorkDuration_create()}. 572 * @param actualGpuDurationNanos The actual GPU work duration in nanoseconds, the number must be 573 * greater than or equal to zero. If it is equal to zero, that means the GPU was not 574 * measured. 575 */ 576 void AWorkDuration_setActualGpuDurationNanos(AWorkDuration* _Nonnull aWorkDuration, 577 int64_t actualGpuDurationNanos) __INTRODUCED_IN(__ANDROID_API_V__); 578 579 /** 580 * Return the APerformanceHintSession wrapped by a Java PerformanceHintManager.Session object. 581 * 582 * The Java session maintains ownership over the wrapped native session, so it cannot be closed 583 * using {@link APerformanceHint_closeSession}. The return value is valid until the Java object 584 * containing this value dies. 585 * 586 * The returned pointer is intended to be used by JNI calls to access native performance APIs using 587 * a Java hint session wrapper, and then immediately discarded. Using the pointer after the death of 588 * the Java container results in undefined behavior. 589 * 590 * @param env The Java environment where the PerformanceHintManager.Session lives. 591 * @param sessionObj The Java Session to unwrap. 592 * 593 * @return A pointer to the APerformanceHintManager that backs the Java Session. 594 */ 595 APerformanceHintSession* _Nonnull APerformanceHint_borrowSessionFromJava( 596 JNIEnv* _Nonnull env, jobject _Nonnull sessionObj) __INTRODUCED_IN(36); 597 598 /* 599 * Creates a new ASessionCreationConfig. 600 * 601 * When the client finishes using {@link ASessionCreationConfig}, it should 602 * call {@link ASessionCreationConfig_release()} to destroy 603 * {@link ASessionCreationConfig} and release all resources 604 * associated with it. 605 * 606 * @return ASessionCreationConfig pointer. 607 */ 608 ASessionCreationConfig* _Nonnull ASessionCreationConfig_create() 609 __INTRODUCED_IN(36); 610 611 /** 612 * Destroys a {@link ASessionCreationConfig} and frees all 613 * resources associated with it. 614 * 615 * @param config The {@link ASessionCreationConfig} 616 * created by calling {@link ASessionCreationConfig_create()}. 617 */ 618 void ASessionCreationConfig_release( 619 ASessionCreationConfig* _Nonnull config) __INTRODUCED_IN(36); 620 621 /** 622 * Sets the tids to be associated with the session to be created. 623 * 624 * @param config The {@link ASessionCreationConfig} 625 * created by calling {@link ASessionCreationConfig_create()} 626 * @param tids The list of tids to be associated with this session. They must be part of 627 * this process' thread group. 628 * @param size The size of the list of tids. 629 */ 630 void ASessionCreationConfig_setTids( 631 ASessionCreationConfig* _Nonnull config, 632 const pid_t* _Nonnull tids, size_t size) __INTRODUCED_IN(36); 633 634 /** 635 * Sets the initial target work duration in nanoseconds for the session to be created. 636 * 637 * @param config The {@link ASessionCreationConfig} 638 * created by calling {@link ASessionCreationConfig_create()}. 639 * @param targetWorkDurationNanos The parameter to specify a target duration in nanoseconds for the 640 * new session; this value must be positive to use the work duration API, and may be ignored 641 * otherwise or set to zero. Negative values are invalid. 642 */ 643 void ASessionCreationConfig_setTargetWorkDurationNanos( 644 ASessionCreationConfig* _Nonnull config, 645 int64_t targetWorkDurationNanos) __INTRODUCED_IN(36); 646 647 /** 648 * Sets whether power efficiency mode will be enabled for the session. 649 * This tells the session that these threads can be 650 * safely scheduled to prefer power efficiency over performance. 651 * 652 * @param config The {@link ASessionCreationConfig} 653 * created by calling {@link ASessionCreationConfig_create()}. 654 * @param enabled Whether power efficiency mode will be enabled. 655 */ 656 void ASessionCreationConfig_setPreferPowerEfficiency( 657 ASessionCreationConfig* _Nonnull config, bool enabled) __INTRODUCED_IN(36); 658 659 /** 660 * Sessions setting this hint are expected to time the critical path of 661 * graphics pipeline from end to end, with the total work duration 662 * representing the time from the start of frame production until the 663 * buffer is fully finished drawing. 664 * 665 * It should include any threads on the critical path of that pipeline, 666 * up to a limit accessible from {@link APerformanceHint_getMaxGraphicsPipelineThreadsCount()}. 667 * 668 * @param config The {@link ASessionCreationConfig} 669 * created by calling {@link ASessionCreationConfig_create()}. 670 * @param enabled Whether this session manages a graphics pipeline's critical path. 671 */ 672 void ASessionCreationConfig_setGraphicsPipeline( 673 ASessionCreationConfig* _Nonnull config, bool enabled) __INTRODUCED_IN(36); 674 675 /** 676 * Associates the created session with any {@link ASurfaceControl} or {@link ANativeWindow} 677 * instances it will be managing. Invalid or dead instances are ignored. 678 * 679 * This method is primarily intended for sessions that manage the timing of an entire 680 * graphics pipeline end-to-end for frame pacing, such as those using the 681 * {@link ASessionCreationConfig_setGraphicsPipeline} API. However, any session directly 682 * or indirectly managing a graphics pipeline should still associate themselves with 683 * directly relevant ASurfaceControl or ANativeWindow instances for better optimization. 684 * Additionally, if the surface associated with a session changes, this method should be called 685 * again to re-create the association. 686 * 687 * To see any benefit from this method, the client must make sure they are updating the frame rate 688 * of attached surfaces using methods such as {@link ANativeWindow_setFrameRate}, or by updating 689 * any associated ASurfaceControls with transactions that have {ASurfaceTransaction_setFrameRate}. 690 * 691 * 692 * @param config The {@link ASessionCreationConfig} 693 * created by calling {@link ASessionCreationConfig_create()}. 694 * @param nativeWindows A pointer to a list of ANativeWindows associated with this session. 695 * nullptr can be passed to indicate there are no associated ANativeWindows. 696 * @param nativeWindowsSize The number of ANativeWindows in the list. 697 * @param surfaceControls A pointer to a list of ASurfaceControls associated with this session. 698 * nullptr can be passed to indicate there are no associated ASurfaceControls. 699 * @param surfaceControlsSize The number of ASurfaceControls in the list. 700 */ 701 void ASessionCreationConfig_setNativeSurfaces( 702 ASessionCreationConfig* _Nonnull config, 703 ANativeWindow* _Nonnull* _Nullable nativeWindows, size_t nativeWindowsSize, 704 ASurfaceControl* _Nonnull* _Nullable surfaceControls, size_t surfaceControlsSize) 705 __INTRODUCED_IN(36); 706 707 /** 708 * Enable automatic timing mode for sessions using the GRAPHICS_PIPELINE API with an attached 709 * surface. In this mode, sessions do not need to report timing data for the CPU, GPU, or both 710 * depending on the configuration. To use this mode, sessions should set a native surface 711 * using {@ASessionCreationConfig_setNativeSurfaces}, enable graphics pipeline mode with 712 * {@link ASessionCreationConfig_setGraphicsPipeline()}, and then call this method to set whether 713 * automatic timing is desired for the CPU, GPU, or both. Trying to enable this without also 714 * enabling the graphics pipeline mode will cause session creation to fail. 715 * 716 * It is still be beneficial to set an accurate target time, as this may help determine 717 * timing information for some workloads where there is less information available from 718 * the framework, such as games. Additionally, reported CPU durations will be ignored 719 * while automatic CPU timing is enabled, and similarly GPU durations will be ignored 720 * when automatic GPU timing is enabled. When both are enabled, the entire 721 * {@link APerformanceHint_reportActualWorkDuration} call will be ignored, and the session will be 722 * managed completely automatically. 723 * 724 * If the client is manually controlling their frame rate for those surfaces, then they must make 725 * sure they are updating the frame rate with {@link ANativeWindow_setFrameRate}, or updating any 726 * associated ASurfaceControls with transactions that have {ASurfaceTransaction_setFrameRate} set. 727 * 728 * The user of this API should ensure this feature is supported by checking 729 * {@link APERF_HINT_AUTO_CPU} and {@link APERF_HINT_AUTO_GPU} with 730 * {@link APerformanceHint_isFeatureSupported} and falling back to manual timing if it is not. 731 * Trying to use automatic timing when it is unsupported will cause session creation to fail. 732 * 733 * @param config The {@link ASessionCreationConfig} 734 * created by calling {@link ASessionCreationConfig_create()}. 735 * @param cpu Whether to enable automatic timing for the CPU for this session. 736 * @param gpu Whether to enable automatic timing for the GPU for this session. 737 */ 738 void ASessionCreationConfig_setUseAutoTiming( 739 ASessionCreationConfig* _Nonnull config, bool cpu, bool gpu) __INTRODUCED_IN(36); 740 741 __END_DECLS 742 743 #endif // ANDROID_NATIVE_PERFORMANCE_HINT_H 744 745 /** @} */ 746