Implement native PerformanceHint API

/*

 * Copyright (C) 2021 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

#ifndef ANDROID_PRIVATE_NATIVE_PERFORMANCE_HINT_PRIVATE_H

#define ANDROID_PRIVATE_NATIVE_PERFORMANCE_HINT_PRIVATE_H

#include <stdint.h>

__BEGIN_DECLS

struct APerformanceHintManager;

struct APerformanceHintSession;

/**

 * An opaque type representing a handle to a performance hint manager.

 * It must be released after use.

 *

 * <p>To use:<ul>

 *    <li>Obtain the performance hint manager instance by calling

 *        {@link APerformanceHint_getManager} function.</li>

 *    <li>Create an {@link APerformanceHintSession} with

 *        {@link APerformanceHint_createSession}.</li>

 *    <li>Get the preferred update rate in nanoseconds with

 *        {@link APerformanceHint_getPreferredUpdateRateNanos}.</li>

 */

typedef struct APerformanceHintManager APerformanceHintManager;

/**

 * An opaque type representing a handle to a performance hint session.

 * A session can only be acquired from a {@link APerformanceHintManager}

 * with {@link APerformanceHint_getPreferredUpdateRateNanos}. It must be

 * freed with {@link APerformanceHint_closeSession} after use.

 *

 * A Session represents a group of threads with an inter-related workload such that hints for

 * their performance should be considered as a unit. The threads in a given session should be

 * long-life and not created or destroyed dynamically.

 *

 * <p>Each session is expected to have a periodic workload with a target duration for each

 * cycle. The cycle duration is likely greater than the target work duration to allow other

 * parts of the pipeline to run within the available budget. For example, a renderer thread may

 * work at 60hz in order to produce frames at the display's frame but have a target work

 * duration of only 6ms.</p>

 *

 * <p>After each cycle of work, the client is expected to use

 * {@link APerformanceHint_reportActualWorkDuration} to report the actual time taken to

 * complete.</p>

 *

 * <p>To use:<ul>

 *    <li>Update a sessions target duration for each cycle of work

 *        with  {@link APerformanceHint_updateTargetWorkDuration}.</li>

 *    <li>Report the actual duration for the last cycle of work with

 *        {@link APerformanceHint_reportActualWorkDuration}.</li>

 *    <li>Release the session instance with

 *        {@link APerformanceHint_closeSession}.</li></ul></p>

 */

typedef struct APerformanceHintSession APerformanceHintSession;

/**

  * Acquire an instance of the performance hint manager.

  *

  * @return manager instance on success, nullptr on failure.

  */

APerformanceHintManager* APerformanceHint_getManager();

/**

 * Creates a session for the given set of threads and sets their initial target work

 * duration.

 * @param manager The performance hint manager instance.

 * @param threadIds The list of threads to be associated with this session. They must be part of

 *     this app's thread group.

 * @param size the size of threadIds.

 * @param initialTargetWorkDurationNanos The desired duration in nanoseconds for the new session.

 *     This must be positive.

 * @return manager instance on success, nullptr on failure.

 */

APerformanceHintSession* APerformanceHint_createSession(APerformanceHintManager* manager,

                                                        const int32_t* threadIds, size_t size,

                                                        int64_t initialTargetWorkDurationNanos);

/**

 * Get preferred update rate information for this device.

 *

 * @param manager The performance hint manager instance.

 * @return the preferred update rate supported by device software.

 */

int64_t APerformanceHint_getPreferredUpdateRateNanos(APerformanceHintManager* manager);

/**

 * Updates this session's target duration for each cycle of work.

 *

 * @param session The performance hint session instance to update.

 * @param targetDurationNanos the new desired duration in nanoseconds. This must be positive.

 * @return 0 on success

 *         EINVAL if targetDurationNanos is not positive.

 *         EPIPE if communication with the system service has failed.

 */

int APerformanceHint_updateTargetWorkDuration(APerformanceHintSession* session,

                                               int64_t targetDurationNanos);

/**

 * Reports the actual duration for the last cycle of work.

 *

 * <p>The system will attempt to adjust the core placement of the threads within the thread

 * group and/or the frequency of the core on which they are run to bring the actual duration

 * close to the target duration.</p>

 *

 * @param session The performance hint session instance to update.

 * @param actualDurationNanos how long the thread group took to complete its last task in

 *     nanoseconds. This must be positive.

 * @return 0 on success

 *         EINVAL if actualDurationNanos is not positive.

 *         EPIPE if communication with the system service has failed.

 */

int APerformanceHint_reportActualWorkDuration(APerformanceHintSession* session,

                                               int64_t actualDurationNanos);

/**

 * Release the performance hint manager pointer acquired via

 * {@link APerformanceHint_createSession}.

 *

 * @param session The performance hint session instance to release.

 */

void APerformanceHint_closeSession(APerformanceHintSession* session);

/**

 * For testing only.

 */

void APerformanceHint_setIHintManagerForTesting(void* iManager);

__END_DECLS

#endif // ANDROID_PRIVATE_NATIVE_PERFORMANCE_HINT_PRIVATE_H