AIDL effect: Add effect AIDL definition
Bug: 238913361
Test: atest VtsHalAudioEffectTargetTest; atest VtsHalAudioEffectFactoryTargetTest
Merged-In: I8cc902df0a396d0703839b8933318a26aab2e38d
Change-Id: I8cc902df0a396d0703839b8933318a26aab2e38d
diff --git a/audio/aidl/Android.bp b/audio/aidl/Android.bp
index d6e6f50..4f9af12 100644
--- a/audio/aidl/Android.bp
+++ b/audio/aidl/Android.bp
@@ -147,11 +147,19 @@
name: "android.hardware.audio.effect",
vendor_available: true,
srcs: [
+ "android/hardware/audio/effect/Capability.aidl",
+ "android/hardware/audio/effect/CommandId.aidl",
"android/hardware/audio/effect/Descriptor.aidl",
+ "android/hardware/audio/effect/Equalizer.aidl",
+ "android/hardware/audio/effect/Flags.aidl",
"android/hardware/audio/effect/IEffect.aidl",
"android/hardware/audio/effect/IFactory.aidl",
+ "android/hardware/audio/effect/Parameter.aidl",
+ "android/hardware/audio/effect/State.aidl",
],
imports: [
+ "android.hardware.common-V2",
+ "android.hardware.common.fmq-V1",
"android.hardware.audio.common-V1",
"android.media.audio.common.types-V2",
],
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl
new file mode 100644
index 0000000..11acf5e
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl
@@ -0,0 +1,43 @@
+/*
+ * 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
+union Capability {
+ android.hardware.audio.effect.Capability.VendorEffectCapability vendor;
+ android.hardware.audio.effect.Equalizer.Capability equalizer;
+ @VintfStability
+ parcelable VendorEffectCapability {
+ ParcelableHolder extension;
+ }
+}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl
new file mode 100644
index 0000000..79299ee
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl
@@ -0,0 +1,50 @@
+/*
+ * 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;
+@Backing(type="int") @VintfStability
+enum CommandId {
+ START = 0,
+ STOP = 1,
+ RESET = 2,
+ VENDOR_COMMAND_0 = 256,
+ VENDOR_COMMAND_1 = 257,
+ VENDOR_COMMAND_2 = 258,
+ VENDOR_COMMAND_3 = 259,
+ VENDOR_COMMAND_4 = 260,
+ VENDOR_COMMAND_5 = 261,
+ VENDOR_COMMAND_6 = 262,
+ VENDOR_COMMAND_7 = 263,
+ VENDOR_COMMAND_8 = 264,
+ VENDOR_COMMAND_9 = 265,
+}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl
index 94cacd9..1c86cf3 100644
--- a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl
@@ -35,6 +35,7 @@
@VintfStability
parcelable Descriptor {
android.hardware.audio.effect.Descriptor.Common common;
+ android.hardware.audio.effect.Capability capability;
const String EFFECT_TYPE_UUID_ENV_REVERB = "c2e5d5f0-94bd-4763-9cac-4e234d06839e";
const String EFFECT_TYPE_UUID_PRESET_REVERB = "47382d60-ddd8-11db-bf3a-0002a5d5c51b";
const String EFFECT_TYPE_UUID_EQUALIZER = "0bed4300-ddd6-11db-8f34-0002a5d5c51b";
@@ -56,5 +57,6 @@
@VintfStability
parcelable Common {
android.hardware.audio.effect.Descriptor.Identity id;
+ android.hardware.audio.effect.Flags flags;
}
}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl
new file mode 100644
index 0000000..31732d3
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl
@@ -0,0 +1,46 @@
+/*
+ * 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
+union Equalizer {
+ android.hardware.audio.effect.Equalizer.VendorExtension vendor;
+ @VintfStability
+ parcelable Capability {
+ ParcelableHolder extension;
+ }
+ @VintfStability
+ parcelable VendorExtension {
+ ParcelableHolder extension;
+ }
+}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl
new file mode 100644
index 0000000..af774e8
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl
@@ -0,0 +1,37 @@
+/*
+ * 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
+parcelable Flags {
+}
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
index 7f868ad..e5c96f5 100644
--- 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
@@ -34,7 +34,23 @@
package android.hardware.audio.effect;
@VintfStability
interface IEffect {
- void open();
+ android.hardware.audio.effect.IEffect.OpenEffectReturn open(in android.hardware.audio.effect.Parameter.Common common, in android.hardware.audio.effect.Parameter.Specific specific);
void close();
android.hardware.audio.effect.Descriptor getDescriptor();
+ void command(in android.hardware.audio.effect.CommandId commandId);
+ android.hardware.audio.effect.State getState();
+ void setParameter(in android.hardware.audio.effect.Parameter param);
+ android.hardware.audio.effect.Parameter getParameter(in android.hardware.audio.effect.Parameter.Id paramId);
+ @FixedSize @VintfStability
+ parcelable Status {
+ int status;
+ int fmqByteConsumed;
+ int fmqByteProduced;
+ }
+ @VintfStability
+ parcelable OpenEffectReturn {
+ android.hardware.common.fmq.MQDescriptor<android.hardware.audio.effect.IEffect.Status,android.hardware.common.fmq.SynchronizedReadWrite> statusMQ;
+ android.hardware.common.fmq.MQDescriptor<byte,android.hardware.common.fmq.SynchronizedReadWrite> inputDataMQ;
+ android.hardware.common.fmq.MQDescriptor<byte,android.hardware.common.fmq.SynchronizedReadWrite> outputDataMQ;
+ }
}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl
new file mode 100644
index 0000000..16bd3bb
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl
@@ -0,0 +1,62 @@
+/*
+ * 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
+union Parameter {
+ android.hardware.audio.effect.Parameter.Common common;
+ android.hardware.audio.effect.Parameter.VendorEffectParameter vendorEffect;
+ android.hardware.audio.effect.Parameter.Specific specific;
+ @VintfStability
+ union Id {
+ int commonTag;
+ int vendorTag;
+ android.hardware.audio.effect.Parameter.Specific.Tag specificTag;
+ }
+ @VintfStability
+ parcelable Common {
+ int session;
+ int ioHandle;
+ android.media.audio.common.AudioDeviceDescription device;
+ android.media.audio.common.AudioConfig input;
+ android.media.audio.common.AudioConfig output;
+ }
+ @VintfStability
+ parcelable VendorEffectParameter {
+ ParcelableHolder extension;
+ }
+ @VintfStability
+ union Specific {
+ android.hardware.audio.effect.Equalizer equalizer;
+ }
+}
diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.aidl
new file mode 100644
index 0000000..3176b01
--- /dev/null
+++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.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;
+@Backing(type="byte") @VintfStability
+enum State {
+ INIT = 0,
+ IDLE = 1,
+ PROCESSING = 2,
+}
diff --git a/audio/aidl/android/hardware/audio/effect/Capability.aidl b/audio/aidl/android/hardware/audio/effect/Capability.aidl
new file mode 100644
index 0000000..e792f86
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/Capability.aidl
@@ -0,0 +1,46 @@
+/*
+ * 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.Equalizer;
+
+/**
+ * Effect capability definitions.
+ * This data structure is used as part of effect Descriptor to identify effect capabilities which
+ * not meant to change at runtime.
+ */
+@VintfStability
+union Capability {
+ /**
+ * Vendor defined effect capability.
+ * This extension can be used when vendor have a new effect implementated and need
+ * capability definition for this new type of effect.
+ * If vendor want to extend existing effect capabilities, it is recommended to expose though
+ * the ParcelableHolder in each effect capability definition. For example:
+ * Equalizer.Capability.extension.
+ */
+ @VintfStability
+ parcelable VendorEffectCapability {
+ ParcelableHolder extension;
+ }
+ VendorEffectCapability vendor;
+
+ /**
+ * Equalizer capability definition.
+ */
+ Equalizer.Capability equalizer;
+}
diff --git a/audio/aidl/android/hardware/audio/effect/CommandId.aidl b/audio/aidl/android/hardware/audio/effect/CommandId.aidl
new file mode 100644
index 0000000..208c163
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/CommandId.aidl
@@ -0,0 +1,70 @@
+/*
+ * 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;
+
+/**
+ * Defines all commands supported by the effect instance.
+ *
+ * There are three groups of commands:
+ * 1. Common part which MUST be supported by all effects.
+ * 2. Commands MUST be supported by a specific type of effect.
+ * 3. Extension commands for vendor.
+ */
+@VintfStability
+@Backing(type="int")
+enum CommandId {
+ /// MUST be supported by all effects
+ /**
+ * Start effect engine processing.
+ * An effect instance must start processing data and transfer to PROCESSING state if it is in
+ * IDLE state and have all necessary information. Otherwise it must:
+ * 1. Throw a EX_ILLEGAL_STATE exception if effect is not in IDLE state, or
+ * 2. Throw a EX_TRANSACTION_FAILED for all other errors.
+ *
+ * Depending on parameters set to the effect instance, effect may do process or reverse
+ * process after START command.
+ */
+ START = 0,
+ /**
+ * Stop effect engine processing with all resource kept.
+ * The currently processed audio data will be discarded if the effect engine is in PROCESSING
+ * state.
+ * Effect instance must do nothing and return ok when it receive STOP command in IDLE state.
+ */
+ STOP = 1,
+ /**
+ * Keep all parameter settings but reset the buffer content, stop engine processing, and transit
+ * instance state to IDLE if its in PROCESSING state.
+ * Effect instance must be able to handle RESET command at IDLE and PROCESSING states.
+ */
+ RESET = 2,
+
+ /// MUST be supported by a specific type of effect.
+ // Commands must supported by Equalizer.
+
+ /// Extension commands for vendor.
+ VENDOR_COMMAND_0 = 0x100,
+ VENDOR_COMMAND_1,
+ VENDOR_COMMAND_2,
+ VENDOR_COMMAND_3,
+ VENDOR_COMMAND_4,
+ VENDOR_COMMAND_5,
+ VENDOR_COMMAND_6,
+ VENDOR_COMMAND_7,
+ VENDOR_COMMAND_8,
+ VENDOR_COMMAND_9,
+}
diff --git a/audio/aidl/android/hardware/audio/effect/Descriptor.aidl b/audio/aidl/android/hardware/audio/effect/Descriptor.aidl
index 51b31c2..aca9bbe 100644
--- a/audio/aidl/android/hardware/audio/effect/Descriptor.aidl
+++ b/audio/aidl/android/hardware/audio/effect/Descriptor.aidl
@@ -16,12 +16,13 @@
package android.hardware.audio.effect;
+import android.hardware.audio.effect.Capability;
+import android.hardware.audio.effect.Flags;
import android.media.audio.common.AudioUuid;
/**
- * Effect descriptor contains all information (capabilities, attributes, and ownership) for an
- * effect implemented in the Audio Effect HAL. Framework uses this information to decide when and
- * how to apply the effect.
+ * Descriptor contains all information (capabilities, attributes, etc) for an effect implementation.
+ * The client uses this information to decide when and how to apply an effect implementation.
*/
@VintfStability
parcelable Descriptor {
@@ -77,6 +78,15 @@
* Identity of effect implementation.
*/
Identity id;
+ /**
+ * Effect engine defined capabilities/requirements flags.
+ */
+ Flags flags;
}
Common common;
+
+ /**
+ * Effect implementation capability.
+ */
+ Capability capability;
}
diff --git a/audio/aidl/android/hardware/audio/effect/Equalizer.aidl b/audio/aidl/android/hardware/audio/effect/Equalizer.aidl
new file mode 100644
index 0000000..309874d
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/Equalizer.aidl
@@ -0,0 +1,47 @@
+/*
+ * 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.media.audio.common.AudioProfile;
+
+/**
+ * Equalizer specific definitions.
+ */
+@VintfStability
+union Equalizer {
+ /**
+ * Defines Equalizer implementation capabilities, it MUST be supported by all equalizer
+ * implementations.
+ *
+ * Equalizer.Capability definition is used by android.hardware.audio.effect.Capability.
+ */
+ @VintfStability
+ parcelable Capability {
+ /**
+ * Equalizer capability extension, vendor can use this extension in case existing capability
+ * definition not enough.
+ */
+ ParcelableHolder extension;
+ }
+
+ // Vendor Equalizer implementation definition for additional parameters.
+ @VintfStability
+ parcelable VendorExtension {
+ ParcelableHolder extension;
+ }
+ VendorExtension vendor;
+}
diff --git a/audio/aidl/android/hardware/audio/effect/Flags.aidl b/audio/aidl/android/hardware/audio/effect/Flags.aidl
new file mode 100644
index 0000000..8add975
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/Flags.aidl
@@ -0,0 +1,26 @@
+/*
+ * 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;
+
+/**
+ * The common part of available capability/configuration for effects. For effect type specific
+ * capability, see @c android.hardware.audio.effect.Capability.
+ */
+@VintfStability
+parcelable Flags {
+ // TODO: add Effect engine defined capabilities/requirements flags.
+}
diff --git a/audio/aidl/android/hardware/audio/effect/IEffect.aidl b/audio/aidl/android/hardware/audio/effect/IEffect.aidl
index d7a9501..9ab8b02 100644
--- a/audio/aidl/android/hardware/audio/effect/IEffect.aidl
+++ b/audio/aidl/android/hardware/audio/effect/IEffect.aidl
@@ -16,24 +16,68 @@
package android.hardware.audio.effect;
+import android.hardware.audio.effect.CommandId;
import android.hardware.audio.effect.Descriptor;
+import android.hardware.audio.effect.Parameter;
+import android.hardware.audio.effect.State;
+import android.hardware.common.fmq.MQDescriptor;
+import android.hardware.common.fmq.SynchronizedReadWrite;
/**
* Effect interfaces definitions to configure and control the effect instance.
*/
@VintfStability
interface IEffect {
+ @VintfStability
+ @FixedSize
+ parcelable Status {
+ /**
+ * One of Binder STATUS_* statuses:
+ * - STATUS_OK: the command has completed successfully;
+ * - STATUS_BAD_VALUE: invalid value in the 'Command' structure;
+ * - STATUS_INVALID_OPERATION: the mix port is not connected
+ * to any producer or consumer, thus
+ * positions can not be reported;
+ * - STATUS_NOT_ENOUGH_DATA: a read or write error has
+ * occurred for the 'audio.fmq' queue;
+ *
+ */
+ int status;
+ /**
+ * The amount of bytes consumed by the effect instance.
+ */
+ int fmqByteConsumed;
+ /**
+ * The amount of bytes produced by the effect instance.
+ */
+ int fmqByteProduced;
+ }
+
+ // Return data structure of IEffect.open() interface.
+ @VintfStability
+ parcelable OpenEffectReturn {
+ // Message queue for effect processing status.
+ MQDescriptor<Status, SynchronizedReadWrite> statusMQ;
+ // Message queue for input data buffer.
+ MQDescriptor<byte, SynchronizedReadWrite> inputDataMQ;
+ // Message queue for output data buffer.
+ MQDescriptor<byte, SynchronizedReadWrite> outputDataMQ;
+ }
+
/**
- * 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.
+ * Open an effect instance, effect must not start processing data before receive
+ * CommandId::START command. All necessary information should be allocated and instance must
+ * transfer to State::IDLE state after open() call has been handled successfully. After open,
+ * the effect instance must be able to handle all IEffect interface calls.
*
+ * @param common Parameters which MUST pass from client at open time.
+ *
+ * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported command.
* @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 should not throw an error.
*/
- void open();
+ OpenEffectReturn open(in Parameter.Common common, in Parameter.Specific specific);
/**
* Called by the client to close the effect instance, processing thread should be destroyed and
@@ -45,7 +89,7 @@
*
* Effect instance close interface should always succeed unless:
* 1. The effect instance is not in a proper state to be closed, for example it's still in
- * processing state.
+ * State::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.
@@ -62,4 +106,53 @@
* @return Descriptor The @c Descriptor of this effect instance.
*/
Descriptor getDescriptor();
+
+ /**
+ * Send a command (defined in enum CommandId) to the effect instance, instance state can be
+ * changed as result of command handling.
+ *
+ * Must be available for the effect instance after it has been open().
+ *
+ * @param commandId ID of the command send to the effect instance.
+ *
+ * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state to handle the
+ * command.
+ * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported command.
+ */
+ void command(in CommandId commandId);
+
+ /**
+ * Get current state of the effect instance.
+ *
+ * Must be available for the effect instance at anytime and should always succeed.
+ *
+ * @return Current effect instance state.
+ */
+ State getState();
+
+ /**
+ * Set a parameter to the effect instance.
+ *
+ * Must be available for the effect instance after open().
+ *
+ * @param param Parameter data to set to the effect instance.
+ *
+ * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported parameter.
+ */
+ void setParameter(in Parameter param);
+
+ /**
+ * Get a parameter from the effect instance with parameter ID.
+ *
+ * This interface must return the current parameter of the effect instance, if no parameter
+ * has been set by client yet, the default value must be returned.
+ *
+ * Must be available for the effect instance after open().
+ *
+ * @param paramId The tag enum of parameter to get.
+ * @return Parameter The parameter to get from the effect instance.
+ *
+ * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported parameter tag.
+ */
+ Parameter getParameter(in Parameter.Id paramId);
}
diff --git a/audio/aidl/android/hardware/audio/effect/Parameter.aidl b/audio/aidl/android/hardware/audio/effect/Parameter.aidl
new file mode 100644
index 0000000..2951660
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/Parameter.aidl
@@ -0,0 +1,87 @@
+/*
+ * 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.Equalizer;
+import android.media.audio.common.AudioConfig;
+import android.media.audio.common.AudioDeviceDescription;
+/**
+ * Defines all parameters supported by the effect instance.
+ *
+ * There are three groups of parameters:
+ * 1. Common parameters are essential parameters, MUST pass to effects at open() interface.
+ * 2. Parameters defined for a specific effect type.
+ * 3. Extension parameters for vendor.
+ *
+ * For all supported parameter, implementation MUST support both set and get.
+ */
+@VintfStability
+union Parameter {
+ /**
+ * Client can pass in Parameter.Id with the corresponding tag value in IEffect.getParameter()
+ * call to get android.hardware.audio.effect.Parameter.
+ *
+ * As an example, if a client want to get audio.hardware.audio.effect.Specific.Equalizer, the
+ * value of Id should be audio.hardware.audio.effect.Parameter.Specific.equalizer.
+ */
+ @VintfStability
+ union Id {
+ // Common parameter tag.
+ int commonTag;
+ // Vendor defined parameter tag.
+ int vendorTag;
+ // Specific effect parameter tag.
+ Specific.Tag specificTag;
+ }
+
+ /**
+ * Common parameters MUST be supported by all effect implementations.
+ */
+ @VintfStability
+ parcelable Common {
+ // Type of Audio device.
+ int session;
+ // I/O Handle.
+ int ioHandle;
+ // Type of Audio device.
+ AudioDeviceDescription device;
+ // Input config.
+ AudioConfig input;
+ // Output config.
+ AudioConfig output;
+ }
+ Common common;
+
+ /**
+ * Parameters for vendor extension effect implementation usage.
+ */
+ @VintfStability
+ parcelable VendorEffectParameter {
+ ParcelableHolder extension;
+ }
+ VendorEffectParameter vendorEffect;
+
+ /**
+ * Parameters MUST be supported by a Specific type of effect.
+ */
+ @VintfStability
+ union Specific {
+ Equalizer equalizer;
+ // TODO: add other effect definitions here
+ }
+ Specific specific;
+}
diff --git a/audio/aidl/android/hardware/audio/effect/State.aidl b/audio/aidl/android/hardware/audio/effect/State.aidl
new file mode 100644
index 0000000..85a4afc
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/State.aidl
@@ -0,0 +1,86 @@
+/*
+ * 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;
+
+/**
+ * Possible states of an effect instance.
+ * A typical effect instance will be in INIT state when it is created with IFactory.createEffect()
+ * interface, transfer to IDLE after open(), and to PROCESSING after
+ * IEffect.command(Command.Id.START) command. When an effect instance receive STOP or RESET command,
+ * it should transfer to IDLE state after handle the command successfully. Effect instance should
+ * consume minimal resource and transfer to INIT state after it was close().
+ *
+ * Refer to State.gv for detailed state diagram.
+ */
+@VintfStability
+@Backing(type="byte")
+enum State {
+
+ /**
+ * An effect instance is in INIT state by default after it was created with
+ * IFactory.createEffect(). When an effect instance is in INIT state, it should have instance
+ * context initialized, and ready to handle IEffect.setParameter(), IEffect.open() as well as
+ * all getter interfaces.
+ *
+ * In INIT state, effect instance must:
+ * 1. Not handle any IEffect.command() and return EX_ILLEGAL_STATE with any Command.Id.
+ * 2. Be able to handle all parameter setting with IEffect.setParameter().
+ * 3. Be able to handle all getter interface calls like IEffect.getParameter() and
+ * IEffect.getState().
+ * 4. Be able to handle IEffect.open() successfully after configuration.
+ *
+ * Client is expected to do necessary configuration with IEffect.setParameter(), get all
+ * resource ready with IEffect.open(), and make sure effect instance transfer to IDLE state
+ * before sending commands with IEffect.command() interface. Effect instance must transfer
+ * from INIT to IDLE state after handle IEffect.open() call successfully.
+ */
+ INIT,
+ /**
+ * An effect instance transfer to IDLE state after it was open successfully with IEffect.open()
+ * in INIT state, or after it was stop/reset with Command.Id.STOP/RESET in PROCESSING state.
+ *
+ * In IDLE state, effect instance must:
+ * 1. Be able to start effect processing engine with IEffect.command(Command.Id.START) call.
+ * 2. Be able to handle all parameter setting with IEffect.setParameter().
+ * 3. Be able to handle all getter interface calls like IEffect.getParameter() and
+ * IEffect.getState().
+ *
+ * The following state transfer can happen in IDLE state:
+ * 1. Transfer to PROCESSING if instance receive an START command and start processing data
+ * successfully.
+ * 2. Transfer to INIT if instance receive a close() call.
+ */
+ IDLE,
+ /**
+ * An effect instance is in PROCESSING state after it receive an START command and start
+ * processing data successfully. Effect instance will transfer from PROCESSING to IDLE state if
+ * it receive an STOP or RESET command and handle the command successfully.
+ *
+ * When an instance is in PROCESSING state, client should try not to close() it directly,
+ * instead client should try to stop processing data first with STOP command before close(). In
+ * the case of a close() call received when instance in PROCESSING state, it should try to stop
+ * processing and transfer to IDLE first before close().
+ *
+ * In PROCESSING state, effect instance must:
+ * 1. Return EX_ILLEGAL_STATE if it's not able to handle any parameter settings at runtime.
+ * 2. Be able to handle STOP and RESET for IEffect.command() interface, and return
+ * EX_ILLEGAL_STATE for all other commands.
+ * 3. Must be able to handle all get* interface calls like IEffect.getParameter() and
+ * IEffect.getState().
+ */
+ PROCESSING,
+}
diff --git a/audio/aidl/android/hardware/audio/effect/state.gv b/audio/aidl/android/hardware/audio/effect/state.gv
new file mode 100644
index 0000000..e19e6c7
--- /dev/null
+++ b/audio/aidl/android/hardware/audio/effect/state.gv
@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+
+// To render: "dot -Tpng state.gv -o state.png"
+digraph effect_state_machine {
+ node [shape=point style=filled fillcolor=black width=0.5] I;
+ node [shape=doublecircle] F;
+ node [shape=oval width=1];
+ node [fillcolor=lightgreen] INIT;
+ node [fillcolor=lightblue] IDLE;
+ node [fillcolor=lightyellow] PROCESSING;
+
+ I -> INIT [label="IFactory.createEffect" labelfontcolor="navy"];
+ INIT -> F [label="IFactory.destroyEffect"];
+ INIT -> IDLE [label="open()" labelfontcolor="lime"];
+ IDLE -> PROCESSING [label="command(START"];
+ PROCESSING -> IDLE [label="command(STOP)\ncommand(RESET)"];
+ IDLE -> INIT [label="close()"];
+
+ INIT -> INIT [label="getState\ngetDescriptor"];
+ IDLE -> IDLE [label="getXXX\nsetParameter\ncommand(RESET)"];
+ PROCESSING -> PROCESSING [label="getXXX\nsetParameter"];
+}
\ No newline at end of file
