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_NATIVE_PERFORMANCE_HINT_H 18 #define ANDROID_NATIVE_PERFORMANCE_HINT_H 19 20 #include <sys/cdefs.h> 21 22 /****************************************************************** 23 * 24 * IMPORTANT NOTICE: 25 * 26 * This file is part of Android's set of stable system headers 27 * exposed by the Android NDK (Native Development Kit). 28 * 29 * Third-party source AND binary code relies on the definitions 30 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 31 * 32 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 33 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 34 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 35 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 36 */ 37 38 #include <android/api-level.h> 39 #include <stdint.h> 40 #include <unistd.h> 41 42 __BEGIN_DECLS 43 44 struct APerformanceHintManager; 45 struct APerformanceHintSession; 46 47 /** 48 * An opaque type representing a handle to a performance hint manager. 49 * It must be released after use. 50 * 51 * <p>To use:<ul> 52 * <li>Obtain the performance hint manager instance by calling 53 * {@link APerformanceHint_getManager} function.</li> 54 * <li>Create an {@link APerformanceHintSession} with 55 * {@link APerformanceHint_createSession}.</li> 56 * <li>Get the preferred update rate in nanoseconds with 57 * {@link APerformanceHint_getPreferredUpdateRateNanos}.</li> 58 */ 59 typedef struct APerformanceHintManager APerformanceHintManager; 60 61 /** 62 * An opaque type representing a handle to a performance hint session. 63 * A session can only be acquired from a {@link APerformanceHintManager} 64 * with {@link APerformanceHint_getPreferredUpdateRateNanos}. It must be 65 * freed with {@link APerformanceHint_closeSession} after use. 66 * 67 * A Session represents a group of threads with an inter-related workload such that hints for 68 * their performance should be considered as a unit. The threads in a given session should be 69 * long-life and not created or destroyed dynamically. 70 * 71 * <p>Each session is expected to have a periodic workload with a target duration for each 72 * cycle. The cycle duration is likely greater than the target work duration to allow other 73 * parts of the pipeline to run within the available budget. For example, a renderer thread may 74 * work at 60hz in order to produce frames at the display's frame but have a target work 75 * duration of only 6ms.</p> 76 * 77 * <p>After each cycle of work, the client is expected to use 78 * {@link APerformanceHint_reportActualWorkDuration} to report the actual time taken to 79 * complete.</p> 80 * 81 * <p>To use:<ul> 82 * <li>Update a sessions target duration for each cycle of work 83 * with {@link APerformanceHint_updateTargetWorkDuration}.</li> 84 * <li>Report the actual duration for the last cycle of work with 85 * {@link APerformanceHint_reportActualWorkDuration}.</li> 86 * <li>Release the session instance with 87 * {@link APerformanceHint_closeSession}.</li></ul></p> 88 */ 89 typedef struct APerformanceHintSession APerformanceHintSession; 90 91 /** 92 * Acquire an instance of the performance hint manager. 93 * 94 * @return manager instance on success, nullptr on failure. 95 */ 96 APerformanceHintManager* APerformanceHint_getManager() __INTRODUCED_IN(__ANDROID_API_T__); 97 98 /** 99 * Creates a session for the given set of threads and sets their initial target work 100 * duration. 101 * @param manager The performance hint manager instance. 102 * @param threadIds The list of threads to be associated with this session. They must be part of 103 * this app's thread group. 104 * @param size the size of threadIds. 105 * @param initialTargetWorkDurationNanos The desired duration in nanoseconds for the new session. 106 * This must be positive. 107 * @return manager instance on success, nullptr on failure. 108 */ 109 APerformanceHintSession* APerformanceHint_createSession( 110 APerformanceHintManager* manager, 111 const int32_t* threadIds, size_t size, 112 int64_t initialTargetWorkDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__); 113 114 /** 115 * Get preferred update rate information for this device. 116 * 117 * @param manager The performance hint manager instance. 118 * @return the preferred update rate supported by device software. 119 */ 120 int64_t APerformanceHint_getPreferredUpdateRateNanos( 121 APerformanceHintManager* manager) __INTRODUCED_IN(__ANDROID_API_T__); 122 123 /** 124 * Updates this session's target duration for each cycle of work. 125 * 126 * @param session The performance hint session instance to update. 127 * @param targetDurationNanos the new desired duration in nanoseconds. This must be positive. 128 * @return 0 on success 129 * EINVAL if targetDurationNanos is not positive. 130 * EPIPE if communication with the system service has failed. 131 */ 132 int APerformanceHint_updateTargetWorkDuration( 133 APerformanceHintSession* session, 134 int64_t targetDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__); 135 136 /** 137 * Reports the actual duration for the last cycle of work. 138 * 139 * <p>The system will attempt to adjust the core placement of the threads within the thread 140 * group and/or the frequency of the core on which they are run to bring the actual duration 141 * close to the target duration.</p> 142 * 143 * @param session The performance hint session instance to update. 144 * @param actualDurationNanos how long the thread group took to complete its last task in 145 * nanoseconds. This must be positive. 146 * @return 0 on success 147 * EINVAL if actualDurationNanos is not positive. 148 * EPIPE if communication with the system service has failed. 149 */ 150 int APerformanceHint_reportActualWorkDuration( 151 APerformanceHintSession* session, 152 int64_t actualDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__); 153 154 /** 155 * Release the performance hint manager pointer acquired via 156 * {@link APerformanceHint_createSession}. 157 * 158 * @param session The performance hint session instance to release. 159 */ 160 void APerformanceHint_closeSession( 161 APerformanceHintSession* session) __INTRODUCED_IN(__ANDROID_API_T__); 162 163 /** 164 * Set a list of threads to the performance hint session. This operation will replace 165 * the current list of threads with the given list of threads. 166 * 167 * @param session The performance hint session instance for the threads. 168 * @param threadIds The list of threads to be associated with this session. They must be part of 169 * this app's thread group. 170 * @param size the size of the list of threadIds. 171 * @return 0 on success. 172 * EINVAL if the list of thread ids is empty or if any of the thread ids is not part of the thread group. 173 * EPIPE if communication with the system service has failed. 174 */ 175 int APerformanceHint_setThreads( 176 APerformanceHintSession* session, 177 const pid_t* threadIds, 178 size_t size) __INTRODUCED_IN(__ANDROID_API_U__); 179 180 __END_DECLS 181 182 #endif // ANDROID_NATIVE_PERFORMANCE_HINT_H 183