AIDL effect: Initial IEffect interface definition
Bug: 238913361
Test: atest VtsHalAudioEffectTargetTest
Merged-In: I0d02fed5d40a108003e735d3619e2fc7c0ef6332
Change-Id: I0d02fed5d40a108003e735d3619e2fc7c0ef6332
diff --git a/audio/aidl/Android.bp b/audio/aidl/Android.bp
index d4c1e85..ad933bc 100644
--- a/audio/aidl/Android.bp
+++ b/audio/aidl/Android.bp
@@ -148,6 +148,7 @@
vendor_available: true,
srcs: [
"android/hardware/audio/effect/Descriptor.aidl",
+ "android/hardware/audio/effect/IEffect.aidl",
"android/hardware/audio/effect/IFactory.aidl",
],
imports: [
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl
new file mode 100644
index 0000000..7f868ad
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl
@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2022 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.
+ */
+///////////////////////////////////////////////////////////////////////////////
+// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
+///////////////////////////////////////////////////////////////////////////////
+
+// This file is a snapshot of an AIDL file. Do not edit it manually. There are
+// two cases:
+// 1). this is a frozen version file - do not edit this in any case.
+// 2). this is a 'current' file. If you make a backwards compatible change to
+// the interface (from the latest frozen version), the build system will
+// prompt you to update this file with `m <name>-update-api`.
+//
+// You must not make a backward incompatible change to any AIDL file built
+// with the aidl_interface module type with versions property set. The module
+// type is used to build AIDL files in a way that they can be used across
+// independently updatable components of the system. If a device is shipped
+// with such a backward incompatible change, it has a high risk of breaking
+// later when a module using the interface is updated, e.g., Mainline modules.
+
+package android.hardware.audio.effect;
+@VintfStability
+interface IEffect {
+ void open();
+ void close();
+ android.hardware.audio.effect.Descriptor getDescriptor();
+}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl
index b6c9aab..db06475 100644
--- a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl
@@ -35,4 +35,6 @@
@VintfStability
interface IFactory {
android.hardware.audio.effect.Descriptor.Identity[] queryEffects(in @nullable android.media.audio.common.AudioUuid type, in @nullable android.media.audio.common.AudioUuid implementation);
+ android.hardware.audio.effect.IEffect createEffect(in android.media.audio.common.AudioUuid implUuid);
+ void destroyEffect(in android.hardware.audio.effect.IEffect handle);
}
diff --git a/audio/aidl/android/hardware/audio/effect/IEffect.aidl b/audio/aidl/android/hardware/audio/effect/IEffect.aidl
new file mode 100644
index 0000000..44e916b
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/IEffect.aidl
@@ -0,0 +1,63 @@
+/*
+ * Copyright (C) 2022 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.
+ */
+
+package android.hardware.audio.effect;
+
+import android.hardware.audio.effect.Descriptor;
+
+/**
+ * Effect interfaces definitions to configure and control the effect instance.
+ */
+@VintfStability
+interface IEffect {
+ /**
+ * Open an effect instance, effect should not start processing data before receive START
+ * command. All necessary information should be allocated and instance should transfer to IDLE
+ * state after open() call has been handled successfully.
+ * After open, the effect instance should be able to handle all IEffect interface calls.
+ *
+ * @throws a EX_UNSUPPORTED_OPERATION if device capability/resource is not enough or system
+ * failure happens.
+ * @note Open an already-opened effect instance should do nothing and not result in throw error.
+ */
+ void open();
+
+ /**
+ * Called by the client to close the effect instance, instance context will be kept after
+ * close, but processing thread should be destroyed and consume no CPU. It is recommended to
+ * close the effect on the client side as soon as it becomes unused, it's client responsibility
+ * to make sure all parameter/buffer is correct if client wants to reopen a closed instance.
+ *
+ * Effect instance close interface should always success unless:
+ * 1. The effect instance is not in a proper state to be closed, for example it's still in
+ * processing state.
+ * 2. There is system/hardware related failure when close.
+ *
+ * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state to be closed.
+ * @throws EX_UNSUPPORTED_OPERATION if the effect instance failed to close for any other reason.
+ * @note Close an already-closed effect should do nothing and not result in throw error.
+ */
+ void close();
+
+ /**
+ * Return the @c Descriptor of this effect instance.
+ *
+ * Must be available for the effect instance at anytime and should always succeed.
+ *
+ * @return Descriptor The @c Descriptor of this effect instance.
+ */
+ Descriptor getDescriptor();
+}
diff --git a/audio/aidl/android/hardware/audio/effect/IFactory.aidl b/audio/aidl/android/hardware/audio/effect/IFactory.aidl
index 99c2e6a..4873d3a 100644
--- a/audio/aidl/android/hardware/audio/effect/IFactory.aidl
+++ b/audio/aidl/android/hardware/audio/effect/IFactory.aidl
@@ -17,6 +17,7 @@
package android.hardware.audio.effect;
import android.hardware.audio.effect.Descriptor;
+import android.hardware.audio.effect.IEffect;
import android.media.audio.common.AudioUuid;
/**
@@ -42,4 +43,30 @@
*/
Descriptor.Identity[] queryEffects(
in @nullable AudioUuid type, in @nullable AudioUuid implementation);
+
+ /**
+ * Called by the audio framework to create the effect (identified by the implementation UUID
+ * parameter).
+ *
+ * The effect instance should be able to maintain its own context and parameters after creation.
+ *
+ * @param implUuid UUID for the effect implementation which instance will be created based on.
+ * @return The effect instance handle created.
+ * @throws EX_ILLEGAL_ARGUMENT if the implUuid is not valid.
+ * @throws EX_TRANSACTION_FAILED if device capability/resource is not enough to create the
+ * effect instance.
+ */
+ IEffect createEffect(in AudioUuid implUuid);
+
+ /**
+ * Called by the framework to destroy the effect and free up all currently allocated resources.
+ * It is recommended to destroy the effect from the client side as soon as it is becomes unused.
+ *
+ * The client must ensure effect instance is closed before destroy.
+ *
+ * @param handle The handle of effect instance to be destroyed.
+ * @throws EX_ILLEGAL_ARGUMENT if the effect handle is not valid.
+ * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state to be destroyed.
+ */
+ void destroyEffect(in IEffect handle);
}