Merge "Implement NDK createSessionUsingConfig API" into main

Author: Andy Yu

include/android/performance_hint.h

@@ -110,10 +110,25 @@ typedef struct AWorkDuration AWorkDuration;
  */
 typedef struct APerformanceHintManager APerformanceHintManager;
 
+/**
+ * An opaque type representing a handle to a performance hint session creation configuration.
+ * It is consumed by {@link APerformanceHint_createSessionUsingConfig}.
+ *
+ * A session creation config encapsulates the required information for a session.
+ * Additionally, the caller can set various settings for the session,
+ * to be passed during creation, streamlining the session setup process.
+ *
+ * The caller may reuse this object and modify the settings in it
+ * to create additional sessions.
+ *
+ */
+typedef struct ASessionCreationConfig ASessionCreationConfig;
+
 /**
  * An opaque type representing a handle to a performance hint session.
  * A session can only be acquired from a {@link APerformanceHintManager}
- * with {@link APerformanceHint_createSession}. It must be
+ * with {@link APerformanceHint_createSession}
+ * or {@link APerformanceHint_createSessionUsingConfig}. 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
@@ -153,13 +168,27 @@ APerformanceHintManager* _Nullable APerformanceHint_getManager()
  * @param size The size of the list of threadIds.
  * @param initialTargetWorkDurationNanos The target duration in nanoseconds for the new session.
  *     This must be positive if using the work duration API, or 0 otherwise.
- * @return APerformanceHintManager instance on success, nullptr on failure.
+ * @return APerformanceHintSession pointer on success, nullptr on failure.
  */
 APerformanceHintSession* _Nullable APerformanceHint_createSession(
         APerformanceHintManager* _Nonnull manager,
         const int32_t* _Nonnull threadIds, size_t size,
         int64_t initialTargetWorkDurationNanos) __INTRODUCED_IN(__ANDROID_API_T__);
 
+/**
+ * Creates a session for the given set of threads that are graphics pipeline threads
+ * and set their initial target work duration.
+ *
+ * @param manager The performance hint manager instance.
+ * @param config The configuration struct containing required information
+ *        to create a session.
+ * @return APerformanceHintSession pointer on success, nullptr on failure.
+ */
+APerformanceHintSession* _Nullable APerformanceHint_createSessionUsingConfig(
+        APerformanceHintManager* _Nonnull manager,
+        ASessionCreationConfig* _Nonnull config)
+        __INTRODUCED_IN(36);
+
 /**
  * Get preferred update rate information for this device.
  *
@@ -169,6 +198,15 @@ APerformanceHintSession* _Nullable APerformanceHint_createSession(
 int64_t APerformanceHint_getPreferredUpdateRateNanos(
         APerformanceHintManager* _Nonnull manager) __INTRODUCED_IN(__ANDROID_API_T__);
 
+/**
+ * Get maximum number of graphics pipieline threads per-app for this device.
+ *
+ * @param manager The performance hint manager instance.
+ * @return the maximum number of graphics pipeline threads supported by device.
+ */
+ int APerformanceHint_getMaxGraphicsPipelineThreadsCount(
+        APerformanceHintManager* _Nonnull manager) __INTRODUCED_IN(36);
+
 /**
  * Updates this session's target duration for each cycle of work.
  *
@@ -320,12 +358,12 @@ int APerformanceHint_notifyWorkloadReset(
  * call {@link AWorkDuration_release()} to destroy {@link AWorkDuration} and release all resources
  * associated with it.
  *
- * @return AWorkDuration on success and nullptr otherwise.
+ * @return AWorkDuration pointer.
  */
 AWorkDuration* _Nonnull AWorkDuration_create() __INTRODUCED_IN(__ANDROID_API_V__);
 
 /**
- * Destroys {@link AWorkDuration} and free all resources associated to it.
+ * Destroys a {@link AWorkDuration} and frees all resources associated with it.
  *
  * @param aWorkDuration The {@link AWorkDuration} created by calling {@link AWorkDuration_create()}
  */
@@ -388,6 +426,99 @@ void AWorkDuration_setActualGpuDurationNanos(AWorkDuration* _Nonnull aWorkDurati
 APerformanceHintSession* _Nonnull APerformanceHint_borrowSessionFromJava(
         JNIEnv* _Nonnull env, jobject _Nonnull sessionObj) __INTRODUCED_IN(36);
 
+/*
+ * Creates a new ASessionCreationConfig.
+ *
+ * When the client finishes using {@link ASessionCreationConfig}, it should
+ * call {@link ASessionCreationConfig_release()} to destroy
+ * {@link ASessionCreationConfig} and release all resources
+ * associated with it.
+ *
+ * @return ASessionCreationConfig pointer.
+ */
+ASessionCreationConfig* _Nonnull ASessionCreationConfig_create()
+                __INTRODUCED_IN(36);
+
+
+/**
+ * Destroys a {@link ASessionCreationConfig} and frees all
+ * resources associated with it.
+ *
+ * @param config The {@link ASessionCreationConfig}
+ *        created by calling {@link ASessionCreationConfig_create()}.
+ */
+void ASessionCreationConfig_release(
+                ASessionCreationConfig* _Nonnull config) __INTRODUCED_IN(36);
+
+/**
+ * Sets the tids to be associated with the session to be created.
+ *
+ * @param config The {@link ASessionCreationConfig}
+ *        created by calling {@link ASessionCreationConfig_create()}
+ * @param tids The list of tids to be associated with this session. They must be part of
+ *        this process' thread group.
+ * @param size The size of the list of tids.
+ *
+ * @return 0 on success.
+ *         EINVAL if invalid array pointer or the value of size
+ */
+int ASessionCreationConfig_setTids(
+        ASessionCreationConfig* _Nonnull config,
+        const pid_t* _Nonnull tids, size_t size)  __INTRODUCED_IN(36);
+
+/**
+ * Sets the initial target work duration in nanoseconds for the session to be created.
+ *
+ * @param config The {@link ASessionCreationConfig}
+ *        created by calling {@link ASessionCreationConfig_create()}.
+ * @param targetWorkDurationNanos The parameter to specify a target duration
+ *        in nanoseconds for the new session; this value must be positive to use
+ *        the work duration API.
+ *
+ * @return 0 on success.
+ *         ENOTSUP if unsupported
+ *         EINVAL if invalid value
+ */
+int ASessionCreationConfig_setTargetWorkDurationNanos(
+        ASessionCreationConfig* _Nonnull config,
+        int64_t targetWorkDurationNanos)  __INTRODUCED_IN(36);
+
+/**
+ * Sets whether power efficiency mode will be enabled for the session.
+ * This tells the session that these threads can be
+ * safely scheduled to prefer power efficiency over performance.
+ *
+ * @param config The {@link ASessionCreationConfig}
+ *        created by calling {@link ASessionCreationConfig_create()}.
+ * @param enabled Whether power efficiency mode will be enabled.
+ *
+ * @return 0 on success.
+ *         ENOTSUP if unsupported
+ *         EINVAL if invalid pointer to creation config
+ */
+int ASessionCreationConfig_setPreferPowerEfficiency(
+        ASessionCreationConfig* _Nonnull config, bool enabled)  __INTRODUCED_IN(36);
+
+/**
+ * Sessions setting this hint are expected to time the critical path of
+ * graphics pipeline from end to end, with the total work duration
+ * representing the time from the start of frame production until the
+ * buffer is fully finished drawing.
+ *
+ * It should include any threads on the critical path of that pipeline,
+ * up to a limit accessible from {@link getMaxGraphicsPipelineThreadsCount()}.
+ *
+ * @param config The {@link ASessionCreationConfig}
+ *        created by calling {@link ASessionCreationConfig_create()}.
+ * @param enabled Whether this session manages a graphics pipeline's critical path.
+ *
+ * @return 0 on success.
+ *         ENOTSUP if unsupported
+ *         EINVAL if invalid pointer to creation config or maximum threads for graphics
+                  pipeline is reached.
+ */
+int ASessionCreationConfig_setGraphicsPipeline(
+        ASessionCreationConfig* _Nonnull confi, bool enabled)  __INTRODUCED_IN(36);
 
 __END_DECLS
 

include/private/performance_hint_private.h

@@ -108,6 +108,12 @@ int APerformanceHint_getThreadIds(APerformanceHintSession* session,
 APerformanceHintSession* APerformanceHint_createSessionInternal(APerformanceHintManager* manager,
                                         const int32_t* threadIds, size_t size,
                                         int64_t initialTargetWorkDurationNanos, SessionTag tag);
+/**
+ * Creates a session using ASessionCreationConfig
+ */
+APerformanceHintSession* APerformanceHint_createSessionUsingConfigInternal(
+        APerformanceHintManager* manager, ASessionCreationConfig* sessionCreationConfig,
+        SessionTag tag);
 
 /**
  * Creates a session from the Java SDK implementation
@@ -137,6 +143,10 @@ void APerformanceHint_getRateLimiterPropertiesForTesting(
  */
 void APerformanceHint_setUseNewLoadHintBehaviorForTesting(bool newBehavior);
 
+/*
+ * Forces the graphics pipeline flag to be enabled or disabled, for testing only.
+ */
+void APerformanceHint_setUseGraphicsPipelineForTesting(bool enabled);
 
 __END_DECLS