Implement NDK createSessionUsingConfig API
This patch implements a new way to create ADPF hint session,
with a new parcelable SessionCreationConfig. This object encapsulates
the required information for session creation, with a set of setters to
assign values to those fields in the session creation config.
This object can be reused on the client side in order to streamline
the session creation process.
Bug: 362801903
Bug: 367803904
Test: atest HintManagerServiceTest
atest PerformanceHintNativeTest
Flag: EXEMPT_NDK
Change-Id: Idd2ea87886c664b625f40066cc05c6df1bf0e6d4
diff --git a/include/android/performance_hint.h b/include/android/performance_hint.h
index 22eab94..37d320a 100644
--- a/include/android/performance_hint.h
+++ b/include/android/performance_hint.h
@@ -111,9 +111,24 @@
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,7 +168,7 @@
* @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,
@@ -161,6 +176,20 @@
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.
*
* @param manager The performance hint manager instance.
@@ -170,6 +199,15 @@
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.
*
* @param session The performance hint session instance to update.
@@ -320,12 +358,12 @@
* 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 @@
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