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 #ifndef ANDROID_PRIVATE_NATIVE_PERFORMANCE_HINT_PRIVATE_H 18 #define ANDROID_PRIVATE_NATIVE_PERFORMANCE_HINT_PRIVATE_H 19 20 #include <stdint.h> 21 22 __BEGIN_DECLS 23 24 struct APerformanceHintManager; 25 struct APerformanceHintSession; 26 27 /** 28 * An opaque type representing a handle to a performance hint manager. 29 * It must be released after use. 30 * 31 * <p>To use:<ul> 32 * <li>Obtain the performance hint manager instance by calling 33 * {@link APerformanceHint_getManager} function.</li> 34 * <li>Create an {@link APerformanceHintSession} with 35 * {@link APerformanceHint_createSession}.</li> 36 * <li>Get the preferred update rate in nanoseconds with 37 * {@link APerformanceHint_getPreferredUpdateRateNanos}.</li> 38 */ 39 typedef struct APerformanceHintManager APerformanceHintManager; 40 41 /** 42 * An opaque type representing a handle to a performance hint session. 43 * A session can only be acquired from a {@link APerformanceHintManager} 44 * with {@link APerformanceHint_getPreferredUpdateRateNanos}. It must be 45 * freed with {@link APerformanceHint_closeSession} after use. 46 * 47 * A Session represents a group of threads with an inter-related workload such that hints for 48 * their performance should be considered as a unit. The threads in a given session should be 49 * long-life and not created or destroyed dynamically. 50 * 51 * <p>Each session is expected to have a periodic workload with a target duration for each 52 * cycle. The cycle duration is likely greater than the target work duration to allow other 53 * parts of the pipeline to run within the available budget. For example, a renderer thread may 54 * work at 60hz in order to produce frames at the display's frame but have a target work 55 * duration of only 6ms.</p> 56 * 57 * <p>After each cycle of work, the client is expected to use 58 * {@link APerformanceHint_reportActualWorkDuration} to report the actual time taken to 59 * complete.</p> 60 * 61 * <p>To use:<ul> 62 * <li>Update a sessions target duration for each cycle of work 63 * with {@link APerformanceHint_updateTargetWorkDuration}.</li> 64 * <li>Report the actual duration for the last cycle of work with 65 * {@link APerformanceHint_reportActualWorkDuration}.</li> 66 * <li>Release the session instance with 67 * {@link APerformanceHint_closeSession}.</li></ul></p> 68 */ 69 typedef struct APerformanceHintSession APerformanceHintSession; 70 71 /** 72 * Acquire an instance of the performance hint manager. 73 * 74 * @return manager instance on success, nullptr on failure. 75 */ 76 APerformanceHintManager* APerformanceHint_getManager(); 77 78 /** 79 * Creates a session for the given set of threads and sets their initial target work 80 * duration. 81 * @param manager The performance hint manager instance. 82 * @param threadIds The list of threads to be associated with this session. They must be part of 83 * this app's thread group. 84 * @param size the size of threadIds. 85 * @param initialTargetWorkDurationNanos The desired duration in nanoseconds for the new session. 86 * This must be positive. 87 * @return manager instance on success, nullptr on failure. 88 */ 89 APerformanceHintSession* APerformanceHint_createSession(APerformanceHintManager* manager, 90 const int32_t* threadIds, size_t size, 91 int64_t initialTargetWorkDurationNanos); 92 93 /** 94 * Get preferred update rate information for this device. 95 * 96 * @param manager The performance hint manager instance. 97 * @return the preferred update rate supported by device software. 98 */ 99 int64_t APerformanceHint_getPreferredUpdateRateNanos(APerformanceHintManager* manager); 100 101 /** 102 * Updates this session's target duration for each cycle of work. 103 * 104 * @param session The performance hint session instance to update. 105 * @param targetDurationNanos the new desired duration in nanoseconds. This must be positive. 106 * @return 0 on success 107 * EINVAL if targetDurationNanos is not positive. 108 * EPIPE if communication with the system service has failed. 109 */ 110 int APerformanceHint_updateTargetWorkDuration(APerformanceHintSession* session, 111 int64_t targetDurationNanos); 112 113 /** 114 * Reports the actual duration for the last cycle of work. 115 * 116 * <p>The system will attempt to adjust the core placement of the threads within the thread 117 * group and/or the frequency of the core on which they are run to bring the actual duration 118 * close to the target duration.</p> 119 * 120 * @param session The performance hint session instance to update. 121 * @param actualDurationNanos how long the thread group took to complete its last task in 122 * nanoseconds. This must be positive. 123 * @return 0 on success 124 * EINVAL if actualDurationNanos is not positive. 125 * EPIPE if communication with the system service has failed. 126 */ 127 int APerformanceHint_reportActualWorkDuration(APerformanceHintSession* session, 128 int64_t actualDurationNanos); 129 130 /** 131 * Release the performance hint manager pointer acquired via 132 * {@link APerformanceHint_createSession}. 133 * 134 * @param session The performance hint session instance to release. 135 */ 136 void APerformanceHint_closeSession(APerformanceHintSession* session); 137 138 /** 139 * For testing only. 140 */ 141 void APerformanceHint_setIHintManagerForTesting(void* iManager); 142 143 __END_DECLS 144 145 #endif // ANDROID_PRIVATE_NATIVE_PERFORMANCE_HINT_PRIVATE_H 146